#include <ImFusion/Dicom/DicomPacsCommunication.h>

Class facilitating the communication with DICOM PACS servers. More...

Inheritance diagram for DicomPacsCommunication:

Detailed Description

Class facilitating the communication with DICOM PACS servers.

DicomPacsCommunication automates issuing C-FIND and C-MOVE commands as well as receiving C-STORE commands. Receiving data from PACS servers is easily customized by attaching a callback function to the request.

This class also provides lean wrappers around asynchronous (non-blocking) requests. DicomPacsCommunication protects all C-MOVE requests to the PACS server by a mutex and thereby ensures that only a single thread is issuing C-MOVE requests at a time. However, outgoing async requests (i.e. C-ECHO, C-FIND and C-STORE) will be sent concurrently since every modern PACS instance should support this. If your particular instance does not, please keep to the synchronous methods. The scheduling of asynchronous requests is based on std::async and thus relies on the OS thread scheduling.

DicomPacsCommunication can be considered as thread-safe in the following way:

Concurrently issuing (synchronous and asynchronous) requests from multiple threads is safe.
Concurrently issuing (synchronous and asynchronous) C-MOVE requests from multiple instances of this class is safe but limited to one request at a time.
Aborting requests/waiting for requests is thread-safe.

Note: The mutex for protecting C-MOVE requests is a static mutex (i.e. it acts globally across all instances of DicomPacsCommunication at the same time).

Examples: PacsExample.cpp.

Classes
struct	AsyncRequestInfo
	Structure wrapping the return value of an asynchronous PACS request. More...

Public Types
enum	RetrieveInformationModel { PatientRootRetrieveInformationModel , StudyRootRetrieveInformationModel , ModalityWorklistInformationModel }
	Enumeration of Standard Query/Retrieve Information Models. More...

Public Types inherited from ErrorRecorder
using	ErrorCallback = std::function<void(const Error&)>
	Alias for a function to call for each error recorded.

Public Member Functions
	DicomPacsCommunication (DicomPacsConfiguration configuration)
	Creates a new PCAS communication instance connecting to the server defined in the given configuration.

const DicomPacsConfiguration &	connectionConfiguration () const
	Returns the connection configuration to use when communicating with the PACS server.

bool	sendEchoRequest ()
	Connects to the configured PACS and sends a C-ECHO message in order to test the association.

void	sendFindRequest (RetrieveInformationModel queryModel, DcmDataset &request, std::function< void(std::unique_ptr< DcmDataset >)> responseItemCallback, std::atomic< bool > *abortFlag=nullptr)
	Synchronously sends a C-FIND request to the currently connected PACS server.

AsyncRequestInfo	sendFindRequestAsync (RetrieveInformationModel queryModel, DcmDataset &request, std::function< void(std::unique_ptr< DcmDataset >)> responseItemCallback, std::function< void(bool)> finishedCallback)
	Asynchronously sends a C-FIND request to the currently connected PACS server.

void	sendMoveRequest (RetrieveInformationModel queryModel, DcmDataset &request, std::function< void(std::unique_ptr< DcmDataset >)> responseItemCallback)
	Synchronously sends a C-MOVE request to the currently connected PACS server.

AsyncRequestInfo	sendMoveRequestAsync (RetrieveInformationModel queryModel, DcmDataset &request, std::function< void(std::unique_ptr< DcmDataset >)> responseItemCallback, std::function< void(bool)> finishedCallback)
	Asynchronously sends a C-MOVE request to the currently connected PACS server.

bool	sendStoreRequest (const std::vector< DcmDataset * > &datasets, int transferSyntax, std::atomic< bool > *abortFlag=nullptr)
	Synchronously sends a C-STORE request to the currently connected PACS server.

void	abortAsyncRequests ()
	Aborts all async request currently in flight.

void	waitForAsyncRequests ()
	Blocks until all async requests that are currently in flight have been completed.

Public Member Functions inherited from ErrorRecorder
virtual void *	registerErrorHandler (ErrorCallback handler)
	Registers a new handler callback function.

virtual void	unregisterErrorHandler (void *handler)
	Removes a previously registered handler again.

void *	forwardErrors (const ErrorRecorder *otherRecorder)
	Convenient function to forward all errors registered to this recorder to another recorder.

virtual void	registerError (const Error &error) const
	Sends the given error to all error handler callbacks.

void	registerError (Error::Code code, Error::Type type, const std::string &details, TagProxy tag=TagProxy()) const

Member Enumeration Documentation

◆ RetrieveInformationModel

enum RetrieveInformationModel

Enumeration of Standard Query/Retrieve Information Models.

See also: http://dicom.nema.org/dicom/2013/output/chtml/part04/sect_C.3.html

Member Function Documentation

◆ sendFindRequest()

void sendFindRequest	(	RetrieveInformationModel	queryModel,
		DcmDataset &	request,
		std::function< void(std::unique_ptr< DcmDataset >)>	responseItemCallback,
		std::atomic< bool > *	abortFlag = nullptr )

Synchronously sends a C-FIND request to the currently connected PACS server.

Parameters

queryModel	Query/Retrieve Information Model to use for the request.
request	Dicom object representing the request to send.
responseItemCallback	Callback method to call for every item of the response.
abortFlag	Flag that will abort the request at next possibility. The pointer must stay valid until the request finishes.

Note: Based on the setting in DicomPluginSettings the DcmDataset in the response will be anonymized.

See also: http://dicom.nema.org/dicom/2013/output/chtml/part07/sect_9.3.html#sect_9.3.2

Examples: PacsExample.cpp.

◆ sendFindRequestAsync()

AsyncRequestInfo sendFindRequestAsync	(	RetrieveInformationModel	queryModel,
		DcmDataset &	request,
		std::function< void(std::unique_ptr< DcmDataset >)>	responseItemCallback,
		std::function< void(bool)>	finishedCallback )

Asynchronously sends a C-FIND request to the currently connected PACS server.

Parameters

queryModel	Query/Retrieve Information Model to use for the request.
request	Dicom object representing the request to send.
responseItemCallback	Callback method to call for every item of the response.
finishedCallback	Callback method to call when the request has been completed, the bool parameter indicates the state of the abort flag.

Returns: AsyncRequestInfo structure allowing to abort and/or wait for the asynchronous execution.

See also: http://dicom.nema.org/dicom/2013/output/chtml/part07/sect_9.3.html#sect_9.3.2

Note: Based on the setting in DicomPluginSettings the DcmDataset in the response will be anonymized.

◆ sendMoveRequest()

void sendMoveRequest	(	RetrieveInformationModel	queryModel,
		DcmDataset &	request,
		std::function< void(std::unique_ptr< DcmDataset >)>	responseItemCallback )

Synchronously sends a C-MOVE request to the currently connected PACS server.

Parameters

queryModel	Query/Retrieve Information Model to use for the request.
request	Dicom object representing the request to send.
responseItemCallback	Callback method to call for every item of the response.

See also: http://dicom.nema.org/dicom/2013/output/chtml/part07/sect_9.3.html#sect_9.3.4

Note: Based on the setting in DicomPluginSettings the DcmDataset in the response will be anonymized.; Internally, DicomPacsCommunication protects C-MOVE requests by a mutex to ensure that only a single request is handled at a time.

Examples: PacsExample.cpp.

◆ sendMoveRequestAsync()

AsyncRequestInfo sendMoveRequestAsync	(	RetrieveInformationModel	queryModel,
		DcmDataset &	request,
		std::function< void(std::unique_ptr< DcmDataset >)>	responseItemCallback,
		std::function< void(bool)>	finishedCallback )

Asynchronously sends a C-MOVE request to the currently connected PACS server.

Parameters

queryModel	Query/Retrieve Information Model to use for the request.
request	Dicom object representing the request to send.
responseItemCallback	Callback method to call for every item of the response.
finishedCallback	Callback method to call when the request has been completed, the bool parameter indicates the state of the abort flag.

Returns: AsyncRequestInfo structure allowing to abort and/or wait for the asynchronous execution.

Note: Based on the setting in DicomPluginSettings the DcmDataset in the response will be anonymized.; Internally, DicomPacsCommunication protects C-MOVE requests by a mutex to ensure that only a single request is handled at a time. Thus, even if you asynchronously issue multiple move requests they will be handled in a serialized fashion.

See also: http://dicom.nema.org/dicom/2013/output/chtml/part07/sect_9.3.html#sect_9.3.4

◆ sendStoreRequest()

bool sendStoreRequest	(	const std::vector< DcmDataset * > &	datasets,
		int	transferSyntax,
		std::atomic< bool > *	abortFlag = nullptr )

Synchronously sends a C-STORE request to the currently connected PACS server.

All datasets are generally send as a single association except if the datasets use over 128 different SOP class UIDs. If the request is aborted before it finishes, all datasets already sent to the PACS are not deleted!

Parameters

datasets	List of DcmDatasets to send to the server.
transferSyntax	Transfer syntax to choose for sending the data set to the PACS instance. Use values from DCMTK's E_TransferSyntax enum in dcxfer.h.
abortFlag	Flag that will abort the request at next possibility. The pointer must stay valid until the request finishes.

Returns: True if the C-STORE request was successful.

Note: The current implementation of this functionality is only very rudimentary and does support any progress monitoring. Once you launch this method it will block until the request has been completed (in case of a network timeout this may be quite some time!).

See also: http://dicom.nema.org/dicom/2013/output/chtml/part07/sect_9.3.html#sect_9.3.1

◆ abortAsyncRequests()

void abortAsyncRequests ( )

Aborts all async request currently in flight.

This includes scheduled move requests that have not yet been started due to another move request being active.

◆ waitForAsyncRequests()

void waitForAsyncRequests ( )

Blocks until all async requests that are currently in flight have been completed.

This includes scheduled move requests that have not yet been started due to another move request being active.

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

ImFusion/Dicom/DicomPacsCommunication.h

Detailed Description

Classes

Public Types

Public Member Functions

Member Enumeration Documentation

◆ RetrieveInformationModel

Member Function Documentation

◆ sendFindRequest()

◆ sendFindRequestAsync()

◆ sendMoveRequest()

◆ sendMoveRequestAsync()

◆ sendStoreRequest()

◆ abortAsyncRequests()

◆ waitForAsyncRequests()