TipcMsgAddNamedUtf8Ptr

Name

TipcMsgAddNamedUtf8Ptr — add a UTF8 field to a message using a name, and a pointer to the field value, rather than a copy

Synopsis

T_BOOL TipcMsgAddNamedUtf8Ptr(msg, name, ptr, field_return) 
T_IPC_MSG msg; 
T_STR name; 
T_PTR ptr; 
T_IPC_MSG_FIELD *field_return; 

Arguments

msg — message to add field to

name — name of the field

ptr — pointer to the value of the field

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

Return Values

TRUE if the addition was successful, FALSE otherwise.

Diagnostics

If TipcMsgAddNamedUtf8Ptr fails, it returns FALSE and sets the global SmartSockets error number to:

Description

TipcMsgAddNamedUtf8Ptr adds a UTF8 field to a message, associating that field with a name. If the name already exists in the message, this fails, and the field is not added to the message. The value given is used as a pointer to the value, so the copy is made when the message is actually sent, not when the call is made. You must ensure that the data pointed to remains valid until the message is sent.

See Also

TipcMsgAppendUtf8Ptr, TipcMsgUpdateNamedUtf8Ptr, TipcMsgFieldUpdateUtf8Ptr

Examples

This example creates a message and adds a UTF8 value to it:

T_IPC_MSG msg; 
T_BOOL status; 
T_IPC_MSG_FIELD *field_return; 
 
msg = TipcMsgCreate(TipcMtLookupByNum(T_MT_INFO)); 
if (msg == NULL) { 
  return;  /* error */ 
} 
 
status = TipcMsgAddNamedUtf8Ptr(msg, "foo", "bar", field_return); 
if (status == FALSE) { 
  return;  /* error */