TipcSrvMonClientSubscribePoll

Name

TipcSrvMonClientSubscribePoll — poll once for the subjects that an RTclient is subscribing to

Synopsis

T_BOOL TipcSrvMonClientSubscribePoll(srv, client_name) 
T_IPC_SRV srv; 
T_STR client_name; 

Arguments

srv — connection handle to RTserver

client_name — name of RTclient to poll for subjects being subscribed to (wildcard names allowed, or use T_IPC_MON_ALL to indicate a poll of all RTclients matching the value of Monitor_Scope)

Return Values

TRUE if the poll for subjects being subscribed to was successfully initiated, FALSE otherwise.

Diagnostics

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

Description

TipcSrvMonClientSubscribePoll polls for subjects that the client_name RTclient is subscribing to by sending a MON_CLIENT_SUBSCRIBE_POLL_CALL message to RTserver. 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. RTserver responds by sending back a MON_CLIENT_SUBSCRIBE_POLL_RESULT message. The response should come back quickly. The polling RTclient can use functions such as TipcSrvConnMsgSearchType or TipcSrvConnMainLoop to get the response.

The MON_CLIENT_SUBSCRIBE_POLL_RESULT message contains one or more groups of two fields:

This group of two fields is repeated multiple times only if client_name is a wildcard or T_IPC_MON_ALL.

To watch for subjects that an RTclient is subscribing to, use TipcSrvMonClientSubscribeSetWatch.

Caution

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

See Also

TipcSrvMonClientSubscribeGetWatch, TipcSrvMonClientSubscribeSetWatch, TipcSrvConnMsgWrite

Examples

This example uses TipcSrvMonClientSubscribePoll to poll for the subjects that all RTclients are subscribing to, waits up to 10 seconds for the poll result, and then prints the poll result message:

T_IPC_MT mt; 
T_IPC_MSG msg; 
T_STR client_name; 
T_STR *subscribe_subject_names; 
T_INT4 num_subscribe_subject_names; 
T_INT4 counter; 
 
/* send the poll request out to RTserver */ 
if (!TipcSrvMonClientSubscribePoll(srv, "/...")) { 
  return;  /* error */ 
}  
 
mt = TipcMtLookupByNum(T_MT_MON_CLIENT_SUBSCRIBE_POLL_RESULT); 
if (mt == NULL) { 
  return;  /* error */ 
}  
 
/* wait up to 10 seconds for the poll result */ 
msg = TipcSrvConnMsgSearchType(srv, 10.0, mt); 
if (msg == NULL) { 
  return;  /* error */ 
}  
 
/* set the current field to the first field */ 
if (!TipcMsgSetCurrent(msg, 0)) { 
  return;  /* error */ 
} 
 
/* loop through all groups */ 
TutOut("Got CLIENT_SUBSCRIBE poll result.\n"); 
while (TipcMsgNextStr(msg, &client_name) 
       && TipcMsgNextStrArray(msg, &subscribe_subject_names, 
                              &num_subscribe_subject_names)) { 
  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]); 
  } 
} 
 
/* make sure we reached the end of the message */ 
if (TutErrNumGet() != T_ERR_MSG_EOM) { 
  return;  /* error */ 
} 
 
/* clean up */ 
if (!TipcMsgDestroy(msg)) { 
  return;  /* error */ 
}