association.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_ASSOCIATION_HPP
#define PACS_NETWORK_ASSOCIATION_HPP
 
#include "kcenon/pacs/network/pdu_types.h"
#include "kcenon/pacs/network/dimse/dimse_message.h"
#include "kcenon/pacs/encoding/transfer_syntax.h"
 
#include <chrono>
#include <cstdint>
#include <functional>
#include <map>
#include <memory>
#include <mutex>
#include <optional>
#include <string>
#include <string_view>
#include <variant>
#include <vector>
 
#include <kcenon/thread/lockfree/lockfree_queue.h>
 
#include "kcenon/pacs/core/result.h"
 
namespace kcenon::pacs::network {
 
// =============================================================================
// Forward Declarations
// =============================================================================
 
class association;
 
// =============================================================================
// Result Type
// =============================================================================
 
template <typename T>
using Result = kcenon::pacs::Result<T>;
 
using VoidResult = kcenon::pacs::VoidResult;
 
// =============================================================================
// Association State
// =============================================================================
 
enum class association_state {
    idle,              
    awaiting_associate_ac, 
    awaiting_associate_rq, 
    established,       
    awaiting_release_rp,   
    awaiting_release_rq,   
    released,          
    aborted            
};
 
[[nodiscard]] constexpr const char* to_string(association_state state) noexcept {
    switch (state) {
        case association_state::idle: return "Idle (Sta1)";
        case association_state::awaiting_associate_ac: return "Awaiting A-ASSOCIATE-AC (Sta5)";
        case association_state::awaiting_associate_rq: return "Awaiting A-ASSOCIATE-RQ (Sta2)";
        case association_state::established: return "Established (Sta6)";
        case association_state::awaiting_release_rp: return "Awaiting A-RELEASE-RP (Sta7)";
        case association_state::awaiting_release_rq: return "Awaiting A-RELEASE-RQ (Sta8)";
        case association_state::released: return "Released";
        case association_state::aborted: return "Aborted";
        default: return "Unknown";
    }
}
 
// =============================================================================
// Association Error
// =============================================================================
 
enum class association_error {
    success = 0,
    connection_failed,
    connection_timeout,
    association_rejected,
    association_aborted,
    invalid_state,
    negotiation_failed,
    no_acceptable_context,
    pdu_encoding_error,
    pdu_decoding_error,
    send_failed,
    receive_failed,
    receive_timeout,
    protocol_error,
    release_failed,
    already_released
};
 
[[nodiscard]] constexpr std::string_view to_string(association_error err) noexcept {
    switch (err) {
        case association_error::success: return "Success";
        case association_error::connection_failed: return "Connection failed";
        case association_error::connection_timeout: return "Connection timeout";
        case association_error::association_rejected: return "Association rejected";
        case association_error::association_aborted: return "Association aborted";
        case association_error::invalid_state: return "Invalid state for operation";
        case association_error::negotiation_failed: return "Negotiation failed";
        case association_error::no_acceptable_context: return "No acceptable presentation context";
        case association_error::pdu_encoding_error: return "PDU encoding error";
        case association_error::pdu_decoding_error: return "PDU decoding error";
        case association_error::send_failed: return "Send failed";
        case association_error::receive_failed: return "Receive failed";
        case association_error::receive_timeout: return "Receive timeout";
        case association_error::protocol_error: return "Protocol error";
        case association_error::release_failed: return "Release failed";
        case association_error::already_released: return "Already released";
        default: return "Unknown error";
    }
}
 
// =============================================================================
// Association Configuration
// =============================================================================
 
struct proposed_presentation_context {
    uint8_t id;                           
    std::string abstract_syntax;          
    std::vector<std::string> transfer_syntaxes; 
 
    proposed_presentation_context() : id(0) {}
    proposed_presentation_context(uint8_t ctx_id, std::string abs_syntax,
                                  std::vector<std::string> ts_list)
        : id(ctx_id)
        , abstract_syntax(std::move(abs_syntax))
        , transfer_syntaxes(std::move(ts_list)) {}
};
 
struct accepted_presentation_context {
    uint8_t id;                           
    std::string abstract_syntax;          
    std::string transfer_syntax;          
    presentation_context_result result;   
 
    accepted_presentation_context()
        : id(0), result(presentation_context_result::acceptance) {}
    accepted_presentation_context(uint8_t ctx_id, std::string abs_syntax,
                                  std::string ts, presentation_context_result res)
        : id(ctx_id)
        , abstract_syntax(std::move(abs_syntax))
        , transfer_syntax(std::move(ts))
        , result(res) {}
 
    [[nodiscard]] bool is_accepted() const noexcept {
        return result == presentation_context_result::acceptance;
    }
};
 
struct association_config {
    std::string calling_ae_title;         
    std::string called_ae_title;          
    std::vector<proposed_presentation_context> proposed_contexts;
    uint32_t max_pdu_length = DEFAULT_MAX_PDU_LENGTH;
    std::string implementation_class_uid;
    std::string implementation_version_name;
 
    association_config() = default;
};
 
struct scp_config {
    std::string ae_title;                 
    std::vector<std::string> accepted_ae_titles; 
    std::vector<std::string> supported_abstract_syntaxes;
    std::vector<std::string> supported_transfer_syntaxes;
    uint32_t max_pdu_length = DEFAULT_MAX_PDU_LENGTH;
    std::string implementation_class_uid;
    std::string implementation_version_name;
 
    scp_config() = default;
};
 
// =============================================================================
// Association Rejection Info
// =============================================================================
 
struct rejection_info {
    reject_result result;
    uint8_t source;
    uint8_t reason;
    std::string description;
 
    rejection_info()
        : result(reject_result::rejected_permanent)
        , source(0)
        , reason(0) {}
 
    rejection_info(reject_result res, uint8_t src, uint8_t rsn)
        : result(res), source(src), reason(rsn) {
        build_description();
    }
 
private:
    void build_description();
};
 
// =============================================================================
// Association Class
// =============================================================================
 
class association {
public:
    // =========================================================================
    // Type Aliases
    // =========================================================================
 
    using clock = std::chrono::steady_clock;
    using duration = std::chrono::milliseconds;
    using time_point = clock::time_point;
 
    static constexpr duration default_timeout{30000};  // 30 seconds
 
    // =========================================================================
    // Construction / Destruction
    // =========================================================================
 
    association();
 
    association(association&& other) noexcept;
 
    association& operator=(association&& other) noexcept;
 
    ~association();
 
    // Disable copy
    association(const association&) = delete;
    association& operator=(const association&) = delete;
 
    // =========================================================================
    // Factory Methods
    // =========================================================================
 
    [[nodiscard]] static Result<association> connect(
        const std::string& host,
        uint16_t port,
        const association_config& config,
        duration timeout = default_timeout);
 
    [[nodiscard]] static association accept(
        const associate_rq& rq,
        const scp_config& config);
 
    [[nodiscard]] static associate_rj reject(
        reject_result result,
        uint8_t source,
        uint8_t reason);
 
    // =========================================================================
    // State Queries
    // =========================================================================
 
    [[nodiscard]] association_state state() const noexcept;
 
    [[nodiscard]] bool is_established() const noexcept;
 
    [[nodiscard]] bool is_closed() const noexcept;
 
    // =========================================================================
    // Negotiated Parameters
    // =========================================================================
 
    [[nodiscard]] std::string_view calling_ae() const noexcept;
 
    [[nodiscard]] std::string_view called_ae() const noexcept;
 
    [[nodiscard]] uint32_t max_pdu_size() const noexcept;
 
    [[nodiscard]] std::string_view remote_implementation_class() const noexcept;
 
    [[nodiscard]] std::string_view remote_implementation_version() const noexcept;
 
    // =========================================================================
    // Presentation Context Management
    // =========================================================================
 
    [[nodiscard]] bool has_accepted_context(std::string_view abstract_syntax) const;
 
    [[nodiscard]] std::optional<uint8_t> accepted_context_id(
        std::string_view abstract_syntax) const;
 
    [[nodiscard]] Result<encoding::transfer_syntax> context_transfer_syntax(
        uint8_t pc_id) const;
 
    [[nodiscard]] const std::vector<accepted_presentation_context>&
        accepted_contexts() const noexcept;
 
    // =========================================================================
    // DIMSE Operations
    // =========================================================================
 
    [[nodiscard]] Result<std::monostate> send_dimse(
        uint8_t context_id,
        const dimse::dimse_message& msg);
 
    [[nodiscard]] Result<std::pair<uint8_t, dimse::dimse_message>> receive_dimse(
        duration timeout = default_timeout);
 
    // =========================================================================
    // PDU Access (for network layer integration)
    // =========================================================================
 
    [[nodiscard]] associate_rq build_associate_rq() const;
 
    [[nodiscard]] associate_ac build_associate_ac() const;
 
    bool process_associate_ac(const associate_ac& ac);
 
    void process_associate_rj(const associate_rj& rj);
 
    [[nodiscard]] std::optional<rejection_info> get_rejection_info() const;
 
    // =========================================================================
    // Lifecycle Management
    // =========================================================================
 
    [[nodiscard]] Result<std::monostate> release(duration timeout = default_timeout);
 
    void process_release_rq();
 
    void process_release_rp();
 
    void abort(uint8_t source = 0, uint8_t reason = 0);
 
    void process_abort(const abort_source& source, const abort_reason& reason);
 
    // =========================================================================
    // Internal State Management (for testing/debugging)
    // =========================================================================
 
    void set_state(association_state new_state);
 
    void set_peer(association* peer);
 
    void enqueue_message(uint8_t context_id, dimse::dimse_message msg);
 
    void update_peer(association* old_peer, association* new_peer);
 
private:
    // =========================================================================
    // Private Implementation
    // =========================================================================
 
    [[nodiscard]] bool can_transition_to(association_state new_state) const;
 
    void transition(association_state new_state);
 
    void build_context_map();
 
    void negotiate_contexts(const associate_rq& rq, const scp_config& config);
 
    // =========================================================================
    // Member Variables
    // =========================================================================
 
    association_state state_{association_state::idle};
 
    std::string calling_ae_;
 
    std::string called_ae_;
 
    std::string our_ae_;
 
    uint32_t max_pdu_size_{DEFAULT_MAX_PDU_LENGTH};
 
    std::string our_implementation_class_;
 
    std::string our_implementation_version_;
 
    std::string remote_implementation_class_;
 
    std::string remote_implementation_version_;
 
    std::vector<proposed_presentation_context> proposed_contexts_;
 
    std::vector<accepted_presentation_context> accepted_contexts_;
 
    std::map<std::string, uint8_t> abstract_syntax_to_context_;
 
    std::map<uint8_t, encoding::transfer_syntax> context_to_transfer_syntax_;
 
    std::optional<rejection_info> rejection_info_;
 
    uint8_t abort_source_{0};
 
    uint8_t abort_reason_{0};
 
    mutable std::mutex mutex_;
 
    bool is_scu_{true};
 
    association* peer_{nullptr};
 
    using message_type = std::pair<uint8_t, dimse::dimse_message>;
    using message_queue_type = kcenon::thread::detail::concurrent_queue<message_type>;
    mutable std::unique_ptr<message_queue_type> incoming_queue_{
        std::make_unique<message_queue_type>()};
};
 
}  // namespace kcenon::pacs::network
 
#endif  // PACS_NETWORK_ASSOCIATION_HPP