Interface class for a Storage Service Class User (SCU). More...

Inheritance diagram for DcmStorageSCU:

Classes
struct	TransferEntry
	internal class/struct for a single transfer entry More...

Public Types
enum	E_DecompressionMode { DM_never , DM_losslessOnly , DM_default = DM_losslessOnly , DM_lossyAndLossless }
	dataset decompression modes More...

enum	E_HandlingMode { HM_doNothing , HM_compactAfterSend , HM_deleteAfterSend , HM_deleteAfterRemove }
	dataset handling modes More...

Public Member Functions
	DcmStorageSCU ()
	default constructor

virtual	~DcmStorageSCU ()
	destructor

virtual void	clear ()
	clear the internal member variables

unsigned long	getAssociationCounter () const
	get value of the association counter.

size_t	getNumberOfSOPInstances () const
	get number of SOP instances stored in the transfer list

size_t	getNumberOfSOPInstancesToBeSent () const
	get number of SOP instances that are to be sent (i.e. that are not yet sent).

E_DecompressionMode	getDecompressionMode () const
	get mode that specifies whether or not compressed datasets are decompressed if needed, i.e. whether the transfer syntax of the dataset is changed for network transmission.

OFBool	getHaltOnInvalidFileMode () const
	get mode that specifies whether to halt if an invalid file is encountered during batch processing (e.g. when adding SOP instances from a DICOMDIR) or whether to continue with the next SOP instance.

OFBool	getHaltOnUnsuccessfulStoreMode () const
	get mode that specifies whether to halt if unsuccessful store encountered or whether to continue with the next SOP instance.

OFBool	getAllowIllegalProposalMode () const
	get mode that specifies whether to propose presentation contexts that do not contain the default transfer syntax although it is needed, which might result in a violation of the DICOM standard.

OFBool	getReadFromDICOMDIRMode () const
	get mode that specifies whether to read information on SOP instances to be sent from the DICOMDIR files that are added to the transfer list.

OFBool	getMOVEOriginatorInfo (OFString &aeTitle, Uint16 &messageID) const
	get C-MOVE originator information (if set)

void	setDecompressionMode (const E_DecompressionMode decompressionMode)
	set mode that specifies whether or not compressed datasets are decompressed if needed, i.e. whether the transfer syntax of the dataset is changed for network transmission.

void	setHaltOnInvalidFileMode (const OFBool haltMode)
	set mode that specifies whether to halt if an invalid file is encountered during batch processing (e.g. when adding SOP instances from a DICOMDIR) or whether to continue with the next SOP instance.

void	setHaltOnUnsuccessfulStoreMode (const OFBool haltMode)
	set mode that specifies whether to halt if unsuccessful store encountered or whether to continue with the next SOP instance.

void	setAllowIllegalProposalMode (const OFBool allowMode)
	set mode that specifies whether to propose presentation contexts that do not contain the default transfer syntax, although it is needed, which might result in a violation of the DICOM standard.

void	setReadFromDICOMDIRMode (const OFBool readMode)
	set mode that specifies whether to read information on SOP instances to be sent from the DICOMDIR files that are added to the transfer list.

void	setMOVEOriginatorInfo (const OFString &aeTitle="", const Uint16 messageID=0)
	set C-MOVE originator information.

void	resetSentStatus (const OFBool sameAssociation=OFFalse)
	reset the sent status for all SOP instances in the transfer list.

void	removeAllSOPInstances ()
	remove all SOP instances from the transfer list.

OFCondition	removeSOPInstance (const OFString &sopClassUID, const OFString &sopInstanceUID, const OFBool allOccurrences=OFTrue)
	remove a particular SOP instance from the transfer list.

OFCondition	addDicomFile (const OFFilename &filename, const E_FileReadMode readMode=ERM_fileOnly, const OFBool checkValues=OFTrue)
	add a SOP instance stored as a DICOM file or a number of SOP instances referenced from a DICOMDIR to the list of instances to be transferred.

OFCondition	addDataset (DcmDataset *dataset, const E_TransferSyntax datasetXfer=EXS_Unknown, const E_HandlingMode handlingMode=HM_compactAfterSend, const OFBool checkValues=OFTrue)
	add a SOP instance from a given DICOM dataset to the list of instances to be transferred.

OFCondition	addPresentationContexts ()
	add presentation contexts for all SOP instances in the transfer list, which were not yet sent (either successfully or unsuccessfully).

virtual OFCondition	negotiateAssociation ()
	negotiate association by using presentation contexts and parameters as defined by earlier method calls.

OFCondition	sendSOPInstances ()
	send SOP instances to be transferred to the specified peer.

void	getStatusSummary (OFString &summary) const
	get some status information on the overall sending process.

OFCondition	createReportFile (const OFString &filename) const
	create a text file with a detailed report on the transfer of DICOM SOP instances.

Public Member Functions inherited from DcmSCU
	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.

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

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

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).

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

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.

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.

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.

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.

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.

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

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

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

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.

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.

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

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.

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.

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.

virtual OFCondition	sendNCREATERequest (const T_ASC_PresentationContextID presID, const OFString &affectedSopInstanceUID, DcmDataset reqDataset, DcmDataset &createdInstance, Uint16 &rspStatusCode)
	This function sends N-CREATE request and receives the corresponding response.

virtual OFCondition	sendNSETRequest (const T_ASC_PresentationContextID presID, const OFString &requestedSopInstanceUID, DcmDataset modificationList, DcmDataset &attributeList, Uint16 &rspStatusCode)
	This function sends N-SET request and receives the corresponding response.

virtual OFCondition	handleSessionResponseDefault (const Uint16 dimseStatus, const OFString &message, OFBool &waitForNextResponse)
	Function handling a single C-GET, C-FIND or C-MOVE Response, used by handleCGETResponse(), handleFINDResponse() and handleMOVEResponse().

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

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

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

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

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

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

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

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

void	setProtocolVersion (T_ASC_ProtocolFamily protocolVersion)
	Set the IP protocol version.

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

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

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

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

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

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.

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

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

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

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.

OFBool	isConnected () const
	Get current connection status.

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

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

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

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

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

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

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

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

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

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

DcmStorageMode	getStorageMode () const
	Returns the storage mode enabled.

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.

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

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.

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

void	freeNetwork ()
	Deletes internal networking structures from memory.

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

Protected Member Functions
OFCondition	addDicomFilesFromDICOMDIR (const OFFilename &filename, const E_FileReadMode readMode, const OFBool checkValues)
	add SOP instances referenced from a given DICOMDIR to the list of instances to be transferred.

virtual OFCondition	checkSOPInstance (const OFString &sopClassUID, const OFString &sopInstanceUID, const OFString &transferSyntaxUID, const OFBool checkValues)
	check given SOP Class UID, SOP Instance UID and Transfer Syntax UID for validity and conformance to the DICOM standard.

virtual void	notifySOPInstanceToBeSent (const TransferEntry &transferEntry)
	this method is called each time before a SOP instance is sent to a peer.

virtual void	notifySOPInstanceSent (const TransferEntry &transferEntry)
	this method is called each time after a SOP instance has been sent to a peer.

virtual OFBool	shouldStopAfterCurrentSOPInstance ()
	this method is called each time after a SOP instance is sent to a peer.

Protected Member Functions inherited from DcmSCU
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.

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.

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.

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

void	clearPresentationContexts ()
	clear list of presentation contexts.

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.

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.

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

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

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

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.

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.

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.

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

Private Member Functions
	OFListIterator (TransferEntry *) CurrentTransferEntry
	iterator pointing to the current entry in the list of SOP instances to be transferred

Private Attributes
unsigned long	AssociationCounter
	association counter

unsigned long	PresentationContextCounter
	presentation context counter

E_DecompressionMode	DecompressionMode
	decompression mode, i.e. whether a dataset is decompressed for transmission

OFBool	HaltOnInvalidFileMode
	flag indicating whether to halt on invalid file

OFBool	HaltOnUnsuccessfulStoreMode
	flag indicating whether to halt on unsuccessful store

OFBool	AllowIllegalProposalMode
	flag indicating whether to allow illegal proposals

OFBool	ReadFromDICOMDIRMode
	flag indicating whether to read from DICOMDIR files

OFString	MoveOriginatorAETitle
	AE title of the C-MOVE client that initiated the C-STORE operation (if applicable)

Uint16	MoveOriginatorMsgID
	message ID of the C-MOVE message that initiated the C-STORE operation (if applicable)

OFList< TransferEntry * >	TransferList
	list of SOP instances to be transferred

Additional Inherited Members
Static Protected Member Functions inherited from DcmSCU
static void	callbackSENDProgress (void *callbackContext, unsigned long byteCount)
	Callback function used for sending DIMSE messages.

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

Detailed Description

Interface class for a Storage Service Class User (SCU).

This class supports C-STORE messages as an SCU. In a first step, the SOP instances to be sent are added to a transfer list. In a second step, the association negotiation takes place where the required presentation contexts are proposed, i.e. it is checked which SOP classes and transfer syntaxes are needed for transferring the SOP instances. Finally, the SOP instances are sent to the SCP (if possible).

Note

The current implementation does not sort the transfer list according to the SOP Class UID and Transfer Syntax UID of the SOP instances and, therefore, might propose more presentation contexts than required for the transfer of all SOP instances. A simple optimization that is performed internally is to check whether the current SOP instance can be sent using a presentation context that has previously been added for another SOP instance (of the same kind). This approach also makes sure that studies and series are not mixed up, assuming that they have been added to the transfer list in the "correct" order.
Another limitation of the current implementation is the handling of the "Default Transfer Syntax" in case of compression. According to the DICOM standard, the default transfer syntax for "Lossless JPEG Compression", "Lossy JPEG Compression" and so on has to be proposed in at least one presentation context for the particular SOP class. This is not (yet) implemented since the re-encoding of compressed datasets is not supported. Nevertheless, depending on the options used, the default transfer syntax for the uncompressed case is always proposed (if possible).
Also the handling of the encapsulated uncompressed transfer syntax is still rather limited, mainly because transcoding to the other uncompressed transfer syntaxes, which use native format, is not yet implemented by "dcmdata".

Member Enumeration Documentation

◆ E_DecompressionMode

enum DcmStorageSCU::E_DecompressionMode

dataset decompression modes

Enumerator
DM_never	never decompress datasets
DM_losslessOnly	decompress lossless only
DM_default	default value: decompress lossless only
DM_lossyAndLossless	decompress both lossy and lossless

◆ E_HandlingMode

enum DcmStorageSCU::E_HandlingMode

dataset handling modes

Enumerator
HM_doNothing	do nothing with the dataset
HM_compactAfterSend	compact the dataset after it has been sent
HM_deleteAfterSend	delete the dataset after it has been sent
HM_deleteAfterRemove	delete the dataset after it has been removed from the transfer list

Member Function Documentation

◆ addDataset()

OFCondition DcmStorageSCU::addDataset	(	DcmDataset *	dataset,
		const E_TransferSyntax	datasetXfer = `EXS_Unknown`,
		const E_HandlingMode	handlingMode = `HM_compactAfterSend`,
		const OFBool	checkValues = `OFTrue`
	)

add a SOP instance from a given DICOM dataset to the list of instances to be transferred.

Before adding the SOP instance to the list, it is checked for validity and conformance to the DICOM standard (see checkSOPInstance() for details). However, duplicate instances are not recognized, i.e. they are added to the list and later on transferred to the storage SCP when calling sendSOPInstances().

Parameters

dataset	DICOM dataset that contains the SOP instance to be sent
datasetXfer	transfer syntax of the dataset (determined automatically if unknown, which is also the default)
handlingMode	mode specifying what to do with the dataset if no longer needed. HM_xxxAfterSend has no effect if the C-STORE request could not be sent. Please do not add the same dataset multiple times with a mode of HM_deleteAfterXXX, since it will result in deleting the same object multiple times!
checkValues	flag indicating whether to check the UID values for validity and conformance. If OFFalse, only empty values are rejected.

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

◆ addDicomFile()

OFCondition DcmStorageSCU::addDicomFile	(	const OFFilename &	filename,
		const E_FileReadMode	readMode = `ERM_fileOnly`,
		const OFBool	checkValues = `OFTrue`
	)

add a SOP instance stored as a DICOM file or a number of SOP instances referenced from a DICOMDIR to the list of instances to be transferred.

Before adding a SOP instance to the list, it is checked for validity and conformance to the DICOM standard (see checkSOPInstance() for details). However, duplicate instances are not recognized, i.e. they are added to the list and later on transferred to the storage SCP when calling sendSOPInstances(). If the specified DICOM file is a DICOMDIR and the 'ReadFromDICOMDIRMode' is enabled, the referenced SOP instances are added to the transfer list (using the relevant information from the DICOMDIR) and not the DICOMDIR itself, which is not meant to be transferred anyway. Please note that it is not checked whether the referenced files really exist.

Parameters

filename	name of the DICOM file that contains the SOP instance or name of the DICOMDIR file that references the SOP instances to be sent
readMode	read mode passed to the DcmFileFormat::loadFile() method. If ERM_fileOnly, only the file meta information header is loaded, i.e. the behavior is identical to using ERM_metaOnly.
checkValues	flag indicating whether to check the UID values for validity and conformance. If OFFalse, only empty values are rejected.

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

◆ addDicomFilesFromDICOMDIR()

OFCondition DcmStorageSCU::addDicomFilesFromDICOMDIR	(	const OFFilename &	filename,
		const E_FileReadMode	readMode,
		const OFBool	checkValues
	)

protected

add SOP instances referenced from a given DICOMDIR to the list of instances to be transferred.

Please note that the referenced DICOM files are not loaded during this process. Only the relevant information contained in the DICOMDIR is used.

Parameters

filename	name of the DICOMDIR file that contains the references to SOP instances to be sent
readMode	read mode passed to the DcmFileFormat::loadFile() method when reading the referenced DICOM files. Not used for the DICOMDIR.
checkValues	flag indicating whether to check the UID values of the SOP instances to be added for validity and conformance. If OFFalse, only empty values are rejected.

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

◆ addPresentationContexts()

OFCondition DcmStorageSCU::addPresentationContexts ( )

add presentation contexts for all SOP instances in the transfer list, which were not yet sent (either successfully or unsuccessfully).

Initially, the internal list of presentation contexts is cleared. Then, the transfer list is iterated and a new presentation context is added for each SOP instance that cannot be sent using any of the previously added presentation contexts. If the maximum of 128 presentation contexts, which can be negotiated during a single association, is reached, this method returns and any subsequent call adds the next bunch of presentation contexts needed.

Returns: status, EC_Normal if successful, an error code otherwise. If no presentation contexts have been added, NET_EC_NoPresentationContextsDefined is returned. This code can, therefore, be used to check that all SOP instances from the transfer list have been negotiated and sent in previous calls.

◆ checkSOPInstance()

virtual OFCondition DcmStorageSCU::checkSOPInstance	(	const OFString &	sopClassUID,
		const OFString &	sopInstanceUID,
		const OFString &	transferSyntaxUID,
		const OFBool	checkValues
	)

protectedvirtual

check given SOP Class UID, SOP Instance UID and Transfer Syntax UID for validity and conformance to the DICOM standard.

For all UID values, the compliance with the requirements of the value representation "Unique Identifier" (UI) and value multiplicity is checked. For the SOP Class UID, it is also checked whether it is a known or at least a possible storage SOP class (either a standard or a private one). For the Transfer Syntax UID, it is checked whether it is known and generally supported. Further checks will be performed when the list of presentation contexts is created for the association negotiation. This method is called for each SOP instance that is added to the transfer list by one of the following methods: addDicomFile(), addDataset(), addDicomFilesFromDICOMDIR()

Parameters

sopClassUID	value of the SOP Class UID to be checked
sopInstanceUID	value of the SOP Instance UID to be checked
transferSyntaxUID	value of the Transfer Syntax UID to be checked
checkValues	flag indicating whether to check the UID values for validity and conformance. If OFFalse, only empty values are rejected.

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

◆ createReportFile()

OFCondition DcmStorageSCU::createReportFile ( const OFString & filename ) const

create a text file with a detailed report on the transfer of DICOM SOP instances.

In addition to a general header and some status information at the end (as generated by getStatusSummary()), a couple of basic details on each SOP instance in the transfer list are written to the file:

Consecutive number
Name of the DICOM file
SOP Instance UID
SOP Class UID (and associated name)
Transfer Syntax UID (and associated name)
Number of the association (that was used to transfer the instance)
Presentation Context ID (that was used to transfer the instance)
DIMSE Status (if instance was sent) or reason why it was not sent
Parameters

filename name of the text file in which the report is stored

Returns
status, EC_Normal if successful, an error code otherwise

◆ getAllowIllegalProposalMode()

OFBool DcmStorageSCU::getAllowIllegalProposalMode ( ) const

get mode that specifies whether to propose presentation contexts that do not contain the default transfer syntax although it is needed, which might result in a violation of the DICOM standard.

Returns: mode indicating whether illegal proposals are allowed or not

◆ getAssociationCounter()

unsigned long DcmStorageSCU::getAssociationCounter ( ) const

get value of the association counter.

This counter is initialized with 0 (that means no association exists) and increased by 1 for every new association. The counter is only reset when clear() is called.

Returns: value of the association counter

◆ getDecompressionMode()

E_DecompressionMode DcmStorageSCU::getDecompressionMode ( ) const

get mode that specifies whether or not compressed datasets are decompressed if needed, i.e. whether the transfer syntax of the dataset is changed for network transmission.

Returns: decompression mode. See definition of DcmStorageSCU::E_DecompressionMode for possible values.

◆ getHaltOnInvalidFileMode()

OFBool DcmStorageSCU::getHaltOnInvalidFileMode ( ) const

get mode that specifies whether to halt if an invalid file is encountered during batch processing (e.g. when adding SOP instances from a DICOMDIR) or whether to continue with the next SOP instance.

Returns: mode indicating whether to halt on invalid file or not

◆ getHaltOnUnsuccessfulStoreMode()

OFBool DcmStorageSCU::getHaltOnUnsuccessfulStoreMode ( ) const

get mode that specifies whether to halt if unsuccessful store encountered or whether to continue with the next SOP instance.

Returns: mode indicating whether to halt on unsuccessful store or not

◆ getMOVEOriginatorInfo()

OFBool DcmStorageSCU::getMOVEOriginatorInfo	(	OFString &	aeTitle,
		Uint16 &	messageID
	)		const

get C-MOVE originator information (if set)

Parameters

aeTitle	the AE title of the originating C-MOVE client. Empty if not set.
messageID	the message ID used within the originating C-MOVE request. 0 if not set.

Returns: OFTrue if either of both parameters is set

◆ getNumberOfSOPInstances()

size_t DcmStorageSCU::getNumberOfSOPInstances ( ) const

get number of SOP instances stored in the transfer list

Returns: number of SOP instances stored in the transfer list

◆ getNumberOfSOPInstancesToBeSent()

size_t DcmStorageSCU::getNumberOfSOPInstancesToBeSent ( ) const

get number of SOP instances that are to be sent (i.e. that are not yet sent).

Please note that internally the transfer list is iterated to determine this number, so depending on the size of the list it might take some time.

Returns: number of SOP instances that are to be sent

◆ getReadFromDICOMDIRMode()

OFBool DcmStorageSCU::getReadFromDICOMDIRMode ( ) const

get mode that specifies whether to read information on SOP instances to be sent from the DICOMDIR files that are added to the transfer list.

Returns: mode indicating whether to read from DICOMDIR files or not

◆ getStatusSummary()

void DcmStorageSCU::getStatusSummary ( OFString & summary ) const

get some status information on the overall sending process.

This text can for example be output to the logger (on the level at the user's option).

Parameters

summary reference to a string in which the summary is stored

◆ negotiateAssociation()

virtual OFCondition DcmStorageSCU::negotiateAssociation ( )

virtual

negotiate association by using presentation contexts and parameters as defined by earlier method calls.

If negotiation fails, there is no need to close the association or to do anything else with this class. In addition to the implementation inherited from the base class DcmSCU, this method also handles the case that none of the proposed presentation contexts was accepted. And, it also increases the association counter by 1 for each new association (including the ones that are not successful).

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

Reimplemented from DcmSCU.

◆ notifySOPInstanceSent()

virtual void DcmStorageSCU::notifySOPInstanceSent ( const TransferEntry & transferEntry )

protectedvirtual

this method is called each time after a SOP instance has been sent to a peer.

Therefore, the transfer entry passed to this method contains current and usually also complete information, e.g. the DIMSE status of the C-STORE response. This allows for counting the number of successful and failed transfers.

Parameters

transferEntry reference to current transfer entry that has been processed

◆ notifySOPInstanceToBeSent()

virtual void DcmStorageSCU::notifySOPInstanceToBeSent ( const TransferEntry & transferEntry )

protectedvirtual

this method is called each time before a SOP instance is sent to a peer.

Therefore, the transfer entry passed to this method does not yet contain all information.

Parameters

transferEntry reference to current transfer entry that will be processed

◆ removeAllSOPInstances()

void DcmStorageSCU::removeAllSOPInstances ( )

remove all SOP instances from the transfer list.

If an entry contains a reference to a DICOM dataset, this dataset is deleted if the handling mode HM_deleteAfterRemove was used to add it to the transfer list.

◆ removeSOPInstance()

OFCondition DcmStorageSCU::removeSOPInstance	(	const OFString &	sopClassUID,
		const OFString &	sopInstanceUID,
		const OFBool	allOccurrences = `OFTrue`
	)

remove a particular SOP instance from the transfer list.

If the corresponding entry contains a reference to a DICOM dataset, this dataset is deleted if the handling mode HM_deleteAfterRemove was used to add it to the transfer list.

Parameters

sopClassUID	SOP Class UID of the SOP instance to be removed
sopInstanceUID	SOP Instance UID of the SOP instance to be removed
allOccurrences	flag specifying whether to delete all occurrences of the SOP instance if it has been added to the list multiple times. If OFFalse, only the first occurrence is removed.

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

◆ resetSentStatus()

void DcmStorageSCU::resetSentStatus ( const OFBool sameAssociation = OFFalse )

reset the sent status for all SOP instances in the transfer list.

This allows for sending the same SOP instances again - on the same or a different association.

Parameters

sameAssociation flag indicating whether the same association will be used for the transfer as last time. If a different association will be used, also the presentation context IDs are set to 0 (undefined), which means that addPresentationContexts() has to be called again. Please make sure that all dataset pointers in the transfer list are still valid, i.e. the datasets have not been deleted.

◆ sendSOPInstances()

OFCondition DcmStorageSCU::sendSOPInstances ( )

send SOP instances to be transferred to the specified peer.

After the presentation contexts for the current association have been added and negotiated, the SOP instances that are to be sent on this association can be transferred with this method. Unless the corresponding mode is disabled using setHaltOnUnsuccessfulStoreMode(), the transfer is stopped on the first SOP instance that could not be "stored" successfully. Please note, however, that the DIMSE status is not checked for this purpose, i.e. the transfer is never stopped when the DIMSE status is different from 0x0000 (success). Each time a SOP instance from the transfer list has been processed, the virtual method notifySOPInstanceSent() is called, which can be overwritten by a derived class. The sending process can be stopped by overwriting shouldStopAfterCurrentSOPInstance() in a derived class. The sending process can be continued with the next SOP instance by calling sendSOPInstances() again.

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

◆ setAllowIllegalProposalMode()

void DcmStorageSCU::setAllowIllegalProposalMode ( const OFBool allowMode )

set mode that specifies whether to propose presentation contexts that do not contain the default transfer syntax, although it is needed, which might result in a violation of the DICOM standard.

For example, if a lossless compressed SOP instance is to be sent, there should be at least one presentation context for this SOP class that also proposes the default transfer syntax (Implicit VR Little Endian).

Note: Please note that support for CP-1704 has not been implemented yet, i.e. it is not checked whether the decompressed data cannot be encoded in the default transfer syntax because it would be too large, which would also waive this requirement.

Parameters

allowMode mode indicating whether illegal proposals are allowed or not (default: OFTrue, i.e. allowed)

◆ setDecompressionMode()

void DcmStorageSCU::setDecompressionMode ( const E_DecompressionMode decompressionMode )

set mode that specifies whether or not compressed datasets are decompressed if needed, i.e. whether the transfer syntax of the dataset is changed for network transmission.

Parameters

decompressionMode decompression mode. See definition of DcmStorageSCU::E_DecompressionMode for both possible values and the default value.

◆ setHaltOnInvalidFileMode()

void DcmStorageSCU::setHaltOnInvalidFileMode ( const OFBool haltMode )

set mode that specifies whether to halt if an invalid file is encountered during batch processing (e.g. when adding SOP instances from a DICOMDIR) or whether to continue with the next SOP instance.

Parameters

haltMode mode indicating whether to halt or not (default: OFTrue, i.e. halt)

◆ setHaltOnUnsuccessfulStoreMode()

void DcmStorageSCU::setHaltOnUnsuccessfulStoreMode ( const OFBool haltMode )

set mode that specifies whether to halt if unsuccessful store encountered or whether to continue with the next SOP instance.

Parameters

haltMode mode indicating whether to halt or not (default: OFTrue, i.e. halt)

◆ setMOVEOriginatorInfo()

void DcmStorageSCU::setMOVEOriginatorInfo	(	const OFString &	aeTitle = `""`,
		const Uint16	messageID = `0`
	)

set C-MOVE originator information.

If the C-STORE operation was initiated by a client's C-MOVE request, it is possible to convey the C-MOVE originating information (AE title and the message ID of the corresponding C-MOVE message) as part of the C-STORE messages in order to inform the C-STORE receiver (Storage SCP) about the original sender (Move SCU).

Parameters

aeTitle	the AE title of the originating C-MOVE client. If empty, none is sent.
messageID	message ID of the originating C-MOVE request. If 0, none is sent.

◆ setReadFromDICOMDIRMode()

void DcmStorageSCU::setReadFromDICOMDIRMode ( const OFBool readMode )

set mode that specifies whether to read information on SOP instances to be sent from the DICOMDIR files that are added to the transfer list.

If this mode is disabled, a DICOMDIR file is treated like any other input file. If this mode is enabled, a DICOMDIR file is not added to the transfer list, but the DICOM files referenced from it are.

Parameters

readMode mode indicating whether to read from DICOMDIR files or not (default: OFFalse, i.e. do not read)

◆ shouldStopAfterCurrentSOPInstance()

virtual OFBool DcmStorageSCU::shouldStopAfterCurrentSOPInstance ( )

protectedvirtual

this method is called each time after a SOP instance is sent to a peer.

If the return value is OFTrue, the SCU will stop the sending process after the current SOP instance. This could for example make sense when transferring SOP instances due to a C-MOVE request, which is externally canceled by a C-CANCEL message. The default implementation always returns OFFalse. A derived class may change this behavior.

Returns: OFTrue if sending should stop after current SOP instance, OFFalse otherwise.

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

dcmnet/include/dcmtk/dcmnet/dstorscu.h

Classes

Public Types

Public Member Functions

Protected Member Functions

Private Member Functions

Private Attributes

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ E_DecompressionMode

◆ E_HandlingMode

Member Function Documentation

◆ addDataset()

◆ addDicomFile()

◆ addDicomFilesFromDICOMDIR()

◆ addPresentationContexts()

◆ checkSOPInstance()

◆ createReportFile()

◆ getAllowIllegalProposalMode()

◆ getAssociationCounter()

◆ getDecompressionMode()

◆ getHaltOnInvalidFileMode()

◆ getHaltOnUnsuccessfulStoreMode()

◆ getMOVEOriginatorInfo()

◆ getNumberOfSOPInstances()

◆ getNumberOfSOPInstancesToBeSent()

◆ getReadFromDICOMDIRMode()

◆ getStatusSummary()

◆ negotiateAssociation()

◆ notifySOPInstanceSent()

◆ notifySOPInstanceToBeSent()

◆ removeAllSOPInstances()

◆ removeSOPInstance()

◆ resetSentStatus()

◆ sendSOPInstances()

◆ setAllowIllegalProposalMode()

◆ setDecompressionMode()

◆ setHaltOnInvalidFileMode()

◆ setHaltOnUnsuccessfulStoreMode()

◆ setMOVEOriginatorInfo()

◆ setReadFromDICOMDIRMode()

◆ shouldStopAfterCurrentSOPInstance()