retrieve_scu.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_SERVICES_RETRIEVE_SCU_HPP
#define PACS_SERVICES_RETRIEVE_SCU_HPP
 
#include "query_scu.h"
#include "retrieve_scp.h"
#include "kcenon/pacs/core/dicom_dataset.h"
#include "kcenon/pacs/network/association.h"
#include "kcenon/pacs/network/dimse/dimse_message.h"
#include "kcenon/pacs/di/ilogger.h"
 
#include <atomic>
#include <chrono>
#include <cstdint>
#include <functional>
#include <string>
#include <vector>
 
namespace kcenon::pacs::services {
 
// =============================================================================
// Retrieve Mode Enumeration
// =============================================================================
 
enum class retrieve_mode {
    c_move,  
    c_get    
};
 
[[nodiscard]] constexpr std::string_view to_string(retrieve_mode mode) noexcept {
    switch (mode) {
        case retrieve_mode::c_move: return "C-MOVE";
        case retrieve_mode::c_get: return "C-GET";
        default: return "Unknown";
    }
}
 
// =============================================================================
// Retrieve Progress Structure
// =============================================================================
 
struct retrieve_progress {
    uint16_t remaining{0};   
    uint16_t completed{0};   
    uint16_t failed{0};      
    uint16_t warning{0};     
    std::chrono::steady_clock::time_point start_time;
 
    [[nodiscard]] uint16_t total() const noexcept {
        return remaining + completed + failed + warning;
    }
 
    [[nodiscard]] float percent() const noexcept {
        uint16_t t = total();
        if (t == 0) return 0.0f;
        return (static_cast<float>(completed + failed + warning) / t) * 100.0f;
    }
 
    [[nodiscard]] std::chrono::milliseconds elapsed() const noexcept {
        return std::chrono::duration_cast<std::chrono::milliseconds>(
            std::chrono::steady_clock::now() - start_time);
    }
};
 
// =============================================================================
// Retrieve Result Structure
// =============================================================================
 
struct retrieve_result {
    uint16_t completed{0};
 
    uint16_t failed{0};
 
    uint16_t warning{0};
 
    uint16_t final_status{0};
 
    std::chrono::milliseconds elapsed{0};
 
    std::vector<core::dicom_dataset> received_instances;
 
    [[nodiscard]] bool is_success() const noexcept {
        return final_status == 0x0000 && failed == 0;
    }
 
    [[nodiscard]] bool is_cancelled() const noexcept {
        return final_status == 0xFE00;
    }
 
    [[nodiscard]] bool has_failures() const noexcept {
        return failed > 0;
    }
 
    [[nodiscard]] bool has_warnings() const noexcept {
        return warning > 0;
    }
};
 
// =============================================================================
// Progress Callback Type
// =============================================================================
 
using retrieve_progress_callback = std::function<void(const retrieve_progress&)>;
 
// =============================================================================
// Instance Receive Callback Type (for C-GET)
// =============================================================================
 
using instance_receive_callback = std::function<bool(const core::dicom_dataset&)>;
 
// =============================================================================
// Retrieve SCU Configuration
// =============================================================================
 
struct retrieve_scu_config {
    retrieve_mode mode{retrieve_mode::c_move};
 
    query_model model{query_model::study_root};
 
    query_level level{query_level::study};
 
    std::string move_destination;
 
    std::chrono::milliseconds timeout{120000};
 
    uint16_t priority{0};
};
 
// =============================================================================
// Retrieve SCU Class
// =============================================================================
 
class retrieve_scu {
public:
    // =========================================================================
    // Construction
    // =========================================================================
 
    explicit retrieve_scu(std::shared_ptr<di::ILogger> logger = nullptr);
 
    explicit retrieve_scu(const retrieve_scu_config& config,
                          std::shared_ptr<di::ILogger> logger = nullptr);
 
    ~retrieve_scu() = default;
 
    // Non-copyable, non-movable (due to atomic members)
    retrieve_scu(const retrieve_scu&) = delete;
    retrieve_scu& operator=(const retrieve_scu&) = delete;
    retrieve_scu(retrieve_scu&&) = delete;
    retrieve_scu& operator=(retrieve_scu&&) = delete;
 
    // =========================================================================
    // C-MOVE Operations
    // =========================================================================
 
    [[nodiscard]] network::Result<retrieve_result> move(
        network::association& assoc,
        const core::dicom_dataset& query_keys,
        std::string_view destination_ae,
        retrieve_progress_callback progress = nullptr);
 
    // =========================================================================
    // C-GET Operations
    // =========================================================================
 
    [[nodiscard]] network::Result<retrieve_result> get(
        network::association& assoc,
        const core::dicom_dataset& query_keys,
        retrieve_progress_callback progress = nullptr);
 
    // =========================================================================
    // Convenience Methods
    // =========================================================================
 
    [[nodiscard]] network::Result<retrieve_result> retrieve_study(
        network::association& assoc,
        std::string_view study_uid,
        retrieve_progress_callback progress = nullptr);
 
    [[nodiscard]] network::Result<retrieve_result> retrieve_series(
        network::association& assoc,
        std::string_view series_uid,
        retrieve_progress_callback progress = nullptr);
 
    [[nodiscard]] network::Result<retrieve_result> retrieve_instance(
        network::association& assoc,
        std::string_view sop_instance_uid,
        retrieve_progress_callback progress = nullptr);
 
    // =========================================================================
    // C-CANCEL Support
    // =========================================================================
 
    [[nodiscard]] network::Result<std::monostate> cancel(
        network::association& assoc,
        uint16_t message_id);
 
    // =========================================================================
    // Configuration
    // =========================================================================
 
    void set_config(const retrieve_scu_config& config);
 
    void set_move_destination(std::string_view ae_title);
 
    [[nodiscard]] const retrieve_scu_config& config() const noexcept;
 
    // =========================================================================
    // Statistics
    // =========================================================================
 
    [[nodiscard]] size_t retrieves_performed() const noexcept;
 
    [[nodiscard]] size_t instances_retrieved() const noexcept;
 
    [[nodiscard]] size_t bytes_retrieved() const noexcept;
 
    void reset_statistics() noexcept;
 
private:
    // =========================================================================
    // Private Implementation
    // =========================================================================
 
    [[nodiscard]] network::Result<retrieve_result> perform_move(
        network::association& assoc,
        const core::dicom_dataset& query_keys,
        std::string_view destination_ae,
        retrieve_progress_callback progress);
 
    [[nodiscard]] network::Result<retrieve_result> perform_get(
        network::association& assoc,
        const core::dicom_dataset& query_keys,
        retrieve_progress_callback progress);
 
    [[nodiscard]] uint16_t next_message_id() noexcept;
 
    [[nodiscard]] std::string_view get_move_sop_class_uid() const noexcept;
 
    [[nodiscard]] std::string_view get_get_sop_class_uid() const noexcept;
 
    [[nodiscard]] core::dicom_dataset build_study_query(
        std::string_view study_uid) const;
 
    [[nodiscard]] core::dicom_dataset build_series_query(
        std::string_view series_uid) const;
 
    [[nodiscard]] core::dicom_dataset build_instance_query(
        std::string_view sop_instance_uid) const;
 
    // =========================================================================
    // Private Members
    // =========================================================================
 
    std::shared_ptr<di::ILogger> logger_;
 
    retrieve_scu_config config_;
 
    std::atomic<uint16_t> message_id_counter_{1};
 
    std::atomic<size_t> retrieves_performed_{0};
 
    std::atomic<size_t> instances_retrieved_{0};
 
    std::atomic<size_t> bytes_retrieved_{0};
};
 
}  // namespace kcenon::pacs::services
 
#endif  // PACS_SERVICES_RETRIEVE_SCU_HPP