Main Page | Class Hierarchy | Alphabetical List | Class List | File List | Class Members | Related Pages

imagedb.h

00001 /*
00002  *
00003  *  Copyright (C) 1993-2002, OFFIS
00004  *
00005  *  This software and supporting documentation were developed by
00006  *
00007  *    Kuratorium OFFIS e.V.
00008  *    Healthcare Information and Communication Systems
00009  *    Escherweg 2
00010  *    D-26121 Oldenburg, Germany
00011  *
00012  *  THIS SOFTWARE IS MADE AVAILABLE,  AS IS,  AND OFFIS MAKES NO  WARRANTY
00013  *  REGARDING  THE  SOFTWARE,  ITS  PERFORMANCE,  ITS  MERCHANTABILITY  OR
00014  *  FITNESS FOR ANY PARTICULAR USE, FREEDOM FROM ANY COMPUTER DISEASES  OR
00015  *  ITS CONFORMITY TO ANY SPECIFICATION. THE ENTIRE RISK AS TO QUALITY AND
00016  *  PERFORMANCE OF THE SOFTWARE IS WITH THE USER.
00017  *
00018  *  Module:  imagectn
00019  *
00020  *  Author:  Andrew Hewett
00021  *
00022  *  Purpose: Public interface for Image Database Module. Module Prefix: DB_ 
00023  *
00024  *  Last Update:      $Author: meichel $
00025  *  Update Date:      $Date: 2002/11/27 13:27:52 $
00026  *  Source File:      $Source: /share/dicom/cvs-depot/dcmtk/imagectn/include/imagedb.h,v $
00027  *  CVS/RCS Revision: $Revision: 1.17 $
00028  *  Status:           $State: Exp $
00029  *
00030  *  CVS/RCS Log at end of file
00031  *
00032  */
00033 
00034 #ifndef IMGDB_H
00035 #define IMGDB_H
00036 
00037 #include "osconfig.h"    /* make sure OS specific configuration is included first */
00038 
00039 #define INCLUDE_CSTDLIB
00040 #define INCLUDE_CSTDIO
00041 #include "ofstdinc.h"
00042 
00043 BEGIN_EXTERN_C
00044 #ifdef HAVE_UNISTD_H
00045 #include <unistd.h>
00046 #endif
00047 END_EXTERN_C
00048 
00049 #include "dicom.h"
00050 #include "cond.h"
00051 #include "dcdatset.h"
00052 #include "dimse.h"
00053 
00054 
00055 #ifndef MAXPATHLEN
00056 #define MAXPATHLEN 1024
00057 #endif
00058 
00059 
00060 #define DBINDEXFILE "index.dat"
00061 
00062 #ifndef _WIN32
00063 /* we lock image files on all platforms except Win32 where it does not work
00064  * due to the different semantics of LockFile/LockFileEx compared to flock.
00065  */
00066 #define LOCK_IMAGE_FILES
00067 #endif
00068 
00069 
00070   /* This enum describes the status of one entry in the database hierarchy.
00071        An entry can describe a study, a series or an instance.
00072        A study or series is new exactly if all subobjects (series and instances) are new.
00073        A study or series contains new subobjecs as long as any subobject
00074        (series or instance) has the status objectIsNew.
00075        Instances can never have the status DVIF_objectContainsNewSubobjects.
00076      */
00077 
00078     enum DVIFhierarchyStatus
00079     {
00080       DVIF_objectIsNotNew,
00081       DVIF_objectIsNew,
00082       DVIF_objectContainsNewSubobjects
00083     };
00084 
00085 
00086 
00087 /* Status Structure */
00088 
00089 typedef struct {
00090     unsigned short status;
00091     DcmDataset *statusDetail;
00092 } DB_Status;
00093 
00094 
00095 /*
00096  * A Database Handle (Opaque Type)
00097  * The Database routines define this differently and its
00098  * structure is hidden from the caller.
00099  */
00100 typedef struct {
00101     void    *privateData;
00102 } DB_Handle;
00103 
00104 
00105 /*
00106  * Public Function Prototypes
00107  */
00108 
00109 void DB_enableQuotaSystem(OFBool enable);
00110 /*
00111 ** Enabled/Disabled the DB quota system.  
00112 ** If the quota system is disabled then no images will be
00113 ** deleted due to quotas being exceeded.
00114 **
00115 ** Default: quota system enabled.
00116 */
00117 
00118 void DB_setDebugLevel(int debugLevel);
00119 int DB_getDebugLevel();
00120 /*
00121 ** set and get the DB module debug level.
00122 */
00123 
00124 void DB_PrintIndexFile(char *storeArea);
00125 /*
00126 ** Dump DB index file to stdout.
00127 */
00128 
00129 void DB_setIdentifierChecking(OFBool checkFind, OFBool checkMove);
00130 OFBool DB_doCheckFindIdentifier();
00131 OFBool DB_doCheckMoveIdentifier();
00132 /*
00133  * Globally set the DB module to perform (or not perform) checking
00134  * of FIND and MOVE request identifiers.
00135  * Default: don't do checking
00136  */
00137 
00138 /* max 500 studies in the database */
00139 #define DB_UpperMaxStudies      500
00140 /* max 1 GByte per study */
00141 #define DB_UpperMaxBytesPerStudy    0x40000000L
00142 
00143 OFCondition DB_createHandle(const char *storageArea,
00144             long maxStudiesPerStorageArea,
00145             long maxBytesPerStudy,
00146             DB_Handle **handle);
00147 /* 
00148  * Creates and initializes a DB_Handle handle for the given 
00149  * database storage area (storageArea) as a mechanism for keeping 
00150  * track of state between sub-operations.
00151  * In addition to the storage area directory, limitations on the
00152  * number of studies per storage area and the number of bytes per study
00153  * are passed over to control the use of the C-STORE operation.
00154  * The DB Module will use these limitations to enforce RSNA'93 Demonstration
00155  * Requirements (i.e. by deleting older studies if the limitation is
00156  * exceeded). 
00157  *
00158  * The routine should return EC_Normal upon normal completion, or
00159  * some other OFCondition code upon failure.
00160  */
00161 
00162 OFCondition DB_destroyHandle(DB_Handle **handle);
00163 /* 
00164  * Destroy a DB_Handle, cancel any ongoing
00165  * request if necessary, delete temporary files used for C-STORE and
00166  * sub-operations of C-MOVE.
00167  * 
00168  * The routine should return EC_Normal upon normal completion, or
00169  * some other OFCondition code upon failure.
00170  */
00171 
00172 
00173 OFCondition DB_makeNewStoreFileName(DB_Handle *handle,
00174             const char *SOPClassUID,
00175             const char *SOPInstanceUID,
00176             char *newImageFileName);
00177 /*
00178  * This routine, given a SOPClassUID and a SOPInstanceUID
00179  * (from a store request), should provide a filename (in newImageFileName)
00180  * where an incomming image can be stored.  
00181  * The Service Class Executive (SCE) will save the image data associated
00182  * with a C-STORE request in this file.
00183  * This file should be semi-permanent.  That is, it should only
00184  * be removed when the image is deleted to satisfy the RSNA 
00185  * Demonstration Requirements, or if the store operation failed.
00186  *
00187  * The file name provided here will subsequently be passed to
00188  * the DB_storeRequest routine for registration in the database.
00189  * The routine will be called by the SCE prior to
00190  * each DB_storeRequest.
00191  *
00192  * This behaviour is needed since the CTN Display process operates
00193  * asynchronously and requires access to stored image data so that it 
00194  * may be displayed.  The SCE will post a request to the CTN Display 
00195  * to display the first image stored in a study.  This file must then
00196  * exist when the CTN Display process tries to perform the display
00197  * action at some later date.
00198  *
00199  * Memory for newImageFileName will be provided by the caller and
00200  * should be at least MAXPATHLEN+1 characters.   
00201  * The file name generated should be an absolute file name.
00202  * 
00203  * The routine should return EC_Normal upon normal completion, or
00204  * some other OFCondition code upon failure.
00205  */
00206 
00207 OFCondition DB_storeRequest(DB_Handle *handle,
00208             const char *SOPClassUID,
00209             const char *SOPInstanceUID,
00210             const char *imageFileName,
00211             DB_Status  *status,
00212             OFBool     isNew = OFTrue /* default: set instance reviewed status to DVIF_objectIsNew */);
00213 /* 
00214  * Add data from imageFileName to database, store given SOP class UID,
00215  * SOP instance UID and read data from imageFileName to store in database
00216  *
00217  * Upon invoking this routine the image stored in imageFileName becomes
00218  * the responsibility of the DB module.
00219  * The status structure should contain SUCCESS or some failure status.
00220  * 
00221  * The routine should return EC_Normal upon normal completion, or
00222  * some other OFCondition code upon failure.
00223  */
00224 
00225 OFCondition DB_startFindRequest(DB_Handle *handle,
00226             const char *SOPClassUID,
00227             DcmDataset *findRequestIdentifiers,
00228             DB_Status *status); 
00229 /* 
00230  * Start FIND action using the given SOP class UID
00231  * and DICOM Object containing the find request identifiers.
00232  *
00233  * The caller retains responsibility for destroying the 
00234  * findRequestIdentifiers when no longer needed.
00235  * 
00236  * Status should contain a value of PENDING if any FIND responses
00237  * will be generated, or a value of SUCCESS if no FIND responses will
00238  * be generated (SUCCESS indicates the completion of a operation), or
00239  * other status codes upon failure.
00240  *
00241  * The routine should return EC_Normal upon normal completion, or
00242  * some other OFCondition code upon failure.
00243  */
00244         
00245 OFCondition DB_nextFindResponse(DB_Handle *handle,
00246             DcmDataset **findResponseIdentifiers,
00247             DB_Status *status);
00248 /* 
00249  * Create a DicomObject containing the next available FIND response
00250  * identifiers (result of previous FIND operation).
00251  *
00252  * The caller is responsible for destroying the findResponseIdentifiers
00253  * when no longer needed.
00254  *
00255  * Status should contain a value of PENDING if a FIND response
00256  * is available, or a value of SUCCESS on completion, or
00257  * other status codes upon failure.
00258  *
00259  * The routine should return EC_Normal upon normal completion, or
00260  * some other OFCondition code upon failure.
00261  */
00262 
00263 OFCondition DB_cancelFindRequest(DB_Handle *handle,
00264             DB_Status *status);
00265 /* 
00266  * Cancel ongoing FIND request, stop and reset every running operation
00267  * associated with this request, delete existing temporary files.
00268  *
00269  * The routine should return EC_Normal upon normal completion, or
00270  * some other OFCondition code upon failure.
00271  */
00272     
00273 OFCondition DB_startMoveRequest(DB_Handle *handle,
00274             const char *SOPClassUID,
00275             DcmDataset *moveRequestIdentifiers,
00276             DB_Status *status);
00277 /* 
00278  * Start MOVE action using the given SOP class UID
00279  * and DICOM Object containing the move request identifiers.
00280  *
00281  * The caller retains responsibility for destroying the 
00282  * moveRequestIdentifiers when no longer needed.
00283  * 
00284  * Status should contain a value of PENDING if any MOVE responses
00285  * will be generated, or a value of SUCCESS if no MOVE responses will
00286  * be generated (SUCCESS indicates the completion of a operation), or
00287  * other status codes upon failure.
00288  *
00289  * The routine should return EC_Normal upon normal completion, or
00290  * some other OFCondition code upon failure.
00291  * 
00292  */
00293 
00294 OFCondition DB_nextMoveResponse(DB_Handle *handle,
00295             char *SOPClassUID,
00296             char *SOPInstanceUID,
00297             char *imageFileName,
00298             unsigned short *numberOfRemainingSubOperations,
00299             DB_Status *status);
00300 /* 
00301  * Constructs the information required for the next available C-MOVE 
00302  * sub-operation (the image SOP class UID, SOP Instance UID and an
00303  * imageFileName containing the requested data).  
00304  *
00305  * The caller will pass sufficient storage for the string parameters.
00306  * 
00307  * The DB module is reponsible for creating and destroying any
00308  * temporary image files.
00309  *
00310  * On return, the numberOfRemainingSubOperations parameter will contain
00311  * the number of suboperations still remaining for the request
00312  * (this number is needed by move responses with PENDING status).
00313  *
00314  * Status should contain a value of PENDING if a MOVE response
00315  * is available, or a value of SUCCESS on completion, or
00316  * other status codes upon failure.
00317  *
00318  * The routine should return EC_Normal upon normal completion, or
00319  * some other OFCondition code upon failure.
00320  */
00321 
00322 OFCondition DB_cancelMoveRequest(DB_Handle *handle,
00323             DB_Status *status);
00324 /* 
00325  * Cancel ongoing MOVE request, stop and reset every running operation
00326  * associated with this request, delete existing temporary files
00327  *
00328  * The routine should return EC_Normal upon normal completion, or
00329  * some other OFCondition code upon failure.
00330  */
00331 
00332 OFCondition DB_pruneInvalidRecords(DB_Handle *dbHandle);
00333 /*
00334  * Prune invalid records from the database.
00335  * Records referring to non-existant image files are invalid.
00336  */
00337 
00338 #endif
00339 
00340 /*
00341 ** CVS Log
00342 ** $Log: imagedb.h,v $
00343 ** Revision 1.17  2002/11/27 13:27:52  meichel
00344 ** Adapted module imagectn to use of new header file ofstdinc.h
00345 **
00346 ** Revision 1.16  2001/11/12 14:54:31  meichel
00347 ** Removed all ctndisp related code from imagectn
00348 **
00349 ** Revision 1.15  2001/10/12 12:43:07  meichel
00350 ** Adapted imagectn to OFCondition based dcmnet module (supports strict mode).
00351 **
00352 ** Revision 1.14  2001/06/01 15:51:26  meichel
00353 ** Updated copyright header
00354 **
00355 ** Revision 1.13  2000/11/23 16:40:52  joergr
00356 ** Added new command line option to dbregimg allowing to specify whether
00357 ** instance reviewed status of newly registered objects should be set to 'new'
00358 ** or 'not new'.
00359 **
00360 ** Revision 1.12  2000/03/08 16:41:07  meichel
00361 ** Updated copyright header.
00362 **
00363 ** Revision 1.11  2000/02/23 15:13:26  meichel
00364 ** Corrected macro for Borland C++ Builder 4 workaround.
00365 **
00366 ** Revision 1.10  2000/02/01 11:43:44  meichel
00367 ** Avoiding to include <stdlib.h> as extern "C" on Borland C++ Builder 4,
00368 **   workaround for bug in compiler header files.
00369 **
00370 ** Revision 1.9  1999/06/10 12:12:13  meichel
00371 ** Adapted imagectn to new command line option scheme.
00372 **   Added support for Patient/Study Only Q/R model and C-GET (experimental).
00373 **
00374 ** Revision 1.8  1998/12/22 15:18:43  vorwerk
00375 ** remove enum DVIFhierarchyStatus from dcmpstat/libsrc/dviface.h and add it
00376 ** here
00377 **
00378 ** Revision 1.7  1998/12/22 15:11:28  vorwerk
00379 ** removed from libsrc and added in include
00380 **
00381 ** Revision 1.6  1997/08/05 07:40:32  andreas
00382 ** Change definition of path to database index now using consistently
00383 ** the defines PATH_SEPARATOR and DBINDEXFILE
00384 **
00385 ** Revision 1.5  1997/07/21 08:59:53  andreas
00386 ** - Replace all boolean types (BOOLEAN, CTNBOOLEAN, DICOM_BOOL, BOOL)
00387 **   with one unique boolean type OFBool.
00388 **
00389 ** Revision 1.4  1996/09/27 08:46:36  hewett
00390 ** Enclosed system include files with BEGIN_EXTERN_C/END_EXTERN_C.
00391 **
00392 ** Revision 1.3  1996/04/29 10:11:46  hewett
00393 ** Added function to disable DB quota system from deleting image files.
00394 **
00395 ** Revision 1.2  1996/04/22 10:31:16  hewett
00396 ** Added function declaration for DB_pruneInvalidRecords().
00397 **
00398 ** Revision 1.1.1.1  1996/03/28 19:24:59  hewett
00399 ** Oldenburg Image CTN Software ported to use the dcmdata C++ toolkit.
00400 **
00401 */


Generated on 8 Dec 2004 for OFFIS DCMTK Version 3.5.3 by Doxygen 1.3.9.1