TipcMonProjectNamesSetWatch

Name

TipcMonProjectNamesSetWatch — start or stop watching project names

Synopsis

T_BOOL TipcMonProjectNamesSetWatch(watch_status) 
T_BOOL watch_status; 

Arguments

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 TipcMonProjectNamesSetWatch fails, it returns FALSE and sets the global SmartSockets error number to one of:

Description

TipcMonProjectNamesSetWatch sets whether this RTclient is watching project names. TipcMonProjectNamesSetWatch 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 TipcMonProjectNamesGetWatch. To poll once for project names, use TipcMonProjectNamesPoll.

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

Caution

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

See Also

TipcMonProjectNamesGetWatch, TipcMonProjectNamesPoll

Examples

This example uses TipcMonProjectNamesSetWatch 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 (!TipcMonProjectNamesSetWatch(TRUE)) { 
  return; /* error */ 
}  
 
mt = TipcMtLookupByNum(T_MT_MON_PROJECT_NAMES_STATUS); 
if (mt == NULL) { 
  return; /* error */ 
} 
 
if (TipcSrvProcessCbCreate(mt, process_mon_project_names_status, 
NULL) 
    == NULL) { 
  return; /* error */ 
} 
 
/* At this point TipcSrvMainLoop can be used to read and process messages. */