query_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_QUERY_SCU_HPP
#define PACS_SERVICES_QUERY_SCU_HPP
 
#include "query_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 {
 
// =============================================================================
// Query Model Enumeration
// =============================================================================
 
enum class query_model {
    patient_root,  
    study_root     
};
 
[[nodiscard]] constexpr std::string_view to_string(query_model model) noexcept {
    switch (model) {
        case query_model::patient_root: return "Patient Root";
        case query_model::study_root: return "Study Root";
        default: return "Unknown";
    }
}
 
[[nodiscard]] constexpr std::string_view get_find_sop_class_uid(
    query_model model) noexcept {
    switch (model) {
        case query_model::patient_root:
            return patient_root_find_sop_class_uid;
        case query_model::study_root:
            return study_root_find_sop_class_uid;
        default:
            return patient_root_find_sop_class_uid;
    }
}
 
// =============================================================================
// Query Result Structure
// =============================================================================
 
struct query_result {
    std::vector<core::dicom_dataset> matches;
 
    uint16_t status{0};
 
    std::chrono::milliseconds elapsed{0};
 
    size_t total_pending{0};
 
    [[nodiscard]] bool is_success() const noexcept {
        return status == 0x0000;
    }
 
    [[nodiscard]] bool is_cancelled() const noexcept {
        return status == 0xFE00;
    }
};
 
// =============================================================================
// Typed Query Key Structures
// =============================================================================
 
struct patient_query_keys {
    std::string patient_name;        
    std::string patient_id;          
    std::string birth_date;          
    std::string sex;                 
};
 
struct study_query_keys {
    std::string patient_id;          
    std::string study_uid;           
    std::string study_date;          
    std::string accession_number;    
    std::string modality;            
    std::string study_description;   
};
 
struct series_query_keys {
    std::string study_uid;           
    std::string series_uid;          
    std::string modality;            
    std::string series_number;       
};
 
struct instance_query_keys {
    std::string series_uid;          
    std::string sop_instance_uid;    
    std::string instance_number;     
};
 
// =============================================================================
// Query SCU Configuration
// =============================================================================
 
struct query_scu_config {
    query_model model{query_model::study_root};
 
    query_level level{query_level::study};
 
    std::chrono::milliseconds timeout{30000};
 
    size_t max_results{0};
 
    bool cancel_on_max{true};
};
 
// =============================================================================
// Streaming Callback Types
// =============================================================================
 
using query_streaming_callback = std::function<bool(const core::dicom_dataset&)>;
 
// =============================================================================
// Query SCU Class
// =============================================================================
 
class query_scu {
public:
    // =========================================================================
    // Construction
    // =========================================================================
 
    explicit query_scu(std::shared_ptr<di::ILogger> logger = nullptr);
 
    explicit query_scu(const query_scu_config& config,
                       std::shared_ptr<di::ILogger> logger = nullptr);
 
    ~query_scu() = default;
 
    // Non-copyable, non-movable (due to atomic members)
    query_scu(const query_scu&) = delete;
    query_scu& operator=(const query_scu&) = delete;
    query_scu(query_scu&&) = delete;
    query_scu& operator=(query_scu&&) = delete;
 
    // =========================================================================
    // Generic Query Operations
    // =========================================================================
 
    [[nodiscard]] network::Result<query_result> find(
        network::association& assoc,
        const core::dicom_dataset& query_keys);
 
    [[nodiscard]] network::Result<size_t> find_streaming(
        network::association& assoc,
        const core::dicom_dataset& query_keys,
        query_streaming_callback callback);
 
    // =========================================================================
    // Typed Convenience Methods
    // =========================================================================
 
    [[nodiscard]] network::Result<query_result> find_patients(
        network::association& assoc,
        const patient_query_keys& keys);
 
    [[nodiscard]] network::Result<query_result> find_studies(
        network::association& assoc,
        const study_query_keys& keys);
 
    [[nodiscard]] network::Result<query_result> find_series(
        network::association& assoc,
        const series_query_keys& keys);
 
    [[nodiscard]] network::Result<query_result> find_instances(
        network::association& assoc,
        const instance_query_keys& keys);
 
    // =========================================================================
    // C-CANCEL Support
    // =========================================================================
 
    [[nodiscard]] network::Result<std::monostate> cancel(
        network::association& assoc,
        uint16_t message_id);
 
    // =========================================================================
    // Configuration
    // =========================================================================
 
    void set_config(const query_scu_config& config);
 
    [[nodiscard]] const query_scu_config& config() const noexcept;
 
    // =========================================================================
    // Statistics
    // =========================================================================
 
    [[nodiscard]] size_t queries_performed() const noexcept;
 
    [[nodiscard]] size_t total_matches() const noexcept;
 
    void reset_statistics() noexcept;
 
private:
    // =========================================================================
    // Private Implementation
    // =========================================================================
 
    [[nodiscard]] network::Result<query_result> find_impl(
        network::association& assoc,
        const core::dicom_dataset& query_keys,
        uint16_t message_id);
 
    [[nodiscard]] uint16_t next_message_id() noexcept;
 
    [[nodiscard]] core::dicom_dataset build_query_dataset(
        const patient_query_keys& keys) const;
 
    [[nodiscard]] core::dicom_dataset build_query_dataset(
        const study_query_keys& keys) const;
 
    [[nodiscard]] core::dicom_dataset build_query_dataset(
        const series_query_keys& keys) const;
 
    [[nodiscard]] core::dicom_dataset build_query_dataset(
        const instance_query_keys& keys) const;
 
    [[nodiscard]] std::string_view get_sop_class_uid() const noexcept;
 
    // =========================================================================
    // Private Members
    // =========================================================================
 
    std::shared_ptr<di::ILogger> logger_;
 
    query_scu_config config_;
 
    std::atomic<uint16_t> message_id_counter_{1};
 
    std::atomic<size_t> queries_performed_{0};
 
    std::atomic<size_t> total_matches_{0};
};
 
}  // namespace kcenon::pacs::services
 
#endif  // PACS_SERVICES_QUERY_SCU_HPP