TipcMsgAppendXmlPtr

Name

TipcMsgAppendXmlPtr — append an XML pointer to a message

Synopsis

T_BOOL TipcMsgAppendXmlPtr(msg, xml_data, field_return) 
T_IPC_MSG msg; 
T_XML xml_data; 
T_IPC_MSG_FIELD *field_return; 

Arguments

msg — message to append the field to

xml_data — XML object for new 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 TipcMsgAppendXmlPtr fails, it returns FALSE and sets the global SmartSockets error number to one of:

Description

TipcMsgAppendXmlPtr appends an XML object to the end of a message’s data. This function does not make a copy of the string. Instead, the supplied pointer to the string 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 TipcMsgAppendXmlPtr over TipcMsgAppendXml is that the string 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 character string is still copied into the connection message buffer when the message is sent.

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

Caution

Caller must ensure that the pointer remains valid until the message is destroyed.

See Also

TipcMsgAppendXml, TipcMsgFieldSetSize, TipcMsgFieldUpdateXmlPtr

Examples

This example creates a message and appends a pointer to an XML field:

T_IPC_MT mt; 
T_IPC_MSG msg; 
T_XML xml; 
 
#define USER_MT_XML_TEST 100 
mt = TipcMtCreate("xml_test", USER_MT_XML_TEST, "xml"); 
if (mt == NULL) { 
return;  /* error */ 
} 
msg = TipcMsgCreate(mt); 
if (mt == NULL) { 
return;  /* error */ 
} 
xml = TutXmlCreate("<data><data1><temp=\"hot\"/></data1></data>"); 
if (xml == NULL) { 
  return;  /* error */ 
} 
if (!TipcMsgAppendXmlPtr(msg, xml, NULL)) { 
return;  /* error */ 
}