TipcMsgNextUnknown

Name

TipcMsgNextUnknown — checks if the next field in a message is of unknown value

Synopsis

T_BOOL TipcMsgNextUnknown(msg) 
T_IPC_MSG msg; 

Arguments

msg — message to check field from

Return Values

TRUE if the field was successfully checked and was of value unknown, FALSE otherwise.

Diagnostics

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

Description

TipcMsgNextUnknown checks to see if the current field of a message is of known value. If the unknown_value property of a field is set, TipcMsgNextUnknown succeeds and advances the current field to the next field in the message. If the unknown_value property is not set, TipcMsgNextUnknown fails and does not advance to the next field in the message, allowing the application to use a different function to retrieve that value from the message.

Frequently, messages have a fixed number of fields in a constant order. In that case, omitting a field when data occasionally does not exist is not feasible. Setting the unknown_value property allows fields to be marked as having no data. This feature is most useful when the entire range of values is valid within an application and there is a need to denote that the field has no valid data.

Caution

A FALSE return value can indicate several things. Check the value of the global SmartSockets error number before assuming that it means the current field is valid.

See Also

TipcMsgAppendUnknown, TipcMsgGetCurrentFieldKnown

Examples

This example creates a message, appends a field of value unknown, and reads the field back from the message:

T_IPC_MT mt; 
T_IPC_MSG msg; 
mt = TipcMtLookupByNum (T_MT_NUMERIC_DATA); 
if (mt==NULL) { 
  return;  /* error */ 
} 
 
msg=TipcMsgCreate(mt); 
if (msg==NULL) { 
  return;  /* error */ 
} 
 
if (!TipcMsgAppendUnknown(msg, T_IPC_FT_INT4)) { 
  return;  /* error */    
} 
 
if (!TipcMsgSetCurrent(msg,0)) { 
  return;  /* error */    
} 
 
if (!TipcMsgNextUnknown(msg)) { 
  return;  /* error */    
}