TipcMonClientSubscribeSetWatch

Name

TipcMonClientSubscribeSetWatch — start or stop watching the subjects that an RTclient is subscribing to

Synopsis

T_BOOL TipcMonClientSubscribeSetWatch(client_name, watch_status) 
T_STR client_name; 
T_BOOL watch_status; 

Arguments

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)

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

Return Values

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

Diagnostics

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

Description

TipcMonClientSubscribeSetWatch sets whether this RTclient is watching the subjects that the client_name RTclient is subscribing to. 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 poll all RTclients in the project that match the value of the Monitor_Scope option. TipcMonClientSubscribeSetWatch saves the watch status and sends a MON_CLIENT_SUBSCRIBE_SET_WATCH message to RTserver. The watch status controls whether the RTclient receives a MON_CLIENT_SUBSCRIBE_STATUS message each time the watched RTclient starts or stops subscribing to a subject. The watch status is saved internally so the RTclient can automatically resume watching all appropriate categories if RTclient has to reconnect to RTserver.

Each MON_CLIENT_SUBSCRIBE_STATUS message contains four fields:

In addition to sending a MON_CLIENT_SUBSCRIBE_STATUS message each time the watched RTclient starts or stops subscribing to a subject, RTserver also sends an initial MON_CLIENT_SUBSCRIBE_STATUS message (or many messages if a wildcard or T_IPC_MON_ALL is used) when the watch status is set to TRUE, so that the RTclient does not have to wait for the next subscribed subject change to receive the first MON_CLIENT_SUBSCRIBE_STATUS message.

To determine if this RTclient is watching the subjects that an RTclient is subscribing to, use TipcMonClientSubscribeGetWatch. To poll once for the subjects that an RTclient is subscribing to, use TipcMonClientSubscribePoll.

For an example of how MON_CLIENT_SUBSCRIBE_STATUS messages can be used, see the RTmon GDI Watch Client Subjects window.

Caution

TipcMonClientSubscribeSetWatch sends a MON_CLIENT_SUBSCRIBE_SET_WATCH message to RTserver, but does not explicitly flush the message. See TipcSrvGetAutoFlushSize for more information on message buffering.

There is no initial status message if the RTclient named client_name does not exist.

See Also

TipcMonClientSubscribeGetWatch, TipcMonClientSubscribePoll

Examples

This example uses TipcMonClientSubscribeSetWatch to start watching the subjects being subscribed to by the primary RTclient and creates a callback to process the incoming MON_CLIENT_SUBSCRIBE_STATUS messages:

/* =============================================================== */ 
/*..process_mon_client_subscribe_status -- process a MON_CLIENT_SUBSCRIBE_STATUS 
message */ 
void T_ENTRY process_mon_client_subscribe_status(conn, data, arg) 
T_IPC_CONN conn; 
T_IPC_CONN_PROCESS_CB_DATA data; 
T_CB_ARG arg; 
{ 
  T_STR client_name; 
  T_STR *subscribe_subject_names; 
  T_INT4 num_subscribe_subject_names; 
  T_STR start_subject; 
  T_STR stop_subject; 
  T_INT4 counter; 
 
  /* must set current field first */ 
  if (!TipcMsgSetCurrent(data->msg, 0)) { 
    return; /* error */ 
  }  
 
  /* get the fields from the message */ 
  if (!TipcMsgNextStr(data->msg, &client_name) 
      || !TipcMsgNextStrArray(data->msg, &subscribe_subject_names, 
                              &num_subscribe_subject_names) 
      || !TipcMsgNextStr(data->msg, &start_subject) 
      || !TipcMsgNextStr(data->msg, &stop_subject)) { 
    return; /* error */ 
  }  
 
  TutOut("Got CLIENT_SUBSCRIBE status.\n"); 
  TutOut("RTclient name = %s\n", client_name); 
  for (counter = 0; counter < num_subscribe_subject_names;  
       counter++) { 
    TutOut("subscribe_subject_names[%d] = %s\n", counter, 
           subscribe_subject_names[counter]); 
  } 
  TutOut("start subject = %s\n", start_subject); 
  TutOut("stop subject = %s\n", stop_subject); 
} /* process_mon_client_subscribe_status */ 
 
/* =========================================================== */ 
/*...code from calling function is below */ 
 
T_IPC_MT mt; 
 
if (!TipcMonClientSubscribeSetWatch("primary", TRUE)) { 
  return; /* error */ 
}  
 
mt = TipcMtLookupByNum(T_MT_MON_CLIENT_SUBSCRIBE_STATUS); 
if (mt == NULL) { 
  return; /* error */ 
} 
 
if (TipcSrvProcessCbCreate(mt, 
process_mon_client_subscribe_status, 
                           NULL) == NULL) { 
  return; /* error */ 
} 
 
/* At this point TipcSrvMainLoop can be used to read and process messages. */