DCMTK Version 3.7.0 OFFIS DICOM Toolkit

Public Member Functions | Static Public Member Functions | Private Member Functions | Private Attributes | List of all members
DcmFindSCU Class Reference

This class implements a complete DICOM C-FIND SCU, including association set-up, execution of the C-FIND transaction including processing of results, and closing of the association. More...

## Public Member Functions
| DcmFindSCU ()
| constructor, does not execute any network-related code.
virtual | ~DcmFindSCU ()
| destructor. Destroys network structure if not done already.
OFCondition | setOutputResponseLimit (const unsigned int limit)
| set maximum number of responses written to file. More...
OFCondition | initializeNetwork (int acse_timeout)
| initialize the network structure. More...
OFCondition | setTransportLayer (DcmTransportLayer *tLayer)
| enable user-defined transport layer. More...
OFCondition | dropNetwork ()
| destroy network struct. More...
OFCondition | performQuery (const char *peer, unsigned int port, const char *ourTitle, const char *peerTitle, const char *abstractSyntax, E_TransferSyntax preferredTransferSyntax, T_DIMSE_BlockingMode blockMode, int dimse_timeout, Uint32 maxReceivePDULength, OFBool secureConnection, OFBool abortAssociation, unsigned int repeatCount, DcmFindSCUExtractMode extractResponses, int cancelAfterNResponses, OFList< OFString > *overrideKeys, DcmFindSCUCallback *callback=NULL, OFList< OFString > *fileNameList=NULL, const char *outputDirectory=NULL, const char *extractFilename=NULL, T_ASC_ProtocolFamily protocolVersion=ASC_AF_Default)
| main worker method that negotiates an association, executes one or more C-FIND-RQ transactions, processes the responses and closes the association once everything is finished (or an error has occurred). More...

## Static Public Member Functions
static OFBool | writeToFile (const char *ofname, DcmDataset *dataset)
| static helper function that writes the content of the given dataset into a DICOM file (using the DICOM file format with metaheader). More...
static OFBool | writeToXMLFile (const char *ofname, DcmDataset *dataset)
| static helper function that writes the content of the given dataset into an XML file (see "dcm2xml.dtd", starts with top-level element "data-set"). More...

## Private Member Functions
OFCondition | addPresentationContext (T_ASC_Parameters *params, const char *abstractSyntax, E_TransferSyntax preferredTransferSyntax)
| add presentation context for given abstract syntax and given preferred transfer syntax to the ACSE parameter struct. More...
OFCondition | findSCU (T_ASC_Association *assoc, const char *fname, int repeatCount, int &responseCount, const char *abstractSyntax, T_DIMSE_BlockingMode blockMode, int dimse_timeout, DcmFindSCUExtractMode extractResponses, int cancelAfterNResponses, OFList< OFString > *overrideKeys, DcmFindSCUCallback *callback=NULL, const char *outputDirectory=NULL, STD_NAMESPACE ofstream *outputStream=NULL) const
| perform a single C-FIND transaction on association that is already open. More...
| DcmFindSCU (const DcmFindSCU &other)
| Private undefined copy constructor. More...
DcmFindSCU & | operator= (const DcmFindSCU &other)
| Private undefined assignment operator. More...

## Private Attributes
T_ASC_Network * | net_
| pointer to network structure
unsigned int | outputResponseLimit_
| maximum number of responses written to file (default: unlimited)

## Detailed Description

This class implements a complete DICOM C-FIND SCU, including association set-up, execution of the C-FIND transaction including processing of results, and closing of the association.

By default, incoming C-FIND-RSP messages will be displayed on console and, optionally, the attached dataset is stored in files. By providing a user-defined callback, other types of processing are possible.

## Constructor & Destructor Documentation

## ◆ DcmFindSCU()

DcmFindSCU::DcmFindSCU | ( | const DcmFindSCU & | other | ) |
| private

Private undefined copy constructor.

Parameters

  other | documented to avoid doxygen warnings

## Member Function Documentation

## ◆ addPresentationContext()

OFCondition DcmFindSCU::addPresentationContext | ( | T_ASC_Parameters * | params,
|  | const char * | abstractSyntax,
|  | E_TransferSyntax | preferredTransferSyntax
| ) |  |
| private

add presentation context for given abstract syntax and given preferred transfer syntax to the ACSE parameter struct.

Parameters

  params | ACSE parameter struct to be modified.
  abstractSyntax | SOP Class UID or Meta SOP Class UID of service.
  preferredTransferSyntax | May be Unknown, Implicit Little Endian, or any of the two uncompressed explicit VR transfer syntaxes. By default (unknown), local endian explicit VR is proposed first, followed by opposite endian explicit VR, followed by implicit VR. This behavior can be modified by explicitly specifying the preferred explicit VR transfer syntax. With Little Endian Implicit, only Implicit VR is proposed.

Returns
  EC_Normal if successful, an error code otherwise.

## ◆ dropNetwork()

OFCondition DcmFindSCU::dropNetwork | ( |  | ) |

destroy network struct.

This should be done only once.

Returns
  EC_Normal if successful, an error code otherwise.

## ◆ findSCU()

OFCondition DcmFindSCU::findSCU | ( | T_ASC_Association * | assoc,
|  | const char * | fname,
|  | int | repeatCount,
|  | int & | responseCount,
|  | const char * | abstractSyntax,
|  | T_DIMSE_BlockingMode | blockMode,
|  | int | dimse_timeout,
|  | DcmFindSCUExtractMode | extractResponses,
|  | int | cancelAfterNResponses,
|  | OFList< OFString > * | overrideKeys,
|  | DcmFindSCUCallback * | callback = `NULL`,
|  | const char * | outputDirectory = `NULL`,
|  | STD_NAMESPACE ofstream * | outputStream = `NULL`
| ) |  | const
| private

perform a single C-FIND transaction on association that is already open.

Parameters

  assoc | DIMSE association
  fname | file name for the query file to be used with this query. May be NULL.
  repeatCount | number of times this query should be repeated (for debugging purposes, works only with default callback).
  responseCount | a reference to the integer indicating the count of received responses.
  abstractSyntax | SOP Class UID or Meta SOP Class UID of service.
  blockMode | DIMSE blocking mode.
  dimse_timeout | timeout for DIMSE operations (in seconds).
  extractResponses | mode specifying whether and how to extract C-FIND responses (works only with default callback).
  cancelAfterNResponses | issue C-FIND-CANCEL after given number of responses (works only with default callback).
  overrideKeys | list of keys/paths that override those in the query files, if any. Either the list of query files or override keys or both should be non-empty, because the query dataset will be empty otherwise. For path syntax see DcmPath.
  callback | user-provided non-default callback handler object. For default callback, pass NULL.
  outputDirectory | directory used to store the output files (e.g. response datasets). If NULL, the current directory is used.
  outputStream | pointer to output stream that is used when extractResponses is set to FEM_singleXMLFile.

Returns
  EC_Normal if successful, an error code otherwise.

## ◆ initializeNetwork()

OFCondition DcmFindSCU::initializeNetwork | ( | int | acse_timeout | ) |

initialize the network structure.

This should be done only once.

Parameters

  acse_timeout | timeout for ACSE operations, in seconds

Returns
  EC_Normal if successful, an error code otherwise.

## ◆ operator=()

DcmFindSCU& DcmFindSCU::operator= | ( | const DcmFindSCU & | other | ) |
| private

Private undefined assignment operator.

Parameters

  other | documented to avoid doxygen warnings

## ◆ performQuery()

OFCondition DcmFindSCU::performQuery | ( | const char * | peer,
|  | unsigned int | port,
|  | const char * | ourTitle,
|  | const char * | peerTitle,
|  | const char * | abstractSyntax,
|  | E_TransferSyntax | preferredTransferSyntax,
|  | T_DIMSE_BlockingMode | blockMode,
|  | int | dimse_timeout,
|  | Uint32 | maxReceivePDULength,
|  | OFBool | secureConnection,
|  | OFBool | abortAssociation,
|  | unsigned int | repeatCount,
|  | DcmFindSCUExtractMode | extractResponses,
|  | int | cancelAfterNResponses,
|  | OFList< OFString > * | overrideKeys,
|  | DcmFindSCUCallback * | callback = `NULL`,
|  | OFList< OFString > * | fileNameList = `NULL`,
|  | const char * | outputDirectory = `NULL`,
|  | const char * | extractFilename = `NULL`,
|  | T_ASC_ProtocolFamily | protocolVersion = `ASC_AF_Default`
| ) |  |

main worker method that negotiates an association, executes one or more C-FIND-RQ transactions, processes the responses and closes the association once everything is finished (or an error has occurred).

Parameters

  peer | hostname or IP address of peer SCP host.
  port | TCP port number of peer SCP host.
  ourTitle | calling AE title.
  peerTitle | called AE title.
  abstractSyntax | SOP Class UID or Meta SOP Class UID of service.
  preferredTransferSyntax | May be Unknown, Implicit Little Endian, or any of the two uncompressed explicit VR transfer syntaxes. By default (unknown), local endian explicit VR is proposed first, followed by opposite endian explicit VR, followed by implicit VR. This behavior can be modified by explicitly specifying the preferred explicit VR transfer syntax. With Little Endian Implicit, only Implicit VR is proposed.
  blockMode | DIMSE blocking mode.
  dimse_timeout | timeout for DIMSE operations (in seconds).
  maxReceivePDULength | limit the maximum PDU size for incoming PDUs to the given value. This value should be less than or equal to ASC_DEFAULTMAXPDU, and is usually identical to ASC_DEFAULTMAXPDU (other values are only useful for debugging purposes).
  secureConnection | this flag, if true, requests a secure TLS connection to be used instead of a normal connection. A transport layer object supporting secure connections must set with setTransportLayer() prior to this call.

Remarks
  this parameter is only functional if DCMTK is compiled with OpenSSL support enabled. Otherwise the method will return an error.

Parameters

  abortAssociation | abort association instead of releasing it (for debugging purposes)
  repeatCount | number of times this query should be repeated (for debugging purposes, works only with default callback).
  extractResponses | mode specifying whether and how to extract C-FIND responses (works only with default callback).
  cancelAfterNResponses | issue C-FIND-CANCEL after given number of responses (works only with default callback).
  overrideKeys | list of keys/paths that override those in the query files, if any. Either the list of query files or override keys or both should be non-empty, because the query dataset will be empty otherwise. For path syntax see DcmPath.
  callback | user-provided non-default callback handler object. For default callback, pass NULL.
  fileNameList | list of query files. Each file is expected to be a DICOM file containing a dataset that is used as a query, possibly modified by override keys, if any. This parameter, if non-NULL, points to a list of filenames (paths).
  outputDirectory | directory used to store the output files (e.g. response datasets). If NULL, the current directory is used.
  extractFilename | filename used to store the response datasets when extractResponses is set to FEM_singleXMLFile.
  protocolVersion | IP protocol version to be used

Returns
  EC_Normal if successful, an error code otherwise.

## ◆ setOutputResponseLimit()

OFCondition DcmFindSCU::setOutputResponseLimit | ( | const unsigned int | limit | ) |

set maximum number of responses written to file.

Limiting the number of responses written to file might be useful e.g. if the C-FIND-CANCEL request does not prevent the SCP from sending further C-FIND-RSP messages. Also see various "extract" parameters of performQuery() method.

Parameters

  limit | maximum number of responses written to file (0 means unlimited)

Returns
  EC_Normal if successful, an error code otherwise.

## ◆ setTransportLayer()

OFCondition DcmFindSCU::setTransportLayer | ( | DcmTransportLayer * | tLayer | ) |

enable user-defined transport layer.

This method is needed when the network association should use a non-default transport layer (e.g. a TLS connection). In this case a fully initialized transport layer object must be passed with this call after a call to initializeNetwork(), but prior to any call to performQuery(). The transport layer object will not be deleted by this class and must remain alive until this object is deleted or a new transport layer is set.

Parameters

  tLayer | pointer to transport layer object.

Returns
  EC_Normal if successful, an error code otherwise.

## ◆ writeToFile()

static OFBool DcmFindSCU::writeToFile | ( | const char * | ofname,
|  | DcmDataset * | dataset
| ) |  |
| static

static helper function that writes the content of the given dataset into a DICOM file (using the DICOM file format with metaheader).

This method produces a temporary copy of the dataset and should, therefore, not be used with very large datasets.

Parameters

  ofname | filename to write.
  dataset | dataset to store in file.

Returns
  EC_Normal if successful, an error code otherwise.

## ◆ writeToXMLFile()

static OFBool DcmFindSCU::writeToXMLFile | ( | const char * | ofname,
|  | DcmDataset * | dataset
| ) |  |
| static

static helper function that writes the content of the given dataset into an XML file (see "dcm2xml.dtd", starts with top-level element "data-set").

This method also tries to determine the character encoding of the dataset.

Parameters

  ofname | filename to write.
  dataset | dataset to store in file.

Returns
  EC_Normal if successful, an error code otherwise.

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

- dcmnet/include/dcmtk/dcmnet/dfindscu.h

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