DCMTK Version 3.6.8
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
aname 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.
anumber 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
msgmessage 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:


Generated on Mon Nov 6 2023 for DCMTK Version 3.6.8 by Doxygen 1.9.8