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

dul.h

00001 /*
00002           Copyright (C) 1993, 1994, RSNA and Washington University
00003 
00004           The software and supporting documentation for the Radiological
00005           Society of North America (RSNA) 1993, 1994 Digital Imaging and
00006           Communications in Medicine (DICOM) Demonstration were developed
00007           at the
00008                   Electronic Radiology Laboratory
00009                   Mallinckrodt Institute of Radiology
00010                   Washington University School of Medicine
00011                   510 S. Kingshighway Blvd.
00012                   St. Louis, MO 63110
00013           as part of the 1993, 1994 DICOM Central Test Node project for, and
00014           under contract with, the Radiological Society of North America.
00015 
00016           THIS SOFTWARE IS MADE AVAILABLE, AS IS, AND NEITHER RSNA NOR
00017           WASHINGTON UNIVERSITY MAKE ANY WARRANTY ABOUT THE SOFTWARE, ITS
00018           PERFORMANCE, ITS MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR
00019           USE, FREEDOM FROM ANY COMPUTER DISEASES OR ITS CONFORMITY TO ANY
00020           SPECIFICATION. THE ENTIRE RISK AS TO QUALITY AND PERFORMANCE OF
00021           THE SOFTWARE IS WITH THE USER.
00022 
00023           Copyright of the software and supporting documentation is
00024           jointly owned by RSNA and Washington University, and free access
00025           is hereby granted as a license to use this software, copy this
00026           software and prepare derivative works based upon this software.
00027           However, any distribution of this software source code or
00028           supporting documentation or derivative works (source code and
00029           supporting documentation) must include the three paragraphs of
00030           the copyright notice.
00031 */
00032 /* Copyright marker.  Copyright will be inserted above.  Do not remove */
00033 /*
00034 ** @$=@$=@$=
00035 */
00036 /*
00037 **              DICOM 93
00038 **          Electronic Radiology Laboratory
00039 **        Mallinckrodt Institute of Radiology
00040 **      Washington University School of Medicine
00041 **
00042 ** Module Name(s):
00043 ** Author, Date:    Stephen M. Moore, 14-Apr-1993
00044 ** Intent:      This file defines the public structures and constants
00045 **          and the function prototypes for the DUL (DICOM Upper
00046 **          Layer) facility.
00047 ** Last Update:     $Author: meichel $, $Date: 2004/02/25 12:31:15 $
00048 ** Source File:     $RCSfile: dul.h,v $
00049 ** Revision:        $Revision: 1.19 $
00050 ** Status:      $State: Exp $
00051 */
00052 
00053 
00054 #ifndef DUL_IS_IN
00055 #define DUL_IS_IN 1
00056 
00057 #include "osconfig.h"    /* make sure OS specific configuration is included first */
00058 #include "ofglobal.h"
00059 #include "oftypes.h"
00060 #include "ofcast.h"
00061 #include "extneg.h"
00062 
00063 class DcmTransportConnection;
00064 class DcmTransportLayer;
00065 
00072 extern OFGlobal<OFBool> dcmDisableGethostbyaddr; /* default OFFalse */
00073 
00077 extern OFGlobal<Sint32> dcmConnectionTimeout;   /* default -1 */
00078 
00083 extern OFGlobal<int> dcmExternalSocketHandle;   /* default -1 */
00084 
00091 extern OFGlobal<const char *> dcmTCPWrapperDaemonName;   /* default NULL */
00092 
00093 /* Global option flag for compatibility with DCMTK releases prior to 3.0 
00094  * Default (0) is automatic handling, which should work in most cases.
00095  */
00096 extern OFGlobal<unsigned long> dcmEnableBackwardCompatibility;
00097 
00098 #ifndef DUL_KEYS
00099 #define DUL_KEYS 1
00100 typedef void DUL_NETWORKKEY;
00101 typedef void DUL_ASSOCIATIONKEY;
00102 typedef unsigned char DUL_PRESENTATIONCONTEXTID;
00103 #endif
00104 
00105 /*  Define a structure containing fixed length fields that can
00106  *  be used for requesting or accepting an association.  The
00107  *  lengths of "titles" and "names" are specified by the DICOM
00108  *  protocol document.  The fields in the structure are made
00109  *  longer to allow for zero-terminators.  DICOM doesn't know
00110  *  about node names, but the DUL_ package needs them.
00111  */
00112 
00113 #define DUL_LEN_TITLE  OFstatic_cast(size_t, 16)    /* required by DICOM protocol    */
00114 #define DUL_LEN_NAME   OFstatic_cast(size_t, 64)    /* required by DICOM protocol    */
00115 #define DUL_LEN_UID    OFstatic_cast(size_t, 64)    /* required by DICOM protocol    */
00116 #define DUL_LEN_NODE   OFstatic_cast(size_t, 127)   /* should be "big enough"    */
00117 
00118 
00119 /* DICOM PDU Types */
00120 
00121 #define DUL_TYPEASSOCIATERQ     OFstatic_cast(unsigned char, 0x01)
00122 #define DUL_TYPEASSOCIATEAC     OFstatic_cast(unsigned char, 0x02)
00123 #define DUL_TYPEASSOCIATERJ     OFstatic_cast(unsigned char, 0x03)
00124 #define DUL_TYPEDATA            OFstatic_cast(unsigned char, 0x04)
00125 #define DUL_TYPERELEASERQ       OFstatic_cast(unsigned char, 0x05)
00126 #define DUL_TYPERELEASERP       OFstatic_cast(unsigned char, 0x06)
00127 #define DUL_TYPEABORT           OFstatic_cast(unsigned char, 0x07)
00128 
00129 #define DUL_MAXTYPE         OFstatic_cast(unsigned char, 0x07)
00130 
00133 class DUL_ModeCallback
00134 {
00135 public:
00139   virtual void callback(unsigned long mode) = 0;
00140 };
00141 
00142 typedef struct {
00143     char applicationContextName[DUL_LEN_NAME + 1];
00144     char callingAPTitle[DUL_LEN_TITLE + 1];
00145     char calledAPTitle[DUL_LEN_TITLE + 1];
00146     char respondingAPTitle[DUL_LEN_TITLE + 1];
00147     unsigned long maxPDU;
00148     unsigned short result;
00149     unsigned short resultSource;
00150     unsigned short diagnostic;
00151     char callingPresentationAddress[64];
00152     char calledPresentationAddress[64];
00153     LST_HEAD *requestedPresentationContext;
00154     LST_HEAD *acceptedPresentationContext;
00155     unsigned short maximumOperationsInvoked;
00156     unsigned short maximumOperationsPerformed;
00157     char callingImplementationClassUID[DICOM_UI_LENGTH + 1];
00158     char callingImplementationVersionName[16 + 1];
00159     char calledImplementationClassUID[DICOM_UI_LENGTH + 1];
00160     char calledImplementationVersionName[16 + 1];
00161     unsigned long peerMaxPDU;
00162     SOPClassExtendedNegotiationSubItemList *requestedExtNegList;
00163     SOPClassExtendedNegotiationSubItemList *acceptedExtNegList;
00164     OFBool useSecureLayer;
00165 }   DUL_ASSOCIATESERVICEPARAMETERS;
00166 
00167 typedef enum {
00168     DUL_SC_ROLE_DEFAULT,
00169     DUL_SC_ROLE_SCU,
00170     DUL_SC_ROLE_SCP,
00171     DUL_SC_ROLE_SCUSCP
00172 }   DUL_SC_ROLE;
00173 
00174 #define DUL_PRESENTATION_ACCEPT         0
00175 #define DUL_PRESENTATION_REJECT_USER        1
00176 #define DUL_PRESENTATION_REJECT_NOREASON    2
00177 #define DUL_PRESENTATION_REJECT_ABSTRACT_SYNTAX 3
00178 #define DUL_PRESENTATION_REJECT_TRANSFER_SYNTAX 4
00179 
00180 typedef OFList<char *> DUL_TRANSFERSYNTAXLIST;
00181 
00182 typedef struct {
00183     void *reserved[2];
00184     DUL_PRESENTATIONCONTEXTID presentationContextID;
00185     char abstractSyntax[DUL_LEN_UID + 1];
00186     LST_HEAD *proposedTransferSyntax;
00187     char acceptedTransferSyntax[DUL_LEN_UID + 1];
00188     unsigned char result;
00189     DUL_SC_ROLE proposedSCRole;
00190     DUL_SC_ROLE acceptedSCRole;
00191 }   DUL_PRESENTATIONCONTEXT;
00192 
00193 typedef struct {
00194     void *reserved[2];
00195     char transferSyntax[DUL_LEN_UID + 1];
00196 }   DUL_TRANSFERSYNTAX;
00197 
00198 typedef struct dul_abortitems {
00199     unsigned char result;
00200     unsigned char source;
00201     unsigned char reason;
00202 }   DUL_ABORTITEMS;
00203 
00204 typedef enum {
00205     DUL_COMMANDPDV,     /* A command PDV inside a data PDU */
00206     DUL_DATASETPDV
00207 }               /* A data set PDV inside a data PDU */
00208     DUL_DATAPDV;
00209 
00210 typedef enum {
00211     DUL_BLOCK,          /* Block on an operation (read, request) */
00212     DUL_NOBLOCK
00213 }               /* Or return immediately if nothing avail */
00214     DUL_BLOCKOPTIONS;
00215 
00216 typedef struct {
00217     unsigned long fragmentLength;
00218     unsigned char presentationContextID;
00219     DUL_DATAPDV pdvType;
00220     OFBool lastPDV;
00221     void *data;
00222 }   DUL_PDV;
00223 
00224 typedef struct {
00225     unsigned long count;
00226     void *scratch;
00227     unsigned long scratchLength;
00228     DUL_ABORTITEMS abort;
00229     DUL_PDV *pdv;
00230 }   DUL_PDVLIST;
00231 
00232 /*  Define the bits that go in the options field for InitializeNetwork
00233 **
00234 **  The low two bits define the byte order of messages at the DICOM
00235 **  level.  This does not define the order of user data inside of a
00236 **  DICOM PDU.
00237 */
00238 
00239 #define DUL_ORDERMASK       0x03    /* The bottom two bits */
00240 #define DUL_ORDERLITTLEENDIAN   0x01
00241 #define DUL_ORDERBIGENDIAN  0x02
00242 
00243 #define DUL_DOMAINMASK      0x04
00244 #define DUL_FULLDOMAINNAME  0x04
00245 
00246 #define DUL_AEREQUESTOR     "AE REQUESTOR"
00247 #define DUL_AEACCEPTOR      "AE ACCEPTOR"
00248 #define DUL_AEBOTH      "AE BOTH"
00249 
00250 /*  These macros define results and reasons for rejecting an association
00251 **  request.  Result is permanent or transient.  There are a number of
00252 **  different reasons for rejecting requests that occur at different layers
00253  */
00254 #define DUL_REJ_RSLTPERMANENT       0x01
00255 #define DUL_REJ_RSLTTRANSIENT       0x02
00256 
00257 /*  These macros define parameters used to construct an ABORT PDU.
00258 **  These include the source of the abort (SCU or SCP) and the
00259 **  reason for the abort.
00260 */
00261 
00262 #define DUL_SCU_INITIATED_ABORT 0x00
00263 #define DUL_SCP_INITIATED_ABORT 0x02
00264 
00265 #define DUL_ABORTSERVICEUSER        0x00
00266 #define DUL_ABORTSERVICEPROVIDER    0x02
00267 
00268 
00269 #define DUL_ABORTNOREASON       0x00
00270 #define DUL_ABORTUNRECOGNIZEDPDU    0x01
00271 #define DUL_ABORTUNEXPECTEDPDU      0x02
00272 #define DUL_ABORTUNRECOGNIZEDPDUPARAM   0x04
00273 #define DUL_ABORTUNEXPECTEDPDUPARAM 0x05
00274 #define DUL_ABORTINVALIDPDUPARAM    0x06
00275 
00276 /*  These macros define parameters used to construct a REJECT PDU.
00277 **  These include the source of the reject (DICOM UL service-user,
00278 **  (DICOM UL service-provider) and the reason for the reject.
00279 */
00280 #define DUL_REJECT_PERMANENT        0x01
00281 #define DUL_REJECT_TRANSIENT        0x02
00282 
00283 #define DUL_ULSU_REJECT         0x01
00284 #define DUL_ULSP_ACSE_REJECT        0x02
00285 #define DUL_ULSP_PRESENTATION_REJECT    0x03
00286 
00287 #define DUL_ULSU_REJ_NOREASON       0x01
00288 #define DUL_ULSU_REJ_UNSUP_APP_CTX_NAME 0x02
00289 #define DUL_ULSU_REJ_UNREC_CALLING_TITLE 0x03
00290 #define DUL_ULSU_REJ_UNREC_CALLED_TITLE 0x07
00291 
00292 #define DUL_ULSP_ACSE_REJ_NOREASON  0x01
00293 #define DUL_ULSP_ACSE_UNSUP_PROTOCOL    0x02
00294 
00295 #define DUL_ULSP_PRES_REJ_TEMP_CONGEST  0x01
00296 #define DUL_ULSP_PRES_REJ_LIMIT     0x02
00297 
00298 #define DUL_ABORTNOREASON       0x00
00299 #define DUL_ABORTUNRECOGNIZEDPDU    0x01
00300 #define DUL_ABORTUNEXPECTEDPDU      0x02
00301 #define DUL_ABORTUNRECOGNIZEDPDUPARAM   0x04
00302 #define DUL_ABORTUNEXPECTEDPDUPARAM 0x05
00303 #define DUL_ABORTINVALIDPDUPARAM    0x06
00304 
00305 /* Define a set of constants and types that let the user get information
00306 ** about the Association
00307 */
00308 
00309 typedef enum {
00310     DUL_K_INTEGER,      /* An integer type */
00311     DUL_K_STRING        /* A string type */
00312 }   DUL_DATA_TYPE;
00313 typedef enum {
00314     DUL_K_MAX_PDV_XMIT
00315 }   DUL_ASSOCIATION_PARAMETER;
00316 
00317 #define DUL_TIMEOUT 180
00318 
00319 /* Operating mode flags as defined in the 1993 toolkit specification.
00320 ** Needed for backward compatibility with DCMTK releases prior to 3.0
00321 ** (and possibly older CTN releases).
00322 */
00323 
00324 #define DUL_DULCOMPAT          2768240730UL 
00325 #define DUL_DIMSECOMPAT        196608UL
00326 #define DUL_MAXPDUCOMPAT       4278190335UL
00327 
00328 /* Define the function prototypes for this facility.
00329 **
00330 ** First set of functions are for establishing the network and associations.
00331 */
00332 
00333 OFCondition
00334 DUL_AcknowledgeAssociationRQ(
00335   DUL_ASSOCIATIONKEY ** association,
00336   DUL_ASSOCIATESERVICEPARAMETERS * params, 
00337   int activatePDUStorage);
00338 
00339 OFCondition
00340 DUL_InitializeNetwork(
00341   const char *mode, 
00342   void *param,
00343   int timeout, 
00344   unsigned long 
00345   options, 
00346   DUL_NETWORKKEY ** network);
00347 
00348 OFCondition
00349 DUL_ReceiveAssociationRQ(
00350   DUL_NETWORKKEY ** net,
00351   DUL_BLOCKOPTIONS blk, 
00352   int timeout,
00353   DUL_ASSOCIATESERVICEPARAMETERS * parameters,
00354   DUL_ASSOCIATIONKEY ** association, 
00355   int activatePDUStorage);
00356 
00357 OFCondition
00358 DUL_RejectAssociationRQ(
00359   DUL_ASSOCIATIONKEY ** association,
00360   DUL_ABORTITEMS * params, 
00361   int activatePDUStorage);
00362   
00363 OFCondition
00364 DUL_RequestAssociation(
00365   DUL_NETWORKKEY ** network,
00366   DUL_ASSOCIATESERVICEPARAMETERS * params,
00367   DUL_ASSOCIATIONKEY ** association,
00368   int activatePDUStorage);
00369 
00370 /* Define functions for releasing/aborting Associations.
00371 */
00372 OFCondition DUL_AbortAssociation(DUL_ASSOCIATIONKEY ** association);
00373 OFCondition DUL_DropAssociation(DUL_ASSOCIATIONKEY ** association);
00374 OFCondition DUL_DropNetwork(DUL_NETWORKKEY ** network);
00375 OFCondition DUL_ReleaseAssociation(DUL_ASSOCIATIONKEY ** association);
00376 OFCondition DUL_AcknowledgeRelease(DUL_ASSOCIATIONKEY ** association);
00377 
00378 /* Functions for reading/write PDVs inside P DATA PDUs.
00379 */
00380 OFCondition
00381 DUL_ReadPDVs(DUL_ASSOCIATIONKEY ** association,
00382          DUL_PDVLIST * pdvList, DUL_BLOCKOPTIONS block, int timeout);
00383 OFCondition
00384 DUL_WritePDVs(DUL_ASSOCIATIONKEY ** association,
00385           DUL_PDVLIST * pdvList);
00386 OFCondition DUL_NextPDV(DUL_ASSOCIATIONKEY ** association, DUL_PDV * pdv);
00387 
00388 
00389 /* Miscellaneous functions.
00390 */
00391 const char *DUL_Message(OFCondition cond);
00392 void DUL_Debug(OFBool flag);
00393 OFCondition
00394 DUL_AssociationParameter(DUL_ASSOCIATIONKEY ** association,
00395              DUL_ASSOCIATION_PARAMETER param, DUL_DATA_TYPE type,
00396              void *address, size_t length);
00397 OFCondition
00398 DUL_MakePresentationCtx(DUL_PRESENTATIONCONTEXT ** ctx,
00399              DUL_SC_ROLE proposedSCRole, DUL_SC_ROLE acceptedSCRole,
00400 DUL_PRESENTATIONCONTEXTID ctxID, unsigned char reason, const char *abstractSyntax,
00401             const char *transferSyntax,...);
00402 void DUL_DumpParams(DUL_ASSOCIATESERVICEPARAMETERS * params);
00403 void DUL_DumpConnectionParameters(DUL_ASSOCIATIONKEY *association, ostream& outstream);
00404 
00405 OFCondition DUL_ClearServiceParameters(DUL_ASSOCIATESERVICEPARAMETERS * params);
00406 void DUL_DefaultServiceParameters(DUL_ASSOCIATESERVICEPARAMETERS * params);
00407 void dumpExtNegList(SOPClassExtendedNegotiationSubItemList& lst);
00408 
00409 /*
00410 ** Additional functions (from dulextra.cc) needed to support 
00411 ** selecting amongst several concurrent associations.
00412 ** Andrew Hewett, Institute OFFIS, Oldenburg, Germany.
00413 */
00414 
00415 OFBool 
00416 DUL_dataWaiting(DUL_ASSOCIATIONKEY * callerAssociation, int timeout);
00417 int 
00418 DUL_networkSocket(DUL_NETWORKKEY * callerNet);
00419 OFBool 
00420 DUL_associationWaiting(DUL_NETWORKKEY * callerNet, int timeout);
00421 
00422 /*
00423  * functions allowing to retrieve raw A-ASSOCIATE PDUs from the DUL layer
00424  */
00425 void DUL_activateAssociatePDUStorage(DUL_ASSOCIATIONKEY *dulassoc);
00426 void DUL_returnAssociatePDUStorage(DUL_ASSOCIATIONKEY *dulassoc, void *& pdu, unsigned long& pdusize);
00427 
00428 /* get pointer to transport connection from opaque association pointer */
00429 DcmTransportConnection *DUL_getTransportConnection(DUL_ASSOCIATIONKEY * callerAssociation);
00430 
00431 /* change transport layer */
00432 OFCondition DUL_setTransportLayer(DUL_NETWORKKEY *callerNetworkKey, DcmTransportLayer *newLayer, int takeoverOwnership);
00433 
00434 /* activate compatibility mode and callback */
00435 void DUL_activateCompatibilityMode(DUL_ASSOCIATIONKEY *dulassoc, unsigned long mode);
00436 void DUL_activateCallback(DUL_ASSOCIATIONKEY *dulassoc, DUL_ModeCallback *cb);
00437 
00438 /*
00439  * function allowing to retrieve the peer certificate from the DUL layer
00440  */
00441 unsigned long DUL_getPeerCertificateLength(DUL_ASSOCIATIONKEY *dulassoc);
00442 unsigned long DUL_getPeerCertificate(DUL_ASSOCIATIONKEY *dulassoc, void *buf, unsigned long bufLen);
00443 
00444 /*
00445 ** END extra functions
00446 */
00447 
00448 
00449 #endif
00450 
00451 /*
00452 ** CVS Log
00453 ** $Log: dul.h,v $
00454 ** Revision 1.19  2004/02/25 12:31:15  meichel
00455 ** Added global option flag for compatibility with very old DCMTK releases in the
00456 **   DICOM upper layer and ACSE code. Default is automatic handling, which should
00457 **   work in most cases.
00458 **
00459 ** Revision 1.18  2003/08/14 09:01:37  meichel
00460 ** Adapted type casts to new-style typecast operators defined in ofcast.h
00461 **
00462 ** Revision 1.17  2003/06/10 13:37:36  meichel
00463 ** Added support for TCP wrappers in DICOM network layer
00464 **
00465 ** Revision 1.16  2003/06/06 13:07:29  meichel
00466 ** Introduced global flag dcmExternalSocketHandle which allows
00467 **   to pass an already opened socket file descriptor to dcmnet.
00468 **
00469 ** Revision 1.15  2003/06/02 16:44:11  meichel
00470 ** Renamed local variables to avoid name clashes with STL
00471 **
00472 ** Revision 1.14  2002/11/28 16:57:36  meichel
00473 ** Added global flag dcmConnectionTimeout that defines a timeout for
00474 **   outgoing association requests in the DICOM upper layer.
00475 **
00476 ** Revision 1.13  2001/11/27 09:54:33  wilkens
00477 ** Updated storescp. 6 new options (--output-directory, --sort-conc-studies,
00478 ** --exec-on-reception, --exec-on-eostudy, --rename-on-eostudy, and
00479 ** --eostudy-timeout) implemented (requirements from GO-Kard).
00480 **
00481 ** Revision 1.12  2001/10/12 10:18:27  meichel
00482 ** Replaced the CONDITION types, constants and functions in the dcmnet module
00483 **   by an OFCondition based implementation which eliminates the global condition
00484 **   stack.  This is a major change, caveat emptor!
00485 **
00486 ** Revision 1.11  2001/09/26 12:28:59  meichel
00487 ** Implemented changes in dcmnet required by the adaptation of dcmdata
00488 **   to class OFCondition.  Removed some unused code.
00489 **
00490 ** Revision 1.10  2001/06/01 11:02:02  meichel
00491 ** Implemented global flag and command line option to disable reverse
00492 **   DNS hostname lookup using gethostbyaddr when accepting associations.
00493 **
00494 ** Revision 1.9  2000/10/10 12:06:54  meichel
00495 ** Updated transport layer error codes and routines for printing
00496 **   connection parameters.
00497 **
00498 ** Revision 1.8  2000/08/10 14:50:54  meichel
00499 ** Added initial OpenSSL support.
00500 **
00501 ** Revision 1.7  2000/06/07 08:57:22  meichel
00502 ** dcmnet ACSE routines now allow to retrieve a binary copy of the A-ASSOCIATE
00503 **   RQ/AC/RJ PDUs, e.g. for logging purposes.
00504 **
00505 ** Revision 1.6  1999/04/19 08:39:27  meichel
00506 ** Added experimental support for extended SOP class negotiation.
00507 **
00508 ** Revision 1.5  1999/03/29 11:19:59  meichel
00509 ** Cleaned up dcmnet code for char* to const char* assignments.
00510 **
00511 ** Revision 1.4  1998/06/29 12:14:27  meichel
00512 ** Removed some name clashes (e.g. local variable with same
00513 **   name as class member) to improve maintainability.
00514 **   Applied some code purifications proposed by the gcc 2.8.1 -Weffc++ option.
00515 **
00516 ** Revision 1.3  1997/07/21 08:40:11  andreas
00517 ** - Replace all boolean types (BOOLEAN, CTNBOOLEAN, DICOM_BOOL, BOOL)
00518 **   with one unique boolean type OFBool.
00519 **
00520 ** Revision 1.2  1997/01/13 15:53:02  hewett
00521 ** Added missing function prototypes (required for CodeWarrior 10).
00522 **
00523 ** Revision 1.1.1.1  1996/03/26 18:38:44  hewett
00524 ** Initial Release.
00525 **
00526 **
00527 */


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