TipcMsgAppendUtf8Ptr

Name

TipcMsgAppendUtf8Ptr — use a pointer to append a UTF8 field to a message

Synopsis

T_BOOL TipcMsgAppendUtf8Ptr(msg, utf8_data, utf8_size, field_return) 
T_IPC_MSG msg; 
T_PTR utf8_data; 
T_INT4 utf8_size; 
T_IPC_MSG_FIELD *field_return; 

Arguments

msg — message to append field to

utf8_data — data for new message field

utf8_size — number of bytes in utf8_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 TipcMsgAppendUtf8Ptr fails, it returns FALSE and sets the global SmartSockets error number to one of:

Description

TipcMsgAppendUtf8Ptr appends a UTF8 field containing utf8_data to the end of a message’s data. TipcMsgAppendUtf8Ptr does not make a copy of the UTF8 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 TipcMsgAppendUtf8Ptr over TipcMsgAppendUtf8 is that the UTF8 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 TipcMsgFieldUpdateUtf8Ptr function.

Caution

None

See Also

TipcMsgAppendUtf8, TipcMsgNextUtf8

Examples

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

T_IPC_MT mt; 
T_IPC_MSG msg; 
T_STR utf8[80]; 
T_IPC_MSG_FIELD field; 
 
#define USER_MT_STR_TEST 100 
mt = TipcMtCreate("str_test", USER_MT_STR_TEST, "str"); 
if (mt == NULL) { 
  return;  /* error */ 
} 
 
msg = TipcMsgCreate(mt); 
if (mt == NULL) { 
  return;  /* error */ 
} 
 
/* An RTclient would typically set the destination of */ 
/* a message at this point by calling TipcMsgSetDest. */ 
 
str[0] = '\0'; 
if (!TipcMsgAppendUtf8Ptr(msg, str, &field)) { 
  return;  /* error */ 
}  
 
strcpy(str, "This is the field data."); 
if (!TipcMsgFieldSetSize(field, strlen(str) + 1)) { 
  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. */