TipcSrvMonProjectNamesSetWatch

Name

TipcSrvMonProjectNamesSetWatch — start or stop watching project names

Synopsis

T_BOOL TipcSrvMonProjectNamesSetWatch(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 project names watch status was successfully set, FALSE otherwise.

Diagnostics

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

Description

TipcSrvMonProjectNamesSetWatch sets whether this RTclient is watching project names. TipcSrvMonProjectNamesSetWatch saves the watch status and sends a MON_PROJECT_NAMES_SET_WATCH message to RTserver. The watch status controls whether the RTclient receives a MON_PROJECT_NAMES_STATUS message each time a project is created or destroyed. A project is considered created when the first RTclient in that project connects to RTserver. A project is considered destroyed when the last RTclient in that project disconnects from RTserver. 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_PROJECT_NAMES_STATUS message contains three fields:

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

To determine if this RTclient is watching project names, use TipcSrvMonProjectNamesGetWatch. To poll once for project names, use TipcSrvMonProjectNamesPoll.

For an example of how MON_PROJECT_NAMES_STATUS messages can be used, see the RTmon GDI Project Browser window.

Caution

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

See Also

TipcSrvMonProjectNamesGetWatch, TipcSrvMonProjectNamesPoll

Examples

This example uses TipcSrvMonProjectNamesSetWatch to start watching project names and creates a callback to process the incoming MON_PROJECT_NAMES_STATUS messages:

/* =============================================================== */ 
/*..process_mon_project_names_status -- process a MON_PROJECT_NAMES_STATUS message 
*/ 
void T_ENTRY process_mon_project_names_status(conn, data, arg) 
T_IPC_CONN conn; 
T_IPC_CONN_PROCESS_CB_DATA data; 
T_CB_ARG arg; 
{ 
  T_STR *project_names; 
  T_INT4 num_project_names; 
  T_STR created_project; 
  T_STR destroyed_project; 
  T_INT4 counter; 
 
  /* must set current field first */ 
  if (!TipcMsgSetCurrent(data->msg, 0)) { 
    return;  /* error */ 
  }  
 
  /* get the fields from the message */ 
  if (!TipcMsgNextStrArray(data->msg, &project_names,  
                           &num_project_names) 
      || !TipcMsgNextStr(data->msg, &created_project) 
      || !TipcMsgNextStr(data->msg, &destroyed_project)) { 
    return;  /* error */ 
  }  
 
  TutOut("Got PROJECT_NAMES status.\n"); 
  for (counter = 0; counter < num_project_names; counter++) { 
    TutOut("project_names[%d] = %s\n", counter,  
           project_names[counter]); 
  } 
  TutOut("created project = %s\n", created_project); 
  TutOut("destroyed project = %s\n", destroyed_project); 
} /* process_mon_project_names_status */ 
 
/* =========================================================== */ 
/*...code from calling function is below */ 
 
T_IPC_MT mt; 
 
if (!TipcSrvMonProjectNamesSetWatch(srv, TRUE)) { 
  return;  /* error */ 
}  
 
mt = TipcMtLookupByNum(T_MT_MON_PROJECT_NAMES_STATUS); 
if (mt == NULL) { 
  return;  /* error */ 
} 
 
if (TipcSrvConnProcessCbCreate(srv, mt, 
                               process_mon_project_names_status, 
NULL) 
    == NULL) { 
  return;  /* error */ 
} 
 
/* At this point TipcSrvConnMainLoop can be used to read and process messages. */