TipcSrvMonSubjectSubscribeSetWatch

Name

TipcSrvMonSubjectSubscribeSetWatch — start or stop watching the RTclients that are subscribing to a subject

Synopsis

T_BOOL TipcSrvMonSubjectSubscribeSetWatch(srv, subject_name, 
watch_status) 
T_IPC_SRV srv; 
T_STR subject_name; 
T_BOOL watch_status; 

Arguments

srv — connection handle to RTserver

subject_name — name of subject to set watch status for (use T_IPC_MON_ALL to indicate a watch of all subjects matching the value of Monitor_Scope)

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

Return Values

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

Diagnostics

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

Description

TipcSrvMonSubjectSubscribeSetWatch sets whether this RTclient is watching the RTclients that are subscribing to a subject. TipcSrvMonSubjectSubscribeSetWatch saves the watch status and sends a MON_SUBJECT_SUBSCRIBE_SET_WATCH message to RTserver. The watch status controls whether the RTclient receives a MON_SUBJECT_SUBSCRIBE_STATUS message each time an RTclient starts or stops subscribing to the subject. The watch status is saved internally so the RTclient can automatically resume watching all appropriate categories if RTclient has to reconnect to RTserver. If subject_name is T_IPC_MON_ALL then all subjects in the current project that match the value of the Monitor_Scope option are watched.

Each MON_SUBJECT_SUBSCRIBE_STATUS message contains four fields:

In addition to sending a MON_SUBJECT_SUBSCRIBE_STATUS message each time an RTclient starts or stops subscribing to the subject, RTserver also sends an initial MON_SUBJECT_SUBSCRIBE_STATUS message (or many messages if 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 subject subscriber change to receive the first MON_SUBJECT_SUBSCRIBE_STATUS message.

To determine if this RTclient is watching the RTclients that are subscribing to a subject, use TipcSrvMonSubjectSubscribeGetWatch. To poll once for the RTclients that are subscribing to a subject, use TipcSrvMonSubjectSubscribePoll.

For an example of how MON_SUBJECT_SUBSCRIBE_STATUS messages can be used, see the RTmon GDI Watch Clients in Subject window.

Caution

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

There is no initial status message if the subject named subject_name does not exist.

See Also

TipcSrvMonSubjectSubscribeGetWatch, TipcSrvMonSubjectSubscribePoll

Examples

This example uses TipcSrvMonSubjectSubscribeSetWatch to start watching the RTclients that are subscribing to the thermal subject and creates a callback to process the incoming MON_SUBJECT_SUBSCRIBE_STATUS messages:

/* =============================================================== */ 
/*..process_mon_subject_subscribe_status -- process a MON_SUBJECT_SUBSCRIBE_STATUS 
message */ 
void T_ENTRY process_mon_subject_subscribe_status(conn, data, arg) 
T_IPC_CONN conn; 
T_IPC_CONN_PROCESS_CB_DATA data; 
T_CB_ARG arg; 
{ 
  T_STR subject_name; 
  T_STR *subscribe_client_names; 
  T_INT4 num_subscribe_client_names; 
  T_STR start_client; 
  T_STR stop_client; 
  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, &subject_name) 
      || !TipcMsgNextStrArray(data->msg, &subscribe_client_names, 
                              &num_subscribe_client_names) 
      || !TipcMsgNextStr(data->msg, &start_client) 
      || !TipcMsgNextStr(data->msg, &stop_client)) { 
    return;  /* error */ 
  }  
 
  TutOut("Got SUBJECT_SUBSCRIBE status.\n"); 
  TutOut("subject name = %s\n", subject_name); 
  for (counter = 0; counter < num_subscribe_client_names; 
counter++) { 
    TutOut("subscribe_client_names[%d] = %s\n", counter, 
           subscribe_client_names[counter]); 
  } 
  TutOut("start RTclient = %s\n", start_client); 
  TutOut("stop RTclient = %s\n", stop_client); 
} /* process_mon_subject_subscribe_status */ 
 
/* =========================================================== */ 
/*...code from calling function is below */ 
 
T_IPC_MT mt; 
 
if (!TipcSrvMonSubjectSubscribeSetWatch(srv, "thermal", TRUE)) { 
  return;  /* error */ 
}  
 
mt = TipcMtLookupByNum(T_MT_MON_SUBJECT_SUBSCRIBE_STATUS); 
if (mt == NULL) { 
  return;  /* error */ 
} 
 
if (TipcSrvConnProcessCbCreate(srv, mt, 
process_mon_subject_subscribe_status,  
                               NULL) == NULL) { 
  return;  /* error */ 
} 
 
/* At this point TipcSrvConnMainLoop can be used to read and process messages. */