DCMTK  Version 3.6.4
OFFIS DICOM Toolkit
Classes | Public Types | Public Member Functions | Protected Member Functions | Private Member Functions | Private Attributes | List of all members
DcmStorageSCU Class Reference

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. More...
 
size_t getNumberOfSOPInstances () const
 get number of SOP instances stored in the transfer list More...
 
size_t getNumberOfSOPInstancesToBeSent () const
 get number of SOP instances that are to be sent (i.e. that are not yet sent). More...
 
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. More...
 
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. More...
 
OFBool getHaltOnUnsuccessfulStoreMode () const
 get mode that specifies whether to halt if unsuccessful store encountered or whether to continue with the next SOP instance. More...
 
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. More...
 
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. More...
 
OFBool getMOVEOriginatorInfo (OFString &aeTitle, Uint16 &messageID) const
 get C-MOVE originator information (if set) More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
void setMOVEOriginatorInfo (const OFString &aeTitle="", const Uint16 messageID=0)
 set C-MOVE originator information. More...
 
void resetSentStatus (const OFBool sameAssociation=OFFalse)
 reset the sent status for all SOP instances in the transfer list. More...
 
void removeAllSOPInstances ()
 remove all SOP instances from the transfer list. More...
 
OFCondition removeSOPInstance (const OFString &sopClassUID, const OFString &sopInstanceUID, const OFBool allOccurrences=OFTrue)
 remove a particular SOP instance from the transfer list. More...
 
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. More...
 
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. More...
 
OFCondition addPresentationContexts ()
 add presentation contexts for all SOP instances in the transfer list, which were not yet sent (either successfully or unsuccessfully). More...
 
virtual OFCondition negotiateAssociation ()
 negotiate association by using presentation contexts and parameters as defined by earlier method calls. More...
 
OFCondition sendSOPInstances ()
 send SOP instances to be transferred to the specified peer. More...
 
void getStatusSummary (OFString &summary) const
 get some status information on the overall sending process. More...
 
OFCondition createReportFile (const OFString &filename) const
 create a text file with a detailed report on the transfer of DICOM SOP instances. More...
 
- 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. More...
 
virtual OFCondition initNetwork ()
 Initialize network, i.e. prepare for association negotiation. More...
 
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. 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 (host name 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 OFStringgetAETitle () const
 Returns the SCU's own configured AE title. More...
 
const OFStringgetPeerHostName () const
 Returns the SCP's (peer's) host configured. More...
 
const OFStringgetPeerAETitle () 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 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. More...
 
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. More...
 
virtual void notifySOPInstanceToBeSent (const TransferEntry &transferEntry)
 this method is called each time before a SOP instance is sent to a peer. More...
 
virtual void notifySOPInstanceSent (const TransferEntry &transferEntry)
 this method is called each time after a SOP instance has been sent to a peer. More...
 
virtual OFBool shouldStopAfterCurrentSOPInstance ()
 this method is called each time after a SOP instance is sent to a peer. More...
 
- 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. 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...
 

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. More...
 
static void callbackRECEIVEProgress (void *callbackContext, unsigned long byteCount)
 Callback function used for receiving DIMSE messages. More...
 

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

◆ 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

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
datasetDICOM dataset that contains the SOP instance to be sent
datasetXfertransfer syntax of the dataset (determined automatically if unknown, which is also the default)
handlingModemode 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!
checkValuesflag 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
filenamename of the DICOM file that contains the SOP instance or name of the DICOMDIR file that references the SOP instances to be sent
readModeread 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.
checkValuesflag 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
filenamename of the DICOMDIR file that contains the references to SOP instances to be sent
readModeread mode passed to the DcmFileFormat::loadFile() method when reading the referenced DICOM files. Not used for the DICOMDIR.
checkValuesflag 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
sopClassUIDvalue of the SOP Class UID to be checked
sopInstanceUIDvalue of the SOP Instance UID to be checked
transferSyntaxUIDvalue of the Transfer Syntax UID to be checked
checkValuesflag 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
    filenamename 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
aeTitlethe AE title of the originating C-MOVE client. Empty if not set.
messageIDthe 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
summaryreference 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
transferEntryreference 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
transferEntryreference 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
sopClassUIDSOP Class UID of the SOP instance to be removed
sopInstanceUIDSOP Instance UID of the SOP instance to be removed
allOccurrencesflag 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
sameAssociationflag 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
allowModemode 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
decompressionModedecompression 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
haltModemode 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
haltModemode 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
aeTitlethe AE title of the originating C-MOVE client. If empty, none is sent.
messageIDmessage 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
readModemode 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:


Generated on Thu Nov 29 2018 for DCMTK Version 3.6.4 by Doxygen 1.8.14