DCMTK: DcmStorageSCU Class Reference

DCMTK Version 3.6.9 OFFIS DICOM Toolkit

Loading...
Searching...
No Matches
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.
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

References EXS_Unknown, and HM_compactAfterSend.

## ◆ 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

References ERM_fileOnly.

## ◆ 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

Generated on Wed Apr 30 2025 for DCMTK Version 3.6.9 by Doxygen 1.13.2