DCMTK Version 3.7.0 OFFIS DICOM Toolkit

Classes | Macros | Enumerations | Functions | Variables
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 | T_ASC_ProtocolFamily { ASC_AF_Default , ASC_AF_INET , ASC_AF_INET6 , ASC_AF_UNSPEC }
| TCP/IP protocol family to be used for network connections. More...
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[], DUL_CREATEPROCESS_CALLBACK cb=NULL)
| 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...
DCMTK_DCMNET_EXPORT OFGlobal< T_ASC_ProtocolFamily > | dcmIncomingProtocolFamily
| TCP/IP protocol family to be supported for incoming network connections in association acceptors.

## 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.

## ◆ T_ASC_ProtocolFamily

enum T_ASC_ProtocolFamily

TCP/IP protocol family to be used for network connections.

Enumerator
ASC_AF_Default | default behaviour. Currently identical to ASC_AF_INET
ASC_AF_INET | only use IPv4
ASC_AF_INET6 | only use IPv6
ASC_AF_UNSPEC | dual-stack operation, automatically select IPv4 or IPv6

## 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[],
|  | DUL_CREATEPROCESS_CALLBACK | cb = `NULL`
| ) |  |

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.
  pointer | to a callback function that will be called on Windows when a child process has been created using CreateProcessA().

## ◆ 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.

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