TipcMsgAppendMsgPtr

Name

TipcMsgAppendMsgPtr — use a pointer to append a MSG field to a message

Synopsis

T_BOOL TipcMsgAppendMsgPtr(msg, msg_data, field_return) 
T_IPC_MSG msg; 
T_IPC_MSG msg_data; 
T_IPC_MSG_FIELD *field_return; 

Arguments

msg — message to append field to

msg_data — data for new message field

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 TipcMsgAppendMsgPtr fails, it returns FALSE and sets the global SmartSockets error number to one of:

Description

TipcMsgAppendMsgPtr appends a MSG field containing msg_data to the end of a message’s data. This function does not make a copy of the message. Instead, the supplied pointer 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 destroying the inner message once the field has been destroyed.

One advantage of TipcMsgAppendMsgPtr over TipcMsgAppendMsg is that the inner message 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 inner message 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 TipcMsgFieldUpdateMsgPtr function.

Caution

None

See Also

TipcMsgAppendMsg, TipcMsgNextMsg, TipcMsgFieldSetSize, TipcMsgFieldUpdateMsgPtr

Examples

This example creates a message and appends a MSG field:

T_IPC_MSG msg; 
T_IPC_MSG msg_data; 
 
#define USER_MT_CONTAINER 100 
 
mt = TipcMtCreate("container", USER_MT_CONTAINER, "msg"); 
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_NUMERIC_DATA); 
if (mt == NULL) { 
  return;  /* error */ 
} 
msg_data = TipcMsgCreate(mt); 
if (msg_data == NULL) { 
  return;  /* error */ 
} 
 
if (!TipcMsgAppendMsgPtr(msg, msg_data, NULL)) { 
  return;  /* error */ 
} 
 
if (!TipcMsgAppendStrReal8(msg_data, "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. */