Base class for implementing DICOM Service Class User functionality. More...

Inheritance diagram for DcmSCU:

Classes
struct	DcmSCUPresContext
	Defines presentation context, consisting of one abstract syntax name and a list of transfer syntaxes for this abstract syntax. More...

Public Member Functions
	DcmSCU ()
	Constructor, just initializes internal class members.

virtual	~DcmSCU ()
	Virtual destructor.

OFCondition	addPresentationContext (const OFString &abstractSyntax, const OFList< OFString > &xferSyntaxes, const T_ASC_SC_ROLE role=ASC_SC_ROLE_DEFAULT)
	Add presentation context to be used for association negotiation. More...

virtual OFCondition	initNetwork ()
	Initialize network, i.e. prepare for association negotiation. More...

virtual OFCondition	negotiateAssociation ()
	Negotiate association by using presentation contexts and parameters as defined by earlier function calls. More...

T_ASC_PresentationContextID	findPresentationContextID (const OFString &abstractSyntax, const OFString &transferSyntax)
	After negotiation association, this call returns the first usable presentation context given the desired abstract syntax and transfer syntax. More...

T_ASC_PresentationContextID	findAnyPresentationContextID (const OFString &abstractSyntax, const OFString &transferSyntax)
	After a successful association negotiation, this function is called to return the presentation context ID that best matches the desired abstract syntax and transfer syntax (TS). More...

virtual OFCondition	sendECHORequest (const T_ASC_PresentationContextID presID)
	This function sends a C-ECHO command via network to another DICOM application. More...

virtual OFCondition	sendSTORERequest (const T_ASC_PresentationContextID presID, const OFFilename &dicomFile, DcmDataset *dataset, Uint16 &rspStatusCode, const OFString &moveOriginatorAETitle="", const Uint16 moveOriginatorMsgID=0)
	This function sends a C-STORE request on the currently opened association and receives the corresponding response then. More...

virtual OFCondition	sendMOVERequest (const T_ASC_PresentationContextID presID, const OFString &moveDestinationAETitle, DcmDataset dataset, OFList< RetrieveResponse > *responses)
	Sends a C-MOVE Request on given presentation context and receives list of responses. More...

virtual OFCondition	handleMOVEResponse (const T_ASC_PresentationContextID presID, RetrieveResponse *response, OFBool &waitForNextResponse)
	This is the standard handler for C-MOVE message responses: It just adds up all responses it receives and prints a DEBUG message. More...

virtual OFCondition	sendCGETRequest (const T_ASC_PresentationContextID presID, DcmDataset dataset, OFList< RetrieveResponse > *responses)
	Sends a C-GET Request on given presentation context and receives list of responses. More...

virtual OFCondition	handleCGETSession (const T_ASC_PresentationContextID presID, DcmDataset dataset, OFList< RetrieveResponse > *responses)
	Does the logic for switching between C-GET Response and C-STORE Requests. More...

virtual OFCondition	handleCGETResponse (const T_ASC_PresentationContextID presID, RetrieveResponse *response, OFBool &continueCGETSession)
	Function handling a single C-GET Response. More...

virtual OFCondition	handleSTORERequest (const T_ASC_PresentationContextID presID, DcmDataset *incomingObject, OFBool &continueCGETSession, Uint16 &cStoreReturnStatus)
	Function handling a single C-STORE Request. More...

virtual OFCondition	handleSTORERequestFile (T_ASC_PresentationContextID presID, const OFString &filename, T_DIMSE_C_StoreRQ request)
	Function handling a single C-STORE Request. More...

virtual OFCondition	sendFINDRequest (const T_ASC_PresentationContextID presID, DcmDataset queryKeys, OFList< QRResponse > *responses)
	Sends a C-FIND Request on given presentation context and receives list of responses. More...

virtual OFCondition	handleFINDResponse (const T_ASC_PresentationContextID presID, QRResponse *response, OFBool &waitForNextResponse)
	This is the standard handler for C-FIND message responses: It just adds up all responses it receives and prints a DEBUG message. More...

virtual OFCondition	sendCANCELRequest (const T_ASC_PresentationContextID presID)
	Send C-CANCEL and, therefore, ends the C-FIND -GET or -MOVE session, i.e. no further responses will be handled. More...

virtual OFCondition	sendACTIONRequest (const T_ASC_PresentationContextID presID, const OFString &sopInstanceUID, const Uint16 actionTypeID, DcmDataset *reqDataset, Uint16 &rspStatusCode)
	This function sends a N-ACTION request on the currently opened association and receives the corresponding response then. More...

virtual OFCondition	sendEVENTREPORTRequest (const T_ASC_PresentationContextID presID, const OFString &sopInstanceUID, const Uint16 eventTypeID, DcmDataset *reqDataset, Uint16 &rspStatusCode)
	This function sends N-EVENT-REPORT request and receives the corresponding response. More...

virtual OFCondition	handleEVENTREPORTRequest (DcmDataset *&reqDataset, Uint16 &eventTypeID, const int timeout=0)
	Receives N-EVENT-REPORT request on the currently opened association and sends a corresponding response. More...

virtual void	closeAssociation (const DcmCloseAssociationType closeType)
	Closes the association created by this SCU. More...

virtual OFCondition	releaseAssociation ()
	Releases the current association by sending an A-RELEASE request to the SCP. More...

virtual OFCondition	abortAssociation ()
	Aborts the current association by sending an A-ABORT request to the SCP. More...

void	setMaxReceivePDULength (const Uint32 maxRecPDU)
	Set maximum PDU length (to be received by SCU) More...

void	setDIMSEBlockingMode (const T_DIMSE_BlockingMode blockingMode)
	Set whether to send in DIMSE blocking or non-blocking mode. More...

void	setAETitle (const OFString &myAETtitle)
	Set SCU's AE title to be used in association negotiation. More...

void	setPeerHostName (const OFString &peerHostName)
	Set SCP's host (hostname or IP address) to talk to in association negotiation. More...

void	setPeerAETitle (const OFString &peerAETitle)
	Set SCP's AE title to talk to in association negotiation. More...

void	setPeerPort (const Uint16 peerPort)
	Set SCP's port number to connect to for association negotiation. More...

void	setDIMSETimeout (const Uint32 dimseTimeout)
	Set timeout for receiving DIMSE messages. More...

void	setACSETimeout (const Uint32 acseTimeout)
	Set timeout for receiving ACSE messages. More...

void	setConnectionTimeout (const Sint32 connectionTimeout)
	Set global timeout for connecting to the SCP. More...

void	setAssocConfigFileAndProfile (const OFString &filename, const OFString &profile)
	Set an association configuration file and profile to be used. More...

void	setStorageDir (const OFString &storeDir)
	Set the directory that should be used by the standard C-GET handler to store objects that come in with the corresponding C-STORE requests. More...

void	setStorageMode (const DcmStorageMode storageMode)
	Set the storage mode to be used. More...

void	setVerbosePCMode (const OFBool mode)
	Set whether to show presentation contexts in verbose or debug mode. More...

void	setDatasetConversionMode (const OFBool mode)
	Set the mode that specifies whether the transfer syntax of the dataset can be changed for network transmission. More...

void	setProgressNotificationMode (const OFBool mode)
	Set the mode that specifies whether the progress of sending and receiving DIMSE messages is notified by calling notifySENDProgress() and notifyRECEIVEProgress(), respectively. More...

OFBool	isConnected () const
	Get current connection status. More...

Uint32	getMaxReceivePDULength () const
	Returns maximum PDU length configured to be received by SCU. More...

T_DIMSE_BlockingMode	getDIMSEBlockingMode () const
	Returns whether DIMSE messaging is configured to be blocking or unblocking. More...

const OFString &	getAETitle () const
	Returns the SCU's own configured AE title. More...

const OFString &	getPeerHostName () const
	Returns the SCP's (peer's) host name configured. More...

const OFString &	getPeerAETitle () const
	Returns the SCP's (peer's) AE title configured. More...

Uint16	getPeerPort () const
	Returns the SCP's (peer's) TCP/IP port configured. More...

Uint32	getDIMSETimeout () const
	Returns DIMSE timeout in seconds for receiving data. More...

Uint32	getACSETimeout () const
	Returns ACSE timeout in seconds used by timer for message timeouts during association negotiation. More...

Sint32	getConnectionTimeout () const
	Returns the timeout configured defining how long SCU will wait for the SCP when requesting an association. More...

OFString	getStorageDir () const
	Returns the storage directory used for storing objects received with C-STORE requests in the context of C-GET sessions. More...

DcmStorageMode	getStorageMode () const
	Returns the storage mode enabled. More...

OFBool	getVerbosePCMode () const
	Returns the verbose presentation context mode configured specifying whether details on the presentation contexts (negotiated during association setup) should be shown in verbose or debug mode. More...

OFBool	getDatasetConversionMode () const
	Returns the mode that specifies whether the transfer syntax of the dataset can be changed for network transmission. More...

OFBool	getProgressNotificationMode () const
	Returns the mode that specifies whether the progress of sending and receiving DIMSE messages is notified by calling notifySENDProgress() and notifyRECEIVEProgress(), respectively. More...

OFBool	getTLSEnabled () const
	Returns whether SCU is configured to create a TLS connection with the SCP. More...

void	freeNetwork ()
	Deletes internal networking structures from memory.

Protected Member Functions
OFCondition	sendDIMSEMessage (const T_ASC_PresentationContextID presID, T_DIMSE_Message msg, DcmDataset dataObject, DcmDataset **commandSet=NULL)
	Sends a DIMSE command and possibly also a dataset from a data object via network to another DICOM application. More...

OFCondition	getDatasetInfo (DcmDataset *dataset, OFString &sopClassUID, OFString &sopInstanceUID, E_TransferSyntax &transferSyntax)
	Returns SOP Class UID, SOP Instance UID and original transfer syntax for a given dataset. More...

OFCondition	useSecureConnection (DcmTransportLayer *tlayer)
	Tells DcmSCU to use a secure TLS connection described by the given TLS layer. More...

OFCondition	receiveDIMSECommand (T_ASC_PresentationContextID presID, T_DIMSE_Message msg, DcmDataset statusDetail, DcmDataset commandSet=NULL, const Uint32 timeout=0)
	Receive DIMSE command (excluding dataset!) over the currently open association. More...

OFCondition	receiveDIMSEDataset (T_ASC_PresentationContextID presID, DcmDataset *dataObject)
	Receives one dataset (of instance data) via network from another DICOM application. More...

void	clearPresentationContexts ()
	clear list of presentation contexts. More...

void	findPresentationContext (const T_ASC_PresentationContextID presID, OFString &abstractSyntax, OFString &transferSyntax)
	After negotiation association, this call returns the presentation context belonging to the given presentation context ID. More...

virtual void	notifyInstanceStored (const OFString &filename, const OFString &sopClassUID, const OFString &sopInstanceUID) const
	This function is called if an object was received due to a C-GET request and can be overwritten by a user in order to be informed about such an event. More...

virtual void	notifySENDProgress (const unsigned long byteCount)
	This function is called while sending DIMSE messages, i.e. on each PDV of a dataset. More...

virtual void	notifyRECEIVEProgress (const unsigned long byteCount)
	This function is called while receiving DIMSE messages, i.e. on each PDV of a dataset. More...

virtual Uint16	checkEVENTREPORTRequest (T_DIMSE_N_EventReportRQ &request, DcmDataset *reqDataset)
	Check given N-EVENT-REPORT request and dataset for validity. More...

virtual OFCondition	sendSTOREResponse (T_ASC_PresentationContextID presID, Uint16 status, const T_DIMSE_C_StoreRQ &request)
	Sends back a C-STORE response on the given presentation context, with the designated status, fitting the corresponding C-STORE request. More...

virtual OFString	createStorageFilename (DcmDataset *dataset)
	Helper function that generates a storage filename by extracting SOP Class and SOP Instance UID from a dataset and combining that with the configured storage directory. More...

virtual OFCondition	ignoreSTORERequest (T_ASC_PresentationContextID presID, const T_DIMSE_C_StoreRQ &request)
	Receives a DICOM dataset on a given presentation context ID but does not store it in memory or disk, thus ignoring it. More...

Static Protected Member Functions
static void	callbackSENDProgress (void *callbackContext, unsigned long byteCount)
	Callback function used for sending DIMSE messages. More...

static void	callbackRECEIVEProgress (void *callbackContext, unsigned long byteCount)
	Callback function used for receiving DIMSE messages. More...

Private Member Functions
	DcmSCU (const DcmSCU &src)
	Private undefined copy-constructor. More...

DcmSCU &	operator= (const DcmSCU &src)
	Private undefined operator=. More...

Uint16	nextMessageID ()
	Returns next available message ID free to be used by SCU. More...

Private Attributes
T_ASC_Association *	m_assoc
	Association of this SCU. This class only handles 1 association at a time.

T_ASC_Network *	m_net
	The DICOM network the association is based on.

T_ASC_Parameters *	m_params
	Association parameters.

OFString	m_assocConfigFilename
	Configuration file for presentation contexts (optional)

OFString	m_assocConfigProfile
	Profile in configuration file that should be used (optional)

OFList< DcmSCUPresContext >	m_presContexts
	List of presentation contexts that should be negotiated.

OFString	m_assocConfigFile
	Configuration file containing association parameters.

T_DIMSE_Message *	m_openDIMSERequest
	The last DIMSE successfully sent, unresponded DIMSE request.

Uint32	m_maxReceivePDULength
	Maximum PDU size (default: 16384 bytes)

T_DIMSE_BlockingMode	m_blockMode
	DIMSE blocking mode (default: blocking)

OFString	m_ourAETitle
	AE title of this application (default: ANY-SCU)

OFString	m_peer
	Peer hostname.

OFString	m_peerAETitle
	AE title of remote application (default: ANY-SCP)

Uint16	m_peerPort
	Port of remote application entity (default: 104)

Uint32	m_dimseTimeout
	DIMSE timeout (default: unlimited)

Uint32	m_acseTimeout
	ACSE timeout (default: 30 seconds)

OFString	m_storageDir
	Storage directory for objects received with C-STORE due to a running C-GET session. More...

DcmStorageMode	m_storageMode
	Set whether bit preserving storage should be enabled, i.e. any objects retrieved via C-STORE should be written directly to disk without any data correction/re-computation (e.g. group length calculations, padding, etc.). More...

OFBool	m_verbosePCMode
	Verbose PC mode (default: disabled)

OFBool	m_datasetConversionMode
	Dataset conversion mode (default: disabled)

OFBool	m_progressNotificationMode
	Progress notification mode (default: enabled)

Detailed Description

Base class for implementing DICOM Service Class User functionality.

The class offers support for negotiating associations and sending and receiving arbitrary DIMSE messages on that connection. DcmSCU has built-in C-ECHO support so derived classes do not have to implement that capability on their own.

Warning: This class is EXPERIMENTAL. Be careful to use it in production environment.

Constructor & Destructor Documentation

DcmSCU::DcmSCU ( const DcmSCU & src )

private

Private undefined copy-constructor.

Shall never be called.

Parameters

src	Source object

Member Function Documentation

virtual OFCondition DcmSCU::abortAssociation ( )

virtual

Aborts the current association by sending an A-ABORT request to the SCP.

Please note that this abort only applies to associations that have been created by calling initNetwork() and negotiateAssociation().

Returns: status, EC_Normal if successful, an error code otherwise

OFCondition DcmSCU::addPresentationContext	(	const OFString &	abstractSyntax,
		const OFList< OFString > &	xferSyntaxes,
		const T_ASC_SC_ROLE	role = `ASC_SC_ROLE_DEFAULT`
	)

Add presentation context to be used for association negotiation.

Parameters

abstractSyntax	[in] Abstract syntax name in UID format
xferSyntaxes	[in] List of transfer syntaxes to be added for the given abstract syntax
role	[in] The role to be negotiated

Returns: EC_Normal if adding was successful, otherwise error code

static void DcmSCU::callbackRECEIVEProgress	(	void *	callbackContext,
		unsigned long	byteCount
	)

staticprotected

Callback function used for receiving DIMSE messages.

Parameters

callbackContext	[in] The desired user callback data
byteCount	[in] Progress bytes count

static void DcmSCU::callbackSENDProgress	(	void *	callbackContext,
		unsigned long	byteCount
	)

staticprotected

Callback function used for sending DIMSE messages.

Parameters

callbackContext	[in] The desired user callback data
byteCount	[in] Progress bytes count

virtual Uint16 DcmSCU::checkEVENTREPORTRequest	(	T_DIMSE_N_EventReportRQ &	request,
		DcmDataset *	reqDataset
	)

protectedvirtual

Check given N-EVENT-REPORT request and dataset for validity.

This method is called by handleEVENTREPORTRequest() before sending the response in order to determine the DIMSE status code to be used for the response message.

Parameters

request	[in] The N-EVENT-REPORT request message data structure
reqDataset	[in] The N-EVENT-REPORT request dataset received. Might be NULL.

Returns: DIMSE status code to be used for the N-EVENT-REPORT response. Always returns STATUS_Success (0). Derived classes should, therefore, overwrite this method and return a more appropriate value based on the result of the checks performed.

void DcmSCU::clearPresentationContexts ( )

protected

clear list of presentation contexts.

In addition, any currently selected association configuration file is disabled.

virtual void DcmSCU::closeAssociation ( const DcmCloseAssociationType closeType )

virtual

Closes the association created by this SCU.

Also resets the current association.

Deprecated:

The use of this method is deprecated. Please use releaseAssociation() or abortAssociation() instead.

Parameters

closeType [in] Define whether to release or abort the association

Reimplemented in DcmTLSSCU.

virtual OFString DcmSCU::createStorageFilename ( DcmDataset * dataset )

protectedvirtual

Helper function that generates a storage filename by extracting SOP Class and SOP Instance UID from a dataset and combining that with the configured storage directory.

The SOP class is used to create an initial two letter abbreviation for the corresponding modality, e.g. CT. An example for a storage filename created by this function is "/storage_dir/CT.1.2.3.4.5" for a CT with SOP Instance UID "1.2.3.4.5". This function might be overwritten to change the filename behaviour completely. This function is only called if the SCU is in DCMSCU_STORAGE_DISK mode.

Parameters

dataset [in] The dataset that should be stored to disk

Returns: Non-empty string if successful, otherwise empty string.

T_ASC_PresentationContextID DcmSCU::findAnyPresentationContextID	(	const OFString &	abstractSyntax,
		const OFString &	transferSyntax
	)

After a successful association negotiation, this function is called to return the presentation context ID that best matches the desired abstract syntax and transfer syntax (TS).

The function tries to do the following:

If possible finds a presentation context with matching TS
Else then tries to find an explicit VR uncompressed TS presentation context
Else then tries to find an implicit VR uncompressed TS presentation context
Else finally accepts each matching presentation ctx independent of TS.
Parameters

abstractSyntax [in] The abstract syntax (UID) to look for

transferSyntax [in] The transfer syntax (UID) to look for. If empty, the transfer syntax is not checked.

Returns
Adequate Presentation context ID that can be used. 0 if no appropriate presentation context could be found at all.

void DcmSCU::findPresentationContext	(	const T_ASC_PresentationContextID	presID,
		OFString &	abstractSyntax,
		OFString &	transferSyntax
	)

protected

After negotiation association, this call returns the presentation context belonging to the given presentation context ID.

Parameters

presID	[in] The presentation context ID to look for
abstractSyntax	[out] The abstract syntax (UID) for that ID. Empty, if such a presentation context does not exist.
transferSyntax	[out] The transfer syntax (UID) for that ID. Empty, if such a presentation context does not exist.

T_ASC_PresentationContextID DcmSCU::findPresentationContextID	(	const OFString &	abstractSyntax,
		const OFString &	transferSyntax
	)

After negotiation association, this call returns the first usable presentation context given the desired abstract syntax and transfer syntax.

Parameters

abstractSyntax	[in] The abstract syntax (UID) to look for
transferSyntax	[in] The transfer syntax (UID) to look for. If empty, the transfer syntax is not checked.

Returns: Adequate Presentation context ID that can be used. 0 if none found.

Uint32 DcmSCU::getACSETimeout ( ) const

Returns ACSE timeout in seconds used by timer for message timeouts during association negotiation.

Returns: The ACSE timeout (in seconds) configured

const OFString& DcmSCU::getAETitle ( ) const

Returns the SCU's own configured AE title.

Returns: The AE title configured for this SCU

Sint32 DcmSCU::getConnectionTimeout ( ) const

Returns the timeout configured defining how long SCU will wait for the SCP when requesting an association.

-1 means infinite waiting (blocking), 0 means no waiting at all. Note that this is currently a global DCMTK setting.

Returns: The connection timeout (in seconds)

OFBool DcmSCU::getDatasetConversionMode ( ) const

Returns the mode that specifies whether the transfer syntax of the dataset can be changed for network transmission.

This mainly covers the compression/decompression of datasets, which is disabled by default.

Returns: The current dataset conversion mode, enabled if OFTrue

OFCondition DcmSCU::getDatasetInfo	(	DcmDataset *	dataset,
		OFString &	sopClassUID,
		OFString &	sopInstanceUID,
		E_TransferSyntax &	transferSyntax
	)

protected

Returns SOP Class UID, SOP Instance UID and original transfer syntax for a given dataset.

If the dataset is NULL, all returned values will be undefined (i.e. empty or EXS_Unknown).

Parameters

dataset	[in] The dataset to read from
sopClassUID	[out] The value of attribute SOP Class UID if present
sopInstanceUID	[out] The value of attribute SOP Instance UID if present
transferSyntax	[out] The value of transfer syntax that originally was read from disk. Will be unknown if the dataset was created in memory.

Returns: EC_Normal if all information could be retrieved and is valid, an error code otherwise

T_DIMSE_BlockingMode DcmSCU::getDIMSEBlockingMode ( ) const

Returns whether DIMSE messaging is configured to be blocking or unblocking.

Returns: The blocking mode configured

Uint32 DcmSCU::getDIMSETimeout ( ) const

Returns DIMSE timeout in seconds for receiving data.

If the blocking mode is DIMSE_NONBLOCKING the SCU will try to read data from the incoming socket stream for the number of seconds configured.

Returns: The DIMSE timeout (in seconds) configured

Uint32 DcmSCU::getMaxReceivePDULength ( ) const

Returns maximum PDU length configured to be received by SCU.

Returns: Maximum PDU length in bytes

const OFString& DcmSCU::getPeerAETitle ( ) const

Returns the SCP's (peer's) AE title configured.

Returns: The AE title configured to be talked to

const OFString& DcmSCU::getPeerHostName ( ) const

Returns the SCP's (peer's) host name configured.

Returns: The hostname (or IP) configured to be talked to

Uint16 DcmSCU::getPeerPort ( ) const

Returns the SCP's (peer's) TCP/IP port configured.

Returns: The port configured to talked to

OFBool DcmSCU::getProgressNotificationMode ( ) const

Returns the mode that specifies whether the progress of sending and receiving DIMSE messages is notified by calling notifySENDProgress() and notifyRECEIVEProgress(), respectively.

The progress notification is enabled by default.

Returns: The current progress notification mode, enabled if OFTrue

OFString DcmSCU::getStorageDir ( ) const

Returns the storage directory used for storing objects received with C-STORE requests in the context of C-GET sessions.

Default is empty string which refers to the current working directory.

Returns: The storage directory

DcmStorageMode DcmSCU::getStorageMode ( ) const

Returns the storage mode enabled.

Returns: The storage mode enabled

OFBool DcmSCU::getTLSEnabled ( ) const

Returns whether SCU is configured to create a TLS connection with the SCP.

Returns: OFFalse for this class but may be overridden by derived classes

OFBool DcmSCU::getVerbosePCMode ( ) const

Returns the verbose presentation context mode configured specifying whether details on the presentation contexts (negotiated during association setup) should be shown in verbose or debug mode.

The latter is the default.

Returns: The current verbose presentation context mode. Show details on the presentation contexts on INFO log level (verbose) if OFTrue and on DEBUG level if OFFalse.

virtual OFCondition DcmSCU::handleCGETResponse	(	const T_ASC_PresentationContextID	presID,
		RetrieveResponse *	response,
		OFBool &	continueCGETSession
	)

virtual

Function handling a single C-GET Response.

This standard handler reads the status of the response and decides whether to receive any further messages related to the original C-GET Request or whether the last response was received or an error occurred.

Parameters

presID	[in] The presentation context the C-GET Response was received on.
response	[in] The response received
continueCGETSession	[out] Defines whether it is decided to wait for further C-GET Responses/C-STORE Requests within this C-GET session

Returns: If no errors occur (dataset response NULL, SCU not connected), this method will return EC_Normal, otherwise error code.

virtual OFCondition DcmSCU::handleCGETSession	(	const T_ASC_PresentationContextID	presID,
		DcmDataset *	dataset,
		OFList< RetrieveResponse * > *	responses
	)

virtual

Does the logic for switching between C-GET Response and C-STORE Requests.

Sends a C-GET Request on given presentation context and receives list of responses. The full list of responses is returned to the caller. If he is not interested, he can set responses=NULL when calling the function. After sending a C-GET Request, there might be two different responses coming in: C-GET-RSP (optional after each received object and mandatory after the last object) or a mandatory C-STORE for each incoming object that is received due to the request. This function therefore either calls handleCGETResponse() or handleSTORERequest() in order to deal with the incoming message. All other messages lead to an error within this handler. This function can be overwritten by actual SCU implementations but just should work fine for most people.

Parameters

presID	[in] The presentation context ID that should be used. Must be an odd number.
dataset	[in] The dataset containing the information about the object(s) to be retrieved
responses	[out] The incoming C-GET responses for this request. If the caller specifies NULL, no responses will be returned; otherwise there should be at least one final C-GET response (mandatory). C-GET responses after each DICOM object received are optional and may have been omitted by the server.

Returns: EC_Normal if everything went fine, i.e. if request could be send and expected responses (with whatever status) could be received.

virtual OFCondition DcmSCU::handleEVENTREPORTRequest	(	DcmDataset *&	reqDataset,
		Uint16 &	eventTypeID,
		const int	timeout = `0`
	)

virtual

Receives N-EVENT-REPORT request on the currently opened association and sends a corresponding response.

Calls checkEVENTREPORTRequest() in order to determine the DIMSE status code to be used for the N-EVENT-REPORT response.

Parameters

reqDataset	[out] Pointer to the dataset received
eventTypeID	[out] Event Type ID from the command set received
timeout	[in] Optional timeout in seconds for receiving data. This value (if not 0) overwrites the standard DIMSE timeout and also enables the non-blocking mode for receiving the request.

Returns: status, EC_Normal if successful, an error code otherwise

virtual OFCondition DcmSCU::handleFINDResponse	(	const T_ASC_PresentationContextID	presID,
		QRResponse *	response,
		OFBool &	waitForNextResponse
	)

virtual

This is the standard handler for C-FIND message responses: It just adds up all responses it receives and prints a DEBUG message.

Therefore, it is called for each response received in sendFINDRequest(). The idea is of course to overwrite this function in a derived, actual SCU implementation if required. Thus, after each response, the caller of sendFINDRequest() can decide on its own whether he wants to cancel the C-FIND session, terminate the association, do something useful or whatever. That way this is a more object-oriented kind of callback.

Parameters

presID	[in] The presentation context ID where the response was received on.
response	[in] The C-FIND response received.
waitForNextResponse	[out] Denotes whether SCU should try to receive another response. If set to OFTrue, then sendFINDRequest() will continue waiting for responses. The current implementation does that for all responses do not have status SUCESSS. If set to OFFalse, sendFINDRequest() will return control to the caller.

Returns: EC_Normal, if response could be handled. Error code otherwise. The current implementation always returns EC_Normal.

virtual OFCondition DcmSCU::handleMOVEResponse	(	const T_ASC_PresentationContextID	presID,
		RetrieveResponse *	response,
		OFBool &	waitForNextResponse
	)

virtual

This is the standard handler for C-MOVE message responses: It just adds up all responses it receives and prints a DEBUG message.

Therefore, it is called for each response received in sendMOVERequest(). The idea is of course to overwrite this function in a derived, actual SCU implementation if required. Thus, after each response, the caller of sendMOVERequest() can decide on its own whether he wants to cancel the C-MOVE session, terminate the association, do something useful or whatever. Thus this function is a more object-oriented kind of callback.

Parameters

presID	[in] The presentation context ID where the response was received on.
response	[in] The C-MOVE response received.
waitForNextResponse	[out] Denotes whether SCU should try to receive another response. If set to OFTrue, then sendMOVERequest() will continue waiting for responses. The current implementation does that for all responses do not have status Failed, Warning, Success or unknown. If set to OFFalse, sendMOVERequest() will return control to the caller.

Returns: EC_Normal, if response could be handled. Error code otherwise. The current implementation always returns EC_Normal.

virtual OFCondition DcmSCU::handleSTORERequest	(	const T_ASC_PresentationContextID	presID,
		DcmDataset *	incomingObject,
		OFBool &	continueCGETSession,
		Uint16 &	cStoreReturnStatus
	)

virtual

Function handling a single C-STORE Request.

If storage mode is set to disk (default), this function is called and the incoming object stored to disk.

Parameters

presID	[in] The presentation context the C-STORE Request was received on.
incomingObject	[in] The dataset (the object) received. The function takes ownership of the dataset, i.e. deletes it after processing.
continueCGETSession	[out] Defines whether it is decided to wait for further C-GET Responses/C-STORE requests within this C-GET session.
cStoreReturnStatus	[out] Denotes the desired C-STORE return status.

Returns: If errors occur (incomingObject NULL or SCU not connected or file could not be stored), this method will return an error code otherwise EC_Normal.

virtual OFCondition DcmSCU::handleSTORERequestFile	(	T_ASC_PresentationContextID *	presID,
		const OFString &	filename,
		T_DIMSE_C_StoreRQ *	request
	)

virtual

Function handling a single C-STORE Request.

If storage mode is set to bit preserving, this function is called and the incoming object stored directly to disk, i.e. not stored fully in memory.

Parameters

presID	[in] The presentation context the C-STORE Response was received on.
filename	[in] The filename to store to
request	[in] The incoming C-STORE request command set

Returns: If errors occur (incomingObject NULL or SCU not connected filename not specified), this method will return an error code otherwise EC_Normal.

virtual OFCondition DcmSCU::ignoreSTORERequest	(	T_ASC_PresentationContextID	presID,
		const T_DIMSE_C_StoreRQ &	request
	)

protectedvirtual

Receives a DICOM dataset on a given presentation context ID but does not store it in memory or disk, thus ignoring it.

Parameters

presID	[in] The presentation context to be used
request	[in] The corresponding C-STORE request

Returns: EC_Normal if ignoring worked, error code otherwise.

virtual OFCondition DcmSCU::initNetwork ( )

virtual

Initialize network, i.e. prepare for association negotiation.

If the SCU is already connected, the call will not be successful and the old connection keeps open.

Returns: EC_Normal if initialization was successful, otherwise error code. NET_EC_AlreadyConnected if SCU is already connected.

Reimplemented in DcmTLSSCU.

OFBool DcmSCU::isConnected ( ) const

Get current connection status.

Returns: OFTrue if SCU is currently connected, OFFalse otherwise

virtual OFCondition DcmSCU::negotiateAssociation ( )

virtual

Negotiate association by using presentation contexts and parameters as defined by earlier function calls.

If negotiation fails, there is no need to close the association or to do anything else with this class.

Returns: EC_Normal if negotiation was successful, otherwise error code. NET_EC_AlreadyConnected if SCU is already connected.

Reimplemented in DcmStorageSCU, and DcmTLSSCU.

Uint16 DcmSCU::nextMessageID ( )

private

Returns next available message ID free to be used by SCU.

Returns: Next free message ID

virtual void DcmSCU::notifyInstanceStored	(	const OFString &	filename,
		const OFString &	sopClassUID,
		const OFString &	sopInstanceUID
	)		const

protectedvirtual

This function is called if an object was received due to a C-GET request and can be overwritten by a user in order to be informed about such an event.

The default implementation just prints a DEBUG message. Note that this function is not called if the SCU is in storage mode DCMSCU_STORAGE_IGNORE.

Parameters

filename	[in] The filename written
sopClassUID	[in] The SOP Class UID of the object written
sopInstanceUID	[in] The SOP Instance UID of the object written

virtual void DcmSCU::notifyRECEIVEProgress ( const unsigned long byteCount )

protectedvirtual

This function is called while receiving DIMSE messages, i.e. on each PDV of a dataset.

The default implementation just prints a TRACE message on the number of bytes received so far. By overwriting this method, the progress of the receive process can be shown to the user in a more appropriate way. The progress notification can also be disabled completely by calling setProgressNotificationMode().

Parameters

byteCount [in] Number of bytes received so far

virtual void DcmSCU::notifySENDProgress ( const unsigned long byteCount )

protectedvirtual

This function is called while sending DIMSE messages, i.e. on each PDV of a dataset.

The default implementation just prints a TRACE message on the number of bytes sent so far. By overwriting this method, the progress of the send process can be shown to the user in a more appropriate way. The progress notification can also be disabled completely by calling setProgressNotificationMode().

Parameters

byteCount [in] Number of bytes sent so far

DcmSCU& DcmSCU::operator= ( const DcmSCU & src )

private

Private undefined operator=.

Shall never be called.

Parameters

src	Source object

Returns: Reference to this

OFCondition DcmSCU::receiveDIMSECommand	(	T_ASC_PresentationContextID *	presID,
		T_DIMSE_Message *	msg,
		DcmDataset **	statusDetail,
		DcmDataset **	commandSet = `NULL`,
		const Uint32	timeout = `0`
	)

protected

Receive DIMSE command (excluding dataset!) over the currently open association.

Parameters

presID	[out] Contains in the end the ID of the presentation context which was specified in the DIMSE command received
msg	[out] The message received
statusDetail	[out] If a non-NULL value is passed this variable will in the end contain detailed information with regard to the status information which is captured in the status element (0000,0900). Note that the value for element (0000,0900) is not contained in this return value but in internal msg. For details on the structure of this object, see DICOM standard part 7, annex C).
commandSet	[out] If this parameter is not NULL, it will return a copy of the DIMSE command which was received from the other DICOM application. The caller is responsible to de-allocate the returned object!
timeout	[in] If this parameter is not 0, it specifies the timeout (in seconds) to be used for receiving the DIMSE command. Otherwise, the default timeout value is used (see setDIMSETimeout()).

Returns: EC_Normal if command could be received successfully, an error code otherwise

OFCondition DcmSCU::receiveDIMSEDataset	(	T_ASC_PresentationContextID *	presID,
		DcmDataset **	dataObject
	)

protected

Receives one dataset (of instance data) via network from another DICOM application.

Parameters

presID	[out] Contains in the end the ID of the presentation context which was used in the PDVs that were received on the network. If the PDVs show different presentation context IDs, this function will return an error.
dataObject	[out] Contains in the end the information which was received over the network

Returns: EC_Normal if dataset could be received successfully, an error code otherwise

virtual OFCondition DcmSCU::releaseAssociation ( )

virtual

Releases the current association by sending an A-RELEASE request to the SCP.

Please note that this release only applies to associations that have been created by calling initNetwork() and negotiateAssociation().

Returns: status, EC_Normal if successful, an error code otherwise

virtual OFCondition DcmSCU::sendACTIONRequest	(	const T_ASC_PresentationContextID	presID,
		const OFString &	sopInstanceUID,
		const Uint16	actionTypeID,
		DcmDataset *	reqDataset,
		Uint16 &	rspStatusCode
	)

virtual

This function sends a N-ACTION request on the currently opened association and receives the corresponding response then.

Parameters

presID	[in] The ID of the presentation context to be used for sending the request message. Should not be 0.
sopInstanceUID	[in] The requested SOP Instance UID
actionTypeID	[in] The action type ID to be used
reqDataset	[in] The dataset to be sent
rspStatusCode	[out] The response status code received. 0 means success, others can be found in the DICOM standard.

Returns: EC_Normal if request could be issued and response was received successfully, an error code otherwise

virtual OFCondition DcmSCU::sendCANCELRequest ( const T_ASC_PresentationContextID presID )

virtual

Send C-CANCEL and, therefore, ends the C-FIND -GET or -MOVE session, i.e. no further responses will be handled.

A call to this function only makes sense if an association is open, the given presentation context represents a valid C-FIND/GET/MOVE-enabled SOP class and usually only, if the last command send on that presentation context was a C-FIND message.

Parameters

presID [in] The presentation context ID where the C-CANCEL should be sent on.

Returns: The current implementation always returns EC_Normal.

virtual OFCondition DcmSCU::sendCGETRequest	(	const T_ASC_PresentationContextID	presID,
		DcmDataset *	dataset,
		OFList< RetrieveResponse * > *	responses
	)

virtual

Sends a C-GET Request on given presentation context and receives list of responses.

It then switches control to the function handleCGETSession(). The full list of responses is returned to the caller. If he is not interested, he can set responses=NULL when calling the function. This function can be overwritten by actual SCU implementations but just should work fine for most people.

Parameters

presID	[in] The presentation context ID that should be used. Must be an odd number.
dataset	[in] The dataset containing the information about the object(s) to be retrieved
responses	[out] The incoming C-GET responses for this request. If the caller specifies NULL, no responses will be returned; otherwise there should be at least one final C-GET response (mandatory). C-GET responses after each DICOM object received are optional and may have been omitted by the server.

Returns: EC_Normal if everything went fine, i.e. if request could be sent and expected responses (with whatever status) could be received.

OFCondition DcmSCU::sendDIMSEMessage	(	const T_ASC_PresentationContextID	presID,
		T_DIMSE_Message *	msg,
		DcmDataset *	dataObject,
		DcmDataset **	commandSet = `NULL`
	)

protected

Sends a DIMSE command and possibly also a dataset from a data object via network to another DICOM application.

Parameters

presID	[in] Presentation context ID to be used for message
msg	[in] Structure that represents a certain DIMSE command which shall be sent
dataObject	[in] The instance data which shall be sent to the other DICOM application; NULL, if there is none
commandSet	[out] If this parameter is not NULL it will return a copy of the DIMSE command which is sent to the other DICOM application

Returns: EC_Normal if sending request was successful, an error code otherwise

virtual OFCondition DcmSCU::sendECHORequest ( const T_ASC_PresentationContextID presID )

virtual

This function sends a C-ECHO command via network to another DICOM application.

Parameters

presID [in] Presentation context ID to use. A value of 0 lets SCP class tries to choose one on its own.

Returns: EC_Normal if echo was successful, an error code otherwise

virtual OFCondition DcmSCU::sendEVENTREPORTRequest	(	const T_ASC_PresentationContextID	presID,
		const OFString &	sopInstanceUID,
		const Uint16	eventTypeID,
		DcmDataset *	reqDataset,
		Uint16 &	rspStatusCode
	)

virtual

This function sends N-EVENT-REPORT request and receives the corresponding response.

Parameters

presID	[in] The ID of the presentation context to be used for sending the request message. Should not be 0.
sopInstanceUID	[in] The requested SOP Instance UID
eventTypeID	[in] The event type ID to be used
reqDataset	[in] The request dataset to be sent
rspStatusCode	[out] The response status code received. 0 means success, others can be found in the DICOM standard.

Returns: EC_Normal if request could be issued and response was received successfully, an error code otherwise

virtual OFCondition DcmSCU::sendFINDRequest	(	const T_ASC_PresentationContextID	presID,
		DcmDataset *	queryKeys,
		OFList< QRResponse * > *	responses
	)

virtual

Sends a C-FIND Request on given presentation context and receives list of responses.

The function receives the first response and then calls the function handleFINDResponse() which gets the relevant presentation context together with the response dataset and status information. Then it waits again for the next response, if there are more to come (i.e. response status is PENDING). In the end, after receiving all responses, the full list of responses is returned to the caller. If he is not interested, he just sets responses=NULL when calling the function. This function can be overwritten by actual SCU implementations but just should work fine for most people.

Parameters

presID	[in] The presentation context ID that should be used. Must be an odd number.
queryKeys	[in] The dataset containing the query keys to be searched for on the server (SCP).
responses	[out] The incoming C-FIND responses for this request. The caller is responsible for providing a non-NULL pointer for this case. After receiving the results, the caller is responsible for freeing the memory of this variable. If NULL is specified, the responses will be not returned to the caller.

Returns: EC_Normal if everything went fine, i.e. if request could be send and responses (with whatever status) could be received.

virtual OFCondition DcmSCU::sendMOVERequest	(	const T_ASC_PresentationContextID	presID,
		const OFString &	moveDestinationAETitle,
		DcmDataset *	dataset,
		OFList< RetrieveResponse * > *	responses
	)

virtual

Sends a C-MOVE Request on given presentation context and receives list of responses.

The function receives the first response and then calls the function handleMOVEResponse() which gets the relevant presentation context together with the response dataset and status information. Then it waits again for the next response, if there are more to come (i.e. response status is PENDING). In the end, after receiving all responses, the full list of responses is returned to the caller. If he is not interested, he just sets responses=NULL when calling the function. This function can be overwritten by actual SCU implementations but just should work fine for most people.

Parameters

presID	[in] The presentation context ID that should be used. Must be an odd number.
moveDestinationAETitle	[in] The move destination's AE title, i.e. the one that is used for connection to the storage server.
dataset	[in] The dataset containing the information about the object(s) to be retrieved.
responses	[out] The incoming C-MOVE responses for this request. The caller is responsible for providing a non-NULL pointer for this case. After receiving the results, the caller is responsible for freeing the memory of this variable. If NULL is specified, the responses will not be returned to the caller.

Returns: EC_Normal if everything went fine, i.e. if request could be send and responses (with whatever status) could be received.

virtual OFCondition DcmSCU::sendSTORERequest	(	const T_ASC_PresentationContextID	presID,
		const OFFilename &	dicomFile,
		DcmDataset *	dataset,
		Uint16 &	rspStatusCode,
		const OFString &	moveOriginatorAETitle = `""`,
		const Uint16	moveOriginatorMsgID = `0`
	)

virtual

This function sends a C-STORE request on the currently opened association and receives the corresponding response then.

If required and supported, the dataset of the SOP instance can be converted automatically to the network transfer syntax that was negotiated (and is specified by the parameter 'presID'). However, this feature is disabled by default. See setDatasetConversionMode() on how to enable it.

Parameters

presID	[in] Contains in the end the ID of the presentation context which was specified in the DIMSE command. If 0 is given, the function tries to find an appropriate presentation context itself (based on SOP class and original transfer syntax of the 'dicomFile' or 'dataset').
dicomFile	[in] The filename of the DICOM file to be sent. Alternatively, a dataset can be given in the next parameter. If both are given the dataset from the file name is used.
dataset	[in] The dataset to be sent. Alternatively, a filename can be specified in the previous parameter. If both are given the dataset from the filename is used.
rspStatusCode	[out] The response status code received. 0 means success, others can be found in the DICOM standard.
moveOriginatorAETitle	[in] If this C-STORE is started due to a C-MOVE request, this parameter informs the C-STORE SCP about the C-MOVE client's AE title.
moveOriginatorMsgID	[in] If this C-STORE is started due to a C-MOVE request, this parameter informs the C-STORE SCP about the C-MOVE message ID.

Returns: EC_Normal if request could be issued and response was received successfully, error code otherwise. That means that if the receiver sends a response denoting failure of the storage request, EC_Normal will be returned.

virtual OFCondition DcmSCU::sendSTOREResponse	(	T_ASC_PresentationContextID	presID,
		Uint16	status,
		const T_DIMSE_C_StoreRQ &	request
	)

protectedvirtual

Sends back a C-STORE response on the given presentation context, with the designated status, fitting the corresponding C-STORE request.

Parameters

presID	[in] The presentation context ID to be used.
status	[in] The storage DIMSE status to be used.
request	[in] The C-STORE request that should be responded to.

Returns: EC_Normal if the response could be sent, error otherwise.

void DcmSCU::setACSETimeout ( const Uint32 acseTimeout )

Set timeout for receiving ACSE messages.

Parameters

acseTimeout [in] ACSE timeout in seconds used by timer for message timeouts during association negotiation

void DcmSCU::setAETitle ( const OFString & myAETtitle )

Set SCU's AE title to be used in association negotiation.

Parameters

myAETtitle [in] The SCU's AE title to be used

void DcmSCU::setAssocConfigFileAndProfile	(	const OFString &	filename,
		const OFString &	profile
	)

Set an association configuration file and profile to be used.

Parameters

filename	[in] File name of the association configuration file
profile	[in] Profile inside the association negotiation file

void DcmSCU::setConnectionTimeout ( const Sint32 connectionTimeout )

Set global timeout for connecting to the SCP.

Note that this is a global DCMTK setting i.e. it affects all code that uses dcmnet to start a DICOM association to another host. Setting the timeout to -1 sets an infinite timeout, i.e. any association request will wait forever (blocking) until the SCP accepts the connection request. A value of 0 lets the SCU return immediately if the SCP is not reachable at the first attempt.

Parameters

connectionTimeout [in] Connection Timeout in seconds when connecting to SCPs. -1 will wait forever (blocking mode).

void DcmSCU::setDatasetConversionMode ( const OFBool mode )

Set the mode that specifies whether the transfer syntax of the dataset can be changed for network transmission.

This mainly covers the compression/decompression of datasets, which is disabled by default.

Parameters

mode	[in] Allow dataset conversion if OFTrue

void DcmSCU::setDIMSEBlockingMode ( const T_DIMSE_BlockingMode blockingMode )

Set whether to send in DIMSE blocking or non-blocking mode.

Parameters

blockingMode [in] Either blocking or non-blocking mode

void DcmSCU::setDIMSETimeout ( const Uint32 dimseTimeout )

Set timeout for receiving DIMSE messages.

Parameters

dimseTimeout [in] DIMSE timeout in seconds for receiving data. If the blocking mode is DIMSE_NONBLOCKING the SCU will try to read data from the incoming socket stream for the number of seconds configured.

void DcmSCU::setMaxReceivePDULength ( const Uint32 maxRecPDU )

Set maximum PDU length (to be received by SCU)

Parameters

maxRecPDU [in] The maximum PDU size to use in bytes

void DcmSCU::setPeerAETitle ( const OFString & peerAETitle )

Set SCP's AE title to talk to in association negotiation.

Parameters

peerAETitle [in] The SCP's AE title to be used

void DcmSCU::setPeerHostName ( const OFString & peerHostName )

Set SCP's host (hostname or IP address) to talk to in association negotiation.

Parameters

peerHostName [in] The SCP's hostname or IP address to be used

void DcmSCU::setPeerPort ( const Uint16 peerPort )

Set SCP's port number to connect to for association negotiation.

Parameters

peerPort [in] The SCP's port number

void DcmSCU::setProgressNotificationMode ( const OFBool mode )

Set the mode that specifies whether the progress of sending and receiving DIMSE messages is notified by calling notifySENDProgress() and notifyRECEIVEProgress(), respectively.

The progress notification is enabled by default.

Parameters

mode	[in] Disable progress notification if OFFalse

void DcmSCU::setStorageDir ( const OFString & storeDir )

Set the directory that should be used by the standard C-GET handler to store objects that come in with the corresponding C-STORE requests.

Parameters

storeDir [in] The directory to store to. It is checked in handleSTORERequest() whether the directory is writeable and readable. By default, the received objects are stored in the current working directory.

void DcmSCU::setStorageMode ( const DcmStorageMode storageMode )

Set the storage mode to be used.

Default is DCMSCU_STORAGE_DISK.

Parameters

storageMode The storage mode to be used.

void DcmSCU::setVerbosePCMode ( const OFBool mode )

Set whether to show presentation contexts in verbose or debug mode.

Parameters

mode	[in] Show presentation contexts in verbose mode if OFTrue. By default, the presentation contexts are shown in debug mode.

OFCondition DcmSCU::useSecureConnection ( DcmTransportLayer * tlayer )

protected

Tells DcmSCU to use a secure TLS connection described by the given TLS layer.

Parameters

tlayer [in] The TLS transport layer including all TLS parameters

Returns: EC_Normal if given transport layer is ok, an error code otherwise

Member Data Documentation

OFString DcmSCU::m_storageDir

private

Storage directory for objects received with C-STORE due to a running C-GET session.

By default, the received objects are stored in the current working directory.

DcmStorageMode DcmSCU::m_storageMode

private

Set whether bit preserving storage should be enabled, i.e. any objects retrieved via C-STORE should be written directly to disk without any data correction/re-computation (e.g. group length calculations, padding, etc.).

This is especially interesting for retaining valid signatures, and also to receive huge files which cannot be fully received in memory. Default value: DCMSCU_STORAGE_DISK

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

dcmnet/include/dcmtk/dcmnet/scu.h

Classes

Public Member Functions

Protected Member Functions

Static Protected Member Functions

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation