TipcMsgFileRead

Name

TipcMsgFileRead — read a message from a message file

Synopsis

T_BOOL TipcMsgFileRead(msg_file, msg_return) 
T_IPC_MSG_FILE msg_file; 
T_IPC_MSG *msg_return; 

Arguments

msg_file — message file

msg_return — storage for message from file

Return Values

TRUE if a message was successfully read from the message file, FALSE otherwise.

Diagnostics

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

Description

TipcMsgFileRead reads one message from a message file. See TipcMsgFileCreate for more information on message files. For text message files, TipcMsgFileRead reads the message type name, creates a message, sets the sender of the message to _file, reads the destination, sets the destination, and finally reads the fields and appends them to the message.

Caution

When the message returned in msg_return by TipcMsgFileRead is no longer needed, destroy it by calling TipcMsgDestroy, unless the message is passed to another function which takes responsibility for destroying the message (such as TipcSrvMsgInsert).

See Also

TipcMsgFileCreate, TipcMsgFileCreateFromFile, TipcMsgFileDestroy, TipcMsgFileWrite

Examples

This example creates a message file from the file data.msg, reads all the messages in the file using TipcMsgFileRead, and prints out the message with TipcMsgPrint:

T_IPC_MSG_FILE msg_file; 
T_IPC_MSG msg; 
 
msg_file = TipcMsgFileCreate("data.msg", 
T_IPC_MSG_FILE_CREATE_READ); 
if (msg_file == NULL) { 
  return;  /* error */ 
} 
 
while (TipcMsgFileRead(msg_file, &msg)) { 
  TutOut("Read a message.\n"); 
  if (!TipcMsgPrint(msg, TutOut)) { 
    return;  /* error */ 
  } 
  if (!TipcMsgDestroy(msg)) { 
    return;  /* error */ 
  } 
}  
 
if (!TipcMsgFileDestroy(msg_file)) { 
  return;  /* error */ 
} 
 

If the file data.msg contained the information:

numeric_data thermal { 
  bat1_voltage 42.4 
} 

then the output from the above example is similar to:

Read a message. 
type = numeric_data 
sender = <_file> 
dest = <thermal> 
max = 2048 
size = 45 
current = 0 
read_only = false 
priority = 0 
delivery_mode = best_effort 
ref_count = 1 
seq_num = 0 
resend_mode = false 
user_prop = 0 
data (num_fields = 2): 
  str "bat1_voltage" 
  real8 42.4