TipcMsgAppendMsgArrayPtr

Name

TipcMsgAppendMsgArrayPtr — use a pointer to append a field containing an array of MSG fields to a message

Synopsis

T_BOOL TipcMsgAppendMsgArrayPtr(msg, msg_array_data, array_size, 
field_return) 
T_IPC_MSG msg; 
T_IPC_MSG *msg_array_data; 
T_INT4 array_size; 
T_IPC_MSG_FIELD *field_return; 

Arguments

msg — message to append field to

msg_array_data — data for new message field

array_size — number of elements in msg_array_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 TipcMsgAppendMsgArrayPtr fails, it returns FALSE and sets the global SmartSockets error number to one of:

Description

TipcMsgAppendMsgArrayPtr appends a message array (MSG_ARRAY) field containing msg_array_data to the end of a message’s data. This function does not make a copy of the array. Instead, the supplied pointer to the array 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 TipcMsgAppendMsgArrayPtr over TipcMsgAppendMsgArray is that the array messages can be modified after the field is appended, but before the message is sent. Also, the overhead of one copy operation is avoided, because the array 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 TipcMsgFieldUpdateMsgArrayPtr function.

Caution

If the field_return argument is used to gain access to the message field, and the size of the field is subsequently modified using TipcMsgFieldSetSize, the array_size argument must be specified in elements rather than bytes.

See Also

TipcMsgAppendMsgArray, TipcMsgNextMsgArray, TipcMsgFieldSetSize, TipcMsgFieldUpdateMsgArrayPtr

Examples

This example creates a message and appends a pointer to a MSG_ARRAY field:

T_IPC_MT mt; 
T_IPC_MSG msg; 
#define ARRAY_SIZE 3 
T_IPC_MSG msg_array_data[ARRAY_SIZE]; 
 
#define USER_MT_CONTAINER 3 
mt = TipcMtCreate("container", USER_MT_CONTAINER, "msg_array"); 
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. */ 
 
mt = TipcMtLookupByNum(T_MT_TIME); 
if (mt == NULL) { 
  return;  /* error */ 
} 
msg_array_data[0] = TipcMsgCreate(mt); 
if (msg_array_data[0] == NULL) { 
  return;  /* error */ 
} 
 
mt = TipcMtLookupByNum(T_MT_NUMERIC_DATA); 
if (mt == NULL) { 
  return;  /* error */ 
} 
msg_array_data[1] = TipcMsgCreate(mt); 
if (msg_array_data[1] == NULL) { 
  return;  /* error */ 
} 
 
mt = TipcMtLookupByNum(T_MT_END_OF_FRAME); 
if (mt == NULL) { 
  return;  /* error */ 
} 
msg_array_data[2] = TipcMsgCreate(mt); 
if (msg_array_data[2] == NULL) { 
  return;  /* error */ 
} 
 
if (!TipcMsgAppendMsgArrayPtr(msg, msg_array_data, ARRAY_SIZE, 
                              NULL)) { 
  return;  /* error */ 
} 
 
if (!TipcMsgAppendReal8(msg_array_data[0], TutGetWallTime())) { 
  return;  /* error */ 
} 
 
if (!TipcMsgAppendStrReal8(msg_array_data[1], "speed_limit", 
70.0)) { 
  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. */