TipcMsgAppendBinaryPtr

Name

TipcMsgAppendBinaryPtr — use a pointer to append a BINARY field to a message

Synopsis

T_BOOL TipcMsgAppendBinaryPtr(msg, binary_data, binary_size, field_return) 
T_IPC_MSG msg; 
T_PTR binary_data; 
T_INT4 binary_size; 
T_IPC_MSG_FIELD *field_return; 

Arguments

msg — message to append field to

binary_data — data for new message field

binary_size — number of bytes in binary_data

field_return — optional location to return field (use NULL if not needed)

Return Values

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

Diagnostics

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

Description

TipcMsgAppendBinaryPtr appends a BINARY field containing binary_data to the end of a message’s data. TipcMsgAppendBinaryPtr does not make a copy of the binary data. Instead, the supplied pointer to the data is entered directly into the new message field’s internal data structure. The caller is responsible for making sure that the pointer remains valid for the lifetime of the message field, and for freeing it, if necessary, when the message field has been destroyed.

One advantage of TipcMsgAppendBinaryPtr over TipcMsgAppendBinary is that the binary data can be modified after the field is appended, but before the message is sent. Another advantage is that the overhead of one copy operation is avoided. The data is still copied into the connection write buffer when the message is sent.

To update the pointer to point to a new memory location, use the TipcMsgFieldUpdateBinaryPtr function.

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

TipcMsgAppendBinary, TipcMsgNextBinary

Examples

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

T_IPC_MSG msg; 
char image[1024][1024]; 
T_IPC_MSG_FIELD field; 
T_INT4 image_size; 
 
#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. */ 
 
if (!TipcMsgAppendBinaryPtr(msg, image, sizeof(image), &field)) { 
  return;  /* error */ 
} 
 
image_size = fill_image(image); /* put data in the image */ 
if (!TipcMsgFieldSetSize(field, image_size)) { 
  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. */