dimse_message.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_DIMSE_DIMSE_MESSAGE_HPP
#define PACS_NETWORK_DIMSE_DIMSE_MESSAGE_HPP
 
#include "command_field.h"
#include "status_codes.h"
 
#include <kcenon/pacs/core/dicom_dataset.h>
#include <kcenon/pacs/core/dicom_tag.h>
#include <kcenon/pacs/core/result.h>
#include <kcenon/pacs/encoding/transfer_syntax.h>
 
#include <cstdint>
#include <functional>
#include <optional>
#include <span>
#include <string>
#include <string_view>
#include <variant>
#include <vector>
 
namespace kcenon::pacs::network::dimse {
 
 
constexpr core::dicom_tag tag_command_group_length{0x0000, 0x0000};
 
constexpr core::dicom_tag tag_affected_sop_class_uid{0x0000, 0x0002};
 
constexpr core::dicom_tag tag_requested_sop_class_uid{0x0000, 0x0003};
 
constexpr core::dicom_tag tag_command_field{0x0000, 0x0100};
 
constexpr core::dicom_tag tag_message_id{0x0000, 0x0110};
 
constexpr core::dicom_tag tag_message_id_responded_to{0x0000, 0x0120};
 
constexpr core::dicom_tag tag_move_destination{0x0000, 0x0600};
 
constexpr core::dicom_tag tag_priority{0x0000, 0x0700};
 
constexpr core::dicom_tag tag_command_data_set_type{0x0000, 0x0800};
 
constexpr core::dicom_tag tag_status{0x0000, 0x0900};
 
constexpr core::dicom_tag tag_offending_element{0x0000, 0x0901};
 
constexpr core::dicom_tag tag_error_comment{0x0000, 0x0902};
 
constexpr core::dicom_tag tag_error_id{0x0000, 0x0903};
 
constexpr core::dicom_tag tag_affected_sop_instance_uid{0x0000, 0x1000};
 
constexpr core::dicom_tag tag_requested_sop_instance_uid{0x0000, 0x1001};
 
constexpr core::dicom_tag tag_event_type_id{0x0000, 0x1002};
 
constexpr core::dicom_tag tag_attribute_identifier_list{0x0000, 0x1005};
 
constexpr core::dicom_tag tag_action_type_id{0x0000, 0x1008};
 
constexpr core::dicom_tag tag_number_of_remaining_subops{0x0000, 0x1020};
 
constexpr core::dicom_tag tag_number_of_completed_subops{0x0000, 0x1021};
 
constexpr core::dicom_tag tag_number_of_failed_subops{0x0000, 0x1022};
 
constexpr core::dicom_tag tag_number_of_warning_subops{0x0000, 0x1023};
 
constexpr core::dicom_tag tag_move_originator_aet{0x0000, 0x1030};
 
constexpr core::dicom_tag tag_move_originator_message_id{0x0000, 0x1031};
 
 
 
constexpr uint16_t command_data_set_type_null = 0x0101;
 
constexpr uint16_t command_data_set_type_present = 0x0001;
 
 
 
constexpr uint16_t priority_low = 0x0002;
 
constexpr uint16_t priority_medium = 0x0000;
 
constexpr uint16_t priority_high = 0x0001;
 
 
enum class dimse_error {
    success = 0,
    invalid_command_set,
    missing_required_field,
    invalid_data_format,
    encoding_error,
    decoding_error,
};
 
[[nodiscard]] constexpr std::string_view to_string(dimse_error err) noexcept {
    switch (err) {
        case dimse_error::success: return "Success";
        case dimse_error::invalid_command_set: return "Invalid command set";
        case dimse_error::missing_required_field: return "Missing required field";
        case dimse_error::invalid_data_format: return "Invalid data format";
        case dimse_error::encoding_error: return "Encoding error";
        case dimse_error::decoding_error: return "Decoding error";
        default: return "Unknown error";
    }
}
 
template <typename T>
using dimse_result = kcenon::pacs::Result<T>;
 
class dimse_message {
public:
    // ========================================================================
    // Construction
    // ========================================================================
 
    dimse_message(command_field cmd, uint16_t message_id);
 
    dimse_message() = default;
 
    dimse_message(const dimse_message&) = default;
 
    dimse_message(dimse_message&&) noexcept = default;
 
    auto operator=(const dimse_message&) -> dimse_message& = default;
 
    auto operator=(dimse_message&&) noexcept -> dimse_message& = default;
 
    ~dimse_message() = default;
 
    // ========================================================================
    // Command Set Access
    // ========================================================================
 
    [[nodiscard]] auto command() const noexcept -> command_field;
 
    [[nodiscard]] auto message_id() const noexcept -> uint16_t;
 
    [[nodiscard]] auto command_set() noexcept -> core::dicom_dataset&;
 
    [[nodiscard]] auto command_set() const noexcept -> const core::dicom_dataset&;
 
    // ========================================================================
    // Dataset Access
    // ========================================================================
 
    [[nodiscard]] auto has_dataset() const noexcept -> bool;
 
    [[nodiscard]] auto dataset() -> kcenon::pacs::Result<std::reference_wrapper<core::dicom_dataset>>;
 
    [[nodiscard]] auto dataset() const -> kcenon::pacs::Result<std::reference_wrapper<const core::dicom_dataset>>;
 
    void set_dataset(core::dicom_dataset ds);
 
    void clear_dataset() noexcept;
 
    // ========================================================================
    // Status (for responses)
    // ========================================================================
 
    [[nodiscard]] auto status() const -> status_code;
 
    void set_status(status_code status);
 
    // ========================================================================
    // Common Attributes
    // ========================================================================
 
    [[nodiscard]] auto affected_sop_class_uid() const -> std::string;
 
    void set_affected_sop_class_uid(std::string_view uid);
 
    [[nodiscard]] auto affected_sop_instance_uid() const -> std::string;
 
    void set_affected_sop_instance_uid(std::string_view uid);
 
    [[nodiscard]] auto priority() const -> uint16_t;
 
    void set_priority(uint16_t priority);
 
    [[nodiscard]] auto message_id_responded_to() const -> uint16_t;
 
    void set_message_id_responded_to(uint16_t id);
 
    // ========================================================================
    // DIMSE-N Specific Attributes
    // ========================================================================
 
    [[nodiscard]] auto requested_sop_class_uid() const -> std::string;
 
    void set_requested_sop_class_uid(std::string_view uid);
 
    [[nodiscard]] auto requested_sop_instance_uid() const -> std::string;
 
    void set_requested_sop_instance_uid(std::string_view uid);
 
    [[nodiscard]] auto event_type_id() const -> std::optional<uint16_t>;
 
    void set_event_type_id(uint16_t type_id);
 
    [[nodiscard]] auto action_type_id() const -> std::optional<uint16_t>;
 
    void set_action_type_id(uint16_t type_id);
 
    [[nodiscard]] auto attribute_identifier_list() const -> std::vector<core::dicom_tag>;
 
    void set_attribute_identifier_list(const std::vector<core::dicom_tag>& tags);
 
    // ========================================================================
    // Sub-operation Counts (for C-GET/C-MOVE responses)
    // ========================================================================
 
    [[nodiscard]] auto remaining_subops() const -> std::optional<uint16_t>;
 
    void set_remaining_subops(uint16_t count);
 
    [[nodiscard]] auto completed_subops() const -> std::optional<uint16_t>;
 
    void set_completed_subops(uint16_t count);
 
    [[nodiscard]] auto failed_subops() const -> std::optional<uint16_t>;
 
    void set_failed_subops(uint16_t count);
 
    [[nodiscard]] auto warning_subops() const -> std::optional<uint16_t>;
 
    void set_warning_subops(uint16_t count);
 
    // ========================================================================
    // Encoding/Decoding
    // ========================================================================
 
    using encoded_message = std::pair<std::vector<uint8_t>, std::vector<uint8_t>>;
 
    [[nodiscard]] static auto encode(
        const dimse_message& msg,
        const encoding::transfer_syntax& dataset_ts)
        -> dimse_result<encoded_message>;
 
    [[nodiscard]] static auto decode(
        std::span<const uint8_t> command_data,
        std::span<const uint8_t> dataset_data,
        const encoding::transfer_syntax& dataset_ts)
        -> dimse_result<dimse_message>;
 
    // ========================================================================
    // Validation
    // ========================================================================
 
    [[nodiscard]] auto is_valid() const noexcept -> bool;
 
    [[nodiscard]] auto is_request() const noexcept -> bool;
 
    [[nodiscard]] auto is_response() const noexcept -> bool;
 
private:
    void update_data_set_type();
 
    void update_command_group_length();
 
    command_field command_{};
    uint16_t message_id_{0};
    core::dicom_dataset command_set_;
    std::optional<core::dicom_dataset> dataset_;
};
 
// ============================================================================
// Factory Functions
// ============================================================================
 
[[nodiscard]] auto make_c_echo_rq(
    uint16_t message_id,
    std::string_view sop_class_uid = "1.2.840.10008.1.1") -> dimse_message;
 
[[nodiscard]] auto make_c_echo_rsp(
    uint16_t message_id_responded_to,
    status_code status = status_success,
    std::string_view sop_class_uid = "1.2.840.10008.1.1") -> dimse_message;
 
[[nodiscard]] auto make_c_store_rq(
    uint16_t message_id,
    std::string_view sop_class_uid,
    std::string_view sop_instance_uid,
    uint16_t priority = priority_medium) -> dimse_message;
 
[[nodiscard]] auto make_c_store_rsp(
    uint16_t message_id_responded_to,
    std::string_view sop_class_uid,
    std::string_view sop_instance_uid,
    status_code status = status_success) -> dimse_message;
 
[[nodiscard]] auto make_c_find_rq(
    uint16_t message_id,
    std::string_view sop_class_uid,
    uint16_t priority = priority_medium) -> dimse_message;
 
[[nodiscard]] auto make_c_find_rsp(
    uint16_t message_id_responded_to,
    std::string_view sop_class_uid,
    status_code status) -> dimse_message;
 
// ============================================================================
// DIMSE-N Factory Functions
// ============================================================================
 
[[nodiscard]] auto make_n_create_rq(
    uint16_t message_id,
    std::string_view sop_class_uid,
    std::string_view sop_instance_uid = "") -> dimse_message;
 
[[nodiscard]] auto make_n_create_rsp(
    uint16_t message_id_responded_to,
    std::string_view sop_class_uid,
    std::string_view sop_instance_uid,
    status_code status = status_success) -> dimse_message;
 
[[nodiscard]] auto make_n_set_rq(
    uint16_t message_id,
    std::string_view sop_class_uid,
    std::string_view sop_instance_uid) -> dimse_message;
 
[[nodiscard]] auto make_n_set_rsp(
    uint16_t message_id_responded_to,
    std::string_view sop_class_uid,
    std::string_view sop_instance_uid,
    status_code status = status_success) -> dimse_message;
 
[[nodiscard]] auto make_n_get_rq(
    uint16_t message_id,
    std::string_view sop_class_uid,
    std::string_view sop_instance_uid,
    const std::vector<core::dicom_tag>& attribute_tags = {}) -> dimse_message;
 
[[nodiscard]] auto make_n_get_rsp(
    uint16_t message_id_responded_to,
    std::string_view sop_class_uid,
    std::string_view sop_instance_uid,
    status_code status = status_success) -> dimse_message;
 
[[nodiscard]] auto make_n_event_report_rq(
    uint16_t message_id,
    std::string_view sop_class_uid,
    std::string_view sop_instance_uid,
    uint16_t event_type_id) -> dimse_message;
 
[[nodiscard]] auto make_n_event_report_rsp(
    uint16_t message_id_responded_to,
    std::string_view sop_class_uid,
    std::string_view sop_instance_uid,
    uint16_t event_type_id,
    status_code status = status_success) -> dimse_message;
 
[[nodiscard]] auto make_n_action_rq(
    uint16_t message_id,
    std::string_view sop_class_uid,
    std::string_view sop_instance_uid,
    uint16_t action_type_id) -> dimse_message;
 
[[nodiscard]] auto make_n_action_rsp(
    uint16_t message_id_responded_to,
    std::string_view sop_class_uid,
    std::string_view sop_instance_uid,
    uint16_t action_type_id,
    status_code status = status_success) -> dimse_message;
 
[[nodiscard]] auto make_n_delete_rq(
    uint16_t message_id,
    std::string_view sop_class_uid,
    std::string_view sop_instance_uid) -> dimse_message;
 
[[nodiscard]] auto make_n_delete_rsp(
    uint16_t message_id_responded_to,
    std::string_view sop_class_uid,
    std::string_view sop_instance_uid,
    status_code status = status_success) -> dimse_message;
 
}  // namespace kcenon::pacs::network::dimse
 
#endif  // PACS_NETWORK_DIMSE_DIMSE_MESSAGE_HPP