worklist_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_WORKLIST_SCU_HPP
#define PACS_SERVICES_WORKLIST_SCU_HPP
 
#include "kcenon/pacs/core/dicom_dataset.h"
#include "kcenon/pacs/network/association.h"
#include "kcenon/pacs/di/ilogger.h"
 
#include <atomic>
#include <chrono>
#include <cstdint>
#include <functional>
#include <memory>
#include <string>
#include <vector>
 
namespace kcenon::pacs::services {
 
// =============================================================================
// Worklist Query Keys Structure
// =============================================================================
 
struct worklist_query_keys {
    // =========================================================================
    // Scheduled Procedure Step Attributes
    // =========================================================================
 
    std::string scheduled_station_ae;
 
    std::string modality;
 
    std::string scheduled_date;
 
    std::string scheduled_time;
 
    std::string scheduled_physician;
 
    std::string scheduled_procedure_step_id;
 
    // =========================================================================
    // Requested Procedure Attributes
    // =========================================================================
 
    std::string requested_procedure_id;
 
    std::string requested_procedure_description;
 
    // =========================================================================
    // Patient Attributes
    // =========================================================================
 
    std::string patient_name;
 
    std::string patient_id;
 
    std::string patient_birth_date;
 
    std::string patient_sex;
 
    // =========================================================================
    // Visit Attributes
    // =========================================================================
 
    std::string accession_number;
 
    std::string referring_physician;
 
    std::string institution;
};
 
// =============================================================================
// Worklist Item Structure
// =============================================================================
 
struct worklist_item {
    // =========================================================================
    // Patient Demographics
    // =========================================================================
 
    std::string patient_name;
 
    std::string patient_id;
 
    std::string patient_birth_date;
 
    std::string patient_sex;
 
    // =========================================================================
    // Scheduled Procedure Step
    // =========================================================================
 
    std::string scheduled_station_ae;
 
    std::string modality;
 
    std::string scheduled_date;
 
    std::string scheduled_time;
 
    std::string scheduled_procedure_step_id;
 
    std::string scheduled_procedure_step_description;
 
    // =========================================================================
    // Requested Procedure
    // =========================================================================
 
    std::string study_instance_uid;
 
    std::string accession_number;
 
    std::string requested_procedure_id;
 
    std::string requested_procedure_description;
 
    // =========================================================================
    // Visit Information
    // =========================================================================
 
    std::string referring_physician;
 
    std::string institution;
 
    // =========================================================================
    // Original Dataset
    // =========================================================================
 
    core::dicom_dataset dataset;
};
 
// =============================================================================
// Worklist Result Structure
// =============================================================================
 
struct worklist_result {
    std::vector<worklist_item> items;
 
    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;
    }
};
 
// =============================================================================
// Worklist SCU Configuration
// =============================================================================
 
struct worklist_scu_config {
    std::chrono::milliseconds timeout{30000};
 
    size_t max_results{0};
 
    bool cancel_on_max{true};
};
 
// =============================================================================
// Streaming Callback Type
// =============================================================================
 
using worklist_streaming_callback = std::function<bool(const worklist_item&)>;
 
// =============================================================================
// Worklist SCU Class
// =============================================================================
 
class worklist_scu {
public:
    // =========================================================================
    // Construction
    // =========================================================================
 
    explicit worklist_scu(std::shared_ptr<di::ILogger> logger = nullptr);
 
    explicit worklist_scu(const worklist_scu_config& config,
                          std::shared_ptr<di::ILogger> logger = nullptr);
 
    ~worklist_scu() = default;
 
    // Non-copyable, non-movable (due to atomic members)
    worklist_scu(const worklist_scu&) = delete;
    worklist_scu& operator=(const worklist_scu&) = delete;
    worklist_scu(worklist_scu&&) = delete;
    worklist_scu& operator=(worklist_scu&&) = delete;
 
    // =========================================================================
    // Generic Query Operations
    // =========================================================================
 
    [[nodiscard]] network::Result<worklist_result> query(
        network::association& assoc,
        const worklist_query_keys& keys);
 
    [[nodiscard]] network::Result<worklist_result> query(
        network::association& assoc,
        const core::dicom_dataset& query_keys);
 
    // =========================================================================
    // Convenience Query Methods
    // =========================================================================
 
    [[nodiscard]] network::Result<worklist_result> query_today(
        network::association& assoc,
        std::string_view station_ae,
        std::string_view modality = "");
 
    [[nodiscard]] network::Result<worklist_result> query_date_range(
        network::association& assoc,
        std::string_view start_date,
        std::string_view end_date,
        std::string_view modality = "");
 
    [[nodiscard]] network::Result<worklist_result> query_patient(
        network::association& assoc,
        std::string_view patient_id);
 
    // =========================================================================
    // Streaming Query
    // =========================================================================
 
    [[nodiscard]] network::Result<size_t> query_streaming(
        network::association& assoc,
        const worklist_query_keys& keys,
        worklist_streaming_callback callback);
 
    // =========================================================================
    // C-CANCEL Support
    // =========================================================================
 
    [[nodiscard]] network::Result<std::monostate> cancel(
        network::association& assoc,
        uint16_t message_id);
 
    // =========================================================================
    // Configuration
    // =========================================================================
 
    void set_config(const worklist_scu_config& config);
 
    [[nodiscard]] const worklist_scu_config& config() const noexcept;
 
    // =========================================================================
    // Statistics
    // =========================================================================
 
    [[nodiscard]] size_t queries_performed() const noexcept;
 
    [[nodiscard]] size_t total_items() const noexcept;
 
    void reset_statistics() noexcept;
 
private:
    // =========================================================================
    // Private Implementation
    // =========================================================================
 
    [[nodiscard]] worklist_item parse_worklist_item(
        const core::dicom_dataset& ds) const;
 
    [[nodiscard]] core::dicom_dataset build_query_dataset(
        const worklist_query_keys& keys) const;
 
    [[nodiscard]] uint16_t next_message_id() noexcept;
 
    [[nodiscard]] network::Result<worklist_result> query_impl(
        network::association& assoc,
        const core::dicom_dataset& query_keys,
        uint16_t message_id);
 
    [[nodiscard]] static std::string get_today_date();
 
    // =========================================================================
    // Private Members
    // =========================================================================
 
    std::shared_ptr<di::ILogger> logger_;
 
    worklist_scu_config config_;
 
    std::atomic<uint16_t> message_id_counter_{1};
 
    std::atomic<size_t> queries_performed_{0};
 
    std::atomic<size_t> total_items_{0};
};
 
}  // namespace kcenon::pacs::services
 
#endif  // PACS_SERVICES_WORKLIST_SCU_HPP