This class maintains database handles based on the classical "index.dat" file. More...

Inheritance diagram for DcmQueryRetrieveIndexDatabaseHandle:

Public Member Functions
	DcmQueryRetrieveIndexDatabaseHandle (const char *storageArea, long maxStudiesPerStorageArea, long maxBytesPerStudy, OFCondition &result)
	Constructor. More...

	~DcmQueryRetrieveIndexDatabaseHandle ()
	Destructor. More...

void	setIdentifierChecking (OFBool checkFind, OFBool checkMove)
	Configure the DB module to perform (or not perform) checking of FIND and MOVE request identifiers. More...

OFCondition	makeNewStoreFileName (const char SOPClassUID, const char SOPInstanceUID, char *newImageFileName, size_t newImageFileNameLen)
	create a filename under which a DICOM object that is currently being received through a C-STORE operation can be stored. More...

OFCondition	storeRequest (const char SOPClassUID, const char SOPInstanceUID, const char imageFileName, DcmQueryRetrieveDatabaseStatus status, OFBool isNew=OFTrue)
	register the given DICOM object, which has been received through a C-STORE operation and stored in a file, in the database. More...

OFCondition	startFindRequest (const char SOPClassUID, DcmDataset findRequestIdentifiers, DcmQueryRetrieveDatabaseStatus *status)
	initiate FIND operation using the given SOP class UID (which identifies the query model) and DICOM dataset containing find request identifiers. More...

OFCondition	nextFindResponse (DcmDataset *findResponseIdentifiers, DcmQueryRetrieveDatabaseStatus status, const DcmQueryRetrieveCharacterSetOptions &characterSetOptions)
	return the next available FIND response as a new DICOM dataset. More...

OFCondition	cancelFindRequest (DcmQueryRetrieveDatabaseStatus *status)
	cancel the ongoing FIND request, stop and reset every running operation associated with this request, delete existing temporary files. More...

OFCondition	startMoveRequest (const char SOPClassUID, DcmDataset moveRequestIdentifiers, DcmQueryRetrieveDatabaseStatus *status)
	initiate MOVE operation using the given SOP class UID (which identifies the retrieve model) and DICOM dataset containing move request identifiers. More...

OFCondition	nextMoveResponse (char SOPClassUID, size_t SOPClassUIDSize, char SOPInstanceUID, size_t SOPInstanceUIDSize, char imageFileName, size_t imageFileNameSize, unsigned short numberOfRemainingSubOperations, DcmQueryRetrieveDatabaseStatus *status)
	Constructs the information required for the next available C-MOVE sub-operation (the image SOP class UID, SOP Instance UID and an imageFileName containing the requested data). More...

OFCondition	cancelMoveRequest (DcmQueryRetrieveDatabaseStatus *status)
	cancel the ongoing MOVE request, stop and reset every running operation associated with this request, delete existing temporary files. More...

OFCondition	pruneInvalidRecords ()
	Prune invalid records from the database. More...

void	enableQuotaSystem (OFBool enable)
	enable/disable the DB quota system (default: enabled) which causes images to be deleted if certain boundaries (number of studies, bytes per study) are exceeded. More...

OFBool	findSOPInstance (const char *storeArea, const OFString &sopClassUID, const OFString &sopInstanceUID)
	search for a SOP class and SOP instance UIDs in index file. More...

OFCondition	deleteImageFile (char *imgFile)
	deletes the given file only if the quota mechanism is enabled. More...

OFCondition	DB_lock (OFBool exclusive)
	create lock on database More...

OFCondition	DB_unlock ()
	release lock on database

OFCondition	DB_IdxGetNext (int idx, IdxRecord idxRec)
	Get next Index record that is in use (i.e. More...

OFCondition	DB_IdxInitLoop (int *idx)
	seek to beginning of image records in index file More...

OFCondition	DB_IdxRead (int idx, IdxRecord *idxRec)
	read index record at given index More...

OFCondition	DB_GetStudyDesc (StudyDescRecord *pStudyDesc)
	get study descriptor record from start of index file More...

OFCondition	DB_StudyDescChange (StudyDescRecord *pStudyDesc)
	write study descriptor record to start of index file More...

OFCondition	DB_IdxRemove (int idx)
	deactivate index record at given index by setting an empty filename More...

OFCondition	instanceReviewed (int idx)
	clear the "is new" flag for the instance with the given index More...

const char *	getStorageArea () const
	return name of storage area

const char *	getIndexFilename () const
	return path to index file

Public Member Functions inherited from DcmQueryRetrieveDatabaseHandle
	DcmQueryRetrieveDatabaseHandle ()
	default constructor

virtual	~DcmQueryRetrieveDatabaseHandle ()
	Destructor. More...

virtual OFCondition	makeNewStoreFileName (const char SOPClassUID, const char SOPInstanceUID, char *newImageFileName, size_t newImageFileNameLen)=0
	create a filename under which a DICOM object that is currently being received through a C-STORE operation can be stored. More...

virtual OFCondition	storeRequest (const char SOPClassUID, const char SOPInstanceUID, const char imageFileName, DcmQueryRetrieveDatabaseStatus status, OFBool isNew=OFTrue)=0
	register the given DICOM object, which has been received through a C-STORE operation and stored in a file, in the database. More...

virtual OFCondition	startFindRequest (const char SOPClassUID, DcmDataset findRequestIdentifiers, DcmQueryRetrieveDatabaseStatus *status)=0
	initiate FIND operation using the given SOP class UID (which identifies the query model) and DICOM dataset containing find request identifiers. More...

virtual OFCondition	nextFindResponse (DcmDataset *findResponseIdentifiers, DcmQueryRetrieveDatabaseStatus status, const DcmQueryRetrieveCharacterSetOptions &characterSetOptions)=0
	return the next available FIND response as a new DICOM dataset. More...

virtual OFCondition	cancelFindRequest (DcmQueryRetrieveDatabaseStatus *status)=0
	cancel the ongoing FIND request, stop and reset every running operation associated with this request, delete existing temporary files. More...

virtual OFCondition	startMoveRequest (const char SOPClassUID, DcmDataset moveRequestIdentifiers, DcmQueryRetrieveDatabaseStatus *status)=0
	initiate MOVE operation using the given SOP class UID (which identifies the retrieve model) and DICOM dataset containing move request identifiers. More...

virtual OFCondition	nextMoveResponse (char SOPClassUID, size_t SOPClassUIDSize, char SOPInstanceUID, size_t SOPInstanceUIDSize, char imageFileName, size_t imageFileNameSize, unsigned short numberOfRemainingSubOperations, DcmQueryRetrieveDatabaseStatus *status)=0
	Constructs the information required for the next available C-MOVE sub-operation (the image SOP class UID, SOP Instance UID and an imageFileName containing the requested data). More...

virtual OFCondition	cancelMoveRequest (DcmQueryRetrieveDatabaseStatus *status)=0
	cancel the ongoing MOVE request, stop and reset every running operation associated with this request, delete existing temporary files. More...

virtual OFCondition	pruneInvalidRecords ()=0
	Prune invalid records from the database. More...

virtual void	setIdentifierChecking (OFBool checkFind, OFBool checkMove)=0
	Configure the DB module to perform (or not perform) checking of FIND and MOVE request identifiers. More...

Static Public Member Functions
static void	printIndexFile (char *storeArea)
	dump database index file to stdout. More...

Private Member Functions
	DcmQueryRetrieveIndexDatabaseHandle (const DcmQueryRetrieveIndexDatabaseHandle &other)
	private undefined copy constructor

DcmQueryRetrieveIndexDatabaseHandle &	operator= (const DcmQueryRetrieveIndexDatabaseHandle &other)
	private undefined assignment operator

Static Private Member Functions
static OFBool	isConversionToUTF8Necessary (const OFString &characterSet)
	Determine if a character set is not compatible to UTF-8, i.e. if it is not UTF-8 or ASCII. More...

static OFBool	isConversionNecessary (const OFString &sourceCharacterSet, const OFString &destinationCharacterSet)
	Determine if data in the source character set must be converted to be compatible to the given destination character set. More...

Private Attributes
DB_Private_Handle *	handle_
	database handle

OFBool	quotaSystemEnabled
	flag indicating whether or not the quota system is enabled

OFBool	doCheckFindIdentifier
	flag indicating whether or not the check function for FIND requests is enabled

OFBool	doCheckMoveIdentifier
	flag indicating whether or not the check function for MOVE requests is enabled

OFFilenameCreator	fnamecreator
	helper object for file name creation

Detailed Description

This class maintains database handles based on the classical "index.dat" file.

A database handle maintains a connection to a database and encapsulates database support for store, find and move/get operations.

Constructor & Destructor Documentation

◆ DcmQueryRetrieveIndexDatabaseHandle()

DcmQueryRetrieveIndexDatabaseHandle::DcmQueryRetrieveIndexDatabaseHandle	(	const char *	storageArea,
		long	maxStudiesPerStorageArea,
		long	maxBytesPerStudy,
		OFCondition &	result
	)

Constructor.

Creates and initializes a index file handle for the given database storage area (storageArea).

Parameters

storageArea	name of storage area, must not be NULL
maxStudiesPerStorageArea	maximum number of studies for this storage area, needed to correctly parse the index file.
maxBytesPerStudy	maximum number of bytes per study, for quota mechanism
result	upon successful initialization of the database handle, EC_Normal is returned in this parameter, otherwise an error code is returned.

◆ ~DcmQueryRetrieveIndexDatabaseHandle()

DcmQueryRetrieveIndexDatabaseHandle::~DcmQueryRetrieveIndexDatabaseHandle ( )

Destructor.

Destroys handle, cancels any ongoing request if necessary, deletes temporary files used for C-STORE and sub-operations of C-MOVE.

Member Function Documentation

◆ cancelFindRequest()

OFCondition DcmQueryRetrieveIndexDatabaseHandle::cancelFindRequest ( DcmQueryRetrieveDatabaseStatus * status )

virtual

cancel the ongoing FIND request, stop and reset every running operation associated with this request, delete existing temporary files.

Parameters

status pointer to DB status object in which a DIMSE status code suitable for use with the C-FIND-RSP message is set.

Returns: EC_Normal upon normal completion, or some other OFCondition code upon failure.

Implements DcmQueryRetrieveDatabaseHandle.

◆ cancelMoveRequest()

OFCondition DcmQueryRetrieveIndexDatabaseHandle::cancelMoveRequest ( DcmQueryRetrieveDatabaseStatus * status )

virtual

cancel the ongoing MOVE request, stop and reset every running operation associated with this request, delete existing temporary files.

Parameters

status pointer to DB status object in which a DIMSE status code suitable for use with the C-MOVE-RSP message is set.

Returns: EC_Normal upon normal completion, or some other OFCondition code upon failure.

Implements DcmQueryRetrieveDatabaseHandle.

◆ DB_GetStudyDesc()

OFCondition DcmQueryRetrieveIndexDatabaseHandle::DB_GetStudyDesc ( StudyDescRecord * pStudyDesc )

get study descriptor record from start of index file

Parameters

pStudyDesc pointer to study record descriptor structure

Returns: EC_Normal upon success, an error code otherwise

◆ DB_IdxGetNext()

OFCondition DcmQueryRetrieveIndexDatabaseHandle::DB_IdxGetNext	(	int *	idx,
		IdxRecord *	idxRec
	)

Get next Index record that is in use (i.e.

references a non-empty a filename)

Parameters

idx	pointer to index number, updated upon successful return
idxRec	pointer to index record structure

Returns: EC_Normal upon success, an error code otherwise

◆ DB_IdxInitLoop()

OFCondition DcmQueryRetrieveIndexDatabaseHandle::DB_IdxInitLoop ( int * idx )

seek to beginning of image records in index file

Parameters

idx	initialized to -1

Returns: EC_Normal upon success, an error code otherwise

◆ DB_IdxRead()

OFCondition DcmQueryRetrieveIndexDatabaseHandle::DB_IdxRead	(	int	idx,
		IdxRecord *	idxRec
	)

read index record at given index

Parameters

idx	index
idxRec	pointer to index record

Returns: EC_Normal upon success, an error code otherwise

◆ DB_IdxRemove()

OFCondition DcmQueryRetrieveIndexDatabaseHandle::DB_IdxRemove ( int idx )

deactivate index record at given index by setting an empty filename

Parameters

idx index

Returns: EC_Normal upon success, an error code otherwise

◆ DB_lock()

OFCondition DcmQueryRetrieveIndexDatabaseHandle::DB_lock ( OFBool exclusive )

create lock on database

Parameters

exclusive exclusive/shared lock flag

Returns: EC_Normal upon success, an error code otherwise

◆ DB_StudyDescChange()

OFCondition DcmQueryRetrieveIndexDatabaseHandle::DB_StudyDescChange ( StudyDescRecord * pStudyDesc )

write study descriptor record to start of index file

Parameters

pStudyDesc pointer to study record descriptor structure

Returns: EC_Normal upon success, an error code otherwise

◆ deleteImageFile()

OFCondition DcmQueryRetrieveIndexDatabaseHandle::deleteImageFile ( char * imgFile )

deletes the given file only if the quota mechanism is enabled.

The image is not de-registered from the database by this routine.

Parameters

imgFile file name (path) to the file to be deleted.

Returns: EC_Normal upon normal completion, or some other OFCondition code upon failure.

◆ enableQuotaSystem()

void DcmQueryRetrieveIndexDatabaseHandle::enableQuotaSystem ( OFBool enable )

enable/disable the DB quota system (default: enabled) which causes images to be deleted if certain boundaries (number of studies, bytes per study) are exceeded.

Parameters

enable weather to disable/enable

◆ findSOPInstance()

OFBool DcmQueryRetrieveIndexDatabaseHandle::findSOPInstance	(	const char *	storeArea,
		const OFString &	sopClassUID,
		const OFString &	sopInstanceUID
	)

search for a SOP class and SOP instance UIDs in index file.

Parameters

storeArea	name of storage area, must not be NULL
sopClassUID	SOP Class UID to search for
sopInstanceUID	SOP Instance UID to search for

Returns: OFTrue if SOP Class and SOP Instance UIDs are found. otherwise return OFFalse.

◆ instanceReviewed()

OFCondition DcmQueryRetrieveIndexDatabaseHandle::instanceReviewed ( int idx )

clear the "is new" flag for the instance with the given index

Parameters

idx index

Returns: EC_Normal upon success, an error code otherwise

◆ isConversionNecessary()

static OFBool DcmQueryRetrieveIndexDatabaseHandle::isConversionNecessary	(	const OFString &	sourceCharacterSet,
		const OFString &	destinationCharacterSet
	)

staticprivate

Determine if data in the source character set must be converted to be compatible to the given destination character set.

Parameters

sourceCharacterSet	the character set the data is encoded in.
destinationCharacterSet	the character set that is requested, e.g. the character set that the SCU understands.

Returns: OFTrue if the source character set is not equal to and not a subset of the destination character set, OFFalse otherwise.

◆ isConversionToUTF8Necessary()

static OFBool DcmQueryRetrieveIndexDatabaseHandle::isConversionToUTF8Necessary ( const OFString & characterSet )

staticprivate

Determine if a character set is not compatible to UTF-8, i.e. if it is not UTF-8 or ASCII.

Parameters

characterSet the character set to inspect.

Returns: OFTrue if the character set is neither ASCII nor UTF-8, OFFalse otherwise.

◆ makeNewStoreFileName()

OFCondition DcmQueryRetrieveIndexDatabaseHandle::makeNewStoreFileName	(	const char *	SOPClassUID,
		const char *	SOPInstanceUID,
		char *	newImageFileName,
		size_t	newImageFileNameLen
	)

virtual

create a filename under which a DICOM object that is currently being received through a C-STORE operation can be stored.

Parameters

SOPClassUID	SOP class UID of DICOM instance
SOPInstanceUID	SOP instance UID of DICOM instance
newImageFileName	file name is returned in this parameter. Memory must be provided by the caller and should be at least MAXPATHLEN+1 characters. The file name generated should be an absolute file name.
newImageFileNameLen	length of buffer pointed to by newImageFileName

Returns: EC_Normal upon normal completion, or some other OFCondition code upon failure.

Implements DcmQueryRetrieveDatabaseHandle.

◆ nextFindResponse()

OFCondition DcmQueryRetrieveIndexDatabaseHandle::nextFindResponse	(	DcmDataset **	findResponseIdentifiers,
		DcmQueryRetrieveDatabaseStatus *	status,
		const DcmQueryRetrieveCharacterSetOptions &	characterSetOptions
	)

virtual

return the next available FIND response as a new DICOM dataset.

Parameters

findResponseIdentifiers	DICOM dataset returned in this parameter. The caller is responsible for destroying the findResponseIdentifiers when no longer needed.
status	pointer to DB status object in which a DIMSE status code suitable for use with the C-FIND-RSP message is set. Status will be PENDING if more FIND responses will be generated or SUCCESS if no more FIND responses will be generated (SUCCESS indicates the completion of a operation), or another status code upon failure.
characterSetOptions	the character set options for response conversion etc.

Returns: EC_Normal upon normal completion, or some other OFCondition code upon failure.

Implements DcmQueryRetrieveDatabaseHandle.

◆ nextMoveResponse()

OFCondition DcmQueryRetrieveIndexDatabaseHandle::nextMoveResponse	(	char *	SOPClassUID,
		size_t	SOPClassUIDSize,
		char *	SOPInstanceUID,
		size_t	SOPInstanceUIDSize,
		char *	imageFileName,
		size_t	imageFileNameSize,
		unsigned short *	numberOfRemainingSubOperations,
		DcmQueryRetrieveDatabaseStatus *	status
	)

virtual

Constructs the information required for the next available C-MOVE sub-operation (the image SOP class UID, SOP Instance UID and an imageFileName containing the requested data).

Parameters

SOPClassUID	pointer to string of at least 65 characters into which the SOP class UID for the next DICOM object to be transferred is copied.
SOPClassUIDSize	size of SOPClassUID element
SOPInstanceUID	pointer to string of at least 65 characters into which the SOP instance UID for the next DICOM object to be transferred is copied.
SOPInstanceUIDSize	size of SOPInstanceUID element
imageFileName	pointer to string of at least MAXPATHLEN+1 characters into which the file path for the next DICOM object to be transferred is copied.
imageFileNameSize	size of imageFileName element
numberOfRemainingSubOperations	On return, this parameter will contain the number of suboperations still remaining for the request (this number is needed by move responses with PENDING status).
status	pointer to DB status object in which a DIMSE status code suitable for use with the C-MOVE-RSP message is set. Status will be PENDING if more MOVE responses will be generated or SUCCESS if no more MOVE responses will be generated (SUCCESS indicates the completion of a operation), or another status code upon failure.

Returns: EC_Normal upon normal completion, or some other OFCondition code upon failure.

Implements DcmQueryRetrieveDatabaseHandle.

◆ printIndexFile()

static void DcmQueryRetrieveIndexDatabaseHandle::printIndexFile ( char * storeArea )

static

dump database index file to stdout.

Parameters

storeArea name of storage area, must not be NULL

◆ pruneInvalidRecords()

OFCondition DcmQueryRetrieveIndexDatabaseHandle::pruneInvalidRecords ( )

virtual

Prune invalid records from the database.

Records referring to non-existent image files are invalid.

Implements DcmQueryRetrieveDatabaseHandle.

◆ setIdentifierChecking()

void DcmQueryRetrieveIndexDatabaseHandle::setIdentifierChecking	(	OFBool	checkFind,
		OFBool	checkMove
	)

virtual

Configure the DB module to perform (or not perform) checking of FIND and MOVE request identifiers.

Default is no checking.

Parameters

checkFind	checking for C-FIND parameters
checkMove	checking for C-MOVE parameters

Implements DcmQueryRetrieveDatabaseHandle.

◆ startFindRequest()

OFCondition DcmQueryRetrieveIndexDatabaseHandle::startFindRequest	(	const char *	SOPClassUID,
		DcmDataset *	findRequestIdentifiers,
		DcmQueryRetrieveDatabaseStatus *	status
	)

virtual

initiate FIND operation using the given SOP class UID (which identifies the query model) and DICOM dataset containing find request identifiers.

Parameters

SOPClassUID	SOP class UID of query service, identifies Q/R model
findRequestIdentifiers	dataset containing request identifiers (i.e., the query) The caller retains responsibility for destroying the findRequestIdentifiers when no longer needed.
status	pointer to DB status object in which a DIMSE status code suitable for use with the C-FIND-RSP message is set. Status will be PENDING if any FIND responses will be generated or SUCCESS if no FIND responses will be generated (SUCCESS indicates the completion of a operation), or another status code upon failure.

Returns: EC_Normal upon normal completion, or some other OFCondition code upon failure.

Implements DcmQueryRetrieveDatabaseHandle.

◆ startMoveRequest()

OFCondition DcmQueryRetrieveIndexDatabaseHandle::startMoveRequest	(	const char *	SOPClassUID,
		DcmDataset *	moveRequestIdentifiers,
		DcmQueryRetrieveDatabaseStatus *	status
	)

virtual

initiate MOVE operation using the given SOP class UID (which identifies the retrieve model) and DICOM dataset containing move request identifiers.

Parameters

SOPClassUID	SOP class UID of retrieve service, identifies Q/R model
moveRequestIdentifiers	dataset containing request identifiers (i.e., the query) The caller retains responsibility for destroying the moveRequestIdentifiers when no longer needed.
status	pointer to DB status object in which a DIMSE status code suitable for use with the C-MOVE-RSP message is set. Status will be PENDING if any MOVE responses will be generated or SUCCESS if no MOVE responses will be generated (SUCCESS indicates the completion of a operation), or another status code upon failure.

Returns: EC_Normal upon normal completion, or some other OFCondition code upon failure.

Implements DcmQueryRetrieveDatabaseHandle.

◆ storeRequest()

OFCondition DcmQueryRetrieveIndexDatabaseHandle::storeRequest	(	const char *	SOPClassUID,
		const char *	SOPInstanceUID,
		const char *	imageFileName,
		DcmQueryRetrieveDatabaseStatus *	status,
		OFBool	isNew = `OFTrue`
	)

virtual

register the given DICOM object, which has been received through a C-STORE operation and stored in a file, in the database.

Parameters

SOPClassUID	SOP class UID of DICOM instance
SOPInstanceUID	SOP instance UID of DICOM instance
imageFileName	file name (full path) of DICOM instance
status	pointer to DB status object in which a DIMSE status code suitable for use with the C-STORE-RSP message is set.
isNew	if true, the instance is marked as "new" in the database, if such a flag is maintained in the database.

Returns: EC_Normal upon normal completion, or some other OFCondition code upon failure.

Implements DcmQueryRetrieveDatabaseHandle.

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

dcmqrdb/include/dcmtk/dcmqrdb/dcmqrdbi.h

Public Member Functions

Static Public Member Functions

Private Member Functions

Static Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ DcmQueryRetrieveIndexDatabaseHandle()

◆ ~DcmQueryRetrieveIndexDatabaseHandle()

Member Function Documentation

◆ cancelFindRequest()

◆ cancelMoveRequest()

◆ DB_GetStudyDesc()

◆ DB_IdxGetNext()

◆ DB_IdxInitLoop()

◆ DB_IdxRead()

◆ DB_IdxRemove()

◆ DB_lock()

◆ DB_StudyDescChange()

◆ deleteImageFile()

◆ enableQuotaSystem()

◆ findSOPInstance()

◆ instanceReviewed()

◆ isConversionNecessary()

◆ isConversionToUTF8Necessary()

◆ makeNewStoreFileName()

◆ nextFindResponse()

◆ nextMoveResponse()

◆ printIndexFile()

◆ pruneInvalidRecords()

◆ setIdentifierChecking()

◆ startFindRequest()

◆ startMoveRequest()

◆ storeRequest()