DcmStorageSCU Class Reference

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

Inheritance diagram for DcmStorageSCU:

List of all members.

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.
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	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 OFString &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.
OFCondition	releaseAssociation ()
	release the current association by sending an A-RELEASE request to the SCP.
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.
Protected Member Functions
OFCondition	addDicomFilesFromDICOMDIR (const OFString &filename, const E_FileReadMode readMode, const OFBool checkValues)
	add SOP instances referenced from a given DICOMDIR to the list of instances to be transferred.
Static Protected Member Functions
static OFCondition	getSOPInstanceFromFile (const OFString &filename, OFString &sopClassUID, OFString &sopInstanceUID, OFString &transferSyntaxUID, const E_FileReadMode readMode)
	get SOP Class UID, SOP Instance UID and Transfer Syntax UID from a DICOM file.
static OFCondition	getSOPInstanceFromDataset (DcmDataset *dataset, const E_TransferSyntax datasetXfer, OFString &sopClassUID, OFString &sopInstanceUID, OFString &transferSyntaxUID)
	get SOP Class UID, SOP Instance UID and Transfer Syntax UID from a DICOM dataset.
static 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.
Private Member Functions
	OFListIterator (TransferEntry *) CurrentTransferEntry
	iterator pointing to the current entry in the list of SOP instances to be transferred
	DcmStorageSCU (const DcmStorageSCU &)
DcmStorageSCU &	operator= (const DcmStorageSCU &)
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
OFList< TransferEntry * >	TransferList
	list of SOP instances to be transferred

---

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

---

Member Enumeration Documentation

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

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 is has been removed from the transfer list

---

Member Function Documentation

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

OFCondition DcmStorageSCU::addDicomFile	(	const OFString &	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

OFCondition DcmStorageSCU::addDicomFilesFromDICOMDIR	(	const OFString &	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

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.

static OFCondition DcmStorageSCU::checkSOPInstance	(	const OFString &	sopClassUID,
		const OFString &	sopInstanceUID,
		const OFString &	transferSyntaxUID,
		const OFBool	checkValues
	)		[static, protected]

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.

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

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

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

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

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 E_DecompressionMode for possible values.

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

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

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

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

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

static OFCondition DcmStorageSCU::getSOPInstanceFromDataset	(	DcmDataset *	dataset,
		const E_TransferSyntax	datasetXfer,
		OFString &	sopClassUID,
		OFString &	sopInstanceUID,
		OFString &	transferSyntaxUID
	)		[static, protected]

get SOP Class UID, SOP Instance UID and Transfer Syntax UID from a DICOM dataset.

The first two UID values are directly copied from the dataset. The latter is either taken from the parameter 'datasetXfer' or, if it is unknown, determined automatically from the dataset (if possible).

Parameters:

dataset	DICOM dataset from which the SOP Class UID and SOP Instance UID values are retrieved
datasetXfer	transfer syntax of the dataset (if known, otherwise it is determined automatically)
sopClassUID	variable in which the value of the SOP Class UID is stored
sopInstanceUID	variable in which the value of the SOP Instance UID is stored
transferSyntaxUID	variable in which the value of the Transfer Syntax UID is stored

Returns:

status, EC_Normal if successful, an error code otherwise

static OFCondition DcmStorageSCU::getSOPInstanceFromFile	(	const OFString &	filename,
		OFString &	sopClassUID,
		OFString &	sopInstanceUID,
		OFString &	transferSyntaxUID,
		const E_FileReadMode	readMode
	)		[static, protected]

get SOP Class UID, SOP Instance UID and Transfer Syntax UID from a DICOM file.

The first two UID values are either copied from the meta-header (preferred) or from the dataset. The latter is either copied from the meta-header (preferred) or determined automatically (if possible).

Parameters:

filename	name of the DICOM file from which the SOP Class UID and SOP Instance UID values are retrieved
sopClassUID	variable in which the value of the SOP Class UID is stored
sopInstanceUID	variable in which the value of the SOP Instance UID is stored
transferSyntaxUID	variable in which the value of the Transfer Syntax UID is stored
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.

Returns:

status, EC_Normal if successful, an error code otherwise

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

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.

OFCondition DcmStorageSCU::releaseAssociation

(

)

release 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 DcmSCU::initNetwork() and DcmSCU::negotiateAssociation().

Returns:

status, EC_Normal if successful, an error code otherwise

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.

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

void DcmStorageSCU::resetSentStatus

(

const OFBool

sameAssociation = OFFalse

)

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

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

Parameters:

sameAssociation

flag indicating whether the same assocation 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.

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

Returns:

status, EC_Normal if successful, an error code otherwise

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

Parameters:

allowMode

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

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 E_DecompressionMode for both possible values and the default value.

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)

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)

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)

---

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

• dcmnet/include/dcmtk/dcmnet/dstorscu.h