TipcMsgAppendUnknown

Name

TipcMsgAppendUnknown — append a field to a message and set that field’s value to unknown

Synopsis

T_BOOL TipcMsgAppendUnknown(msg, field_type) 
T_IPC_MSG msg; 
T_IPC_FT field_type; 

Arguments

msg — message to append unknown-valued field to

field_type — field type for new message field

Return Values

TRUE if the field was successfully appended to the message, FALSE otherwise.

Diagnostics

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

Description

TipcMsgAppendUnknown appends a field of the type specified to the end of a message’s data, and sets the unknown_value property of the field to TRUE. 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 field values is valid within an application and there is a need to denote that the field has no valid data.

Caution

Only valid field types as defined in the enumerated structure T_IPC_FT are allowable values for the field_type argument. Property components of that structure indicated with the T_IPC_PROP prefix, such as destination (T_IPC_PROP_DEST) or sender (T_IPC_PROP_SENDER) cannot be appended as unknown values. See Messages for a a definition of this structure.

See Also

TipcMsgNextUnknown, TipcMsgGetCurrentFieldKnown

Examples

This example creates a message and appends a field of unknown value:

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 */  
}  
 
/* An RTclient would typically set the destination of */  
/* a message at this point by calling TipcMsgSetDest. */  
 
if (!TipcMsgAppendUnknown(msg, T_IPC_FT_INT4)) { 
  return;  /* error */  
}  
 
/* A process would typically send a message at this point by */  
/* calling TipcConnMsgSend or TipcSrvMsgSend. */ 
 
/* A process would typically destroy a message at this point by */  
/* calling TipcMsgDestroy. */