Wrapper class for DCMTK command-line tools. More...

#include <dcmtk_tool.h>

Collaboration diagram for kcenon::pacs::integration_test::dcmtk_tool:

Static Public Member Functions
static bool	is_available ()
	Check if DCMTK is available on the system.

static std::optional< std::string >	version ()
	Get DCMTK version string.

static dcmtk_result	echoscu (const std::string &host, uint16_t port, const std::string &called_ae, const std::string &calling_ae="ECHOSCU", std::chrono::seconds timeout=std::chrono::seconds{30})
	Run C-ECHO (echoscu) client.

static dcmtk_result	storescu (const std::string &host, uint16_t port, const std::string &called_ae, const std::vector< std::filesystem::path > &files, const std::string &calling_ae="STORESCU", std::chrono::seconds timeout=std::chrono::seconds{60})
	Run C-STORE (storescu) client.

static dcmtk_result	findscu (const std::string &host, uint16_t port, const std::string &called_ae, const std::string &query_level, const std::vector< std::pair< std::string, std::string > > &keys, const std::string &calling_ae="FINDSCU", std::chrono::seconds timeout=std::chrono::seconds{30})
	Run C-FIND (findscu) client.

static dcmtk_result	movescu (const std::string &host, uint16_t port, const std::string &called_ae, const std::string &dest_ae, const std::string &query_level, const std::vector< std::pair< std::string, std::string > > &keys, const std::string &calling_ae="MOVESCU", std::chrono::seconds timeout=std::chrono::seconds{120})
	Run C-MOVE (movescu) client.

static std::chrono::seconds	default_scp_startup_timeout ()
	Default startup timeout for DCMTK SCP servers.

static background_process_guard	storescp (uint16_t port, const std::string &ae_title, const std::filesystem::path &output_dir, std::chrono::seconds startup_timeout=default_scp_startup_timeout())
	Start C-STORE SCP (storescp) server.

static background_process_guard	echoscp (uint16_t port, const std::string &ae_title, std::chrono::seconds startup_timeout=default_scp_startup_timeout())
	Start C-ECHO SCP (echoscp) server.

Static Private Member Functions
static std::string	find_tool_path (const std::string &tool_name)
	Find the full path to a DCMTK tool.

static dcmtk_result	run_tool (const std::string &tool_name, const std::vector< std::string > &args, std::chrono::seconds timeout)
	Run a DCMTK tool and capture output.

static process_launcher::pid_type	start_tool_background (const std::string &tool_name, const std::vector< std::string > &args)
	Start a DCMTK tool in background.

Detailed Description

Wrapper class for DCMTK command-line tools.

Provides static methods to invoke DCMTK CLI tools with standardized timeout handling, error checking, and output parsing.

Definition at line 60 of file dcmtk_tool.h.

Member Function Documentation

◆ default_scp_startup_timeout()

static std::chrono::seconds kcenon::pacs::integration_test::dcmtk_tool::default_scp_startup_timeout ( )

inlinestatic

Default startup timeout for DCMTK SCP servers.

Uses adaptive timeout based on environment:

Normal: 15s for quick responsiveness
CI: 60s to account for slower VM/container environments

Returns: Appropriate startup timeout for current environment

Definition at line 259 of file dcmtk_tool.h.

                                                          {
        return is_ci_environment()
            ? std::chrono::seconds{60}
            : std::chrono::seconds{15};
    }

References kcenon::pacs::integration_test::is_ci_environment().

Here is the call graph for this function:

◆ echoscp()

static background_process_guard kcenon::pacs::integration_test::dcmtk_tool::echoscp	(	uint16_t	port,
		const std::string &	ae_title,
		std::chrono::seconds	startup_timeout = default_scp_startup_timeout() )

inlinestatic

Start C-ECHO SCP (echoscp) server.

Parameters

port	Port to listen on
ae_title	AE title for server
startup_timeout	Maximum time to wait for server to start (default: adaptive based on environment)

Returns: Background process guard for the server

Definition at line 311 of file dcmtk_tool.h.

                                                                          {
 
        std::vector<std::string> args = {
            "-aet", ae_title,
            std::to_string(port)
        };
 
        auto pid = start_tool_background("echoscp", args);
        background_process_guard guard(pid);
 
        if (pid > 0) {
            if (!process_launcher::wait_for_port(port, startup_timeout)) {
                guard.stop();
                return background_process_guard(process_launcher::invalid_pid);
            }
        }
 
        return guard;
    }

References kcenon::pacs::integration_test::process_launcher::invalid_pid, start_tool_background(), kcenon::pacs::integration_test::background_process_guard::stop(), and kcenon::pacs::integration_test::process_launcher::wait_for_port().

Referenced by TEST_CASE(), TEST_CASE(), and TEST_CASE().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ echoscu()

static dcmtk_result kcenon::pacs::integration_test::dcmtk_tool::echoscu	(	const std::string &	host,
		uint16_t	port,
		const std::string &	called_ae,
		const std::string &	calling_ae = "ECHOSCU",
		std::chrono::seconds	timeout = std::chrono::seconds{30} )

inlinestatic

Run C-ECHO (echoscu) client.

Parameters

host	Server host address
port	Server port
called_ae	Called AE title
calling_ae	Calling AE title (default: ECHOSCU)
timeout	Operation timeout

Returns: DCMTK execution result

Definition at line 111 of file dcmtk_tool.h.

                                                   {30}) {
 
        std::vector<std::string> args = {
            "-aec", called_ae,
            "-aet", calling_ae,
            host,
            std::to_string(port)
        };
 
        return run_tool("echoscu", args, timeout);
    }

Referenced by TEST_CASE(), TEST_CASE(), TEST_CASE(), and TEST_CASE().

Here is the caller graph for this function:

◆ find_tool_path()

static std::string kcenon::pacs::integration_test::dcmtk_tool::find_tool_path ( const std::string & tool_name )

inlinestaticprivate

Find the full path to a DCMTK tool.

Parameters

tool_name Name of the tool (e.g., "echoscu")

Returns: Full path to the tool, or just the tool name if not found

Definition at line 344 of file dcmtk_tool.h.

                                                                {
        // First, check common installation paths
        std::vector<std::string> search_paths = {
            "/usr/local/bin",
            "/usr/bin",
            "/opt/homebrew/bin",  // macOS Homebrew (Apple Silicon)
            "/opt/local/bin"      // MacPorts
        };
 
        for (const auto& path : search_paths) {
            std::filesystem::path full_path = std::filesystem::path(path) / tool_name;
            if (std::filesystem::exists(full_path)) {
                return full_path.string();
            }
        }
 
        // Fall back to relying on PATH
        return tool_name;
    }

Referenced by run_tool(), and start_tool_background().

Here is the caller graph for this function:

◆ findscu()

static dcmtk_result kcenon::pacs::integration_test::dcmtk_tool::findscu	(	const std::string &	host,
		uint16_t	port,
		const std::string &	called_ae,
		const std::string &	query_level,
		const std::vector< std::pair< std::string, std::string > > &	keys,
		const std::string &	calling_ae = "FINDSCU",
		std::chrono::seconds	timeout = std::chrono::seconds{30} )

inlinestatic

Run C-FIND (findscu) client.

Parameters

host	Server host address
port	Server port
called_ae	Called AE title
query_level	Query/Retrieve level (PATIENT, STUDY, SERIES, IMAGE)
keys	Query keys as tag-value pairs (e.g., {"PatientID", "TEST001"})
calling_ae	Calling AE title (default: FINDSCU)
timeout	Operation timeout

Returns: DCMTK execution result

Definition at line 171 of file dcmtk_tool.h.

                                                   {30}) {
 
        std::vector<std::string> args = {
            "-aec", called_ae,
            "-aet", calling_ae,
            "-W"  // Use worklist model for MWL or study root for others
        };
 
        // Set query level
        if (query_level == "PATIENT" || query_level == "STUDY" ||
            query_level == "SERIES" || query_level == "IMAGE") {
            args.push_back("-k");
            args.push_back("QueryRetrieveLevel=" + query_level);
        }
 
        // Add query keys
        for (const auto& [key, value] : keys) {
            args.push_back("-k");
            args.push_back(key + "=" + value);
        }
 
        args.push_back(host);
        args.push_back(std::to_string(port));
 
        return run_tool("findscu", args, timeout);
    }

Referenced by TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), and TEST_CASE().

Here is the caller graph for this function:

◆ is_available()

static bool kcenon::pacs::integration_test::dcmtk_tool::is_available ( )

inlinestatic

Check if DCMTK is available on the system.

Returns: true if echoscu command is found in PATH

Definition at line 70 of file dcmtk_tool.h.

                               {
        auto result = run_tool("echoscu", {"--version"}, std::chrono::seconds{5});
        return result.exit_code == 0;
    }

References kcenon::pacs::integration_test::dcmtk_result::exit_code, and run_tool().

Referenced by TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), and TEST_CASE().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ movescu()

static dcmtk_result kcenon::pacs::integration_test::dcmtk_tool::movescu	(	const std::string &	host,
		uint16_t	port,
		const std::string &	called_ae,
		const std::string &	dest_ae,
		const std::string &	query_level,
		const std::vector< std::pair< std::string, std::string > > &	keys,
		const std::string &	calling_ae = "MOVESCU",
		std::chrono::seconds	timeout = std::chrono::seconds{120} )

inlinestatic

Run C-MOVE (movescu) client.

Parameters

host	Server host address
port	Server port
called_ae	Called AE title
dest_ae	Destination AE title
query_level	Query/Retrieve level
keys	Query keys as tag-value pairs
calling_ae	Calling AE title (default: MOVESCU)
timeout	Operation timeout

Returns: DCMTK execution result

Definition at line 217 of file dcmtk_tool.h.

                                                   {120}) {
 
        std::vector<std::string> args = {
            "-aec", called_ae,
            "-aet", calling_ae,
            "-aem", dest_ae,  // Move destination AE title
            "-k", "QueryRetrieveLevel=" + query_level
        };
 
        // Add query keys
        for (const auto& [key, value] : keys) {
            args.push_back("-k");
            args.push_back(key + "=" + value);
        }
 
        args.push_back(host);
        args.push_back(std::to_string(port));
 
        return run_tool("movescu", args, timeout);
    }

Referenced by TEST_CASE(), TEST_CASE(), TEST_CASE(), and TEST_CASE().

Here is the caller graph for this function:

◆ run_tool()

static dcmtk_result kcenon::pacs::integration_test::dcmtk_tool::run_tool	(	const std::string &	tool_name,
		const std::vector< std::string > &	args,
		std::chrono::seconds	timeout )

inlinestaticprivate

Run a DCMTK tool and capture output.

Parameters

tool_name	Name of the tool
args	Command-line arguments
timeout	Maximum execution time

Returns: DCMTK execution result

Definition at line 371 of file dcmtk_tool.h.

                                  {
 
        dcmtk_result result;
 
        std::string tool_path = find_tool_path(tool_name);
        auto process_res = process_launcher::run(tool_path, args, timeout);
 
        result.exit_code = process_res.exit_code;
        result.stdout_output = std::move(process_res.stdout_output);
        result.stderr_output = std::move(process_res.stderr_output);
        result.duration = process_res.duration;
        result.timed_out = process_res.timed_out;
 
        return result;
    }

References kcenon::pacs::integration_test::dcmtk_result::duration, kcenon::pacs::integration_test::dcmtk_result::exit_code, find_tool_path(), kcenon::pacs::integration_test::process_launcher::run(), kcenon::pacs::integration_test::dcmtk_result::stderr_output, kcenon::pacs::integration_test::dcmtk_result::stdout_output, and kcenon::pacs::integration_test::dcmtk_result::timed_out.

Referenced by is_available(), and version().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ start_tool_background()

static process_launcher::pid_type kcenon::pacs::integration_test::dcmtk_tool::start_tool_background	(	const std::string &	tool_name,
		const std::vector< std::string > &	args )

inlinestaticprivate

Start a DCMTK tool in background.

Parameters

tool_name	Name of the tool
args	Command-line arguments

Returns: Process ID

Definition at line 396 of file dcmtk_tool.h.

                                          {
 
        std::string tool_path = find_tool_path(tool_name);
        return process_launcher::start_background(tool_path, args);
    }

References find_tool_path(), and kcenon::pacs::integration_test::process_launcher::start_background().

Referenced by echoscp(), and storescp().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ storescp()

static background_process_guard kcenon::pacs::integration_test::dcmtk_tool::storescp	(	uint16_t	port,
		const std::string &	ae_title,
		const std::filesystem::path &	output_dir,
		std::chrono::seconds	startup_timeout = default_scp_startup_timeout() )

inlinestatic

Start C-STORE SCP (storescp) server.

Parameters

port	Port to listen on
ae_title	AE title for server
output_dir	Directory to store received files
startup_timeout	Maximum time to wait for server to start (default: adaptive based on environment)

Returns: Background process guard for the server

Definition at line 274 of file dcmtk_tool.h.

                                                                          {
 
        // Ensure output directory exists
        std::filesystem::create_directories(output_dir);
 
        std::vector<std::string> args = {
            "-aet", ae_title,
            "-od", output_dir.string(),
            std::to_string(port)
        };
 
        auto pid = start_tool_background("storescp", args);
        background_process_guard guard(pid);
 
        // Wait for server to start accepting connections
        if (pid > 0) {
            if (!process_launcher::wait_for_port(port, startup_timeout)) {
                guard.stop();
                return background_process_guard(process_launcher::invalid_pid);
            }
        }
 
        return guard;
    }

References kcenon::pacs::integration_test::process_launcher::invalid_pid, start_tool_background(), kcenon::pacs::integration_test::background_process_guard::stop(), and kcenon::pacs::integration_test::process_launcher::wait_for_port().

Referenced by TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), and TEST_CASE().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ storescu()

static dcmtk_result kcenon::pacs::integration_test::dcmtk_tool::storescu	(	const std::string &	host,
		uint16_t	port,
		const std::string &	called_ae,
		const std::vector< std::filesystem::path > &	files,
		const std::string &	calling_ae = "STORESCU",
		std::chrono::seconds	timeout = std::chrono::seconds{60} )

inlinestatic

Run C-STORE (storescu) client.

Parameters

host	Server host address
port	Server port
called_ae	Called AE title
files	DICOM files to send
calling_ae	Calling AE title (default: STORESCU)
timeout	Operation timeout

Returns: DCMTK execution result

Definition at line 138 of file dcmtk_tool.h.

                                                   {60}) {
 
        std::vector<std::string> args = {
            "-aec", called_ae,
            "-aet", calling_ae,
            host,
            std::to_string(port)
        };
 
        for (const auto& file : files) {
            args.push_back(file.string());
        }
 
        return run_tool("storescu", args, timeout);
    }

Referenced by TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), and TEST_CASE().

Here is the caller graph for this function:

◆ version()

static std::optional< std::string > kcenon::pacs::integration_test::dcmtk_tool::version ( )

inlinestatic

Get DCMTK version string.

Returns: Version string if available, nullopt otherwise

Definition at line 79 of file dcmtk_tool.h.

                                            {
        auto result = run_tool("echoscu", {"--version"}, std::chrono::seconds{5});
        if (result.exit_code != 0) {
            return std::nullopt;
        }
 
        // Parse version from output (first line usually contains version)
        auto& output = result.stdout_output.empty()
                           ? result.stderr_output
                           : result.stdout_output;
 
        std::istringstream stream(output);
        std::string first_line;
        if (std::getline(stream, first_line) && !first_line.empty()) {
            return first_line;
        }
        return std::nullopt;
    }

References run_tool(), and kcenon::pacs::integration_test::dcmtk_result::stdout_output.

Referenced by TEST_CASE().

Here is the call graph for this function:

Here is the caller graph for this function:

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

examples/integration_tests/dcmtk_tool.h

Static Public Member Functions

Static Private Member Functions

Detailed Description

Member Function Documentation

◆ default_scp_startup_timeout()

◆ echoscp()

◆ echoscu()

◆ find_tool_path()

◆ findscu()

◆ is_available()

◆ movescu()

◆ run_tool()

◆ start_tool_background()

◆ storescp()

◆ storescu()

◆ version()