TipcMsgAppendBinary

Name

TipcMsgAppendBinary — append a BINARY field to a message

Synopsis

T_BOOL TipcMsgAppendBinary(msg, binary_data, binary_size) 
T_IPC_MSG msg; 
T_PTR binary_data; 
T_INT4 binary_size; 

Arguments

msg — message to which to append the field

binary_data — data for new message field

binary_size — number of bytes in binary_data

Return Values

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

Diagnostics

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

Description

TipcMsgAppendBinary appends a BINARY field containing binary_data to the end of a message’s data. A binary field is a special case of an array of characters. Binary fields are useful for transferring images or large amounts of opaque data (such as an entire binary file). TipcMsgAppendBinary makes a copy of the binary data.

Binary fields can be used for transferring actual C or C++ data structures, but the recommended approach is to use a separate message field for each data structure field. The separate fields allow SmartSockets to perform data conversion in a heterogeneous network environment. If the layout of the message must be determined dynamically, a message type grammar of "verbose" can be used.

There is a small amount of overhead associated with each message field, so binary fields can occasionally be useful for large amounts of data (such as a large array of data structures containing several different-sized data types) sent between processes in a homogeneous network.

Caution

Because binary fields can contain any kind of data, there is no way that Tipc* functions or RTserver can byte-swap integers or convert floating-point numbers. It is up to the application to take care of this when sending binary fields.

See Also

TipcMsgNextBinary

Examples

This example creates a message and appends a BINARY image field:

T_IPC_MSG msg; 
char image[1024][1024]; 
 
#define USER_MT_BINARY_TEST 100 
mt = TipcMtCreate("binary_test", USER_MT_BINARY_TEST, "binary"); 
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. */ 
 
fill_image(image); /* put data in the image */ 
if (!TipcMsgAppendBinary(msg, image, sizeof(image))) { 
  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. */