dicom_association_handler.h

Go to the documentation of this file.

// BSD 3-Clause License
// Copyright (c) 2021-2025, 🍀☀🌕🌥 🌊
// See the LICENSE file in the project root for full license information.
 
#ifndef PACS_NETWORK_V2_DICOM_ASSOCIATION_HANDLER_HPP
#define PACS_NETWORK_V2_DICOM_ASSOCIATION_HANDLER_HPP
 
#include "kcenon/pacs/network/association.h"
#include "kcenon/pacs/network/pdu_types.h"
#include "kcenon/pacs/network/server_config.h"
#include "kcenon/pacs/security/access_control_manager.h"
#include "kcenon/pacs/services/scp_service.h"
#include "kcenon/pacs/integration/dicom_session.h"
 
#include <atomic>
#include <chrono>
#include <functional>
#include <map>
#include <memory>
#include <mutex>
#include <optional>
#include <string>
#include <vector>
 
// Note: pdu_data and Result types are provided by
// pacs/integration/dicom_session.hpp which is included above
 
// Forward declaration for public network_system interface
namespace kcenon::network::interfaces {
class i_session;
}  // namespace kcenon::network::interfaces
 
namespace kcenon::pacs::network::v2 {
 
// =============================================================================
// Handler State
// =============================================================================
 
enum class handler_state {
    idle,              
    awaiting_response, 
    established,       
    releasing,         
    closed             
};
 
[[nodiscard]] constexpr const char* to_string(handler_state state) noexcept {
    switch (state) {
        case handler_state::idle: return "Idle";
        case handler_state::awaiting_response: return "Awaiting Response";
        case handler_state::established: return "Established";
        case handler_state::releasing: return "Releasing";
        case handler_state::closed: return "Closed";
        default: return "Unknown";
    }
}
 
// =============================================================================
// Handler Callbacks
// =============================================================================
 
using association_established_callback =
    std::function<void(const std::string& session_id,
                       const std::string& calling_ae,
                       const std::string& called_ae)>;
 
using association_closed_callback =
    std::function<void(const std::string& session_id, bool graceful)>;
 
using handler_error_callback =
    std::function<void(const std::string& session_id, const std::string& error)>;
 
// =============================================================================
// DICOM Association Handler Class
// =============================================================================
 
class dicom_association_handler
    : public std::enable_shared_from_this<dicom_association_handler> {
public:
    // =========================================================================
    // Type Aliases
    // =========================================================================
 
    using session_ptr = std::shared_ptr<kcenon::network::interfaces::i_session>;
    using service_map = std::map<std::string, services::scp_service*>;
    using clock = std::chrono::steady_clock;
    using time_point = clock::time_point;
    using duration = std::chrono::milliseconds;
 
    static constexpr size_t pdu_header_size = 6;
 
    static constexpr size_t max_pdu_size = 64 * 1024 * 1024;  // 64 MB
 
    // =========================================================================
    // Construction / Destruction
    // =========================================================================
 
    dicom_association_handler(
        session_ptr session,
        const server_config& config,
        const service_map& services);
 
    ~dicom_association_handler();
 
    // Non-copyable, non-movable
    dicom_association_handler(const dicom_association_handler&) = delete;
    dicom_association_handler& operator=(const dicom_association_handler&) = delete;
    dicom_association_handler(dicom_association_handler&&) = delete;
    dicom_association_handler& operator=(dicom_association_handler&&) = delete;
 
    // =========================================================================
    // Lifecycle Management
    // =========================================================================
 
    void start();
 
    void stop(bool graceful = false);
 
    // =========================================================================
    // Server-Level Event Forwarding
    // =========================================================================
 
    void feed_data(const std::vector<uint8_t>& data);
 
    void handle_disconnect();
 
    void handle_error(std::error_code ec);
 
    // =========================================================================
    // State Queries
    // =========================================================================
 
    [[nodiscard]] handler_state state() const noexcept;
 
    [[nodiscard]] bool is_established() const noexcept;
 
    [[nodiscard]] bool is_closed() const noexcept;
 
    [[nodiscard]] std::string session_id() const;
 
    [[nodiscard]] std::string calling_ae() const;
 
    [[nodiscard]] std::string called_ae() const;
 
    [[nodiscard]] Result<std::reference_wrapper<association>> get_association();
    [[nodiscard]] Result<std::reference_wrapper<const association>> get_association() const;
 
    [[nodiscard]] time_point last_activity() const noexcept;
 
    // =========================================================================
    // Callbacks
    // =========================================================================
 
    void set_established_callback(association_established_callback callback);
 
    void set_closed_callback(association_closed_callback callback);
 
    void set_error_callback(handler_error_callback callback);
 
    // =========================================================================
    // Statistics
    // =========================================================================
 
    [[nodiscard]] uint64_t pdus_received() const noexcept;
 
    [[nodiscard]] uint64_t pdus_sent() const noexcept;
 
    [[nodiscard]] uint64_t messages_processed() const noexcept;
 
    // =========================================================================
    // Security / Access Control
    // =========================================================================
 
    void set_access_control(std::shared_ptr<security::access_control_manager> acm);
 
    void set_access_control_enabled(bool enabled);
 
private:
    // =========================================================================
    // Network Callbacks
    // =========================================================================
 
    void on_data_received(const std::vector<uint8_t>& data);
 
    void on_disconnected(const std::string& session_id);
 
    void on_error(std::error_code ec);
 
    // =========================================================================
    // PDU Processing
    // =========================================================================
 
    void process_buffer();
 
    void process_pdu(const integration::pdu_data& pdu);
 
    void handle_associate_rq(const std::vector<uint8_t>& payload);
 
    void handle_p_data_tf(const std::vector<uint8_t>& payload);
 
    void handle_release_rq();
 
    void handle_abort(const std::vector<uint8_t>& payload);
 
    // =========================================================================
    // Response Sending
    // =========================================================================
 
    void send_associate_ac();
 
    void send_associate_rj(reject_result result, uint8_t source, uint8_t reason);
 
    void send_p_data_tf(const std::vector<uint8_t>& payload);
 
    void send_release_rp();
 
    void send_abort(abort_source source, abort_reason reason);
 
    void send_pdu(pdu_type type, const std::vector<uint8_t>& payload);
 
    // =========================================================================
    // Service Dispatching
    // =========================================================================
 
    Result<std::monostate> dispatch_to_service(
        uint8_t context_id,
        const dimse::dimse_message& msg);
 
    [[nodiscard]] services::scp_service* find_service(const std::string& sop_class_uid) const;
 
    // =========================================================================
    // State Management
    // =========================================================================
 
    void transition_to(handler_state new_state);
 
    void touch();
 
    void report_error(const std::string& error);
 
    void close_handler(bool graceful);
 
    // =========================================================================
    // Member Variables
    // =========================================================================
 
    session_ptr session_;
 
    server_config config_;
 
    service_map services_;
 
    association association_;
 
    std::atomic<handler_state> state_{handler_state::idle};
 
    std::vector<uint8_t> receive_buffer_;
 
    [[maybe_unused]] uint32_t expected_pdu_length_{0};
 
    [[maybe_unused]] pdu_type current_pdu_type_{pdu_type::abort};
 
    time_point last_activity_;
 
    std::atomic<uint64_t> pdus_received_{0};
    std::atomic<uint64_t> pdus_sent_{0};
    std::atomic<uint64_t> messages_processed_{0};
 
    association_established_callback established_callback_;
    association_closed_callback closed_callback_;
    handler_error_callback error_callback_;
 
    mutable std::mutex mutex_;
    mutable std::mutex callback_mutex_;
 
    std::shared_ptr<security::access_control_manager> access_control_;
 
    std::optional<security::user_context> user_context_;
 
    bool access_control_enabled_{false};
};
 
}  // namespace kcenon::pacs::network::v2
 
#endif  // PACS_NETWORK_V2_DICOM_ASSOCIATION_HANDLER_HPP