DCMTK: DcmTransportConnection Class Reference

DCMTK Version 3.7.0 OFFIS DICOM Toolkit

Loading...
Searching...
No Matches
Public Member Functions | Static Public Member Functions | Protected Member Functions | Private Member Functions | Static Private Member Functions | Private Attributes | List of all members
DcmTransportConnection Class Referenceabstract

this class represents a TCP/IP based transport connection which can be a transparent TCP/IP socket communication or a secure transport protocol such as TLS. More...

Inheritance diagram for DcmTransportConnection:

## Public Member Functions
| DcmTransportConnection (DcmNativeSocketType openSocket)
| constructor.
virtual | ~DcmTransportConnection ()
| destructor
virtual OFCondition | serverSideHandshake ()=0
| performs server side handshake on established socket.
virtual OFCondition | clientSideHandshake ()=0
| performs client side handshake on established socket.
virtual OFCondition | renegotiate (const char *newSuite)=0
| performs a re-negotiation of the connection with different connection parameters.
virtual ssize_t | read (void *buf, size_t nbyte)=0
| attempts to read nbyte bytes from the transport connection and writes them into the given buffer.
virtual ssize_t | write (void *buf, size_t nbyte)=0
| attempts to write nbyte bytes from the given buffer to the transport connection.
virtual void | close ()=0
| Closes the transport connection.
virtual void | closeTransportConnection ()=0
| Closes the transport connection directly.
virtual unsigned long | getPeerCertificateLength ()=0
| returns the size in bytes of the peer certificate of a secure connection.
virtual OFBool | networkDataAvailable (int timeout)=0
| checks if data is available to be read on the transport connection.
virtual OFBool | isTransparentConnection ()=0
| returns OFTrue if this connection is a transparent TCP connection, OFFalse if the connection is a secure connection.
virtual OFString & | dumpConnectionParameters (OFString &str)=0
| dump the characteristics of the current connection
virtual void | setParentProcessMode ()
| this method must be called by the parent process after a fork() if the TLS connection is handled by the child process.
virtual OFBool | isParentProcessMode () const
| check if the connection has been set to parent process mode by a prior call to setParentProcessMode().
OFdeprecated void | dumpConnectionParameters (STD_NAMESPACE ostream &out)
| prints the characteristics of the current connection on the given output stream.

## Static Public Member Functions
static OFBool | selectReadableAssociation (DcmTransportConnection *connections[], int connCount, int timeout)
| indicates which of the specified transport connections is ready for reading.

## Protected Member Functions
DcmNativeSocketType | getSocket ()
| returns the socket file descriptor managed by this object.
void | setSocket (DcmNativeSocketType socket)
| set the socket file descriptor managed by this object.

## Private Member Functions
| DcmTransportConnection (const DcmTransportConnection &)
| private undefined copy constructor
DcmTransportConnection & | operator= (const DcmTransportConnection &)
| private undefined assignment operator

## Static Private Member Functions
static OFBool | safeSelectReadableAssociation (DcmTransportConnection *connections[], int connCount, int timeout)
| indicates which of the specified transport connections is ready for reading.
static OFBool | fastSelectReadableAssociation (DcmTransportConnection *connections[], int connCount, int timeout)
| indicates which of the specified transport connections is ready for reading.

## Private Attributes
DcmNativeSocketType | theSocket
| the socket file descriptor/handle used by the transport connection.
OFBool | isForkedParent
| a flag that must be set in the parent process after a fork() if the TLS connection is handled by the child process.

## Detailed Description

this class represents a TCP/IP based transport connection which can be a transparent TCP/IP socket communication or a secure transport protocol such as TLS.

## Constructor & Destructor Documentation

## ◆ DcmTransportConnection()

DcmTransportConnection::DcmTransportConnection | ( | DcmNativeSocketType | openSocket | ) |

constructor.

Parameters

  openSocket | TCP/IP socket to be used for the transport connection. the connection must already be established on socket level. This object takes over control of the socket.

Referenced by DcmTransportConnection(), fastSelectReadableAssociation(), operator=(), safeSelectReadableAssociation(), and selectReadableAssociation().

## Member Function Documentation

## ◆ clientSideHandshake()

virtual OFCondition DcmTransportConnection::clientSideHandshake | ( |  | ) |
| pure virtual

performs client side handshake on established socket.

This function is used to establish a secure transport connection over the established TCP connection. Abstract method.

Returns
  EC_Normal if successful, an error code otherwise.

Implemented in DcmTCPConnection, and DcmTLSConnection.

## ◆ close()

virtual void DcmTransportConnection::close | ( |  | ) |
| pure virtual

Closes the transport connection.

If a secure connection is used, a closure alert is sent before the connection is closed. Abstract method.

Implemented in DcmTCPConnection, and DcmTLSConnection.

## ◆ closeTransportConnection()

virtual void DcmTransportConnection::closeTransportConnection | ( |  | ) |
| pure virtual

Closes the transport connection directly.

If a secure connection is used, a closure alert is NOT sent before the connection is closed. Abstract method.

Implemented in DcmTCPConnection, and DcmTLSConnection.

## ◆ dumpConnectionParameters() [1/2]

virtual OFString & DcmTransportConnection::dumpConnectionParameters | ( | OFString & | str | ) |
| pure virtual

dump the characteristics of the current connection

Parameters

  str | the string to dump into

Returns
  reference to string

Implemented in DcmTCPConnection, and DcmTLSConnection.

## ◆ dumpConnectionParameters() [2/2]

OFdeprecated void DcmTransportConnection::dumpConnectionParameters | ( | STD_NAMESPACE ostream & | out | ) |

prints the characteristics of the current connection on the given output stream.

Parameters

  out | output stream

Deprecated
  Please use the other dumpConnectionParameters() function instead!

References OFdeprecated.

## ◆ fastSelectReadableAssociation()

OFBool DcmTransportConnection::fastSelectReadableAssociation | ( | DcmTransportConnection * | connections[],
|  | int | connCount,
|  | int | timeout )
| staticprivate

indicates which of the specified transport connections is ready for reading.

If none of the specified transport connections is ready for reading, this method blocks up to the specified timeout interval or until one of the connections becomes readable, whatever occurs first. This method uses the poll() or select() system call. It may only be used with an array of transparent TCP transport connections. This precondition must be assured by the caller.

Parameters

  connections | list of transport connections. May contain NULL entries. Upon successful return of this method, all transport connections which are not ready for reading are set to NULL in this array.
  connCount | number of entries in connections array.
  timeout | number of seconds for timeout. If timeout is 0, this method does not block.

Returns
  OFTrue if one or more connections are readable upon return from this method, OFFalse if no connection is ready for reading.

References DcmTransportConnection().

## ◆ getPeerCertificateLength()

virtual unsigned long DcmTransportConnection::getPeerCertificateLength | ( |  | ) |
| pure virtual

returns the size in bytes of the peer certificate of a secure connection.

May return 0 if connection is transparent TCP/IP.

Returns
  peer certificate length in bytes

Implemented in DcmTCPConnection, and DcmTLSConnection.

## ◆ getSocket()

DcmNativeSocketType DcmTransportConnection::getSocket | ( |  | ) |
| inlineprotected

returns the socket file descriptor managed by this object.

Returns
  socket file descriptor

References theSocket.

## ◆ networkDataAvailable()

virtual OFBool DcmTransportConnection::networkDataAvailable | ( | int | timeout | ) |
| pure virtual

checks if data is available to be read on the transport connection.

Abstract method.

Parameters

  timeout | maximum number of seconds to wait if no data is available. If this parameter is 0, the function does not block.

Returns
  OFTrue if data is available, OFFalse otherwise.

Implemented in DcmTCPConnection, and DcmTLSConnection.

## ◆ read()

virtual ssize_t DcmTransportConnection::read | ( | void * | buf,
|  | size_t | nbyte )
| pure virtual

attempts to read nbyte bytes from the transport connection and writes them into the given buffer.

Abstract method.

Parameters

  buf | buffer
  nbyte | number of bytes to read

Returns
  number of bytes read, negative number if unsuccessful.

Implemented in DcmTCPConnection, and DcmTLSConnection.

## ◆ renegotiate()

virtual OFCondition DcmTransportConnection::renegotiate | ( | const char * | newSuite | ) |
| pure virtual

performs a re-negotiation of the connection with different connection parameters.

Used to change the parameters of the secure transport connection. Abstract method.

Parameters

  newSuite | string identifying the ciphersuite to be negotiated.

Returns
  EC_Normal if successful, an error code otherwise.

Implemented in DcmTCPConnection, and DcmTLSConnection.

## ◆ safeSelectReadableAssociation()

OFBool DcmTransportConnection::safeSelectReadableAssociation | ( | DcmTransportConnection * | connections[],
|  | int | connCount,
|  | int | timeout )
| staticprivate

indicates which of the specified transport connections is ready for reading.

If none of the specified transport connections is ready for reading, this method blocks up to the specified timeout interval or until one of the connections becomes readable, whatever occurs first. This method uses a safe approach that also works with secure transport connections, but which may be slower than a select() system call and consumes slightly more computation time.

Parameters

  connections | list of transport connections. May contain NULL entries. Upon successful return of this method, all transport connections which are not ready for reading are set to NULL in this array.
  connCount | number of entries in connections array.
  timeout | number of seconds for timeout. If timeout is 0, this method does not block.

Returns
  OFTrue if one or more connections are readable upon return from this method, OFFalse if no connection is ready for reading.

References DcmTransportConnection().

## ◆ selectReadableAssociation()

OFBool DcmTransportConnection::selectReadableAssociation | ( | DcmTransportConnection * | connections[],
|  | int | connCount,
|  | int | timeout )
| static

indicates which of the specified transport connections is ready for reading.

If none of the specified transport connections is ready for reading, this method blocks up to the specified timeout interval or until one of the connections becomes readable, whatever occurs first.

Parameters

  connections | list of transport connections. May contain NULL entries. Upon successful return of this method, all transport connections which are not ready for reading are set to NULL in this array.
  connCount | number of entries in connections array.
  timeout | number of seconds for timeout. If timeout is 0, this method does not block.

Returns
  OFTrue if one or more connections are readable upon return from this method, OFFalse if no connection is ready for reading.

References DcmTransportConnection().

## ◆ serverSideHandshake()

virtual OFCondition DcmTransportConnection::serverSideHandshake | ( |  | ) |
| pure virtual

performs server side handshake on established socket.

This function is used to establish a secure transport connection over the established TCP connection. Abstract method.

Returns
  EC_Normal if successful, an error code otherwise.

Implemented in DcmTCPConnection, and DcmTLSConnection.

## ◆ setParentProcessMode()

virtual void DcmTransportConnection::setParentProcessMode | ( |  | ) |
| virtual

this method must be called by the parent process after a fork() if the TLS connection is handled by the child process.

This will prevent the destructor in the parent process from calling SSL_shutdown().

## ◆ setSocket()

void DcmTransportConnection::setSocket | ( | DcmNativeSocketType | socket | ) |
| inlineprotected

set the socket file descriptor managed by this object.

Parameters

  socket | file descriptor

References theSocket.

## ◆ write()

virtual ssize_t DcmTransportConnection::write | ( | void * | buf,
|  | size_t | nbyte )
| pure virtual

attempts to write nbyte bytes from the given buffer to the transport connection.

Abstract method.

Parameters

  buf | buffer
  nbyte | number of bytes to write

Returns
  number of bytes written, negative number if unsuccessful.

Implemented in DcmTCPConnection, and DcmTLSConnection.

## Member Data Documentation

## ◆ isForkedParent

OFBool DcmTransportConnection::isForkedParent
| private

a flag that must be set in the parent process after a fork() if the TLS connection is handled by the child process.

This will prevent the destructor in the parent process from calling SSL_shutdown().

The documentation for this class was generated from the following file:

- dcmnet/include/dcmtk/dcmnet/dcmtrans.h

Generated on for DCMTK Version 3.7.0 by Doxygen 1.16.1