TipcSrvMonClientMsgSendSetWatch

Name

TipcSrvMonClientMsgSendSetWatch — start or stop watching RTclient sent messages

Synopsis

T_BOOL TipcSrvMonClientMsgSendSetWatch(srv, client_name, msg_type_name, 
watch_status) 
T_IPC_SRV srv; 
T_STR client_name; 
T_STR msg_type_name; 
T_BOOL watch_status; 

Arguments

srv — connection handle to RTserver

client_name — name of RTclient to set watch status for (wildcard names allowed, or use T_IPC_MON_ALL to indicate a watch of all RTclients matching the value of Monitor_Scope)

msg_type_name — name of message type to set watch status for (use T_IPC_MON_ALL to indicate a watch of all message types)

watch_status — new watch status (TRUE to start watching, FALSE to stop watching)

Return Values

TRUE if the RTclient sent messages watch status was successfully set, FALSE otherwise.

Diagnostics

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

Description

TipcSrvMonClientMsgSendSetWatch sets whether this RTclient is watching sent messages in the client_name RTclient. The client_name argument can be the unique subject name of a single RTclient, a wildcarded subject name to match many RTclients, or T_IPC_MON_ALL to watch all RTclients in the project that match the value of the Monitor_Scope option. TipcSrvMonClientMsgSendSetWatch saves the watch status and sends a MON_CLIENT_MSG_SEND_SET_WATCH message to the client_name RTclient. The watch status controls whether the RTclient receives a MON_CLIENT_MSG_SEND_STATUS message each time a message is sent to RTserver in the watched RTclient. The watch status is saved internally so the RTclient can automatically resume watching all appropriate categories if RTclient has to reconnect to RTserver. If msg_type_name is T_IPC_MON_ALL then all message types in the watched RTclient are watched.

Each MON_CLIENT_MSG_SEND_STATUS message contains two fields:

Unlike most of the other watch categories, the watched RTclient does not also send an initial MON_CLIENT_MSG_SEND_STATUS message when the watch status is set to TRUE. This is because the status message is only sent when a message is sent, and thus there is no current status to use for initialization.

To determine if this RTclient is watching RTclient sent messages, use TipcSrvMonClientMsgSendGetWatch.

For an example of how MON_CLIENT_MSG_SEND_STATUS messages can be used, see the RTmon GDI Watch Messages Sent window.

Caution

TipcSrvMonClientMsgSendSetWatch sends a MON_CLIENT_MSG_SEND_SET_WATCH message to RTserver, but does not explicitly flush the message. See TipcSrvConnGetAutoFlushSize for more information on message buffering.

RTclient sent messages can only be watched, not polled.

The MON_CLIENT_BUFFER_STATUS, MON_CLIENT_MSG_RECV_STATUS, and MON_CLIENT_MSG_SEND_STATUS message types cannot be watched and are silently ignored by the internal monitoring callbacks that generate outgoing MON_CLIENT_MSG_SEND_STATUS messages. The callbacks ignore these message types to prevent infinite loops.

See Also

TipcSrvMonClientMsgSendGetWatch

Examples

This example uses TipcSrvMonClientMsgSendSetWatch to start watching all sent messages in the primary RTclient and creates a callback to process the incoming MON_CLIENT_MSG_SEND_STATUS messages:

/* ============================================================== */ 
/*..process_mon_client_msg_send_status -- process a MON_CLIENT_MSG_SEND_STATUS 
message */ 
 
void T_ENTRY process_mon_client_msg_send_status(conn, data, arg) 
T_IPC_CONN conn; 
T_IPC_CONN_PROCESS_CB_DATA data; 
T_CB_ARG arg; 
{ 
  T_STR client_name; 
  T_IPC_MSG send_msg; 
   
  /* must set current field first */ 
  if (!TipcMsgSetCurrent(data->msg, 0)) { 
    return;  /* error */ 
  }  
 
  /* get the fields from the message */ 
  if (!TipcMsgRead(data->msg,  
                   T_IPC_FT_STR, &client_name, 
                   T_IPC_FT_MSG, &send_msg, 
                   NULL)) { 
    return;  /* error */ 
  }  
 
  TutOut("Got CLIENT_MSG_SEND status.\n"); 
  TutOut("RTclient name = %s\n", client_name); 
  TutOut("send msg\n"); 
  if (!TipcMsgPrint(send_msg, TutOut)) { 
    return;  /* error */ 
  } 
} /* process_mon_client_msg_send_status */ 
 
/* =========================================================== */ 
/*...code from calling function is below */ 
 
T_IPC_MT mt; 
 
if (!TipcSrvMonClientMsgSendSetWatch(srv, "primary_rtie", 
T_IPC_MON_ALL, 
                                     TRUE)) { 
  return;  /* error */ 
}  
 
mt = TipcMtLookupByNum(T_MT_MON_CLIENT_MSG_SEND_STATUS); 
if (mt == NULL) { 
  return;  /* error */ 
} 
 
if (TipcSrvConnProcessCbCreate(srv, mt,  
                               process_mon_client_msg_send_status,  
                               NULL) == NULL) { 
  return;  /* error */ 
} 
 
/* At this point TipcSrvConnMainLoop can be used to read and process messages. */