TipcMsgRead

Name

TipcMsgRead — read fields from a message

Synopsis

T_BOOL TipcMsgRead(msg, ...) 
T_IPC_MSG msg;

Arguments

msg — message to read fields from

additional arguments — null-terminated field type-value pairs

Return Values

TRUE if all the fields were successfully read, FALSE otherwise.

Diagnostics

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

T_ERR_NULL_PTR — msg was null

T_ERR_MSG_INVALID — msg was not a valid message

T_ERR_FT_INVALID — a field type argument was not a valid field type

T_ERR_MSG_EOM — the current field is at the end of message

any error number from TipcMsgReadVa

Description

TipcMsgRead is a convenience function that takes a null-terminated variable number of field type-value pairs and reads these fields from the message. The field type part of the pair is a T_IPC_FT, and the value part of the pair corresponds to the argument(s) for the related TipcMsgNext* function (for example, if the type part is T_IPC_FT_REAL8, then the value part is a pointer to a REAL8 number) or TipcMsgGet* function (for example, if the type part is T_IPC_PROP_DELIVERY_MODE, then the value part is a pointer to a T_IPC_DELIVERY_MODE setting).

TipcMsgRead is a short wrapper function that calls TipcMsgReadVa.

Caution

The last argument passed to TipcMsgRead must be null, otherwise TipcMsgRead may read garbage fields from the message. Using TipcMsgRead is slightly slower than using the TipcMsgNext* functions directly.

Examples

This example creates a message, appends two fields, and reads the fields back with TipcMsgRead:

T_IPC_MT mt; 
T_IPC_MSG msg; 
T_STR var_name; 
T_REAL8 var_value; 
 
mt = TipcMtLookupByNum(T_MT_NUMERIC_DATA); 
if (mt == NULL) { 
  return;  /* error */ 
} 
 
msg = TipcMsgCreate(mt); 
if (msg == NULL) { 
  return;  /* error */ 
}  
 
if (!TipcMsgAppendStrReal8(msg, "speed_limit", 55.0)) { 
  return;  /* error */ 
} 
 
if (!TipcMsgRead(msg,  
                 T_IPC_FT_STR, &var_name, 
                 T_IPC_FT_REAL8, &var_value, 
                 NULL)) { 
  return;  /* error */ 
}