TipcSrvConnMsgSearch

Name

TipcSrvConnMsgSearch — search the message queue of the connection for a specific message

Synopsis

T_IPC_MSG TipcSrvConnMsgSearch(srv, timeout, func, arg) 
T_IPC_SRV srv; 
T_REAL8 timeout; 
T_IPC_CONN_MSG_SEARCH_FUNC func; 
T_PTR arg; 

Arguments

srv — connection handle to RTserver

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

func — function to call once for each message

arg — user-defined argument to pass to func

Return Values

A message if successful, NULL otherwise.

Diagnostics

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

Description

TipcSrvConnMsgSearch searches the message queue of the connection to RTserver for a specific message by calling TipcConnMsgSearch. A connection has a priority queue of incoming messages. See TipcConnMsgSearch for more information on searching a connection’s message queue.

TipcSrvConnMsgSearch may attempt to automatically create a connection to RTserver. If RTclient has a warm connection to RTserver, and if any messages are in the warm connection message queue, TipcSrvConnMsgSearch searches the messages in the warm connection. If no messages are queued in the warm connection, then TipcSrvConnMsgSearch calls TutSleep with timeout, so that RTclient does not use an abnormal amount of CPU time. See TipcSrvConnOpen for more information on automatic creation of connections and warm connections to RTserver.

Caution

The message returned by TipcSrvConnMsgSearch 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 TipcSrvConnMsgInsert.

RTclients that receive messages with TipcSrvConnMsgNext or TipcSrvConnMsgSearch but do not call TipcSrvConnMsgProcess on those message are not monitorable with the TipcSrvMon* API or RTmon. RTclient monitoring is implemented using connection process callbacks, which are all called by TipcSrvConnMsgProcess.

See Also

TipcConnMsgSearch, TipcSrvConnMsgSearchType

Examples

This example waits for up to 10 seconds for a message to arrive that was sent to the /system/_all subject:

/* =============================================================== */ 
/*..search_for_dest -- search one message */ 
static T_ENTRY T_BOOL search_for_dest(conn, msg, arg) 
T_IPC_CONN conn; 
T_IPC_MSG msg; 
T_PTR arg; /* really (T_STR) */ 
{ 
  T_STR desired_dest = arg; 
  T_STR dest; 
 
  if (!TipcMsgGetDest(msg, &dest)) { 
    return;  /* error */ 
  }  
  return strcmp(dest, desired_dest) == 0; 
 
} /* search_for_dest */ 
 
 
/*...fragment that uses above search function */ 
 
msg = TipcSrvConnMsgSearch(srv, 10.0, search_for_dest, 
"/system/_all"); 
if (msg == NULL) { 
  return;  /* error */ 
}