TipcMonSubjectSubscribePoll

Name

TipcMonSubjectSubscribePoll — poll once for the RTclients that are subscribing to a subject

Synopsis

T_BOOL TipcMonSubjectSubscribePoll(subject_name) 
T_STR subject_name; 

Arguments

subject_name — name of subject to poll for subscribers (use T_IPC_MON_ALL to indicate a poll of all subjects matching the value of Monitor_Scope)

Return Values

TRUE if the poll for the RTclients that are subscribing to a subject was successfully initiated, FALSE otherwise.

Diagnostics

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

Description

TipcMonSubjectSubscribePoll polls for RTclients that are subscribing to a subject by sending a MON_SUBJECT_SUBSCRIBE_POLL_CALL message 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 polled. RTserver responds by sending back a MON_SUBJECT_SUBSCRIBE_POLL_RESULT message. The response should come back quickly.

The polling RTclient can use functions such as TipcSrvMsgSearchType or TipcSrvMainLoop to get the response.

The MON_SUBJECT_SUBSCRIBE_POLL_RESULT message contains groups of two fields:

The group of two fields is repeated multiple times only if subject_name is T_IPC_MON_ALL.

To watch for subject subscribers, use TipcMonSubjectSubscribeSetWatch.

Caution

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

See Also

TipcMonSubjectSubscribeGetWatch, TipcMonSubjectSubscribeSetWatch, TipcSrvMsgWrite

Examples

This example uses TipcMonSubjectSubscribePoll to poll all subjects for the RTclients that are subscribing to the subject, 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 subject_name; 
T_STR *subscribe_client_names; 
T_INT4 num_subscribe_client_names; 
T_INT4 counter; 
 
/* send the poll request out to RTserver */ 
if (!TipcMonSubjectSubscribePoll("/...")) { 
  return; /* error */ 
}  
 
mt = TipcMtLookupByNum(T_MT_MON_SUBJECT_SUBSCRIBE_POLL_RESULT); 
if (mt == NULL) { 
  return; /* error */ 
}  
 
/* wait up to 10 seconds for the poll result */ 
msg = TipcSrvMsgSearchType(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 SUBJECT_SUBSCRIBE poll result.\n"); 
while (TipcMsgNextStr(msg, &subject_name) 
       && TipcMsgNextStrArray(msg, &subscribe_client_names, 
                              &num_subscribe_client_names)) { 
  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]); 
  } 
} 
 
/* make sure we reached the end of the message */ 
if (TutErrNumGet() != T_ERR_MSG_EOM) { 
  return; /* error */ 
} 
 
/* clean up */ 
if (!TipcMsgDestroy(msg)) { 
  return; /* error */ 
}