TipcSrvMonServerNamesSetWatch

Name

TipcSrvMonServerNamesSetWatch — start or stop watching RTserver names

Synopsis

T_BOOL TipcSrvMonServerNamesSetWatch(srv, watch_status) 
T_IPC_SRV srv; 
T_BOOL watch_status; 

Arguments

srv — connection handle to RTserver

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

Return Values

TRUE if the RTserver names watch status was successfully set, FALSE otherwise.

Diagnostics

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

Description

TipcSrvMonServerNamesSetWatch sets whether this RTclient is watching the RTserver names that match the value of the Monitor_Scope option. TipcSrvMonServerNamesSetWatch saves the watch status and sends a MON_SERVER_NAMES_SET_WATCH message to RTserver. The watch status controls whether the RTclient receives a MON_SERVER_NAMES_STATUS message each time an RTserver is created or destroyed. An RTserver is considered created when it starts up (and usually connects to other RTservers). An RTserver is considered destroyed when it terminates or disconnects from other RTservers. 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_SERVER_NAMES_STATUS message contains four fields:

In addition to sending a MON_SERVER_NAMES_STATUS message each time an RTserver is created or destroyed, RTserver also sends an initial MON_SERVER_NAMES_STATUS message when the watch status is set to TRUE, so that the RTclient does not have to wait for the next RTserver name change to receive the first MON_SERVER_NAMES_STATUS message.

To determine if this RTclient is watching RTserver names, use TipcSrvMonServerNamesGetWatch. To poll once for RTserver names, use TipcSrvMonServerNamesPoll.

Caution

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

See Also

TipcSrvMonServerNamesGetWatch, TipcSrvMonServerNamesPoll

Examples

This example uses TipcSrvMonServerNamesSetWatch to start watching RTserver names and creates a callback to process the incoming MON_SERVER_NAMES_STATUS messages:

/* =============================================================== */ 
/*..process_mon_server_names_status -- process a MON_SERVER_NAMES_STATUS message */ 
void T_ENTRY process_mon_server_names_status(conn, data, arg) 
T_IPC_CONN conn; 
T_IPC_CONN_PROCESS_CB_DATA data; 
T_CB_ARG arg; 
{ 
  T_STR *server_names; 
  T_INT4 num_server_names; 
  T_STR *info_strs; 
  T_STR created_server; 
  T_STR destroyed_server; 
  T_INT4 counter; 
 
  /* must set current field first */ 
  if (!TipcMsgSetCurrent(data->msg, 0)) { 
    return;  /* error */ 
  }  
 
  /* get the fields from the message */ 
 
  /* both server_names and info_strs contains the same number of  
  elements */ 
 
  if (!TipcMsgNextStrArray(data->msg, &server_names,  
                           &num_server_names) 
      || !TipcMsgNextStrArray(data->msg, &info_strs, 
                              &num_server_names) 
      || !TipcMsgNextStr(data->msg, &created_server) 
      || !TipcMsgNextStr(data->msg, &destroyed_server)) { 
    return;  /* error */ 
  }  
 
  TutOut("Got SERVER_NAMES status.\n"); 
  for (counter = 0; counter < num_server_names; counter++) { 
    TutOut("server_names[%d] = %s\n", counter, 
server_names[counter]); 
    TutOut("info_strs[%d] = %s\n", counter, info_strs[counter]); 
  } 
  TutOut("created RTserver = %s\n", created_server); 
  TutOut("destroyed RTserver = %s\n", destroyed_server); 
} /* process_mon_server_names_status */ 
 
/* =========================================================== */ 
/*...code from calling function is below */ 
 
T_IPC_MT mt; 
 
if (!TipcSrvMonServerNamesSetWatch(srv, TRUE)) { 
  return;  /* error */ 
}  
 
mt = TipcMtLookupByNum(T_MT_MON_SERVER_NAMES_STATUS); 
if (mt == NULL) { 
  return;  /* error */ 
} 
 
if (TipcSrvConnProcessCbCreate(srv, mt, 
                               process_mon_server_names_status, NULL) 
    == NULL) { 
  return;  /* error */ 
} 
 
/* At this point TipcSrvConnMainLoop can be used to read and process messages. */