OFFIS DCMTK: dcmnet/include/assoc.h Source File

00001 /* 00002 ** Copyright (C) 1993/1994, OFFIS, Oldenburg University and CERIUM 00003 ** 00004 ** This software and supporting documentation were 00005 ** developed by 00006 ** 00007 ** Institut OFFIS 00008 ** Bereich Kommunikationssysteme 00009 ** Westerstr. 10-12 00010 ** 26121 Oldenburg, Germany 00011 ** 00012 ** Fachbereich Informatik 00013 ** Abteilung Prozessinformatik 00014 ** Carl von Ossietzky Universitaet Oldenburg 00015 ** Ammerlaender Heerstr. 114-118 00016 ** 26111 Oldenburg, Germany 00017 ** 00018 ** CERIUM 00019 ** Laboratoire SIM 00020 ** Faculte de Medecine 00021 ** 2 Avenue du Pr. Leon Bernard 00022 ** 35043 Rennes Cedex, France 00023 ** 00024 ** for CEN/TC251/WG4 as a contribution to the Radiological 00025 ** Society of North America (RSNA) 1993 Digital Imaging and 00026 ** Communications in Medicine (DICOM) Demonstration. 00027 ** 00028 ** THIS SOFTWARE IS MADE AVAILABLE, AS IS, AND NEITHER OFFIS, 00029 ** OLDENBURG UNIVERSITY NOR CERIUM MAKE ANY WARRANTY REGARDING 00030 ** THE SOFTWARE, ITS PERFORMANCE, ITS MERCHANTABILITY OR 00031 ** FITNESS FOR ANY PARTICULAR USE, FREEDOM FROM ANY COMPUTER 00032 ** DISEASES OR ITS CONFORMITY TO ANY SPECIFICATION. THE 00033 ** ENTIRE RISK AS TO QUALITY AND PERFORMANCE OF THE SOFTWARE 00034 ** IS WITH THE USER. 00035 ** 00036 ** Copyright of the software and supporting documentation 00037 ** is, unless otherwise stated, jointly owned by OFFIS, 00038 ** Oldenburg University and CERIUM and free access is hereby 00039 ** granted as a license to use this software, copy this 00040 ** software and prepare derivative works based upon this 00041 ** software. However, any distribution of this software 00042 ** source code or supporting documentation or derivative 00043 ** works (source code and supporting documentation) must 00044 ** include the three paragraphs of this copyright notice. 00045 ** 00046 */ 00047 /* 00048 ** 00049 ** Author: Andrew Hewett Created: 03-06-93 00050 ** 00051 ** Module: association 00052 ** 00053 ** Purpose: 00054 ** This file contains the routines which provide association management 00055 ** for DICOM applications. It maintains structures which describe 00056 ** active associations and provides access to association specific 00057 ** informtion. Also provided are routines for aiding association 00058 ** negotiation (presentation contexts, abstract syntaxes, transfer 00059 ** syntaxes, maximum PDU length, and other extended negotiation). 00060 ** 00061 ** This package uses the facilities of the DICOM Upper Layer for 00062 ** receiving/sending association requests/responses. 00063 ** 00064 ** Each active association is represented by an T_ASC_Association 00065 ** structure which contains all relevant information. 00066 ** 00067 ** Module Prefix: ASC_ 00068 ** 00069 ** 00070 ** Last Update: $Author: meichel $ 00071 ** Update Date: $Date: 2004/04/07 10:22:09 $ 00072 ** Source File: $Source: /share/dicom/cvs-depot/dcmtk/dcmnet/include/assoc.h,v $ 00073 ** CVS/RCS Revision: $Revision: 1.22 $ 00074 ** Status: $State: Exp $ 00075 ** 00076 ** CVS/RCS Log at end of file 00077 */ 00078 00079 00080 #ifndef ASSOCIATION_H 00081 #define ASSOCIATION_H 00082 00083 #include "osconfig.h" /* make sure OS specific configuration is included first */ 00084 00085 /* 00086 ** Required Include Files 00087 */ 00088 #include "dicom.h" 00089 #include "lst.h" 00090 #include "dul.h" 00091 00092 /* 00093 ** Constant Definitions 00094 */ 00095 00096 /* 00097 * There have been reports that smaller PDUs work better in some environments. 00098 * Allow a 4K minimum and a 128K maximum. Any further extension requires 00099 * modifications in the DUL code. 00100 */ 00101 #define ASC_DEFAULTMAXPDU 16384 /* 16K is default if nothing else specified */ 00102 #define ASC_MINIMUMPDUSIZE 4096 00103 #define ASC_MAXIMUMPDUSIZE 131072 /* 128K - we only handle this big */ 00104 00105 /* 00106 ** Type Definitions 00107 */ 00108 00109 /* 00110 ** Network initialization structure. 00111 ** Is a wrapper for DUL functionality. 00112 */ 00113 00114 enum T_ASC_NetworkRole 00115 { 00116 NET_ACCEPTOR, /* Provider Only */ 00117 NET_REQUESTOR, /* User Only */ 00118 NET_ACCEPTORREQUESTOR /* User and Provider */ 00119 }; 00120 00121 struct T_ASC_Network 00122 { 00123 T_ASC_NetworkRole role; 00124 int acceptorPort; 00125 DUL_NETWORKKEY *network; 00126 }; 00127 00128 00129 /* 00130 ** Association negotiation parameters. 00131 ** 00132 */ 00133 00134 00135 /* not defined anywhere (I think) but a hard limitation for now. 00136 * DICOM (1998) defines 22 transfer syntaxes, this upper limit 00137 * should allow for sufficiently many private transfer syntaxes. 00138 */ 00139 #define DICOM_MAXTRANSFERSYNTAXES 50 00140 00141 00142 typedef DUL_PRESENTATIONCONTEXTID T_ASC_PresentationContextID; 00143 00144 enum T_ASC_P_ResultReason 00145 { /* Part 8, pp 45. */ 00146 ASC_P_ACCEPTANCE = 0, 00147 ASC_P_USERREJECTION = 1, 00148 ASC_P_NOREASON = 2, 00149 ASC_P_ABSTRACTSYNTAXNOTSUPPORTED = 3, 00150 ASC_P_TRANSFERSYNTAXESNOTSUPPORTED = 4, 00151 ASC_P_NOTYETNEGOTIATED = 255 00152 }; 00153 00154 enum T_ASC_SC_ROLE 00155 { 00156 ASC_SC_ROLE_DEFAULT, 00157 ASC_SC_ROLE_SCU, 00158 ASC_SC_ROLE_SCP, 00159 ASC_SC_ROLE_SCUSCP 00160 }; 00161 00162 struct T_ASC_PresentationContext 00163 { 00164 T_ASC_PresentationContextID presentationContextID; 00165 DIC_UI abstractSyntax; 00166 unsigned char transferSyntaxCount; 00167 DIC_UI proposedTransferSyntaxes[DICOM_MAXTRANSFERSYNTAXES]; 00168 DIC_UI acceptedTransferSyntax; 00169 T_ASC_P_ResultReason resultReason; 00170 T_ASC_SC_ROLE proposedRole; 00171 T_ASC_SC_ROLE acceptedRole; 00172 }; 00173 00174 enum T_ASC_RejectParametersResult 00175 { 00176 ASC_RESULT_REJECTEDPERMANENT = 1, 00177 ASC_RESULT_REJECTEDTRANSIENT = 2 00178 }; 00179 00180 enum T_ASC_RejectParametersSource 00181 { 00182 ASC_SOURCE_SERVICEUSER = 1, 00183 ASC_SOURCE_SERVICEPROVIDER_ACSE_RELATED = 2, 00184 ASC_SOURCE_SERVICEPROVIDER_PRESENTATION_RELATED = 3 00185 }; 00186 00187 enum T_ASC_RejectParametersReason 00188 { /* the following values are coded by DUL */ 00189 /* Service User reasons */ 00190 ASC_REASON_SU_NOREASON = 0x0101, 00191 ASC_REASON_SU_APPCONTEXTNAMENOTSUPPORTED = 0x0102, 00192 ASC_REASON_SU_CALLINGAETITLENOTRECOGNIZED = 0x0103, 00193 ASC_REASON_SU_CALLEDAETITLENOTRECOGNIZED = 0x0107, 00194 /* Service Provider ACSE Related reasons */ 00195 ASC_REASON_SP_ACSE_NOREASON = 0x0201, 00196 ASC_REASON_SP_ACSE_PROTOCOLVERSIONNOTSUPPORTED = 0x0202, 00197 /* Service Provider Presentation Related reasons */ 00198 ASC_REASON_SP_PRES_TEMPORARYCONGESTION = 0x0301, 00199 ASC_REASON_SP_PRES_LOCALLIMITEXCEEDED = 0x0302 00200 }; 00201 00202 struct T_ASC_RejectParameters 00203 { 00204 T_ASC_RejectParametersResult result; 00205 T_ASC_RejectParametersSource source; 00206 T_ASC_RejectParametersReason reason; 00207 }; 00208 00209 00210 struct T_ASC_Parameters 00211 { 00212 DIC_UI ourImplementationClassUID; 00213 DIC_SH ourImplementationVersionName; 00214 DIC_UI theirImplementationClassUID; 00215 DIC_SH theirImplementationVersionName; 00216 DUL_ModeCallback *modeCallback; 00217 00218 DUL_ASSOCIATESERVICEPARAMETERS DULparams; 00219 /* 00220 * DICOM Upper Layer service parameters. They should only be 00221 * accessed via functions defined below. 00222 */ 00223 00224 long ourMaxPDUReceiveSize; /* we say what we can receive */ 00225 long theirMaxPDUReceiveSize; /* they say what we can send */ 00226 00227 }; 00228 00229 /* 00230 ** Association structure containing all association specific 00231 ** information. 00232 */ 00233 struct T_ASC_Association 00234 { 00235 DUL_ASSOCIATIONKEY *DULassociation; 00236 T_ASC_Parameters *params; 00237 00238 unsigned short nextMsgID; /* should be incremented by user */ 00239 unsigned long sendPDVLength; /* max length of PDV to send out */ 00240 unsigned char *sendPDVBuffer; /* buffer of size sendPDVLength */ 00241 }; 00242 00243 /* 00244 ** Public Function Prototypes 00245 */ 00246 00257 OFCondition ASC_initializeNetwork( 00258 T_ASC_NetworkRole role, 00259 int acceptorPort, 00260 int timeout, 00261 T_ASC_Network ** network, 00262 unsigned long options = 0); 00263 00268 OFCondition ASC_dropNetwork(T_ASC_Network ** network); 00269 00270 /* 00271 * Building Association parameters 00272 */ 00273 00274 OFCondition 00275 ASC_createAssociationParameters( 00276 T_ASC_Parameters ** params, 00277 long maxReceivePDUSize); 00278 00279 OFCondition 00280 ASC_destroyAssociationParameters( 00281 T_ASC_Parameters ** params); 00282 00283 /* set transport layer type in association parameters */ 00284 OFCondition 00285 ASC_setTransportLayerType( 00286 T_ASC_Parameters * params, 00287 OFBool useSecureLayer); 00288 00289 OFCondition 00290 ASC_setAPTitles( 00291 T_ASC_Parameters * params, 00292 const char* callingAPTitle, 00293 const char* calledAPTitle, 00294 const char* respondingAPTitle); 00295 00296 OFCondition 00297 ASC_getAPTitles( 00298 T_ASC_Parameters * params, 00299 char* callingAPTitle, 00300 char* calledAPTitle, 00301 char* respondingAPTitle); 00302 00303 OFCondition 00304 ASC_getApplicationContextName( 00305 T_ASC_Parameters * params, 00306 char* applicationContextName); 00307 00308 OFCondition 00309 ASC_setPresentationAddresses( 00310 T_ASC_Parameters * params, 00311 const char* callingPresentationAddress, 00312 const char* calledPresentationAddress); 00313 00314 OFCondition 00315 ASC_getPresentationAddresses( 00316 T_ASC_Parameters * params, 00317 char* callingPresentationAddress, 00318 char* calledPresentationAddress); 00319 00320 OFCondition 00321 ASC_getRejectParameters( 00322 T_ASC_Parameters * params, 00323 T_ASC_RejectParameters * rejectParameters); 00324 00325 void 00326 ASC_printRejectParameters( 00327 FILE *f, 00328 T_ASC_RejectParameters *rej); 00329 00330 void 00331 ASC_printRejectParameters( 00332 ostream &out, 00333 T_ASC_RejectParameters *rej); 00334 00335 OFCondition 00336 ASC_addPresentationContext( 00337 T_ASC_Parameters * params, 00338 T_ASC_PresentationContextID presentationContextID, 00339 const char* abstractSyntax, 00340 const char* transferSyntaxList[], 00341 int transferSyntaxListCount, 00342 T_ASC_SC_ROLE proposedRole = ASC_SC_ROLE_DEFAULT); 00343 00344 int 00345 ASC_countPresentationContexts( 00346 T_ASC_Parameters * params); 00347 00348 int 00349 ASC_countAcceptedPresentationContexts( 00350 T_ASC_Parameters * params); 00351 00352 OFCondition 00353 ASC_getPresentationContext( 00354 T_ASC_Parameters * params, 00355 int listPosition, 00356 T_ASC_PresentationContext * presentationContext); 00357 00358 OFCondition 00359 ASC_acceptPresentationContext( 00360 T_ASC_Parameters * params, 00361 T_ASC_PresentationContextID presentationContextID, 00362 const char* transferSyntax, 00363 T_ASC_SC_ROLE acceptedRole = ASC_SC_ROLE_DEFAULT); 00364 00365 OFCondition 00366 ASC_acceptContextsWithPreferredTransferSyntaxes( 00367 T_ASC_Parameters * params, 00368 const char* abstractSyntaxes[], int abstractSyntaxCount, 00369 const char* transferSyntaxes[], int transferSyntaxCount, 00370 T_ASC_SC_ROLE acceptedRole = ASC_SC_ROLE_DEFAULT); 00371 00372 OFCondition 00373 ASC_acceptContextsWithTransferSyntax( 00374 T_ASC_Parameters * params, 00375 const char* transferSyntax, int abstractSyntaxCount, 00376 const char* abstractSyntaxes[], 00377 T_ASC_SC_ROLE acceptedRole = ASC_SC_ROLE_DEFAULT); 00378 00379 OFCondition 00380 ASC_refusePresentationContext( 00381 T_ASC_Parameters * params, 00382 T_ASC_PresentationContextID presentationContextID, 00383 T_ASC_P_ResultReason resultReason); 00384 00385 OFCondition 00386 ASC_findAcceptedPresentationContext( 00387 T_ASC_Parameters * params, 00388 T_ASC_PresentationContextID presentationContextID, 00389 T_ASC_PresentationContext * presentationContext); 00390 00391 T_ASC_PresentationContextID 00392 ASC_findAcceptedPresentationContextID( 00393 T_ASC_Association *assoc, 00394 const char* abstractSyntax); 00395 00396 T_ASC_PresentationContextID 00397 ASC_findAcceptedPresentationContextID( 00398 T_ASC_Association *assoc, 00399 const char* abstractSyntax, 00400 const char * transferSyntax); 00401 00402 /* extended negotiation */ 00403 void ASC_getRequestedExtNegList(T_ASC_Parameters* params, SOPClassExtendedNegotiationSubItemList** extNegList); 00404 void ASC_getAcceptedExtNegList(T_ASC_Parameters* params, SOPClassExtendedNegotiationSubItemList** extNegList); 00405 void ASC_setRequestedExtNegList(T_ASC_Parameters* params, SOPClassExtendedNegotiationSubItemList* extNegList); 00406 void ASC_setAcceptedExtNegList(T_ASC_Parameters* params, SOPClassExtendedNegotiationSubItemList* extNegList); 00407 00408 /* get peer certificate from open association */ 00409 unsigned long ASC_getPeerCertificateLength(T_ASC_Association *assoc); 00410 unsigned long ASC_getPeerCertificate(T_ASC_Association *assoc, void *buf, unsigned long bufLen); 00411 00412 /* set new transport layer object */ 00413 OFCondition 00414 ASC_setTransportLayer(T_ASC_Network *network, DcmTransportLayer *newLayer, int takeoverOwnership); 00415 00416 void 00417 ASC_dumpParameters(T_ASC_Parameters * params, ostream& outstream); 00418 00419 void 00420 ASC_dumpPresentationContext(T_ASC_PresentationContext * presentationContext, ostream& outstream); 00421 00422 void 00423 ASC_dumpConnectionParameters(T_ASC_Association *association, ostream& outstream); 00424 00425 void ASC_activateCallback(T_ASC_Parameters *params, DUL_ModeCallback *cb); 00426 00427 /* 00428 * Association Inquiries 00429 */ 00430 00431 OFBool 00432 ASC_associationWaiting(T_ASC_Network * network, int timeout); 00433 00434 OFBool 00435 ASC_dataWaiting(T_ASC_Association * association, int timeout); 00436 00437 OFBool 00438 ASC_selectReadableAssociation( 00439 T_ASC_Association* assocs[], 00440 int assocCount, int timeout); 00441 00442 /* 00443 * Association Messages 00444 */ 00445 00446 OFCondition 00447 ASC_requestAssociation( 00448 T_ASC_Network * network, 00449 T_ASC_Parameters * params, /* params will be saved 00450 * in the association 00451 * structure */ 00452 T_ASC_Association ** association, 00453 void **associatePDU=NULL, 00454 unsigned long *associatePDUlength=NULL); 00455 00456 OFCondition 00457 ASC_receiveAssociation( 00458 T_ASC_Network * network, 00459 T_ASC_Association ** association, 00460 long maxReceivePDUSize, 00461 void **associatePDU=NULL, 00462 unsigned long *associatePDUlength=NULL, 00463 OFBool useSecureLayer=OFFalse, 00464 DUL_BLOCKOPTIONS block=DUL_BLOCK, 00465 int timeout=0); 00466 00467 OFCondition 00468 ASC_acknowledgeAssociation( 00469 T_ASC_Association * assoc, 00470 void **associatePDU=NULL, 00471 unsigned long *associatePDUlength=NULL); 00472 00473 OFCondition 00474 ASC_rejectAssociation( 00475 T_ASC_Association * association, 00476 T_ASC_RejectParameters * rejectParameters, 00477 void **associatePDU=NULL, 00478 unsigned long *associatePDUlength=NULL); 00479 00480 OFCondition 00481 ASC_releaseAssociation(T_ASC_Association * association); 00482 00483 OFCondition 00484 ASC_acknowledgeRelease(T_ASC_Association * association); 00485 00486 OFCondition 00487 ASC_abortAssociation(T_ASC_Association * association); 00488 00489 OFCondition 00490 ASC_dropSCPAssociation(T_ASC_Association * association); 00491 00492 OFCondition 00493 ASC_dropAssociation(T_ASC_Association * association); 00494 00495 OFCondition 00496 ASC_destroyAssociation(T_ASC_Association ** association); 00497 00498 00499 #endif 00500 00501 /* 00502 ** CVS Log 00503 ** $Log: assoc.h,v $ 00504 ** Revision 1.22 2004/04/07 10:22:09 meichel 00505 ** Added optional parameter to ASC_initializeNetwork that allows to pass 00506 ** the DUL_FULLDOMAINNAME option to the DUL layer 00507 ** 00508 ** Revision 1.21 2004/02/25 12:31:15 meichel 00509 ** Added global option flag for compatibility with very old DCMTK releases in the 00510 ** DICOM upper layer and ACSE code. Default is automatic handling, which should 00511 ** work in most cases. 00512 ** 00513 ** Revision 1.20 2003/06/10 13:42:07 meichel 00514 ** Replaced unnamed C style structs by C++ declarations 00515 ** 00516 ** Revision 1.19 2002/07/10 11:43:55 meichel 00517 ** Replaced dcmnet specific definitions for implementation class UID and 00518 ** version name by the constants defined in dcmdata. 00519 ** 00520 ** Revision 1.18 2001/11/27 09:54:33 wilkens 00521 ** Updated storescp. 6 new options (--output-directory, --sort-conc-studies, 00522 ** --exec-on-reception, --exec-on-eostudy, --rename-on-eostudy, and 00523 ** --eostudy-timeout) implemented (requirements from GO-Kard). 00524 ** 00525 ** Revision 1.17 2001/10/12 10:18:25 meichel 00526 ** Replaced the CONDITION types, constants and functions in the dcmnet module 00527 ** by an OFCondition based implementation which eliminates the global condition 00528 ** stack. This is a major change, caveat emptor! 00529 ** 00530 ** Revision 1.16 2001/09/28 13:23:46 joergr 00531 ** Added forward declaration of "ostream" to keep gcc 3.0 quiet. 00532 ** 00533 ** Revision 1.15 2000/10/10 12:06:05 meichel 00534 ** Added version of function ASC_printRejectParameters that takes 00535 ** an ostream& instead of a FILE* 00536 ** 00537 ** Revision 1.14 2000/08/10 14:50:52 meichel 00538 ** Added initial OpenSSL support. 00539 ** 00540 ** Revision 1.13 2000/06/07 13:56:20 meichel 00541 ** Output stream now passed as mandatory parameter to ASC_dumpParameters. 00542 ** 00543 ** Revision 1.12 2000/06/07 08:57:21 meichel 00544 ** dcmnet ACSE routines now allow to retrieve a binary copy of the A-ASSOCIATE 00545 ** RQ/AC/RJ PDUs, e.g. for logging purposes. 00546 ** 00547 ** Revision 1.11 2000/05/30 13:07:41 joergr 00548 ** Added a condition value to report the external request for a shutdown of 00549 ** the application (used for imagectn). 00550 ** 00551 ** Revision 1.10 1999/09/06 13:28:31 meichel 00552 ** Enhanced max receive PDU range to 4-128K. 00553 ** 00554 ** Revision 1.9 1999/04/26 17:20:55 meichel 00555 ** Added new "transfer syntax aware" variant of the dcmnet function 00556 ** ASC_findAcceptedPresentationContextID. This variant tries to find an 00557 ** accepted presentation context that matches both abstract and transfer syntax. 00558 ** 00559 ** Revision 1.8 1999/04/21 13:01:23 meichel 00560 ** Increased max. number of transfer syntaxes that 00561 ** can be managed in an A-ASSOCIATE packet from 25 to 50. 00562 ** 00563 ** Revision 1.7 1999/04/19 08:39:27 meichel 00564 ** Added experimental support for extended SOP class negotiation. 00565 ** 00566 ** Revision 1.6 1997/08/05 07:38:08 andreas 00567 ** Corrected error in DUL finite state machine 00568 ** SCPs shall close sockets after the SCU have closed the socket in 00569 ** a normal association release. Therfore, an ARTIM timer is described 00570 ** in DICOM part 8 that is not implemented correctly in the 00571 ** DUL. Since the whole DUL finite state machine is affected, we 00572 ** decided to solve the proble outside the fsm. Now it is necessary to call the 00573 ** ASC_DropSCPAssociation() after the calling ASC_acknowledgeRelease(). 00574 ** 00575 ** Revision 1.5 1997/07/21 08:40:08 andreas 00576 ** - Replace all boolean types (BOOLEAN, CTNBOOLEAN, DICOM_BOOL, BOOL) 00577 ** with one unique boolean type OFBool. 00578 ** 00579 ** Revision 1.4 1997/05/05 13:05:53 meichel 00580 ** Removed unused constant DICOM_MAXPRESENTATIONCONTEXTS. 00581 ** 00582 ** Revision 1.3 1997/05/05 10:30:08 meichel 00583 ** Fixed bugs related to association negotiation in the DICOM upper layer module. 00584 ** Added application tests/assctest.cc to examine handling of large A-ASSOCIATE 00585 ** PDUs. See CHANGES file for details. 00586 ** 00587 ** Revision 1.2 1996/04/25 16:06:27 hewett 00588 ** Replaced declarations of DIC_UL with unsigned long. 00589 ** 00590 ** Revision 1.1.1.1 1996/03/26 18:38:44 hewett 00591 ** Initial Release. 00592 ** 00593 ** 00594 */