tpf_doc_modifyContent: Change the content value for a node

This function changes the content value for an element node.

Last updated

  • Changed for PUT11.
  • Added for PUT02.

Format

LIBS := CXAP
#include <tpf/c_node.h> 
                           
int tpf_doc_modifyContent (XMLHandle api_handle,
                           char *tagName,
                           char *tagValue)
api_handle
The parser API handle associated with the XML structure that is being processed.
tagName
A pointer to a null-terminated string that contains the tag name of the element or attribute.
tagValue
A pointer to a null-terminated string that contains the new content value. The current value will be changed to this new content value.

Normal return

A value of 0 indicates that the entire element content node value is replaced by the new value.

Error return

A value of -1.

The tpf_doc_modifyContent function also sets the errno C/C++ language variable to indicate the specific error:
EFAULT
The api_handle parameter does not refer to a valid parser API handle.
EINVAL
The specified tag name was not found.

Programming considerations

  • The parser API handle must be a valid handle:
    • Ensure that the handle was initialized by using the tpf_doc_initialize_handle function.
    • The handle must contain an XML structure, which can be accomplished by calling the tpf_doc_createXMLstructure, tpf_doc_initialize_handle, or tpf_doc_parseDocument function.
  • The namespace is not used when matching element tag names.
  • The tpf_doc_modifyContent function traverses, in document order, the XML structure starting from the current position pointer to find a match for the specified element. The traversal continues forward until either a matching element is found or the end of the XML structure is reached.
  • The position pointer in the parser API handle is not changed on return from this function.
  • Applications must ensure that they are positioned before the correct element node when more than one element has the same name.

Examples

The following example changes the specified element node content value in the XML structure. 
#include <tpf/c_node.h>

int retCode;

/* This example assumes that the parser API handle has been             */
/* initialized by a prior call to tpf_doc_initialize_handle          */

/* This API will search the XML structure for the element tag name   */ 
/* and update the content for that element if it is found.           */

retCode = tpf_doc_modifyContent (xml_ptr, "FirstName", "Carol");

if (retCode != 0)
{
⋮   /* error processing */
}
⋮

Example: (part of an XML message)
 <m:Passengers xmlns:m="some-URI">
        <m:PassengerName title="Mrs.">
            <m:FirstName>Carol</m:FirstName>
<!-- on return from api, FirstName will be modified to "Carol" -->
            <m:LastName>Sayers</m:LastName>
        </m:PassengerName>
 </m:Passengers>
<PhoneNumber countryCode="44" areaCode="340" pNumber="6353343" />