DCMTK  Version 3.6.7
OFFIS DICOM Toolkit
Public Member Functions | Static Public Member Functions | Private Member Functions | Static Private Member Functions | Private Attributes | List of all members
DcmQueryRetrieveIndexDatabaseHandle Class Reference

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

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
 
DcmQueryRetrieveIndexDatabaseHandleoperator= (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_Handlehandle_
 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
storageAreaname of storage area, must not be NULL
maxStudiesPerStorageAreamaximum number of studies for this storage area, needed to correctly parse the index file.
maxBytesPerStudymaximum number of bytes per study, for quota mechanism
resultupon 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
statuspointer 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
statuspointer 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
pStudyDescpointer 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
idxpointer to index number, updated upon successful return
idxRecpointer 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
idxinitialized 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
idxindex
idxRecpointer 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
idxindex
Returns
EC_Normal upon success, an error code otherwise

◆ DB_lock()

OFCondition DcmQueryRetrieveIndexDatabaseHandle::DB_lock ( OFBool  exclusive)

create lock on database

Parameters
exclusiveexclusive/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
pStudyDescpointer 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
imgFilefile 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
enableweather 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
storeAreaname of storage area, must not be NULL
sopClassUIDSOP Class UID to search for
sopInstanceUIDSOP 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
idxindex
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
sourceCharacterSetthe character set the data is encoded in.
destinationCharacterSetthe 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
characterSetthe 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
SOPClassUIDSOP class UID of DICOM instance
SOPInstanceUIDSOP instance UID of DICOM instance
newImageFileNamefile 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.
newImageFileNameLenlength 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
findResponseIdentifiersDICOM dataset returned in this parameter. The caller is responsible for destroying the findResponseIdentifiers when no longer needed.
statuspointer 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.
characterSetOptionsthe 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
SOPClassUIDpointer to string of at least 65 characters into which the SOP class UID for the next DICOM object to be transferred is copied.
SOPClassUIDSizesize of SOPClassUID element
SOPInstanceUIDpointer to string of at least 65 characters into which the SOP instance UID for the next DICOM object to be transferred is copied.
SOPInstanceUIDSizesize of SOPInstanceUID element
imageFileNamepointer to string of at least MAXPATHLEN+1 characters into which the file path for the next DICOM object to be transferred is copied.
imageFileNameSizesize of imageFileName element
numberOfRemainingSubOperationsOn return, this parameter will contain the number of suboperations still remaining for the request (this number is needed by move responses with PENDING status).
statuspointer 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
storeAreaname of storage area, must not be NULL

◆ pruneInvalidRecords()

OFCondition DcmQueryRetrieveIndexDatabaseHandle::pruneInvalidRecords ( )
virtual

Prune invalid records from the database.

Records referring to non-existant 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
checkFindchecking for C-FIND parameters
checkMovechecking 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
SOPClassUIDSOP class UID of query service, identifies Q/R model
findRequestIdentifiersdataset containing request identifiers (i.e., the query) The caller retains responsibility for destroying the findRequestIdentifiers when no longer needed.
statuspointer 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
SOPClassUIDSOP class UID of retrieve service, identifies Q/R model
moveRequestIdentifiersdataset containing request identifiers (i.e., the query) The caller retains responsibility for destroying the moveRequestIdentifiers when no longer needed.
statuspointer 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
SOPClassUIDSOP class UID of DICOM instance
SOPInstanceUIDSOP instance UID of DICOM instance
imageFileNamefile name (full path) of DICOM instance
statuspointer to DB status object in which a DIMSE status code suitable for use with the C-STORE-RSP message is set.
isNewif 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:


Generated on Thu Apr 28 2022 for DCMTK Version 3.6.7 by Doxygen 1.9.1