dul.h File Reference

type definitions, constants, global variables and functions for the dcmnet/dul module More...

Classes
class	DUL_ModeCallback
struct	DUL_ASSOCIATESERVICEPARAMETERS
struct	DUL_PRESENTATIONCONTEXT
struct	DUL_TRANSFERSYNTAX
struct	dul_abortitems
struct	DUL_PDV
struct	DUL_PDVLIST

Macros
#define	DUL_LEN_TITLE   OFstatic_cast(size_t, 16) /* required by DICOM protocol */
	pure virtual base class for DUL mode callbacks

Enumerations
enum	DUL_SC_ROLE
	Enum describing the possible role settings for role negotiation sub items. More...

Functions
DCMTK_DCMNET_EXPORT OFBool	DUL_processIsForkedChild ()
	this function returns true if the current process was created by the DICOM network layer during receipt of a TCP transport connection, i.e. More...
DCMTK_DCMNET_EXPORT void	DUL_markProcessAsForkedChild ()
	this function marks the current process as a child created by the DICOM network layer during receipt of a TCP transport connection, i.e. More...
DCMTK_DCMNET_EXPORT OFCondition	DUL_readSocketHandleAsForkedChild ()
	this helper function calls DUL_markProcessAsForkedChild(), then reads the socket handle from the pipe opened by the parent process and stores it in the global variable dcmExternalSocketHandle. More...
DCMTK_DCMNET_EXPORT void	DUL_requestForkOnTransportConnectionReceipt (int argc, char *argv[])
	this function marks the current process as a multi-process server and enables the creation of child processes for each incoming TCP transport connection in receiveTransportConnectionTCP(). More...
DCMTK_DCMNET_EXPORT void	DUL_setParentProcessMode (DUL_ASSOCIATIONKEY *callerAssociation)
	this function sets a flag in the association that the current process is the parent process after a fork() operation and that the association will be handled by the child process. More...
OFdeprecated DCMTK_DCMNET_EXPORT void	DUL_DumpParams (DUL_ASSOCIATESERVICEPARAMETERS *params)
OFdeprecated DCMTK_DCMNET_EXPORT void	DUL_DumpConnectionParameters (DUL_ASSOCIATIONKEY *association, STD_NAMESPACE ostream &outstream)
OFdeprecated DCMTK_DCMNET_EXPORT void	dumpExtNegList (SOPClassExtendedNegotiationSubItemList &lst)

Variables
DCMTK_DCMNET_EXPORT OFGlobal< OFBool >	dcmDisableGethostbyaddr
	Global flag to enable/disable reverse DNS lookup when accepting associations. More...
DCMTK_DCMNET_EXPORT OFGlobal< Sint32 >	dcmConnectionTimeout
	Global timeout in seconds for connecting to remote hosts. More...
DCMTK_DCMNET_EXPORT OFGlobal< DcmNativeSocketType >	dcmExternalSocketHandle
	This global flag allows to set an already opened socket file descriptor which will be used by dcmnet the next time receiveTransportConnectionTCP() is called. More...
DCMTK_DCMNET_EXPORT OFGlobal< const char * >	dcmTCPWrapperDaemonName
	When compiled with WITH_TCPWRAPPER, DCMTK server processes may use the TCP wrapper library to enforce access control - see hosts_access(5). More...
DCMTK_DCMNET_EXPORT OFGlobal< size_t >	dcmAssociatePDUSizeLimit
	Maximum size (in bytes) of incoming A-ASSOCIATE-RQ or A-ASSOCIATE-AC PDUs that we are willing to accept. More...

Detailed Description

type definitions, constants, global variables and functions for the dcmnet/dul module

---

Class Documentation

DUL_ASSOCIATESERVICEPARAMETERS

struct DUL_ASSOCIATESERVICEPARAMETERS

DUL_PRESENTATIONCONTEXT

struct DUL_PRESENTATIONCONTEXT

DUL_TRANSFERSYNTAX

struct DUL_TRANSFERSYNTAX

dul_abortitems

struct dul_abortitems

DUL_PDV

struct DUL_PDV

DUL_PDVLIST

struct DUL_PDVLIST

Enumeration Type Documentation

DUL_SC_ROLE

enum DUL_SC_ROLE

Enum describing the possible role settings for role negotiation sub items.

DCMTK implements the following role negotiation behaviour for association acceptors:

*  +--------------------+------------------+---------+
*  | Requestor Proposal | Acceptor Setting | Result  |
*  +--------------------+------------------+---------+
*  | SCU                | SCP              | NONE    |
*  | SCU                | SCU              | SCU     |
*  | SCU                | SCU/SCP          | SCU     |
*  | SCU                | DEFAULT          | DEFAULT |
*  | SCP                | SCP              | SCP     |
*  | SCP                | SCU              | NONE    |
*  | SCP                | SCU/SCP          | SCP     |
*  | SCP                | DEFAULT          | DEFAULT |
*  | SCU/SCP            | SCP              | SCP     |
*  | SCU/SCP            | SCU              | SCU     |
*  | SCU/SCP            | SCU/SCP          | SCU/SCP |
*  | SCU/SCP            | DEFAULT          | DEFAULT |
*  | DEFAULT            | SCP              | Reject  |
*  | DEFAULT            | SCU              | DEFAULT |
*  | DEFAULT            | SCU/SCP          | DEFAULT |
*  | DEFAULT            | DEFAULT          | DEFAULT |
*  +--------------------+------------------+---------+
*  

NONE, SCU, SCP as well as SCU/SCP denote the related flags in the association role selection user items. The "Reject" case denotes that such a presentation context will be rejected by the association acceptor: If the requestor connects with default role but the acceptor explicitly requires the SCP role (only) then the presentation context will be rejected. All other cases do not lead to rejection but to actual "negotiation".

The Reject case can be avoided by setting a related option available in association acceptance code like ASC_acceptPresentationContext() or DcmSCP. to OFTrue (reading something like "alwaysAcceptDefaultRole" since when enabled, with the Reject being disabled all Default role proposals will be accepted). This can make sense for faulty Requestors, e.g. faulty Storage Commitment Servers connecting on a second connection for delivering an N-EVENT-REPORT, or broken Retrieve requestors proposing GET-based SOP Classes for retrieval using the Default role instead of the required SCP role.

Function Documentation

DUL_DumpConnectionParameters()

OFdeprecated DCMTK_DCMNET_EXPORT void DUL_DumpConnectionParameters	(	DUL_ASSOCIATIONKEY *	association,
		STD_NAMESPACE ostream &	outstream
	)

Deprecated:

Use OFString& DUL_DumpConnectionParameters(OFString&, DUL_ASSOCIATIONKEY*) instead.

DUL_DumpParams()

OFdeprecated DCMTK_DCMNET_EXPORT void DUL_DumpParams

(

DUL_ASSOCIATESERVICEPARAMETERS *

params

)

Deprecated:

Use OFString& DUL_DumpParams(OFString&, DUL_ASSOCIATESERVICEPARAMETERS) instead.

DUL_markProcessAsForkedChild()

DCMTK_DCMNET_EXPORT void DUL_markProcessAsForkedChild

(

)

this function marks the current process as a child created by the DICOM network layer during receipt of a TCP transport connection, i.e.

in receiveTransportConnectionTCP(). The call is not reversible - use with care.

DUL_processIsForkedChild()

DCMTK_DCMNET_EXPORT OFBool DUL_processIsForkedChild

(

)

this function returns true if the current process was created by the DICOM network layer during receipt of a TCP transport connection, i.e.

in receiveTransportConnectionTCP().

Returns

true if current process is a forked child of a multi-process server

DUL_readSocketHandleAsForkedChild()

DCMTK_DCMNET_EXPORT OFCondition DUL_readSocketHandleAsForkedChild

(

)

this helper function calls DUL_markProcessAsForkedChild(), then reads the socket handle from the pipe opened by the parent process and stores it in the global variable dcmExternalSocketHandle.

This is in most cases everything needed to prepare the network layer to act as a forked child on Win32. On other operating system, the function does nothing.

Returns

EC_Normal if successful, an error code otherwise.

DUL_requestForkOnTransportConnectionReceipt()

DCMTK_DCMNET_EXPORT void DUL_requestForkOnTransportConnectionReceipt	(	int	argc,
		char *	argv[]
	)

this function marks the current process as a multi-process server and enables the creation of child processes for each incoming TCP transport connection in receiveTransportConnectionTCP().

Parameters

argc	argc command line argument counter variable passed to main(). The content of this parameter is ignored on Posix platforms but required on Win32, where the child process is created with CreateProcess and the command line parameters have to be passed from parent to child.
argv	argv command line argument value array passed to main(). The content of this parameter is ignored on Posix platforms but required on Win32, where the child process is created with CreateProcess and the command line parameters have to be passed from parent to child.

DUL_setParentProcessMode()

DCMTK_DCMNET_EXPORT void DUL_setParentProcessMode

(

DUL_ASSOCIATIONKEY *

callerAssociation

)

this function sets a flag in the association that the current process is the parent process after a fork() operation and that the association will be handled by the child process.

In the case of TLS connections, this prevents the destructor from calling SSL_shutdown().

dumpExtNegList()

OFdeprecated DCMTK_DCMNET_EXPORT void dumpExtNegList

(

SOPClassExtendedNegotiationSubItemList &

lst

)

Deprecated:

Use OFString& dumpExtNegList(OFString&, SOPClassExtendedNegotiationSubItemList&) instead.

Variable Documentation

dcmAssociatePDUSizeLimit

DCMTK_DCMNET_EXPORT OFGlobal<size_t> dcmAssociatePDUSizeLimit

extern

Maximum size (in bytes) of incoming A-ASSOCIATE-RQ or A-ASSOCIATE-AC PDUs that we are willing to accept.

Under normal conditions, valid A-ASSOCIATE PDUs will never be larger than 64 kBytes, so the default of 1 MByte should be safe. We should limit the maximum accepted PDU size to avoid denial of service attacks through faulty PDUs that cause the network layer to allocate up to 4 GByte of memory for one PDU.

Note: This limit can be disabled by setting a value of zero, which causes the behaviour to revert to that of DCMTK releases up to 3.6.3.

dcmConnectionTimeout

DCMTK_DCMNET_EXPORT OFGlobal<Sint32> dcmConnectionTimeout

extern

Global timeout in seconds for connecting to remote hosts.

Default value is -1, which selects infinite timeout, i.e. blocking connect().

Deprecated:

The use of this global variable is deprecated. Please pass the TCP connection timeout to ASC_createAssociationParameters() as a parameter.

dcmDisableGethostbyaddr

DCMTK_DCMNET_EXPORT OFGlobal<OFBool> dcmDisableGethostbyaddr

extern

Global flag to enable/disable reverse DNS lookup when accepting associations.

If disabled, the numerical IP address instead of the symbolic hostname is stored in the callingPresentationAddress field of the association parameters structure. Most DICOM applications (except imagectn) don't need the symbolic hostname anyway, and the reverse DNS lookup can cause a long timeout.

dcmExternalSocketHandle

DCMTK_DCMNET_EXPORT OFGlobal<DcmNativeSocketType> dcmExternalSocketHandle

extern

This global flag allows to set an already opened socket file descriptor which will be used by dcmnet the next time receiveTransportConnectionTCP() is called.

Useful for use with proxy applications, but inherently thread unsafe!

dcmTCPWrapperDaemonName

DCMTK_DCMNET_EXPORT OFGlobal<const char *> dcmTCPWrapperDaemonName

extern

When compiled with WITH_TCPWRAPPER, DCMTK server processes may use the TCP wrapper library to enforce access control - see hosts_access(5).

If this global flag is non-NULL, the TCP wrapper is enabled and the string pointed to is used as the daemon name. If the flag is NULL, no access control is performed.