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

DcmFindSCU &	operator= (const DcmFindSCU &other)
	Private undefined assignment operator.

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.

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.

◆ 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`
	)

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.

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

Public Member Functions

Static Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Member Function Documentation

◆ addPresentationContext()

◆ dropNetwork()

◆ findSCU()

◆ initializeNetwork()

◆ performQuery()

◆ setOutputResponseLimit()

◆ setTransportLayer()

◆ writeToFile()

◆ writeToXMLFile()