XMLドキュメントを解析してXMLオブジェクトに変換します。

構文

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
);

パラメータ

src_type
[in] ソースデータのタイプを次の値で指定します。
タイプ説明
XML_LOCAL_STRINGローカルコードで記述したXMLドキュメントのバッファ
XML_UTF_STRINGUFT-8またはUTF-16で記述したXMLドキュメントのバッファ
XML_UTF_FILEUTF-8またはUTF-16で記述したXMLドキュメントのファイル
src
[in] ソースデータのタイプにより次の値を設定します。
タイプ設定する値
XML_LOCAL_STRINGXMLドキュメントを格納したバッファを指すポインタ
XML_UTF_STRINGXMLドキュメントを格納したバッファを指すポインタ
XML_UTF_FILEファイル名の文字列を指すポインタ
offset
[in] XMLドキュメントのデータの開始位置をソースデータ上のバイトオフセットで指定します。
length
[in] XMLドキュメントのデータのバイト数を指定します。負の値を指定すると、指定されたソースデータの最後までを解析します。
LocalToUtf8Func
[in] ローカルコードの文字列をUTF-8の文字列に変換するXML_LOCAL_TO_UTF8_STRING型のコールバック関数を指すポインタ。コード変換が不要のときはNULLを指定します。
Utf8ToLocalFunc
[in] UTF-8の文字列をローカルコードの文字列に変換するXML_UTF8_TO_LOCAL_STRING型のコールバック関数を指すポインタ。コード変換が不要のときはNULLを指定します。
ErrCode
[out] エラーコードを返す変数を指すポインタ。エラーコードが不要のときはNULLを指定します。

戻り値

　関数が成功したらXMLハンドル (XML_HANDLE) の値を、それ以外はNULLを返します。

解説

　指定されたバッファまたはファイルに格納されているXMLドキュメントのデータを解析してXMLオブジェクトに変換し、このオブジェクトを参照するためのXMLハンドル (XML_HANDLE) を返します。

　制限事項については次のページを確認してください。

XMLドキュメントを読み込むときの制限事項

　src_typeに、XML_LOCAL_STRING、XML_UTF_STRING、XML_UTF_FILEのいずれかの値を指定して、XMLドキュメントのソースデータのタイプを指定します。

　src_typeにXML_LOCAL_STRINGを指定すると、ローカルコードのXMLドキュメントを読み込むことができます。これは、アプリケーションプログラムで新規のXMLドキュメントを作成するときに便利な方法を提供します。

サンプル
    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);

　src_typeにXML_UTF_STRINGを指定すると、サーバから受信したUTF-8のXMLドキュメントなどを読み込んでXMLオブジェクトに変換することができます。

　src_typeにXML_UTF_FILEを指定すると、ファイルに保存したUTFのXMLドキュメントを読み込んでXMLオブジェクトに変換することができます。

(注意)
  • ローカルコードまたはUTF-16のドキュメントは、解析を開始する前にUTF-8に変換されます。
  • UTF-16のドキュメントでは、UTF-16 LE または UTF-16 BE を表すBOMがXMLデータの先頭に配置されている必要があります。
  • UTF-16のドキュメントでは、UFT-16エンコーディングを指定したXML宣言がドキュメントの先頭に配置されている必要があります。
  • XML_UTF_STRING または XML_UTF_FILE を指定したとき、XML宣言が省略されている場合はUTF-8のドキュメントとして解析します。

　srcに、ソースデータのタイプに合わせて、バッファまたはファイル名の文字列を指すポインタを指定します。

　offsetにバイトオフセットを指定することにより、src_typeとsrcで指定したソースデータ上でのXMLドキュメントのデータの開始位置を指定することができます。0を指定すると、ソースデータの先頭から解析を行います。

　lengthにXMLドキュメントのデータのバイト数を指定します。負の値を指定すると、次の範囲のデータを解析します。

タイプlengthに負の値を指定したときの解析範囲
XML_LOCAL_STRINGoffsetの位置からASCIIのNUL文字 ('\0') まで。
XML_UTF_STRINGUTF-8の場合、offsetの位置からASCIIのNUL文字 ('\0') まで。
UTF-16の場合、offsetの位置からユニコードのnull文字 (L'\0') まで。
XML_UTF_FILEoffsetの位置からファイルの最後まで。

　LocalToUtf8Funcに、ローカルコードの文字列をUTF-8の文字列に変換するコールバック関数を指すポインタを指定します。XMLドキュメントでASCIIコードしか使用しない場合など、コード変換が不要のときはNULLを指定します。

　このコールバック関数には、XML_LOCAL_TO_UTF8_STRING型の関数を指定します。次の関数はこの型と互換性があり、LocalToUtf8Funcパラメータに直接指定できます。

　このコールバック関数は、次の関数を使用したときに呼び出されます。

XML_AddChildNode関数
XML_CreateXmlObject関数 (本関数): src_typeにXML_LOCAL_STRINGを指定したとき
XML_SetAttribute関数
XML_SetChildNodeValueByPath関数
XML_SetNodeValue関数
XML_SetNodeValueByPath関数

　Utf8ToLocalFuncに、UTF-8の文字列をローカルコードの文字列に変換するコールバック関数を指すポインタを指定します。XMLドキュメントでASCIIコードしか使用しない場合など、コード変換が不要のときはNULLを指定します。

　このコールバック関数には、XML_UTF8_TO_LOCAL_STRING型の関数を指定します。次の関数はこの型と互換性があり、Utf8ToLocalFuncパラメータに直接指定できます。

　このコールバック関数は次の関数を使用したときに呼び出されます。

XML_CreateXmlObject関数 (本関数)

　XMLドキュメントの解析が成功し、XMLハンドルを返す場合でも、次の条件を満たす場合はErrCodeにエラーコードが返されるので注意してください。

  • src_typeにXML_UTF_STRINGまたはXML_UTF_FILEを指定した。
  • Utf8ToLocalFuncにコールバック関数を指定した。
  • XMLの解析は成功したが、上記のコールバック関数がローカルコードに変換できないユニコードを検出した。（この場合、ローカルコードに変換できなかった文字は'?'に置き換えられています。）

　この場合、ErrCodeに次のエラーコードを返します。

エラーコード説明
XML_UNSUPPORTED_CODE_WARNINGローカルコードに変換できないユニコードの文字が検出された。

　関数が失敗したときはNULLを返し、ErrCodeには次のエラーコードを返します。

エラーコード説明
XML_INVALID_PARAMETER_ERRORパラメーターエラー
XML_MEMORY_ALLOCATION_ERRORメモリーアロケーションエラー
CONV_INVALID_UTF8_FORMAT_ERRORUTF-8の規格に合致しないバイト列を検出した。
XML_FORMAT_ERRORXMLの解析でフォーマットの異常が検出された。
XML_FILE_ERRORファイルエラー
XML_UNICODE_CONVERSION_ERRORユニコードに変換できないローカルコードの文字が検出された。

　本関数で取得したXMLオブジェクトが不要になったら必ずXML_ReleaseXmlObject関数を呼び出してXMLオブジェクトのリソースを解放してください。

必要条件

ヘッダファイル:
XML.h
CodeConversion.h : ver.1.1.1以降
ライブラリファイル:
libXML.a
libCodeConversion.a : ver.1.1.1以降
libSTARTUPOPH5000.a

サンプル

　UTF-8やUTF-16のXMLドキュメントをSJISに変換するサンプルです。Utf8ToLocalFuncにCONV_Utf8ToSjisString関数を指定しています。

#include "CodeConversion.h"
...

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

　プログラムでXMLオブジェクトの編集を行い、その際にSJISからUTF-8へのコード変換が必要な場合は、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);
...

関連事項

XMLドキュメントをXMLオブジェクトに変換する
XMLドキュメントを読み込むときの制限事項
ノードを操作するサンプルプログラム

最終更新日：2021/10/21

Copyright © 2020 OPTOELECTRONICS CO.,LTD. All rights reserved.