TipcConnMsgNext

Name

TipcConnMsgNext — get the next message from a connection

Synopsis

T_IPC_MSG TipcConnMsgNext(conn, timeout) 
T_IPC_CONN conn; 
T_REAL8 timeout; 

Arguments

conn — connection to get next message from

timeout — maximum number of seconds to wait for message to arrive

Return Values

A message if successful, NULL otherwise.

Diagnostics

If TipcConnMsgNext fails, it returns NULL and sets the global SmartSockets error number to one of:

Description

TipcConnMsgNext gets the next message from a connection. A connection has a priority queue of incoming messages. TipcConnMsgNext removes the message from the front of the queue (which is usually the message with the highest priority) and calls the connection’s queue callbacks. As a convenience, TipcConnMsgNext sets the current field of the returned message to field number 0 (the first field) with TipcMsgSetCurrent. To get a message other than the first message, use TipcConnMsgSearch. Once a message is acquired by calling TipcConnMsgNext, it is normally processed with TipcConnMsgProcess and then destroyed by calling TipcMsgDestroy.

If the connection’s message queue is not empty, TipcConnMsgNext can return a message immediately. If the message queue is empty, TipcConnMsgNext keeps calling TipcConnRead with timeout until at least one full message is read or TipcConnRead returns FALSE. Use 0.0 for timeout to poll for a message without blocking. Use T_TIMEOUT_FOREVER for timeout to wait until a message arrives.

Caution

The message returned by TipcConnMsgNext should be destroyed when it is no longer needed by calling TipcMsgDestroy, unless the message is passed to another function which takes responsibility for destroying the message (such as TipcConnMsgInsert).

For performance reasons, if TipcConnMsgNext has to call TipcConnRead several times, TipcConnMsgNext does not calculate how much of timeout has elapsed. Instead it calls TipcConnRead with the full timeout each time. If a large message is arriving very slowly in small increments, then the elapsed time may be much longer than the desired timeout.

See Also

TipcConnMsgProcess, TipcConnMainLoop, TipcConnRead

Examples

This example waits for up to 10 seconds to get the next message, processes the message, and finally destroys the message:

T_IPC_MSG msg; 
 
msg = TipcConnMsgNext(conn, 10.0); 
if (msg == NULL) { 
  return;  /* error */ 
} 
 
if (!TipcConnMsgProcess(conn, msg)) { 
  return;  /* error */ 
} 
 
if (!TipcMsgDestroy(msg)) { 
  return;  /* error */ 
}