XML C Encode Functions

The XML C low-level encode functions handle the XML encoding of simple XML schema data types. Calls to these functions are assembled in the C source code generated by the XBinder compiler to accomplish the encoding of complex structures. These functions are also directly callable from within a user's application program if the need to accomplish a low level encoding function exists.

The procedure to call a low-level encode function is the same as the procedure to call a compiler generated encode function described earlier. It is as follows:

  1. The rtXmlInitContext function must first be called to initialize a context block structure.

  2. Either a stream must be set up or a memory buffer specified to receive the encoded message. To set up a stream, one of the rtxStream functions must be called. To set up a memory buffer, the rtXmlSetEncBufPtr function is used.

  3. The rtXmlEncStartDocument function is called to add the standard XML document header to the buffer.

  4. Encode functions are then invoked to encode the XML data types.

  5. The rtXmlEncEndDocument function is then called to complete the encoding.

If a stream was used, the encoded message will have been written to the output stream. If a memory buffer was used, the result of the encoding will start at the beginning of the buffer, or, if a dynamic buffer was used, can be obtained by calling rtXmlGetEncMsgPtr. The length of the encoded component can be obtained by calling the C standard library strlen function. The encoded stream is a standard UTF-8 null-terminated text string.

For example, the following code fragment could be used to encode a document with a single, boolean value.

        OSOCTET buf[1000];
        OSBOOL boolValue = TRUE; /* true */
        OSCTXT ctxt;
        int msglen, stat;

        rtXmlInitContext (&ctxt);
        rtXmlSetEncBufPtr (&ctxt, buf, sizeof(buf));

        stat = rtXmlEncStartDocument (&ctxt);
        if (stat != 0) {
           rtxErrPrint (&ctxt);
           exit (-1);
        }

        stat = rtXmlEncBool (&ctxt, boolValue, “boolValue”);
        if (stat != 0) {
           rtxErrPrint (&ctxt);
           exit (-1);
        }

        stat = rtXmlEncEndDocument (&ctxt);
        if (stat != 0) {
           rtxErrPrint (&ctxt);
           exit (-1);
        }

        msglen = strlen (buf);

The msglen variable now contains the length (in octets) of the encoded boolean value and the encoded data starts at the beginning of buf.

A complete reference to all of the built-in C XML encode functions is available in the XBinder C/C++ Runtime Reference Manual.