DCMTK Version 3.7.0 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
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
| ) |  |
| static private

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 | ) |
| static private

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

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