DCMTK: OFIPCMessageQueueServer Class Reference

DCMTK Version 3.6.9 OFFIS DICOM Toolkit

Loading...
Searching...
No Matches
Public Member Functions | Static Public Member Functions | Private Member Functions | Friends | List of all members
OFIPCMessageQueueServer Class Reference

a server class for one-directional IPC messaging. More...

## Public Member Functions
| OFIPCMessageQueueServer ()
| default constructor
virtual | ~OFIPCMessageQueueServer ()
| destructor, will implicitly call deleteQueue() if not already called by the user.
OFCondition | createQueue (const char *name, Uint32 port)
| create a new message queue
OFBool | hasQueue () const
| check if this object manages an open message queue
OFCondition | deleteQueue ()
| delete the message queue
void | detachQueue ()
| resets this object to default constructed state without closing the message queue.
OFBool | messageWaiting ()
| check if an incoming message is waiting in the queue.
size_t | numMessagesWaiting ()
| return the number of incoming messages waiting in the queue
OFCondition | receiveMessage (OFString &msg)
| receive a message from the message queue and remove it from the queue.

## Static Public Member Functions
static void | registerSignalHandler ()
| register signal handlers for SIGINT and SIGTERM that call closeAllMessageQueues() upon receiving the signal, thus globally closing all message queues created by the process, if these message queues would persist after the end of the process otherwise.

## Private Member Functions
OFCondition | deleteQueueInternal ()
| delete the message queue without touching the internally managed global list of message queues.

## Friends
void | closeAllMessageQueues ()
| friend function that will call deleteQueueInternal().

## Detailed Description

a server class for one-directional IPC messaging.

It enables the user to create an IPC message queue and to receive incoming messages. Depending on the platform, the implementation is based on Windows mailslots, Posix message queues, System V message queues or, on Android, on Unix domain sockets and a separate handler thread that handles incoming connections. The latter implementation is preferred over the alternatives if the macro DCMTK_USE_UNIX_SOCKET_QUEUE is defined.

Note
  Note that there are platform specific limits to the message queue implementation depending on the underlying operating system API used. For example, Posix message queues on Linux only permit a maximum of 10 messages in the queue, and a maximum of 255 open queues system-wide. System V message queues on Linux only permit a maximum of 8 kBytes of data in a message queue. Furthermore, there are also limits on the maximum message size. For portable usage, messages should be text-based and short (e.g. a DICOM UID), and message queues should be kept short.

## Member Function Documentation

## ◆ createQueue()

OFCondition OFIPCMessageQueueServer::createQueue | ( | const char * | name,
|  | Uint32 | port )

create a new message queue

Parameters

  a | name for the queue that is known both to the client and the server. Typically the name of the tool using the queue. Must not contain characters that are not permitted in a filename. Should not be longer than 128 bytes.
  a | number that is known both to the client and the server. Usually this will be the port number under which the server process accepts incoming TCP/IP network connection. When used in other contexts, a number larger than 65535 should be used.

Returns
  EC_Normal if successful, an error code otherwise

## ◆ deleteQueue()

OFCondition OFIPCMessageQueueServer::deleteQueue | ( |  | ) |

delete the message queue

Returns
  EC_Normal if successful, an error code otherwise

## ◆ deleteQueueInternal()

OFCondition OFIPCMessageQueueServer::deleteQueueInternal | ( |  | ) |
| private

delete the message queue without touching the internally managed global list of message queues.

Returns
  EC_Normal if successful, an error code otherwise

## ◆ detachQueue()

void OFIPCMessageQueueServer::detachQueue | ( |  | ) |

resets this object to default constructed state without closing the message queue.

This method may be called by forked child processes to make sure that the destructor executed in the child process will not close the message queue for the parent process as well.

## ◆ hasQueue()

OFBool OFIPCMessageQueueServer::hasQueue | ( |  | ) | const

check if this object manages an open message queue

Returns
  true if message queue is open, false otherwise

## ◆ messageWaiting()

OFBool OFIPCMessageQueueServer::messageWaiting | ( |  | ) |

check if an incoming message is waiting in the queue.

Returns
  true if a message is waiting, false otherwise

## ◆ numMessagesWaiting()

size_t OFIPCMessageQueueServer::numMessagesWaiting | ( |  | ) |

return the number of incoming messages waiting in the queue

Returns
  number of incoming messages waiting in the queue

## ◆ receiveMessage()

OFCondition OFIPCMessageQueueServer::receiveMessage | ( | OFString & | msg | ) |

receive a message from the message queue and remove it from the queue.

If no message is available, the method will immediately return EC_IPCMessageQueueEmpty (no blocking).

Parameters

  msg | message received into this parameter if successful

Returns
  EC_Normal if successful, an error code otherwise

## ◆ registerSignalHandler()

static void OFIPCMessageQueueServer::registerSignalHandler | ( |  | ) |
| static

register signal handlers for SIGINT and SIGTERM that call closeAllMessageQueues() upon receiving the signal, thus globally closing all message queues created by the process, if these message queues would persist after the end of the process otherwise.

Does nothing on Windows.

## Related Definitions

## ◆ closeAllMessageQueues

void closeAllMessageQueues | ( |  | ) |
| friend

friend function that will call deleteQueueInternal().

Not to be called by normal user code, not thread safe!

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

- ofstd/include/dcmtk/ofstd/ofipc.h

Generated on Sat Mar 1 2025 for DCMTK Version 3.6.9 by Doxygen 1.13.2