Parses an XML document and transforms it into an XML object.

Syntax

XML_HANDLE XML_CreateXmlObject(
  int src_type,
  const char *src,
  int offset,
  int length,
  XML_LOCAL_TO_UTF8_STRING LocalToUtf8Func,
  XML_UTF8_TO_LOCAL_STRING Utf8ToLocalFunc,
  int *ErrCode
);

Parameters

src_type

[in] Specify the type of source data with the following values.

Type	Description
XML_LOCAL_STRING	XML document buffer written in local code.
XML_UTF_STRING	XML document buffer written in UFT-8 or UTF-16.
XML_UTF_FILE	XML document file written in UTF-8 or UTF-16.

src

[in] Set the following values depending on the type of source data.

Type	Value to set
XML_LOCAL_STRING	A pointer to the buffer that contains the XML document.
XML_UTF_STRING	A pointer to the buffer that contains the XML document.
XML_UTF_FILE	A pointer to a file name string.

offset

[in] Specifies the starting position of the XML document as a byte offset on the source data.

length

[in] Specifies the length of the XML document in bytes. If you specify a negative value, it parses up to the end of the specified source data.

LocalToUtf8Func

[in] A pointer to a callback function of XML_LOCAL_TO_UTF8_STRING type that converts a local code string to a UTF-8 string. Specify NULL when no code conversion is required.

Utf8ToLocalFunc

[in] A pointer to a callback function of XML_UTF8_TO_LOCAL_STRING type that converts a UTF-8 string to a local code string. Specify NULL when no code conversion is required.

ErrCode

[out] A pointer to a variable that returns an error code. Specify NULL when no error code is required.

Return value

Returns an XML handle (XML_HANDLE) if the function succeeds, NULL otherwise.

Remarks

Parses the XML document stored in the specified buffer or file, transforms it into an XML object, and returns an XML handle (XML_HANDLE) to reference this object.

Please check the page below for limitations.

Limitations when parsing XML documents

Specify the type of XML document source data by specifying one of the XML_LOCAL_STRING, XML_UTF_STRING, or XML_UTF_FILE values in the src_type.

You can load an XML document in local code by specifying XML_LOCAL_STRING for the src_type. This provides a convenient way to create new XML documents in your application program.

Sample

    char *xmlDefault =
        "<appConfig>"
        "  <addr>192.168.1.1</addr>"
        "</appConfig>";

    XML_HANDLE hXml;

    hXml = XML_CreateXmlObject(XML_LOCAL_STRING, xmlDefault, 0, -1, NULL, NULL, NULL);

If you specify XML_UTF_STRING for src_type, you can load the UTF-8 XML document received from the server and convert it to an XML object.

You can specify XML_UTF_FILE for src_type to read a UTF XML document saved in a file and convert it to an XML object.

Note:

Local code or UTF-16 documents are converted to UTF-8 before starting parsing.
UTF-16 documents require a BOM representing UTF-16 LE or UTF-16 BE at the beginning of the XML document.
For UTF-16 documents, the XML declaration with the encoding specified as UFT-16 must be placed at the beginning of the document.
When XML_UTF_STRING or XML_UTF_FILE is specified, if the XML declaration is omitted, it is parsed as a UTF-8 document.

In src, specify a pointer to a buffer or filename string, depending on the type of source data.

You can specify the starting position of the XML document data on the source data by specifying a byte offset for offset. If 0 is specified, the source data will be parsed from the beginning.

Specify the number of bytes of XML document data in length. Negative values parse the following range of data:

Type	Range to be parsed when a negative value is specified
XML_LOCAL_STRING	From the offset position to the ASCII NUL character ('\0').
XML_UTF_STRING	For UTF-8, from the offset position to the ASCII NUL character ('\0'). For UTF-16, from the offset position to the Unicode null character (L'\0').
XML_UTF_FILE	From the offset position to the end of the file.

In LocalToUtf8Func, specify a pointer to the callback function that converts the local code string to a UTF-8 string. Specify NULL when no code conversion is required, such as when the XML document uses only ASCII code.

For this callback function, specify a function of XML_LOCAL_TO_UTF8_STRING type. The following functions are compatible with this type and can be specified directly on the LocalToUtf8Func parameter.

CONV_CP437oseToUtf8String
CONV_SjisToUtf8String

This callback function is called when you use the following function:

XML_AddChildNode
XML_CreateXmlObject: When XML_LOCAL_STRING is specified for src_type.
XML_SetAttribute
XML_SetChildNodeValueByPath
XML_SetNodeValue
XML_SetNodeValueByPath

In Utf8ToLocalFunc, specify a pointer to the callback function that converts the UTF string to a local code string. Specify NULL when no code conversion is required, such as when the XML document uses only ASCII code.

For this callback function, specify a function of XML_UTF8_TO_LOCAL_STRING type. The following functions are compatible with this type and can be specified directly on the Utf8ToLocalFunc parameter.

CONV_Utf8ToCP437oseString
CONV_Utf8ToSjisString

This callback function is called when you use the following function:

XML_CreateXmlObject

Note that even if the XML document is parsed successfully and returns an XML handle, an error code will be returned in ErrCode if the following conditions are met:

XML_UTF_STRING or XML_UTF_FILE was specified for src_type.
A callback function was specified in Utf8ToLocalFunc.
The XML parsing was successful, but the above callback function detected Unicode that could not be converted to local code. (In this case, the characters that could not be converted to local code are replaced with'?'.)

In this case, it returns the following error code in ErrCode.

Error code	Description
XML_UNSUPPORTED_CODE_WARNING	Unicode characters that cannot be converted to local code have been detected.

If the function fails, it returns NULL and ErrCode returns the following error code:

Error code	Description
XML_INVALID_PARAMETER_ERROR	Parameter error
XML_MEMORY_ALLOCATION_ERROR	Memory allocation error
CONV_INVALID_UTF8_FORMAT_ERROR	A byte string that does not meet the UTF-8 standard was detected.
XML_FORMAT_ERROR	A format error was detected during XML parsing.
XML_FILE_ERROR	File error.
XML_UNICODE_CONVERSION_ERROR	Local code characters that cannot be converted to Unicode have been detected.

When you no longer need the XML object acquired by this function, be sure to call XML_ReleaseXmlObject function to release the XML object resources.

Requirements

Header file:

XML.h
CodeConversion.h : ver. 1.1.1 or later.

Library file:

libXML.a
libCodeConversion.a : ver.1.1.1 or later
libSTARTUPOPH5000.a

Sample

　This is a sample to convert UTF-8 or UTF-16 XML document to SJIS. The CONV_Utf8ToSjisString function is specified in Utf8ToLocalFunc.

#include "CodeConversion.h"
...

    XML_HANDLE hXml;
    int ErrCode;
    char *utfBuffer;
...
    hXml = XML_CreateXmlObject(XML_UTF_STRING, utfBuffer, 0, -1,
        NULL, CONV_Utf8ToSjisString, &ErrCode);
...

If you edit the XML object programmatically and need to convert the code from SJIS to UTF-8 at that time, you also need to set LocalToUtf8Func.

#include "CodeConversion.h"
...

    XML_HANDLE hXml;
    int ErrCode;
    char *utfBuffer;
...
    hXml = XML_CreateXmlObject(XML_UTF_STRING, utfBuffer, 0, -1,
        CONV_SjisToUtf8String, CONV_Utf8ToSjisString, &ErrCode);
...

OPH-5000i SDK Manual

Syntax

Parameters

Return value

Remarks

Requirements

Sample

See also