DCMTK Version 3.7.0 OFFIS DICOM Toolkit

Public Member Functions | Protected Member Functions | Static Protected Member Functions | Private Member Functions | Private Attributes | Friends | List of all members
DcmSCP Class Reference

Base class for implementing a DICOM Service Class Provider (SCP). More...

Inheritance diagram for DcmSCP:

## Public Member Functions
| DcmSCP ()
| Constructor. More...
virtual | ~DcmSCP ()
| Virtual destructor, frees internal memory.
virtual OFCondition | listen ()
| Starts providing the implemented services to SCUs. More...
virtual OFCondition | openListenPort ()
| Alternative interface to providing the implemented services to SCUs. More...
virtual OFCondition | acceptAssociations ()
| Alternative interface to providing the implemented services to SCUs. More...
OFCondition | setEnableVerification (const OFString &profile="DEFAULT")
| Enables negotiation of the Verification SOP Class. More...
virtual OFCondition | addPresentationContext (const OFString &abstractSyntax, const OFList< OFString > &xferSyntaxes, const T_ASC_SC_ROLE requestorRole=ASC_SC_ROLE_DEFAULT, const OFString &profile="DEFAULT")
| Add abstract syntax to presentation contexts the SCP is able to negotiate with SCUs. More...
void | setPort (const Uint16 port)
| Set SCP's TCP/IP listening port. More...
void | setAETitle (const OFString &aetitle)
| Set AE title of the server. More...
void | setRespondWithCalledAETitle (const OFBool useCalled)
| Set SCP to use the called AE title from the SCU request for the response, i.e. the SCP will always respond with setting it's own name to the one the SCU used for calling. More...
virtual OFCondition | loadAssociationCfgFile (const OFString &assocFile)
| Loads association configuration file. More...
virtual OFCondition | setAndCheckAssociationProfile (const OFString &profileName)
| If an association profile should be selected, either by loading an association configuration file or using the addPresentationContext() function, one of those can be selected and checked for validity using this method. More...
void | forceAssociationRefuse (const OFBool doRefuse)
| Force every association request to be refused by SCP, no matter what the SCU is offering. More...
void | setMaxReceivePDULength (const Uint32 maxRecPDU)
| Set maximum PDU size the SCP is able to receive. More...
void | setConnectionBlockingMode (const DUL_BLOCKOPTIONS blockingMode)
| Set whether waiting for a TCP/IP connection should be blocking or non-blocking. More...
void | setDIMSEBlockingMode (const T_DIMSE_BlockingMode blockingMode)
| Set whether DIMSE messaging should be blocking or non-blocking. More...
void | setDIMSETimeout (const Uint32 dimseTimeout)
| Set the timeout to be waited for incoming DIMSE message packets. More...
void | setACSETimeout (const Uint32 acseTimeout)
| Set the timeout used during ACSE messaging protocol. More...
void | setConnectionTimeout (const Uint32 timeout)
| Set the timeout that should be waited for connection requests. More...
void | setVerbosePCMode (const OFBool mode)
| Set whether to show presentation contexts in verbose or debug mode. More...
void | setHostLookupEnabled (const OFBool mode)
| Enables or disables looking up the host name from a connecting system. 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...
void | setAlwaysAcceptDefaultRole (const OFBool enabled)
| Option to always accept a default role as association acceptor. More...
Uint16 | getPort () const
| Returns TCP/IP port number SCP listens for new connection requests. More...
const OFString & | getAETitle () const
| Returns SCP's own AE title. More...
OFBool | getRespondWithCalledAETitle () const
| Returns whether SCP uses the called AE title from SCU requests to respond to connection requests instead of a configured AE title. More...
OFBool | getRefuseAssociation () const
| Returns whether SCP should refuse any association request no matter what the SCU proposes. More...
Uint32 | getMaxReceivePDULength () const
| Returns maximum PDU length configured to be received by SCP. More...
DUL_BLOCKOPTIONS | getConnectionBlockingMode () const
| Returns whether receiving of TCP/IP connection requests is done in blocking or unblocking mode. More...
T_DIMSE_BlockingMode | getDIMSEBlockingMode () const
| Returns whether receiving of DIMSE messages is done in blocking or unblocking mode. More...
Uint32 | getDIMSETimeout () const
| Returns DIMSE timeout (only applicable in blocking mode) More...
Uint32 | getACSETimeout () const
| Returns ACSE timeout. More...
Uint32 | getConnectionTimeout () const
| Returns connection timeout. 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 | getHostLookupEnabled () const
| Returns whether a connecting system's host name is looked up. 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...
virtual DcmSCPConfig & | getConfig ()
| Get access to the configuration of the SCP. More...
virtual OFCondition | setConfig (const DcmSCPConfig &config)
| Set the DcmSCPConfig object to use for configuring this DcmSCP object. More...
OFBool | isConnected () const
| Returns whether SCP is currently connected. More...
Uint16 | numAssociations () const
| Returns number of associations currently running. More...
OFString | getCalledAETitle () const
| Returns AE title the SCU used as called AE title in association request. More...
OFString | getPeerAETitle () const
| Returns AE title (calling AE title) the SCU used for association request. More...
OFString | getPeerIP () const
| Returns IP address of connected SCU. More...
Uint32 | getPeerMaxPDULength () const
| Returns maximum PDU size the communication peer (i.e. the SCU) is able to receive. More...

## Protected Member Functions
void | findPresentationContext (const T_ASC_PresentationContextID presID, OFString &abstractSyntax, OFString &transferSyntax)
| This call returns the presentation context belonging to the given presentation context ID. More...
virtual OFCondition | abortAssociation ()
| Aborts the current association by sending an A-ABORT request to the SCU. More...
virtual OFCondition | handleIncomingCommand (T_DIMSE_Message *incomingMsg, const DcmPresentationContextInfo &presInfo)
| Handle incoming command set and react accordingly, e.g. sending response via DIMSE_sendXXXResponse(). More...
virtual void | notifyAssociationRequest (const T_ASC_Parameters &params, DcmSCPActionType &desiredAction)
| Overwrite this function to be notified about an incoming association request. More...
virtual OFBool | checkCalledAETitleAccepted (const OFString &calledAE)
| Overwrite this function if called AE title should undergo custom checking. More...
virtual OFBool | checkCallingAETitleAccepted (const OFString &callingAE)
| Overwrite this function if calling AE title should undergo checking. More...
virtual OFBool | checkCallingHostAccepted (const OFString &hostOrIP)
| Overwrite this function if calling IP / host name should undergo checking. More...
virtual void | notifyAssociationAcknowledge ()
| Overwrite this function to be notified about an incoming association request. More...
virtual void | notifyReleaseRequest ()
| Overwrite this function to be notified about an incoming association release request. More...
virtual void | notifyAbortRequest ()
| Overwrite this function to be notified about an incoming association abort request. More...
virtual void | notifyAssociationTermination ()
| Overwrite this function to be notified when an association is terminated. More...
virtual void | notifyConnectionTimeout ()
| Overwrite this function to be notified about a connection timeout in non-blocking mode (see setConnectionBlockingMode() and setConnectionTimeout() methods). More...
virtual void | notifyDIMSEError (const OFCondition &cond)
| Overwrite this function to be notified when a DIMSE error occurs. 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 OFBool | stopAfterCurrentAssociation ()
| This method can be used to return from the listen() loop in a controlled way. More...
virtual OFBool | stopAfterConnectionTimeout ()
| This method can be used to return from the listen() loop in a controlled way. More...
virtual OFCondition | handleECHORequest (T_DIMSE_C_EchoRQ &reqMessage, const T_ASC_PresentationContextID presID)
| Standard handler for Verification Service Class (DICOM Echo). More...
virtual OFCondition | handleSTORERequest (T_DIMSE_C_StoreRQ &reqMessage, const T_ASC_PresentationContextID presID, DcmDataset *&reqDataset)
| Receive C-STORE request on the currently opened association, store the accompanying dataset in memory and send a corresponding response. More...
virtual OFCondition | receiveSTORERequest (T_DIMSE_C_StoreRQ &reqMessage, const T_ASC_PresentationContextID presID, DcmDataset *&reqDataset)
| Receive C-STORE request (and store accompanying dataset in memory). More...
virtual OFCondition | receiveSTORERequest (T_DIMSE_C_StoreRQ &reqMessage, const T_ASC_PresentationContextID presID, const OFString &filename)
| Receive C-STORE request (and store accompanying dataset directly to file). More...
virtual OFCondition | sendSTOREResponse (const T_ASC_PresentationContextID presID, const T_DIMSE_C_StoreRQ &reqMessage, const Uint16 rspStatusCode)
| Respond to the C-STORE request (with details from the request message) More...
virtual OFCondition | sendSTOREResponse (const T_ASC_PresentationContextID presID, const Uint16 messageID, const OFString &sopClassUID, const OFString &sopInstanceUID, const Uint16 rspStatusCode, DcmDataset *statusDetail=NULL)
| Respond to the C-STORE request (with given details) More...
virtual Uint16 | checkSTORERequest (T_DIMSE_C_StoreRQ &reqMessage, DcmDataset *reqDataset)
| Check given C-STORE request and dataset for validity. More...
virtual OFCondition | receiveFINDRequest (T_DIMSE_C_FindRQ &reqMessage, const T_ASC_PresentationContextID presID, DcmDataset *&reqDataset)
| Receive C-FIND request. More...
virtual OFCondition | handleFINDRequest (T_DIMSE_C_FindRQ &reqMessage, const T_ASC_PresentationContextID presID, DcmDataset *&reqDataset)
| Handle C-FIND request. More...
virtual OFCondition | sendFINDResponse (const T_ASC_PresentationContextID presID, const Uint16 messageID, const OFString &sopClassUID, DcmDataset *rspDataset, const Uint16 rspStatusCode, DcmDataset *statusDetail=NULL)
| Respond to the C-FIND request. More...
virtual OFCondition | checkForCANCEL (T_ASC_PresentationContextID presID, const Uint16 messageID)
| Check for C-CANCEL. More...
virtual OFCondition | receiveMOVERequest (T_DIMSE_C_MoveRQ &reqMessage, const T_ASC_PresentationContextID presID, DcmDataset *&reqDataset, OFString &moveDest)
| Receive C-MOVE request on the currently active association. More...
virtual OFCondition | handleMOVERequest (T_DIMSE_C_MoveRQ &reqMessage, const T_ASC_PresentationContextID presID, DcmDataset *&reqDataset, OFString &moveDest)
| Receive C-MOVE request on the currently active association. More...
virtual OFCondition | sendMOVEResponse (const T_ASC_PresentationContextID presID, const Uint16 messageID, const OFString &sopClassUID, DcmDataset *rspDataset, const Uint16 rspStatusCode, DcmDataset *statusDetail=NULL, const Uint16 numRemain=0, const Uint16 numComplete=0, const Uint16 numFail=0, const Uint16 numWarn=0)
| Respond to the C-MOVE request. More...
virtual OFCondition | receiveACTIONRequest (T_DIMSE_N_ActionRQ &reqMessage, const T_ASC_PresentationContextID presID, DcmDataset *&reqDataset, Uint16 &actionTypeID)
| Receive N-ACTION request on the currently opened association. More...
virtual OFCondition | handleACTIONRequest (T_DIMSE_N_ActionRQ &reqMessage, const T_ASC_PresentationContextID presID, DcmDataset *&reqDataset, Uint16 &actionTypeID)
| Receive N-ACTION request on the currently opened association. More...
virtual OFCondition | sendACTIONResponse (const T_ASC_PresentationContextID presID, const Uint16 messageID, const OFString &sopClassUID, const OFString &sopInstanceUID, const Uint16 rspStatusCode)
| Respond to the N-ACTION request. More...
virtual OFCondition | handleEVENTREPORTRequest (T_DIMSE_N_EventReportRQ &reqMessage, const T_ASC_PresentationContextID presID, DcmDataset *&reqDataset, Uint16 &eventTypeID)
| Receive N-EVENT-REPORT request on the currently opened association and send a corresponding response. More...
virtual OFCondition | sendEVENTREPORTRequest (const T_ASC_PresentationContextID presID, const OFString &sopInstanceUID, const Uint16 messageID, const Uint16 eventTypeID, DcmDataset *reqDataset, Uint16 &rspStatusCode)
| Send N-EVENT-REPORT request on the current association and receive a corresponding response. More...
virtual Uint16 | checkEVENTREPORTRequest (T_DIMSE_N_EventReportRQ &reqMessage, DcmDataset *reqDataset)
| Check given N-EVENT-REPORT request and dataset for validity. More...
virtual OFCondition | waitForAssociationRQ (T_ASC_Network *network)
| This function takes care of receiving, negotiating and accepting/refusing an association request. More...
virtual OFCondition | processAssociationRQ ()
| Actually process association request. More...
virtual OFCondition | negotiateAssociation ()
| This function checks all presentation contexts proposed by the SCU whether they are supported or not. More...
virtual void | refuseAssociation (const DcmRefuseReasonType reason)
| This function takes care of refusing an association request. More...
virtual void | handleAssociation ()
| This function takes care of handling the other DICOM application's request. More...
OFCondition | sendDIMSEMessage (const T_ASC_PresentationContextID presID, T_DIMSE_Message *message, DcmDataset *dataObject, DcmDataset *statusDetail=NULL, DcmDataset **commandSet=NULL)
| Send a DIMSE command and possibly also a dataset from a data object via network to another DICOM application. More...
OFCondition | receiveDIMSECommand (T_ASC_PresentationContextID *presID, T_DIMSE_Message *message, 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)
| Receive one dataset (of instance data) via network from another DICOM application. More...
OFCondition | receiveSTORERequestDataset (T_ASC_PresentationContextID *presID, T_DIMSE_C_StoreRQ &reqMessage, const OFString &filename)
| Receive one C-STORE request dataset via network from another DICOM application and store it directly to file (i.e. exactly as received without any conversions) More...

## Static Protected Member Functions
static DUL_PRESENTATIONCONTEXT * | findPresentationContextID (LST_HEAD *head, T_ASC_PresentationContextID presentationContextID)
| Helper function to return presentation context information by given presentation context ID. More...
static OFBool | getPresentationContextInfo (const T_ASC_Association *assoc, const Uint8 presID, DcmPresentationContextInfo &presInfo)
| Helper function to return presentation context information by given presentation context ID. More...
static OFBool | addStatusDetail (DcmDataset **statusDetail, const DcmElement *elem)
| Add given element to existing status detail object or create new one. More...
static void | callbackSENDProgress (void *callbackContext, unsigned long byteCount)
| Callback function used for sending DIMSE messages. More...
static void | callbackRECEIVEProgress (void *callbackContext, unsigned long byteCount)
| Callback function used for receiving DIMSE messages. More...

## Private Member Functions
void | dropAndDestroyAssociation ()
| Drops association and clears internal structures to free memory.
| DcmSCP (const DcmSCP &src)
| Private undefined copy constructor. More...
DcmSCP & | operator= (const DcmSCP &src)
| Private undefined assignment operator. More...

## Private Attributes
T_ASC_Network * | m_network
| Network instance run by this SCP.
T_ASC_Association * | m_assoc
| Current association run by this SCP.
DcmSharedSCPConfig | m_cfg
| SCP configuration. More...

## Friends
class | DcmThreadSCP
| DcmThreadSCP needs access to configuration (m_cfg), at least.

## Detailed Description

Base class for implementing a DICOM Service Class Provider (SCP).

Derived classes can add the presentation contexts they want to support, set further parameters (port, peer host name, etc. as desired) and then call DcmSCP's listen() method to start the server. For incoming associations and DIMSE messages, a derived class can define the behavior of the server. The DcmSCP base class does not support any presentation contexts per default. In particular the Verification SOP class which every SCP must support, is not added automatically in order to give the user full control over the supported list of presentation contexts. However, if this class should negotiate Verification, call setEnableVerification(). In that case DcmSCP will also respond to related C-ECHO requests. Note that this cannot be reverted.

## Constructor & Destructor Documentation

## ◆ DcmSCP() [1/2]

DcmSCP::DcmSCP | ( |  | ) |

Constructor.

Initializes internal member variables.

## ◆ DcmSCP() [2/2]

DcmSCP::DcmSCP | ( | const DcmSCP & | src | ) |
| private

Private undefined copy constructor.

Shall never be called.

Parameters

  src | Source object

## Member Function Documentation

## ◆ abortAssociation()

virtual OFCondition DcmSCP::abortAssociation | ( |  | ) |
| protected virtual

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

This method allows derived classes to abort an association in case of severe errors.

Returns
  status, EC_Normal if successful, an error code otherwise

## ◆ acceptAssociations()

virtual OFCondition DcmSCP::acceptAssociations | ( |  | ) |
| virtual

Alternative interface to providing the implemented services to SCUs.

This method should be called after a call to openListenPort().

Returns
  The result. Per default, the method only returns in case of fatal errors. See documentation of listen() method on how to stop listening in a controlled way.

## ◆ addPresentationContext()

virtual OFCondition DcmSCP::addPresentationContext | ( | const OFString & | abstractSyntax,
|  | const OFList< OFString > & | xferSyntaxes,
|  | const T_ASC_SC_ROLE | requestorRole = `ASC_SC_ROLE_DEFAULT`,
|  | const OFString & | profile = `"DEFAULT"`
| ) |  |
| virtual

Add abstract syntax to presentation contexts the SCP is able to negotiate with SCUs.

Parameters

  abstractSyntax | [in] The UID of the abstract syntax (e.g. SOP class) to add
  xferSyntaxes | [in] List of transfer syntaxes (UIDs) that should be supported for the given abstract syntax name
  requestorRole | [in] The role to be negotiated. This denotes the role of the the association requestor that this instance should accept, i.e. if set to ASC_SC_ROLE_SCP it means that the association requestor is allowed to negotiate the SCP role, thus, that this DcmSCP instance will be playing the SCU role for this abstract syntax. The default role (ASC_SC_ROLE_DEFAULT) implicates that this DcmSCP instance will be allowed to play the SCP role only, i.e. it will acknowledge such an explicit SCU role request, but also it will accept a proposal for the abstract syntax with no explicit role being proposed at all (since per default the requestor is SCU and the acceptor SCP).
  profile | [in] The profile the abstract syntax should be added to. The default is to add it to the DcmSCP's internal standard profile called "DEFAULT".

Returns
  EC_Normal if adding was successful, an error code otherwise

## ◆ addStatusDetail()

static OFBool DcmSCP::addStatusDetail | ( | DcmDataset ** | statusDetail,
|  | const DcmElement * | elem
| ) |  |
| static protected

Add given element to existing status detail object or create new one.

Parameters

  statusDetail | The status detail to add the element to. Status detail is information additional to the DIMSE status code which can be provided for some DIMSE messages. If NULL is provided, a new status detail object is created and returned. All status detail attributes need to have the VR AT or LO which is also checked by the underlying routine.
  elem | The element to be copied into the status detail.

Returns
  OFTrue if status detail was successfully added, OFFalse otherwise.

## ◆ callbackRECEIVEProgress()

static void DcmSCP::callbackRECEIVEProgress | ( | void * | callbackContext,
|  | unsigned long | byteCount
| ) |  |
| static protected

Callback function used for receiving DIMSE messages.

Parameters

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

## ◆ callbackSENDProgress()

static void DcmSCP::callbackSENDProgress | ( | void * | callbackContext,
|  | unsigned long | byteCount
| ) |  |
| static protected

Callback function used for sending DIMSE messages.

Parameters

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

## ◆ checkCalledAETitleAccepted()

virtual OFBool DcmSCP::checkCalledAETitleAccepted | ( | const OFString & | calledAE | ) |
| protected virtual

Overwrite this function if called AE title should undergo custom checking.

If OFTrue is returned, the AE title is accepted and processing is continued. In case of OFFalse, the SCP will refuse the incoming association with error "Called Application Entity Title Not Recognized".

The standard handler always returns true, if setRespondWithCalledAETitle() has been enabled, i.e. DcmSCP will respond with the AE Title the remote AE used for DcmSCP as the "Called AE Title". This is DcmSCP's default behaviour and in particular good for testing.

If setRespondWithCalledAETitle() is set to false, DcmSCP will check whether the Called AE Title used by the remote AE matches the one configured for DcmSCP. The default value is "DCMTK_SCP" and can be changed calling setAETitle().

Parameters

  calledAE | The called AE title the SCU used that should be checked

Returns
  OFTrue, if AE title is accepted, OFFalse otherwise

## ◆ checkCallingAETitleAccepted()

virtual OFBool DcmSCP::checkCallingAETitleAccepted | ( | const OFString & | callingAE | ) |
| protected virtual

Overwrite this function if calling AE title should undergo checking.

If OFTrue is returned, the AE title is accepted and processing is continued. In case of OFFalse, the SCP will refuse the incoming association with error "Calling Application Entity Title Not Recognized". The standard handler always returns OFTrue.

Parameters

  callingAE | The calling AE title the SCU used that should be checked

Returns
  OFTrue, if AE title is accepted, OFFalse otherwise

## ◆ checkCallingHostAccepted()

virtual OFBool DcmSCP::checkCallingHostAccepted | ( | const OFString & | hostOrIP | ) |
| protected virtual

Overwrite this function if calling IP / host name should undergo checking.

If OFTrue is returned, the host is accepted and processing is continued. In case of OFFalse, the SCP will refuse the incoming association with an error. The standard handler always returns OFTrue.

Parameters

  hostOrIP | The IP of the client to check.

Returns
  OFTrue, if IP/host is accepted, OFFalse otherwise

## ◆ checkEVENTREPORTRequest()

virtual Uint16 DcmSCP::checkEVENTREPORTRequest | ( | T_DIMSE_N_EventReportRQ & | reqMessage,
|  | DcmDataset * | reqDataset
| ) |  |
| protected virtual

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

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

Parameters

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

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

## ◆ checkForCANCEL()

virtual OFCondition DcmSCP::checkForCANCEL | ( | T_ASC_PresentationContextID | presID,
|  | const Uint16 | messageID
| ) |  |
| protected virtual

Check for C-CANCEL.

This is needed for example for a Query/Retrieve server that is in the middle of returning C-FIND responses to a client and has to perform a regular check whether the client sent a C-CANCEL in order to stop receiving C-FIND responses.

Parameters

  presID | [in] The presentation context ID where C-CANCEL is expected.
  messageID | [in] The "message ID responded to" that the client is expected to use (usually this is the message ID used in the original FIND/GET/MOVE request).

Returns
  EC_Normal, if C-CANCEL was received. DIMSE_NODATAAVAILABLE if no DIMSE message (or anything) was received from the client. DIMSEC_UNEXPECTEDREQUEST if command is received but it is not a C-CANCEL message, or the message ID used by client is wrong (message ID must be the one from the original FIND/MOVE/GET request). DIMSEC_INVALIDPRESENTATIONCONTEXTID if the wrong presentation context (ID) was used for sending. Other low level errors (e.g. DIMSEC_UNEXPECTEDPDVTYPE) could be returned, too.

## ◆ checkSTORERequest()

virtual Uint16 DcmSCP::checkSTORERequest | ( | T_DIMSE_C_StoreRQ & | reqMessage,
|  | DcmDataset * | reqDataset
| ) |  |
| protected virtual

Check given C-STORE request and dataset for validity.

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

Parameters

  reqMessage | [in] The C-STORE request message data structure
  reqDataset | [in] The C-STORE request dataset received. Might be NULL.

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

## ◆ findPresentationContext()

void DcmSCP::findPresentationContext | ( | const T_ASC_PresentationContextID | presID,
|  | OFString & | abstractSyntax,
|  | OFString & | transferSyntax
| ) |  |
| protected

This call returns the presentation context belonging to the given presentation context ID.

Parameters

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

## ◆ findPresentationContextID()

static DUL_PRESENTATIONCONTEXT* DcmSCP::findPresentationContextID | ( | LST_HEAD * | head,
|  | T_ASC_PresentationContextID | presentationContextID
| ) |  |
| static protected

Helper function to return presentation context information by given presentation context ID.

Parameters

  head | The presentation context list
  presentationContextID | The presentation context ID

Returns
  The presentation context information

## ◆ forceAssociationRefuse()

void DcmSCP::forceAssociationRefuse | ( | const OFBool | doRefuse | ) |

Force every association request to be refused by SCP, no matter what the SCU is offering.

Parameters

  doRefuse | [in] If OFTrue, every association is being refused. DcmSCP's default is not to refuse every association.

## ◆ getACSETimeout()

Uint32 DcmSCP::getACSETimeout | ( |  | ) | const

Returns ACSE timeout.

Returns
  ACSE timeout in seconds

## ◆ getAETitle()

const OFString& DcmSCP::getAETitle | ( |  | ) | const

Returns SCP's own AE title.

Only used if the SCP is not configured to respond with the called AE title the SCU uses for association negotiation, see setRespondWithCalledAETitle().

Returns
  The configured AE title

## ◆ getCalledAETitle()

OFString DcmSCP::getCalledAETitle | ( |  | ) | const

Returns AE title the SCU used as called AE title in association request.

Returns
  AE title the SCP was called with. Empty string if SCP is currently not connected.

## ◆ getConfig()

virtual DcmSCPConfig& DcmSCP::getConfig | ( |  | ) |
| virtual

Get access to the configuration of the SCP.

Note that the functionality on the configuration object is shadowed by other API functions of DcmSCP. The existing functions are provided in order to not break users of this "older" API where no configuration object existed.

Returns
  a reference to the DcmSCPConfig object used by this DcmSCP object.

## ◆ getConnectionBlockingMode()

DUL_BLOCKOPTIONS DcmSCP::getConnectionBlockingMode | ( |  | ) | const

Returns whether receiving of TCP/IP connection requests is done in blocking or unblocking mode.

Returns
  DUL_BLOCK if in blocking mode, otherwise DUL_NOBLOCK

## ◆ getConnectionTimeout()

Uint32 DcmSCP::getConnectionTimeout | ( |  | ) | const

Returns connection timeout.

Returns
  TCP/IP connection timeout in seconds

## ◆ getDIMSEBlockingMode()

T_DIMSE_BlockingMode DcmSCP::getDIMSEBlockingMode | ( |  | ) | const

Returns whether receiving of DIMSE messages is done in blocking or unblocking mode.

Returns
  DIMSE_BLOCKING if in blocking mode, otherwise DIMSE_NONBLOCKING

## ◆ getDIMSETimeout()

Uint32 DcmSCP::getDIMSETimeout | ( |  | ) | const

Returns DIMSE timeout (only applicable in blocking mode)

Returns
  DIMSE timeout in seconds

## ◆ getHostLookupEnabled()

OFBool DcmSCP::getHostLookupEnabled | ( |  | ) | const

Returns whether a connecting system's host name is looked up.

Returns
  OFTrue, if host name lookup is enabled, OFFalse otherwise

## ◆ getMaxReceivePDULength()

Uint32 DcmSCP::getMaxReceivePDULength | ( |  | ) | const

Returns maximum PDU length configured to be received by SCP.

Returns
  Maximum PDU length in bytes

## ◆ getPeerAETitle()

OFString DcmSCP::getPeerAETitle | ( |  | ) | const

Returns AE title (calling AE title) the SCU used for association request.

Returns
  Calling AE title of SCU. Empty string if SCP is currently not connected.

## ◆ getPeerIP()

OFString DcmSCP::getPeerIP | ( |  | ) | const

Returns IP address of connected SCU.

Returns
  IP address of connected SCU. Empty string if SCP is currently not connected.

## ◆ getPeerMaxPDULength()

Uint32 DcmSCP::getPeerMaxPDULength | ( |  | ) | const

Returns maximum PDU size the communication peer (i.e. the SCU) is able to receive.

Returns
  Maximum PDU size the SCU is able to receive. Returns zero if SCP is currently not connected.

## ◆ getPort()

Uint16 DcmSCP::getPort | ( |  | ) | const

Returns TCP/IP port number SCP listens for new connection requests.

Returns
  The port number

## ◆ getPresentationContextInfo()

static OFBool DcmSCP::getPresentationContextInfo | ( | const T_ASC_Association * | assoc,
|  | const Uint8 | presID,
|  | DcmPresentationContextInfo & | presInfo
| ) |  |
| static protected

Helper function to return presentation context information by given presentation context ID.

Parameters

  assoc | The association to search
  presID | The presentation context ID
  presInfo | The result presentation context information, if found

Returns
  OFTrue if presentation context with ID could be found, OFFalse otherwise

## ◆ getProgressNotificationMode()

OFBool DcmSCP::getProgressNotificationMode | ( |  | ) | const

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

The progress notification is enabled by default.

Returns
  The current progress notification mode, enabled if OFTrue

## ◆ getRefuseAssociation()

OFBool DcmSCP::getRefuseAssociation | ( |  | ) | const

Returns whether SCP should refuse any association request no matter what the SCU proposes.

Returns
  OFTrue, if SCP is configured to refuse every association

## ◆ getRespondWithCalledAETitle()

OFBool DcmSCP::getRespondWithCalledAETitle | ( |  | ) | const

Returns whether SCP uses the called AE title from SCU requests to respond to connection requests instead of a configured AE title.

Returns
  OFTrue, if the SCU's calling AE title is utilized, OFFalse otherwise

## ◆ getVerbosePCMode()

OFBool DcmSCP::getVerbosePCMode | ( |  | ) | const

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

The latter is the default.

Returns
  The verbose presentation context mode configured

## ◆ handleACTIONRequest()

virtual OFCondition DcmSCP::handleACTIONRequest | ( | T_DIMSE_N_ActionRQ & | reqMessage,
|  | const T_ASC_PresentationContextID | presID,
|  | DcmDataset *& | reqDataset,
|  | Uint16 & | actionTypeID
| ) |  |
| inline protected virtual

Receive N-ACTION request on the currently opened association.

This function is deprecated and will be removed in the future. For now it calls receiveACTIONRequest() which should be used instead.

Parameters

  reqMessage | [in] The N-ACTION request message that was received
  presID | [in] The presentation context to be used. By default, the presentation context of the request is used.
  reqDataset | [out] Pointer to the dataset received
  actionTypeID | [out] Action Type ID from the command set received

Returns
  status, EC_Normal if successful, an error code otherwise

References receiveACTIONRequest().

## ◆ handleAssociation()

virtual void DcmSCP::handleAssociation | ( |  | ) |
| protected virtual

This function takes care of handling the other DICOM application's request.

After having accomplished all necessary steps, the association will be dropped and destroyed.

## ◆ handleECHORequest()

virtual OFCondition DcmSCP::handleECHORequest | ( | T_DIMSE_C_EchoRQ & | reqMessage,
|  | const T_ASC_PresentationContextID | presID
| ) |  |
| protected virtual

Standard handler for Verification Service Class (DICOM Echo).

Returns echo response (i.e. whether C-ECHO could be responded to with status success).

Parameters

  reqMessage | [in] The C-ECHO request message that was received
  presID | [in] The presentation context to be used. By default, the presentation context of the request is used.

Returns
  status, EC_Normal if successful, an error code otherwise

## ◆ handleEVENTREPORTRequest()

virtual OFCondition DcmSCP::handleEVENTREPORTRequest | ( | T_DIMSE_N_EventReportRQ & | reqMessage,
|  | const T_ASC_PresentationContextID | presID,
|  | DcmDataset *& | reqDataset,
|  | Uint16 & | eventTypeID
| ) |  |
| protected virtual

Receive N-EVENT-REPORT request on the currently opened association and send a corresponding response.

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

Parameters

  reqMessage | [in] The N-EVENT-REPORT request message that was received
  presID | [in] The presentation context to be used. By default, the presentation context of the request is used.
  reqDataset | [out] Pointer to the dataset received
  eventTypeID | [out] Event Type ID from the command set received

Returns
  status, EC_Normal if successful, an error code otherwise

## ◆ handleFINDRequest()

virtual OFCondition DcmSCP::handleFINDRequest | ( | T_DIMSE_C_FindRQ & | reqMessage,
|  | const T_ASC_PresentationContextID | presID,
|  | DcmDataset *& | reqDataset
| ) |  |
| inline protected virtual

Handle C-FIND request.

This function is deprecated and will be removed in the future. For now it calls receiveFINDRequest() which should be used instead.

Parameters

  reqMessage | [in] The C-FIND request message that was received
  presID | [in] The presentation context to be used. By default, the presentation context of the request is used.
  reqDataset | [out] Pointer to the dataset received

Returns
  status, EC_Normal if successful, an error code otherwise

References receiveFINDRequest().

## ◆ handleIncomingCommand()

virtual OFCondition DcmSCP::handleIncomingCommand | ( | T_DIMSE_Message * | incomingMsg,
|  | const DcmPresentationContextInfo & | presInfo
| ) |  |
| protected virtual

Handle incoming command set and react accordingly, e.g. sending response via DIMSE_sendXXXResponse().

The standard handler only knows how to handle a C-ECHO request message (by calling handleEchoRequest()) if it is sent on a presentation context configured for the Verification SOP Class. This function is most likely to be implemented by a derived class implementing a specific SCP behavior.

Parameters

  incomingMsg | The DIMSE message received
  presInfo | Additional information on the Presentation Context used

Returns
  EC_Normal if the message could be handled, error if not. Especially DIMSE_BADCOMMANDTYPE should be returned if there is no handler for this particular type of DIMSE message. E.g. the default handler in DcmSCP only handles C-ECHO requests and, therefore, returns DIMSE_BADCOMMANDTYPE otherwise.

Reimplemented in DcmStorageSCP.

## ◆ handleMOVERequest()

virtual OFCondition DcmSCP::handleMOVERequest | ( | T_DIMSE_C_MoveRQ & | reqMessage,
|  | const T_ASC_PresentationContextID | presID,
|  | DcmDataset *& | reqDataset,
|  | OFString & | moveDest
| ) |  |
| inline protected virtual

Receive C-MOVE request on the currently active association.

This function is deprecated and will be removed in the future. For now it calls receiveMOVERequest() which should be used instead.

Parameters

  reqMessage | [in] The C-MOVE request message that was received
  presID | [in] The presentation context to be used. By default, the presentation context of the request is used.
  reqDataset | [out] Pointer to the dataset received
  moveDest | [out] The move destination where to send the instances

Returns
  status, EC_Normal if successful, an error code otherwise

References receiveMOVERequest().

## ◆ handleSTORERequest()

virtual OFCondition DcmSCP::handleSTORERequest | ( | T_DIMSE_C_StoreRQ & | reqMessage,
|  | const T_ASC_PresentationContextID | presID,
|  | DcmDataset *& | reqDataset
| ) |  |
| protected virtual

Receive C-STORE request on the currently opened association, store the accompanying dataset in memory and send a corresponding response.

Calls checkSTORERequest() in order to determine the DIMSE status code to be used for the C-STORE response.

Note
  This handler receives the dataset belonging the C-STORE request completely in memory. If very large datasets are expected, another handler should be implemented that calls the receiveSTORERequest() method with a filename.

Parameters

  reqMessage | [in] The C-STORE request message that was received
  presID | [in] The presentation context to be used. By default, the presentation context of the request is used.
  reqDataset | [inout] Pointer to data structure where the received dataset should be stored. If NULL, a new dataset is created, which has to be deleted by the caller.

Returns
  status, EC_Normal if successful, an error code otherwise

## ◆ isConnected()

OFBool DcmSCP::isConnected | ( |  | ) | const

Returns whether SCP is currently connected.

If in multi-process mode, the "father" process should always return false here, because connection is always handled by child process.

Returns
  OFTrue, if SCP is currently connected to calling SCU

## ◆ listen()

virtual OFCondition DcmSCP::listen | ( |  | ) |
| virtual

Starts providing the implemented services to SCUs.

After calling this method the SCP is listening for connection requests.

Returns
  The result. Per default, the method only returns in case of fatal errors. However, there are ways to stop listening in a controlled way:
  - In non-blocking mode, use stopAfterConnectionTimeout() in order shut down after the TCP timeout set with setConnectionTimeout() has occurred. In that case, the method returns with NET_EC_StopAfterConnectionTimeout.
  - In non-blocking and blocking mode, stopAfterCurrentAssociation() can be used to return after an association has been handled and ended. In that case, NET_EC_StopAfterAssociation is returned.
  Other error codes include
  - NET_EC_InvalidSCPAssociationProfile: Returned if the SCP's presentation context information is invalid (e.g. no presentation contexts have been added).
  - NET_EC_InsufficientPortPrivileges: Returned if the SCP is not allowed to open the specified TCP port for listening. The reason may be that you try to open a port number below 1024 on a Unix-like system as non-root user.
  - EC_setuidFailed: Returned (on Unix-like systems) if the DcmSCP was not able to drop root privileges.

## ◆ loadAssociationCfgFile()

virtual OFCondition DcmSCP::loadAssociationCfgFile | ( | const OFString & | assocFile | ) |
| virtual

Loads association configuration file.

Parameters

  assocFile | [in] The filename of the association configuration to be loaded. The association configuration file must be valid for an SCP.

Returns
  EC_Normal if loading was successful, error otherwise

## ◆ negotiateAssociation()

virtual OFCondition DcmSCP::negotiateAssociation | ( |  | ) |
| protected virtual

This function checks all presentation contexts proposed by the SCU whether they are supported or not.

It is not an error if no common presentation context could be identified with the SCU; only issues like problems in memory management etc. are reported as an error. This function does not send a response message to the SCU. This is done in other functions.

Returns
  EC_Normal if negotiation was successfully done, an error code otherwise

## ◆ notifyAbortRequest()

virtual void DcmSCP::notifyAbortRequest | ( |  | ) |
| protected virtual

Overwrite this function to be notified about an incoming association abort request.

The standard handler only outputs some information to the logger.

## ◆ notifyAssociationAcknowledge()

virtual void DcmSCP::notifyAssociationAcknowledge | ( |  | ) |
| protected virtual

Overwrite this function to be notified about an incoming association request.

The standard handler only outputs some information to the logger.

## ◆ notifyAssociationRequest()

virtual void DcmSCP::notifyAssociationRequest | ( | const T_ASC_Parameters & | params,
|  | DcmSCPActionType & | desiredAction
| ) |  |
| protected virtual

Overwrite this function to be notified about an incoming association request.

The standard handler only outputs some information to the logger.

Parameters

  params | The association parameters that were received.
  desiredAction | The desired action how to handle this association request.

## ◆ notifyAssociationTermination()

virtual void DcmSCP::notifyAssociationTermination | ( |  | ) |
| protected virtual

Overwrite this function to be notified when an association is terminated.

The standard handler only outputs some information to the logger.

## ◆ notifyConnectionTimeout()

virtual void DcmSCP::notifyConnectionTimeout | ( |  | ) |
| protected virtual

Overwrite this function to be notified about a connection timeout in non-blocking mode (see setConnectionBlockingMode() and setConnectionTimeout() methods).

In blocking mode, this method has no effect since it's never called. The standard handler only outputs some information to the TRACE logger.

## ◆ notifyDIMSEError()

virtual void DcmSCP::notifyDIMSEError | ( | const OFCondition & | cond | ) |
| protected virtual

Overwrite this function to be notified when a DIMSE error occurs.

The standard handler only outputs error information to the logger.

Parameters

  cond | [in] The DIMSE error occurred.

## ◆ notifyRECEIVEProgress()

virtual void DcmSCP::notifyRECEIVEProgress | ( | const unsigned long | byteCount | ) |
| protected virtual

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

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

Parameters

  byteCount | [in] Number of bytes received so far

## ◆ notifyReleaseRequest()

virtual void DcmSCP::notifyReleaseRequest | ( |  | ) |
| protected virtual

Overwrite this function to be notified about an incoming association release request.

The standard handler only outputs some information to the logger.

## ◆ notifySENDProgress()

virtual void DcmSCP::notifySENDProgress | ( | const unsigned long | byteCount | ) |
| protected virtual

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

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

Parameters

  byteCount | [in] Number of bytes sent so far

## ◆ numAssociations()

Uint16 DcmSCP::numAssociations | ( |  | ) | const

Returns number of associations currently running.

Only applicable in Unix-like operating systems. Can only be greater than one when running in multi-process mode.

Returns
  Number of currently running associations

## ◆ openListenPort()

virtual OFCondition DcmSCP::openListenPort | ( |  | ) |
| virtual

Alternative interface to providing the implemented services to SCUs.

This method opens the TCP port for incoming connections, drops root privileges if necessary and then returns. The caller can then perform short other operations and finally call acceptAssociations(). If any SCU tries to connect between this method and the call to acceptAssociations(), they are placed on the TCP listen backlog and will be handled by acceptAssociations() unless they time out or the backlog overflows (the size of the backlog is defined by the PRV_LISTENBACKLOG macro).

Returns
  EC_Normal if successful, an error code otherwise.

## ◆ operator=()

DcmSCP& DcmSCP::operator= | ( | const DcmSCP & | src | ) |
| private

Private undefined assignment operator.

Shall never be called.

Parameters

  src | Source object

Returns
  Reference to this

## ◆ processAssociationRQ()

virtual OFCondition DcmSCP::processAssociationRQ | ( |  | ) |
| protected virtual

Actually process association request.

Returns
  EC_Normal if association could be processed, ASC_NULLKEY otherwise (only if internal association structure is invalid, should never happen)

## ◆ receiveACTIONRequest()

virtual OFCondition DcmSCP::receiveACTIONRequest | ( | T_DIMSE_N_ActionRQ & | reqMessage,
|  | const T_ASC_PresentationContextID | presID,
|  | DcmDataset *& | reqDataset,
|  | Uint16 & | actionTypeID
| ) |  |
| protected virtual

Receive N-ACTION request on the currently opened association.

Parameters

  reqMessage | [in] The N-ACTION request message that was received
  presID | [in] The presentation context to be used. By default, the presentation context of the request is used.
  reqDataset | [out] Pointer to the dataset received
  actionTypeID | [out] Action Type ID from the command set received

Returns
  status, EC_Normal if successful, an error code otherwise

Referenced by handleACTIONRequest().

## ◆ receiveDIMSECommand()

OFCondition DcmSCP::receiveDIMSECommand | ( | T_ASC_PresentationContextID * | presID,
|  | T_DIMSE_Message * | message,
|  | DcmDataset ** | statusDetail,
|  | DcmDataset ** | commandSet = `NULL`,
|  | const Uint32 | timeout = `0`
| ) |  |
| protected

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

Parameters

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

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

## ◆ receiveDIMSEDataset()

OFCondition DcmSCP::receiveDIMSEDataset | ( | T_ASC_PresentationContextID * | presID,
|  | DcmDataset ** | dataObject
| ) |  |
| protected

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

Parameters

  presID | [out] Contains in the end the ID of the presentation context which was used in the PDVs that were received on the network. If the PDVs show different presentation context IDs, this function will return an error.
  dataObject | [inout] Contains in the end the information that was received over the network. If this parameter points to NULL, a new dataset will be created by the underlying routines, which has to be deleted by the caller.

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

## ◆ receiveFINDRequest()

virtual OFCondition DcmSCP::receiveFINDRequest | ( | T_DIMSE_C_FindRQ & | reqMessage,
|  | const T_ASC_PresentationContextID | presID,
|  | DcmDataset *& | reqDataset
| ) |  |
| protected virtual

Receive C-FIND request.

Parameters

  reqMessage | [in] The C-FIND request message that was received
  presID | [in] The presentation context to be used. By default, the presentation context of the request is used.
  reqDataset | [out] Pointer to the dataset received

Returns
  status, EC_Normal if successful, an error code otherwise

Referenced by handleFINDRequest().

## ◆ receiveMOVERequest()

virtual OFCondition DcmSCP::receiveMOVERequest | ( | T_DIMSE_C_MoveRQ & | reqMessage,
|  | const T_ASC_PresentationContextID | presID,
|  | DcmDataset *& | reqDataset,
|  | OFString & | moveDest
| ) |  |
| protected virtual

Receive C-MOVE request on the currently active association.

Parameters

  reqMessage | [in] The C-MOVE request message that was received
  presID | [in] The presentation context to be used. By default, the presentation context of the request is used.
  reqDataset | [out] Pointer to the dataset received
  moveDest | [out] The move destination where to send the instances

Returns
  status, EC_Normal if successful, an error code otherwise

Referenced by handleMOVERequest().

## ◆ receiveSTORERequest() [1/2]

virtual OFCondition DcmSCP::receiveSTORERequest | ( | T_DIMSE_C_StoreRQ & | reqMessage,
|  | const T_ASC_PresentationContextID | presID,
|  | const OFString & | filename
| ) |  |
| protected virtual

Receive C-STORE request (and store accompanying dataset directly to file).

The dataset is stored exactly as received, i.e. without any conversions.

Parameters

  reqMessage | [in] The C-STORE request message that was received
  presID | [in] The presentation context to be used. By default, the presentation context of the request is used.
  filename | [in] The filename used to store the received dataset

Returns
  status, EC_Normal if successful, an error code otherwise

## ◆ receiveSTORERequest() [2/2]

virtual OFCondition DcmSCP::receiveSTORERequest | ( | T_DIMSE_C_StoreRQ & | reqMessage,
|  | const T_ASC_PresentationContextID | presID,
|  | DcmDataset *& | reqDataset
| ) |  |
| protected virtual

Receive C-STORE request (and store accompanying dataset in memory).

For very large datasets, the other receiveSTORERequest() method should be used because it stores the received dataset directly to file.

Parameters

  reqMessage | [in] The C-STORE request message that was received
  presID | [in] The presentation context to be used. By default, the presentation context of the request is used.
  reqDataset | [inout] Pointer to data structure where the received dataset should be stored. If NULL, a new dataset is created, which has to be deleted by the caller.

Returns
  status, EC_Normal if successful, an error code otherwise

## ◆ receiveSTORERequestDataset()

OFCondition DcmSCP::receiveSTORERequestDataset | ( | T_ASC_PresentationContextID * | presID,
|  | T_DIMSE_C_StoreRQ & | reqMessage,
|  | const OFString & | filename
| ) |  |
| protected

Receive one C-STORE request dataset via network from another DICOM application and store it directly to file (i.e. exactly as received without any conversions)

Parameters

  presID | [inout] Initially, the presentation context the C-STORE request was received on. Contains in the end the ID of the presentation context which was used in the PDVs that were received on the network. If the PDVs show different presentation context IDs, this function will return an error.
  reqMessage | [in] The C-STORE request message that was received
  filename | [in] Name of the file that is created to store the received dataset

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

## ◆ refuseAssociation()

virtual void DcmSCP::refuseAssociation | ( | const DcmRefuseReasonType | reason | ) |
| protected virtual

This function takes care of refusing an association request.

Parameters

  reason | [in] The reason why the association request will be refused and that will be reported to the SCU.

## ◆ sendACTIONResponse()

virtual OFCondition DcmSCP::sendACTIONResponse | ( | const T_ASC_PresentationContextID | presID,
|  | const Uint16 | messageID,
|  | const OFString & | sopClassUID,
|  | const OFString & | sopInstanceUID,
|  | const Uint16 | rspStatusCode
| ) |  |
| protected virtual

Respond to the N-ACTION request.

Parameters

  presID | [in] The presentation context ID to respond to
  messageID | [in] The message ID being responded to
  sopClassUID | [in] The affected SOP class UID
  sopInstanceUID | [in] The affected SOP instance UID
  rspStatusCode | [in] The response status code. 0 means success, others can found in the DICOM standard.

Returns
  EC_Normal, if responding was successful, an error code otherwise

## ◆ sendDIMSEMessage()

OFCondition DcmSCP::sendDIMSEMessage | ( | const T_ASC_PresentationContextID | presID,
|  | T_DIMSE_Message * | message,
|  | DcmDataset * | dataObject,
|  | DcmDataset * | statusDetail = `NULL`,
|  | DcmDataset ** | commandSet = `NULL`
| ) |  |
| protected

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

Parameters

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

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

## ◆ sendEVENTREPORTRequest()

virtual OFCondition DcmSCP::sendEVENTREPORTRequest | ( | const T_ASC_PresentationContextID | presID,
|  | const OFString & | sopInstanceUID,
|  | const Uint16 | messageID,
|  | const Uint16 | eventTypeID,
|  | DcmDataset * | reqDataset,
|  | Uint16 & | rspStatusCode
| ) |  |
| protected virtual

Send N-EVENT-REPORT request on the current association and receive a corresponding response.

Parameters

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

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

## ◆ sendFINDResponse()

virtual OFCondition DcmSCP::sendFINDResponse | ( | const T_ASC_PresentationContextID | presID,
|  | const Uint16 | messageID,
|  | const OFString & | sopClassUID,
|  | DcmDataset * | rspDataset,
|  | const Uint16 | rspStatusCode,
|  | DcmDataset * | statusDetail = `NULL`
| ) |  |
| protected virtual

Respond to the C-FIND request.

Parameters

  presID | [in] The presentation context ID to respond to
  messageID | [in] The message ID being responded to
  sopClassUID | [in] The affected SOP class UID
  rspDataset | [in] The response dataset
  rspStatusCode | [in] The response status code. 0 means success, others can found in the DICOM standard.
  statusDetail | [in] Any status (must fit response code), if desired

Returns
  EC_Normal, if responding was successful, an error code otherwise

## ◆ sendMOVEResponse()

virtual OFCondition DcmSCP::sendMOVEResponse | ( | const T_ASC_PresentationContextID | presID,
|  | const Uint16 | messageID,
|  | const OFString & | sopClassUID,
|  | DcmDataset * | rspDataset,
|  | const Uint16 | rspStatusCode,
|  | DcmDataset * | statusDetail = `NULL`,
|  | const Uint16 | numRemain = `0`,
|  | const Uint16 | numComplete = `0`,
|  | const Uint16 | numFail = `0`,
|  | const Uint16 | numWarn = `0`
| ) |  |
| protected virtual

Respond to the C-MOVE request.

Parameters

  presID | [in] The presentation context ID to respond to
  messageID | [in] The message ID being responded to
  sopClassUID | [in] The affected SOP class UID
  rspDataset | [in] The response dataset
  rspStatusCode | [in] The status code of the response. 0 means success, others can found in the DICOM standard.
  statusDetail | [in] The status detail of the response (if desired).
  numRemain | [in] Number of remaining sub-operations. Required for Pending status codes, often optional otherwise. Sent if one of the num parameters is not 0.
  numComplete | [in] Number of completed sub-operations. Required for Pending status codes, often optional otherwise. Sent if one of the num parameters is not 0.
  numFail | [in] Number of failed sub-operations. Required for Pending status codes, often optional otherwise. Sent if one of the num parameters is not 0.
  numWarn | [in] Number of warning sub-operations. Required for Pending status codes, often optional otherwise. Sent if one of the num parameters is not 0.

Returns
  EC_Normal, if responding was successful, an error code otherwise

## ◆ sendSTOREResponse() [1/2]

virtual OFCondition DcmSCP::sendSTOREResponse | ( | const T_ASC_PresentationContextID | presID,
|  | const T_DIMSE_C_StoreRQ & | reqMessage,
|  | const Uint16 | rspStatusCode
| ) |  |
| protected virtual

Respond to the C-STORE request (with details from the request message)

Parameters

  presID | [in] The presentation context ID to respond to
  reqMessage | [in] The C-STORE request that should be responded to
  rspStatusCode | [in] The response status code. 0 means success, others can found in the DICOM standard.

Returns
  EC_Normal, if responding was successful, an error code otherwise

## ◆ sendSTOREResponse() [2/2]

virtual OFCondition DcmSCP::sendSTOREResponse | ( | const T_ASC_PresentationContextID | presID,
|  | const Uint16 | messageID,
|  | const OFString & | sopClassUID,
|  | const OFString & | sopInstanceUID,
|  | const Uint16 | rspStatusCode,
|  | DcmDataset * | statusDetail = `NULL`
| ) |  |
| protected virtual

Respond to the C-STORE request (with given details)

Parameters

  presID | [in] The presentation context ID to respond to
  messageID | [in] The message ID being responded to
  sopClassUID | [in] The affected SOP class UID
  sopInstanceUID | [in] The affected SOP instance UID
  rspStatusCode | [in] The response status code. 0 means success, others can found in the DICOM standard.
  statusDetail | [in] The status detail of the response (if desired).

Returns
  EC_Normal, if responding was successful, an error code otherwise

## ◆ setACSETimeout()

void DcmSCP::setACSETimeout | ( | const Uint32 | acseTimeout | ) |

Set the timeout used during ACSE messaging protocol.

Parameters

  acseTimeout | [in] ACSE timeout in seconds.

## ◆ setAETitle()

void DcmSCP::setAETitle | ( | const OFString & | aetitle | ) |

Set AE title of the server.

Parameters

  aetitle | [in] The AE title of the server. By default, all SCU association requests calling another AE title will be rejected. This behavior can be changed by using the setRespondWithCalledAETitle() method.

## ◆ setAlwaysAcceptDefaultRole()

void DcmSCP::setAlwaysAcceptDefaultRole | ( | const OFBool | enabled | ) |

Option to always accept a default role as association acceptor.

If OFFalse (default) the acceptor will reject a presentation context proposed with Default role (no role selection at all) when it is configured for role SCP only. If this option is set to OFTrue then such presentation contexts will be accepted in Default role (i.e. acceptor does not return role selection for this presentation context at all). Overall, if set to OFTrue, there are no requestor proposals possible that lead to a complete rejection of a presentation context. See also role documentation in dul.h.

Parameters

  enabled | If OFTrue, do not reject Default role proposals when configured for SCP role. OFFalse (default behaviour): Reject such proposals.

## ◆ setAndCheckAssociationProfile()

virtual OFCondition DcmSCP::setAndCheckAssociationProfile | ( | const OFString & | profileName | ) |
| virtual

If an association profile should be selected, either by loading an association configuration file or using the addPresentationContext() function, one of those can be selected and checked for validity using this method.

Parameters

  profileName | [in] The name of the association profile which must be configured before being selected here

Returns
  EC_Normal if selecting/checking was successful, an error code otherwise

## ◆ setConfig()

virtual OFCondition DcmSCP::setConfig | ( | const DcmSCPConfig & | config | ) |
| virtual

Set the DcmSCPConfig object to use for configuring this DcmSCP object.

A deep copy is performed.

Parameters

  config | The configuration to use.

Returns
  EC_Normal if configuration can be used. The configuration can only be changed if the SCP is not yet connected, otherwise NET_EC_AlreadyConnected is returned.

## ◆ setConnectionBlockingMode()

void DcmSCP::setConnectionBlockingMode | ( | const DUL_BLOCKOPTIONS | blockingMode | ) |

Set whether waiting for a TCP/IP connection should be blocking or non-blocking.

In non-blocking mode, the networking routines will wait for specified connection timeout, see setConnectionTimeout() function. In blocking mode, no timeout is set but the operating system's network routines will be used to read from the socket for incoming data. In the worst case, this may be a long time until that call returns. The default of DcmSCP is blocking mode.

Parameters

  blockingMode | [in] Either DUL_BLOCK for blocking mode or DUL_NOBLOCK for non-blocking mode

## ◆ setConnectionTimeout()

void DcmSCP::setConnectionTimeout | ( | const Uint32 | timeout | ) |

Set the timeout that should be waited for connection requests.

Only relevant in non-blocking mode (which is not the default).

Parameters

  timeout | [in] TCP/IP connection timeout in seconds.

## ◆ setDIMSEBlockingMode()

void DcmSCP::setDIMSEBlockingMode | ( | const T_DIMSE_BlockingMode | blockingMode | ) |

Set whether DIMSE messaging should be blocking or non-blocking.

In non-blocking mode, the networking routines will wait for DIMSE messages for the specified DIMSE timeout time, see setDIMSETimeout() function. In blocking mode, no timeout is set but the operating system's network routines will be used to read from the socket for new data. In the worst case, this may be a long time until that call returns. The default of DcmSCP is blocking mode.

Parameters

  blockingMode | [in] Either DIMSE_BLOCKING for blocking mode or DIMSE_NONBLOCKING for non-blocking mode

## ◆ setDIMSETimeout()

void DcmSCP::setDIMSETimeout | ( | const Uint32 | dimseTimeout | ) |

Set the timeout to be waited for incoming DIMSE message packets.

This is only relevant for DIMSE blocking mode messaging (see also setDIMSEBlockingMode()).

Parameters

  dimseTimeout | [in] DIMSE receive timeout in seconds

## ◆ setEnableVerification()

OFCondition DcmSCP::setEnableVerification | ( | const OFString & | profile = `"DEFAULT"` | ) |

Enables negotiation of the Verification SOP Class.

It adds the Verification SOP Class to the list of supported abstract syntaxes for the given profile. All uncompressed transfer syntaxes are supported. If Verification SOP class is added here, DcmSCP will respond to related C-ECHO requests. Note that this cannot be reverted. The default behavior of DcmSCP is not to support any SOP Class at all.

Parameters

  profile | [in] The profile Verification SOP Class should be added to. The default is to add it to the DcmSCP's internal standard profile called "DEFAULT".

Returns
  EC_Normal if Verification SOP Class could be added, error otherwise.

## ◆ setHostLookupEnabled()

void DcmSCP::setHostLookupEnabled | ( | const OFBool | mode | ) |

Enables or disables looking up the host name from a connecting system.

Note that this sets a GLOBAL flag in DCMTK, i.e. the behavior changes for all servers. This should be changed in the future.

Parameters

  mode | [in] OFTrue, if host name lookup should be enabled, OFFalse for disabling it.

## ◆ setMaxReceivePDULength()

void DcmSCP::setMaxReceivePDULength | ( | const Uint32 | maxRecPDU | ) |

Set maximum PDU size the SCP is able to receive.

This size is sent in association response message to SCU.

Parameters

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

## ◆ setPort()

void DcmSCP::setPort | ( | const Uint16 | port | ) |

Set SCP's TCP/IP listening port.

Parameters

  port | [in] The port number to listen on. Note that usually on Unix-like systems only root user is permitted to open ports below 1024. If port number 0 is provided, the OS will assign a free port once openListenPort() is being called. The port number actually used is then available via getPort().

## ◆ setProgressNotificationMode()

void DcmSCP::setProgressNotificationMode | ( | const OFBool | mode | ) |

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

The progress notification is enabled by default.

Parameters

  mode | [in] Disable progress notification if OFFalse

## ◆ setRespondWithCalledAETitle()

void DcmSCP::setRespondWithCalledAETitle | ( | const OFBool | useCalled | ) |

Set SCP to use the called AE title from the SCU request for the response, i.e. the SCP will always respond with setting it's own name to the one the SCU used for calling.

Overrides any AE title eventually set with setAETitle().

Parameters

  useCalled | [in] If OFTrue, the SCP will use the called AE title from the request for responding. DcmSCP's default is OFFalse.

## ◆ setVerbosePCMode()

void DcmSCP::setVerbosePCMode | ( | const OFBool | mode | ) |

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

Parameters

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

## ◆ stopAfterConnectionTimeout()

virtual OFBool DcmSCP::stopAfterConnectionTimeout | ( |  | ) |
| protected virtual

This method can be used to return from the listen() loop in a controlled way.

In order to use it, it must be overwritten in a derived class. As long as no severe error occurs and this method returns OFFalse, the listen() method will wait for incoming associations in an infinite loop. If this method returns OFTrue, the SCP will return from the listen() loop after a connection timeout occurs (see setConnectionTimeout() method). In blocking mode (see setConnectionBlockingMode() method), this method has no effect (it's never called) since the underlying routines will wait forever for an incoming TCP connection.

Returns
  The standard handler always returns OFFalse

## ◆ stopAfterCurrentAssociation()

virtual OFBool DcmSCP::stopAfterCurrentAssociation | ( |  | ) |
| protected virtual

This method can be used to return from the listen() loop in a controlled way.

In order to use it, it must be overwritten in a derived class. As long as no severe error occurs and this method returns OFFalse, the listen() method will wait for incoming associations in an infinite loop.

Returns
  The standard handler always returns OFFalse

## ◆ waitForAssociationRQ()

virtual OFCondition DcmSCP::waitForAssociationRQ | ( | T_ASC_Network * | network | ) |
| protected virtual

This function takes care of receiving, negotiating and accepting/refusing an association request.

Additionally, if negotiation was successful, it handles any incoming DIMSE commands by calling handleAssociation(). An error is only returned, if something goes wrong. Therefore, refusing an association because of wrong application context name or no common presentation contexts with the SCU does NOT lead to an error.

Parameters

  network | [in] Contains network parameters

Returns
  EC_Normal, if everything went fine, DUL_NOASSOCIATIONREQUEST if a timeout occurs in non-blocking mode, DIMSE_ILLEGALASSOCIATION or ASC_NULLKEY if severe internal errors occurred (should not happen)

## Member Data Documentation

## ◆ m_cfg

DcmSharedSCPConfig DcmSCP::m_cfg
| private

SCP configuration.

The configuration is a shared object since in some scenarios one might like to share a single configuration instance with multiple SCPs without copying it, e.g. in the context of the DcmSCPPool class.

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

- dcmnet/include/dcmtk/dcmnet/scp.h

Generated on Mon Dec 15 2025 for DCMTK Version 3.7.0 by Doxygen 1.9.1