kcenon::pacs::services::ups_watch_scu Class Reference

UPS Watch SCU service for subscribing to events on remote systems. More...

#include <ups_watch_scu.h>

Collaboration diagram for kcenon::pacs::services::ups_watch_scu:

Public Types
using	event_received_callback
	Callback type for received event notifications.

Public Member Functions
	ups_watch_scu (std::shared_ptr< di::ILogger > logger=nullptr)
	Construct UPS Watch SCU with default configuration.
	ups_watch_scu (const ups_watch_scu_config &config, std::shared_ptr< di::ILogger > logger=nullptr)
	Construct UPS Watch SCU with custom configuration.
	~ups_watch_scu ()=default
	ups_watch_scu (const ups_watch_scu &)=delete
ups_watch_scu &	operator= (const ups_watch_scu &)=delete
	ups_watch_scu (ups_watch_scu &&)=delete
ups_watch_scu &	operator= (ups_watch_scu &&)=delete
void	set_event_received_callback (event_received_callback cb)
	Set callback for received event notifications.
network::Result< ups_result >	subscribe (network::association &assoc, const ups_subscribe_data &data)
	Subscribe to UPS workitem events (N-ACTION Type 3)
network::Result< ups_result >	unsubscribe (network::association &assoc, const ups_unsubscribe_data &data)
	Unsubscribe from UPS workitem events (N-ACTION Type 4)
network::Result< ups_result >	suspend_global (network::association &assoc)
	Suspend global subscription (N-ACTION Type 5)
network::Result< ups_watch_event >	handle_event_report (const network::dimse::dimse_message &event_rq)
	Handle an N-EVENT-REPORT-RQ received from the SCP.
size_t	subscribes_performed () const noexcept
size_t	unsubscribes_performed () const noexcept
size_t	events_received () const noexcept
void	reset_statistics () noexcept

Private Member Functions
network::Result< ups_result >	send_watch_action (network::association &assoc, const std::string &sop_instance_uid, uint16_t action_type_id)
uint16_t	next_message_id () noexcept

Static Private Member Functions
static ups_watch_event	parse_event_dataset (uint16_t event_type_id, const std::string &workitem_uid, const core::dicom_dataset &dataset)

Private Attributes
std::shared_ptr< di::ILogger >	logger_
ups_watch_scu_config	config_
event_received_callback	event_callback_
std::atomic< uint16_t >	message_id_counter_ {1}
std::atomic< size_t >	subscribes_performed_ {0}
std::atomic< size_t >	unsubscribes_performed_ {0}
std::atomic< size_t >	events_received_ {0}

Detailed Description

UPS Watch SCU service for subscribing to events on remote systems.

The UPS Watch SCU (Service Class User) sends N-ACTION requests to remote UPS Watch SCP servers to subscribe/unsubscribe from workitem events, and handles incoming N-EVENT-REPORT notifications.

UPS Watch SCU Message Flow

UPS Watch SCU (This PACS)               Remote UPS Watch SCP
 |                                       |
 |  N-ACTION-RQ (Subscribe, Type 3)      |
 |  WorkitemUID: 1.2.3.4...             |
 |-------------------------------------->|
 |  N-ACTION-RSP (Success)              |
 |<--------------------------------------|
 |                                       |
 |  [Workitem state changes on SCP]      |
 |                                       |
 |  N-EVENT-REPORT-RQ (Type 1)          |
 |  State: COMPLETED                    |
 |<--------------------------------------|
 |  N-EVENT-REPORT-RSP                  |
 |-------------------------------------->|
 |                                       |
 |  N-ACTION-RQ (Unsubscribe, Type 4)   |
 |-------------------------------------->|
 |  N-ACTION-RSP (Success)              |
 |<--------------------------------------|

Definition at line 131 of file ups_watch_scu.h.

Member Typedef Documentation

event_received_callback

using kcenon::pacs::services::ups_watch_scu::event_received_callback

Initial value:

 std::function<void(
        const ups_watch_event& event)>

Callback type for received event notifications.

Invoked when an N-EVENT-REPORT is received from the SCP.

Definition at line 170 of file ups_watch_scu.h.

Constructor & Destructor Documentation

ups_watch_scu() [1/4]

kcenon::pacs::services::ups_watch_scu::ups_watch_scu ( std::shared_ptr< di::ILogger > logger = nullptr )

explicit

Construct UPS Watch SCU with default configuration.

Parameters

logger

Logger instance (nullptr uses null_logger)

Definition at line 22 of file ups_watch_scu.cpp.

    : logger_(logger ? std::move(logger) : di::null_logger()) {}

ups_watch_scu() [2/4]

kcenon::pacs::services::ups_watch_scu::ups_watch_scu ( const ups_watch_scu_config & config, std::shared_ptr< di::ILogger > logger = nullptr )

explicit

Construct UPS Watch SCU with custom configuration.

Parameters

config	Configuration options
logger	Logger instance (nullptr uses null_logger)

Definition at line 25 of file ups_watch_scu.cpp.

    : logger_(logger ? std::move(logger) : di::null_logger()),
      config_(config) {}

~ups_watch_scu()

kcenon::pacs::services::ups_watch_scu::~ups_watch_scu ( )

default

ups_watch_scu() [3/4]

kcenon::pacs::services::ups_watch_scu::ups_watch_scu ( const ups_watch_scu & )

delete

ups_watch_scu() [4/4]

kcenon::pacs::services::ups_watch_scu::ups_watch_scu ( ups_watch_scu && )

delete

Member Function Documentation

events_received()

size_t kcenon::pacs::services::ups_watch_scu::events_received ( ) const

nodiscardnoexcept

Definition at line 184 of file ups_watch_scu.cpp.

                                                     {
    return events_received_.load(std::memory_order_relaxed);
}

References events_received_.

handle_event_report()

network::Result< ups_watch_event > kcenon::pacs::services::ups_watch_scu::handle_event_report ( const network::dimse::dimse_message & event_rq )

nodiscard

Handle an N-EVENT-REPORT-RQ received from the SCP.

Parses the event dataset and invokes the registered callback.

Parameters

event_rq

The N-EVENT-REPORT-RQ message

Returns

The parsed event notification

Definition at line 115 of file ups_watch_scu.cpp.

                                               {
 
    using namespace network::dimse;
 
    // Verify command is N-EVENT-REPORT-RQ
    if (event_rq.command() != command_field::n_event_report_rq) {
        return kcenon::pacs::pacs_error<ups_watch_event>(
            kcenon::pacs::error_codes::ups_unexpected_command,
            "Expected N-EVENT-REPORT-RQ, got: " +
            std::string(to_string(event_rq.command())));
    }
 
    // Get event type ID
    auto event_type = event_rq.event_type_id();
    if (!event_type.has_value()) {
        return kcenon::pacs::pacs_error<ups_watch_event>(
            kcenon::pacs::error_codes::ups_invalid_action_type,
            "Missing Event Type ID in N-EVENT-REPORT");
    }
 
    // Get workitem UID from the affected SOP Instance UID
    std::string workitem_uid{event_rq.affected_sop_instance_uid()};
 
    // Parse dataset if present
    ups_watch_event event;
    if (event_rq.has_dataset()) {
        auto dataset_result = event_rq.dataset();
        if (dataset_result.is_ok()) {
            event = parse_event_dataset(
                event_type.value(), workitem_uid,
                dataset_result.value().get());
        } else {
            event.event_type_id = event_type.value();
            event.workitem_uid = workitem_uid;
            event.timestamp = std::chrono::system_clock::now();
        }
    } else {
        event.event_type_id = event_type.value();
        event.workitem_uid = workitem_uid;
        event.timestamp = std::chrono::system_clock::now();
    }
 
    events_received_.fetch_add(1, std::memory_order_relaxed);
 
    logger_->info("UPS Watch SCU: Received event type " +
                  std::to_string(event.event_type_id) +
                  " for workitem " + event.workitem_uid);
 
    // Invoke callback if registered
    if (event_callback_) {
        event_callback_(event);
    }
 
    return kcenon::pacs::Result<ups_watch_event>::ok(std::move(event));
}

References kcenon::pacs::network::dimse::dimse_message::affected_sop_instance_uid(), kcenon::pacs::network::dimse::dimse_message::command(), kcenon::pacs::network::dimse::dimse_message::dataset(), event_callback_, kcenon::pacs::network::dimse::dimse_message::event_type_id(), kcenon::pacs::services::ups_watch_event::event_type_id, events_received_, kcenon::pacs::network::dimse::dimse_message::has_dataset(), logger_, kcenon::pacs::pacs_error(), parse_event_dataset(), kcenon::pacs::services::to_string(), kcenon::pacs::error_codes::ups_invalid_action_type, kcenon::pacs::error_codes::ups_unexpected_command, and kcenon::pacs::services::ups_watch_event::workitem_uid.

Here is the call graph for this function:

next_message_id()

uint16_t kcenon::pacs::services::ups_watch_scu::next_message_id ( )

nodiscardprivatenoexcept

Definition at line 320 of file ups_watch_scu.cpp.

                                                 {
    uint16_t id = message_id_counter_.fetch_add(1, std::memory_order_relaxed);
    if (id == 0) {
        id = message_id_counter_.fetch_add(1, std::memory_order_relaxed);
    }
    return id;
}

References message_id_counter_.

Referenced by send_watch_action().

Here is the caller graph for this function:

operator=() [1/2]

ups_watch_scu & kcenon::pacs::services::ups_watch_scu::operator= ( const ups_watch_scu & )

delete

operator=() [2/2]

ups_watch_scu & kcenon::pacs::services::ups_watch_scu::operator= ( ups_watch_scu && )

delete

parse_event_dataset()

ups_watch_event kcenon::pacs::services::ups_watch_scu::parse_event_dataset ( uint16_t event_type_id, const std::string & workitem_uid, const core::dicom_dataset & dataset )

staticnodiscardprivate

Definition at line 281 of file ups_watch_scu.cpp.

                                      {
 
    ups_watch_event event;
    event.event_type_id = event_type_id;
    event.workitem_uid = workitem_uid;
    event.event_info = dataset;
    event.timestamp = std::chrono::system_clock::now();
 
    // Extract fields based on event type
    switch (event_type_id) {
        case ups_event_state_report:
            event.procedure_step_state = dataset.get_string(
                ups_tags::procedure_step_state);
            break;
 
        case ups_event_cancel_requested:
            event.cancellation_reason = dataset.get_string(
                ups_tags::reason_for_cancellation);
            break;
 
        case ups_event_progress_report:
            event.progress = dataset.get_string(
                ups_tags::procedure_step_progress);
            break;
 
        default:
            break;
    }
 
    return event;
}

References kcenon::pacs::services::ups_watch_event::event_type_id, kcenon::pacs::core::dicom_dataset::get_string(), kcenon::pacs::services::ups_tags::procedure_step_progress, kcenon::pacs::services::ups_tags::procedure_step_state, kcenon::pacs::services::ups_tags::reason_for_cancellation, kcenon::pacs::services::ups_event_cancel_requested, kcenon::pacs::services::ups_event_progress_report, and kcenon::pacs::services::ups_event_state_report.

Referenced by handle_event_report().

Here is the call graph for this function:

Here is the caller graph for this function:

reset_statistics()

void kcenon::pacs::services::ups_watch_scu::reset_statistics ( )

noexcept

Definition at line 188 of file ups_watch_scu.cpp.

                                              {
    subscribes_performed_.store(0, std::memory_order_relaxed);
    unsubscribes_performed_.store(0, std::memory_order_relaxed);
    events_received_.store(0, std::memory_order_relaxed);
}

References events_received_, subscribes_performed_, and unsubscribes_performed_.

send_watch_action()

network::Result< ups_result > kcenon::pacs::services::ups_watch_scu::send_watch_action ( network::association & assoc, const std::string & sop_instance_uid, uint16_t action_type_id )

nodiscardprivate

Definition at line 198 of file ups_watch_scu.cpp.

                             {
 
    using namespace network::dimse;
 
    auto start_time = std::chrono::steady_clock::now();
 
    // Verify association is established
    if (!assoc.is_established()) {
        return kcenon::pacs::pacs_error<ups_result>(
            kcenon::pacs::error_codes::association_not_established,
            "Association not established");
    }
 
    // Get accepted presentation context for UPS Watch
    auto context_id = assoc.accepted_context_id(ups_watch_sop_class_uid);
    if (!context_id) {
        return kcenon::pacs::pacs_error<ups_result>(
            kcenon::pacs::error_codes::ups_context_not_accepted,
            "No accepted presentation context for UPS Watch SOP Class");
    }
 
    // Build the N-ACTION request
    auto request = make_n_action_rq(
        next_message_id(),
        ups_watch_sop_class_uid,
        sop_instance_uid,
        action_type_id);
 
    // Send the request
    auto send_result = assoc.send_dimse(*context_id, request);
    if (send_result.is_err()) {
        logger_->error("UPS Watch SCU: Failed to send N-ACTION: " +
                       send_result.error().message);
        return send_result.error();
    }
 
    // Receive the response
    auto recv_result = assoc.receive_dimse(config_.timeout);
    if (recv_result.is_err()) {
        logger_->error("UPS Watch SCU: Failed to receive N-ACTION response: " +
                       recv_result.error().message);
        return recv_result.error();
    }
 
    const auto& [recv_context_id, response] = recv_result.value();
 
    // Verify it's an N-ACTION response
    if (response.command() != command_field::n_action_rsp) {
        return kcenon::pacs::pacs_error<ups_result>(
            kcenon::pacs::error_codes::ups_unexpected_command,
            "Expected N-ACTION-RSP but received " +
            std::string(to_string(response.command())));
    }
 
    auto end_time = std::chrono::steady_clock::now();
    auto elapsed = std::chrono::duration_cast<std::chrono::milliseconds>(
        end_time - start_time);
 
    // Build result
    ups_result result;
    result.workitem_uid = sop_instance_uid;
    result.status = static_cast<uint16_t>(response.status());
    result.elapsed = elapsed;
 
    if (response.command_set().contains(tag_error_comment)) {
        result.error_comment = response.command_set().get_string(tag_error_comment);
    }
 
    if (!result.is_success()) {
        logger_->warn("UPS Watch SCU: N-ACTION returned status 0x" +
                      std::to_string(result.status));
    }
 
    return result;
}

References kcenon::pacs::network::association::accepted_context_id(), kcenon::pacs::error_codes::association_not_established, config_, kcenon::pacs::services::ups_result::elapsed, kcenon::pacs::services::ups_result::error_comment, kcenon::pacs::network::association::is_established(), kcenon::pacs::services::ups_result::is_success(), logger_, next_message_id(), kcenon::pacs::pacs_error(), kcenon::pacs::network::association::receive_dimse(), kcenon::pacs::network::association::send_dimse(), kcenon::pacs::services::ups_result::status, kcenon::pacs::services::ups_watch_scu_config::timeout, kcenon::pacs::services::to_string(), kcenon::pacs::error_codes::ups_context_not_accepted, kcenon::pacs::error_codes::ups_unexpected_command, kcenon::pacs::services::ups_watch_sop_class_uid, and kcenon::pacs::services::ups_result::workitem_uid.

Referenced by subscribe(), suspend_global(), and unsubscribe().

Here is the call graph for this function:

Here is the caller graph for this function:

set_event_received_callback()

void kcenon::pacs::services::ups_watch_scu::set_event_received_callback

(

event_received_callback

cb

)

Set callback for received event notifications.

Parameters

cb	The callback function

Definition at line 34 of file ups_watch_scu.cpp.

                                                                          {
    event_callback_ = std::move(cb);
}

References event_callback_.

subscribe()

network::Result< ups_result > kcenon::pacs::services::ups_watch_scu::subscribe ( network::association & assoc, const ups_subscribe_data & data )

nodiscard

Subscribe to UPS workitem events (N-ACTION Type 3)

Sends a subscribe request to the remote UPS Watch SCP. Use empty workitem_uid for global subscription.

Parameters

assoc	The established association to use
data	The subscription parameters

Returns

Result containing ups_result on success, or error

Definition at line 42 of file ups_watch_scu.cpp.

                                    {
 
    // Determine the SOP Instance UID: workitem-specific or global
    std::string sop_instance_uid = data.workitem_uid.empty()
        ? std::string(ups_global_subscription_instance_uid)
        : data.workitem_uid;
 
    logger_->debug("UPS Watch SCU: Subscribe request" +
                   (data.workitem_uid.empty() ? std::string(" (global)") :
                    " for workitem " + data.workitem_uid));
 
    auto result = send_watch_action(
        assoc, sop_instance_uid, ups_watch_action_subscribe);
 
    if (result.is_ok() && result.value().is_success()) {
        subscribes_performed_.fetch_add(1, std::memory_order_relaxed);
        logger_->info("UPS Watch SCU: Subscribe successful" +
                      (data.workitem_uid.empty() ? std::string(" (global)") :
                       " for workitem " + data.workitem_uid));
    }
 
    return result;
}

References logger_, send_watch_action(), subscribes_performed_, kcenon::pacs::services::ups_global_subscription_instance_uid, kcenon::pacs::services::ups_watch_action_subscribe, and kcenon::pacs::services::ups_subscribe_data::workitem_uid.

Here is the call graph for this function:

subscribes_performed()

size_t kcenon::pacs::services::ups_watch_scu::subscribes_performed ( ) const

nodiscardnoexcept

Definition at line 176 of file ups_watch_scu.cpp.

                                                          {
    return subscribes_performed_.load(std::memory_order_relaxed);
}

References subscribes_performed_.

suspend_global()

network::Result< ups_result > kcenon::pacs::services::ups_watch_scu::suspend_global ( network::association & assoc )

nodiscard

Suspend global subscription (N-ACTION Type 5)

Parameters

assoc

The established association to use

Returns

Result containing ups_result on success, or error

Definition at line 93 of file ups_watch_scu.cpp.

                               {
 
    logger_->debug("UPS Watch SCU: Suspend global subscription");
 
    auto result = send_watch_action(
        assoc,
        std::string(ups_global_subscription_instance_uid),
        ups_watch_action_suspend_global);
 
    if (result.is_ok() && result.value().is_success()) {
        unsubscribes_performed_.fetch_add(1, std::memory_order_relaxed);
        logger_->info("UPS Watch SCU: Global subscription suspended");
    }
 
    return result;
}

References logger_, send_watch_action(), unsubscribes_performed_, kcenon::pacs::services::ups_global_subscription_instance_uid, and kcenon::pacs::services::ups_watch_action_suspend_global.

Here is the call graph for this function:

unsubscribe()

network::Result< ups_result > kcenon::pacs::services::ups_watch_scu::unsubscribe ( network::association & assoc, const ups_unsubscribe_data & data )

nodiscard

Unsubscribe from UPS workitem events (N-ACTION Type 4)

Parameters

assoc	The established association to use
data	The unsubscription parameters

Returns

Result containing ups_result on success, or error

Definition at line 68 of file ups_watch_scu.cpp.

                                      {
 
    std::string sop_instance_uid = data.workitem_uid.empty()
        ? std::string(ups_global_subscription_instance_uid)
        : data.workitem_uid;
 
    logger_->debug("UPS Watch SCU: Unsubscribe request" +
                   (data.workitem_uid.empty() ? std::string(" (global)") :
                    " for workitem " + data.workitem_uid));
 
    auto result = send_watch_action(
        assoc, sop_instance_uid, ups_watch_action_unsubscribe);
 
    if (result.is_ok() && result.value().is_success()) {
        unsubscribes_performed_.fetch_add(1, std::memory_order_relaxed);
        logger_->info("UPS Watch SCU: Unsubscribe successful" +
                      (data.workitem_uid.empty() ? std::string(" (global)") :
                       " for workitem " + data.workitem_uid));
    }
 
    return result;
}

References logger_, send_watch_action(), unsubscribes_performed_, kcenon::pacs::services::ups_global_subscription_instance_uid, kcenon::pacs::services::ups_watch_action_unsubscribe, and kcenon::pacs::services::ups_unsubscribe_data::workitem_uid.

Here is the call graph for this function:

unsubscribes_performed()

size_t kcenon::pacs::services::ups_watch_scu::unsubscribes_performed ( ) const

nodiscardnoexcept

Definition at line 180 of file ups_watch_scu.cpp.

                                                            {
    return unsubscribes_performed_.load(std::memory_order_relaxed);
}

References unsubscribes_performed_.

Member Data Documentation

config_

ups_watch_scu_config kcenon::pacs::services::ups_watch_scu::config_

private

Definition at line 264 of file ups_watch_scu.h.

Referenced by send_watch_action().

event_callback_

event_received_callback kcenon::pacs::services::ups_watch_scu::event_callback_

private

Definition at line 265 of file ups_watch_scu.h.

Referenced by handle_event_report(), and set_event_received_callback().

events_received_

std::atomic<size_t> kcenon::pacs::services::ups_watch_scu::events_received_ {0}

private

Definition at line 269 of file ups_watch_scu.h.

{0};

Referenced by events_received(), handle_event_report(), and reset_statistics().

logger_

std::shared_ptr<di::ILogger> kcenon::pacs::services::ups_watch_scu::logger_

private

Definition at line 263 of file ups_watch_scu.h.

Referenced by handle_event_report(), send_watch_action(), subscribe(), suspend_global(), and unsubscribe().

message_id_counter_

std::atomic<uint16_t> kcenon::pacs::services::ups_watch_scu::message_id_counter_ {1}

private

Definition at line 266 of file ups_watch_scu.h.

{1};

Referenced by next_message_id().

subscribes_performed_

std::atomic<size_t> kcenon::pacs::services::ups_watch_scu::subscribes_performed_ {0}

private

Definition at line 267 of file ups_watch_scu.h.

{0};

Referenced by reset_statistics(), subscribe(), and subscribes_performed().

unsubscribes_performed_

std::atomic<size_t> kcenon::pacs::services::ups_watch_scu::unsubscribes_performed_ {0}

private

Definition at line 268 of file ups_watch_scu.h.

{0};

Referenced by reset_statistics(), suspend_global(), unsubscribe(), and unsubscribes_performed().

---

The documentation for this class was generated from the following files:

• include/kcenon/pacs/services/ups/ups_watch_scu.h
• src/services/ups/ups_watch_scu.cpp