TipcSrvMsgSearch

Name

TipcSrvMsgSearch — search the message queue of the connection to RTserver for a specific message

Synopsis

T_IPC_MSG TipcSrvMsgSearch(timeout, func, arg) 
T_REAL8 timeout; 
T_IPC_CONN_MSG_SEARCH_FUNC func; 
T_PTR arg; 

Arguments

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 TipcSrvMsgSearch fails, it returns NULL and sets the global SmartSockets error number to one of:

Description

TipcSrvMsgSearch 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.

TipcSrvMsgSearch 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, TipcSrvMsgSearch searches the messages in the warm connection. If no messages are queued in the warm connection, then TipcSrvMsgSearch calls TutSleep with timeout, so that RTclient does not use an abnormal amount of CPU time. See TipcSrvCreate on automatic creation of connections and warm connections to RTserver.

Caution

The message returned by TipcSrvMsgSearch 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 TipcSrvMsgInsert.

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

See Also

TipcConnMsgSearch, TipcSrvMsgSearchType

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 = TipcSrvMsgSearch(10.0, search_for_dest, "/system/_all"); 
if (msg == NULL) { 
  return;  /* error */ 
}