XMLライブラリは、XML形式で記述されたXMLドキュメントを処理するためのライブラリです。
XMLライブラリの概要は次のとおりです。
XMLドキュメントをXMLオブジェクトに変換する
XML_CreateXmlObject関数でXMLドキュメントを解析してXMLオブジェクトに変換し、このオブジェクトを参照するためのXMLハンドルを取得します。
XML_CreateXmlObject関数を実行すると、XMLドキュメントの各エレメントがXML_Node構造体で表されるノードに変換され、XMLオブジェクトにリンクされます。それぞれのノードは、唯一のルートノードを起点として相互にリンクされたひとつのグラフを構成します。
XML_Node構造体で表すノードのリンクには、同じ階層内の次のノード（兄弟ノード）へのリンク、子ノードへのリンクと、親ノードへのリンク（下図には記載なし）の3種類があり、XMLライブラリの各関数はこれらのリンクを用いて処理を実行します。
エレメントに属性がある場合は、属性の名前と値がXML_Attribute構造体に格納され、ノードのXML_Node構造体にリンクされます。複数の属性がある場合、2番目以降の属性は1個前の属性のXML_Attribute構造体からリンクされます。
XMLライブラリのほとんどの関数は、パラメータとしてXMLハンドルを受け取り、このハンドルで参照されるXMLオブジェクトに対して処理を行います。
(例) ノードのグラフ
XMLドキュメント:
<request_message>
<issuer>SALES0001</issuer>
<ship_order>
<date>2021/09/10</date>
<customer>
<customerID>C00001</customerID>
<name>A corporation</name>
</customer>
<orders>
<order>
<productID>PID0000100</productID>
<name>A product</name>
</order>
<order>
<productID>PID0000200</productID>
<name>B product</name>
</order>
</orders>
</ship_order>
</request_message>
ノードのグラフ: 各ノードはXML_Node構造体で表されます。
(例) 属性のグラフ
XMLドキュメント:
<message>
<email msgID='10010' from='a@b.c'>Good!</email>
</message>
属性のグラフ: 各属性はXML_Attribute構造体で表されます。
XMLオブジェクトの内容をダンプする
デバッグのために、XMLオブジェクトの内容をログメッセージにダンプするには次の関数を使用します。
- XML_DumpNode関数
- ノードの内容をログメッセージにダンプします。
- XML_DumpXmlObject関数
- XMLオブジェクト全体の内容をログメッセージにダンプします。
XMLオブジェクトをXMLドキュメントに変換する
XMLオブジェクトの内容をXMLドキュメントに変換して出力するには次の関数を使用します。
- XML_SaveAsXmlFile関数
- 指定のXMLオブジェクトの内容をUTF-8のXMLドキュメントに変換してファイルに保存します。
- XML_SaveAsXmlMemory関数
- 指定のXMLオブジェクトの内容をUTF-8のXMLドキュメントに変換してメモリに出力します。
これらの関数は、UTF-8以外のエンコーディングでの出力はサポートしていません。
XMLオブジェクトを解放する
XMLオブジェクトが不要になったら必ずXML_ReleaseXmlObject関数を呼び出してXMLオブジェクトのリソースを解放します。
ノードパスを使用する
XMLオブジェクトにリンクされた各ノードを簡単に指定するためにノードパスを使用できます。
ノードパスは、上位から下位の階層に向かってノード名を'/'で順番に連結した文字列です。例えば、次のように記述します。
"ship_order/customer/name"
フルパスを指定する
フルパスはノードパスの一種です。ルートノードの直下からのすべての階層を記述したフルパスでノードを指定できます。
例えば、次の例で"ship_order/customer/name"を指定すると、下図の"name"ノードを指定できます。
<request_message> ← ルートノード <issuer>SALES0001</issuer> <ship_order> <date>2021/09/10</date> <customer> <customerID>C00001</customerID> <name>A corporation</name> ← このノードを指定します </customer> </ship_order> </request_message>
次の関数でフルパスを指定できます。
相対パスを指定する
相対パスはノードパスの一種です。親ノードと、そのノードより下の階層だけを記述した相対パスとを指定してノードを指定できます。
例えば、次の例で"ship_order"ノードを親ノードに指定し、相対パスで"customer/customerID"を指定すると、下図の"customerID"ノードを指定できます。
<request_message> <issuer>SALES0001</issuer> <ship_order> ← このノードを親ノードに指定 <date>2021/09/10</date> <customer> <customerID>C00001</customerID> ← 相対パスでこのノードを指定します <name>A corporation</name> </customer> </ship_order> </request_message>
次の関数で相対パスを指定できます。
ワイルドカード（*）を使用する
ノードパスの最後のノードで * を指定すると、その階層の最初のノードと一致させることができます。例えば、次のように記述します。
"*"
"ship_order/*"
"ship_order/customer/*"
次の例で"ship_order/customer/*"を指定すると、"customerID"ノードを取得できます。
<request_message> ← ルートノード <issuer>SALES0001</issuer> <ship_order> <date>2021/09/10</date> <customer> <customerID>C00001</customerID> ← このノードを取得します <name>A corporation</name> </customer> </ship_order> </request_message>
次の関数でワイルドカード (*) を指定できます。
ノードパスの一意性に関する注意
XMLでは、同じ階層の中に同じ名前のエレメント（ノード）を複数配置することができます。しかし、ノードパスを使用してノードを指定するときは、ノードパスで指定したノードが一意に特定できないとエラーが発生し、関数が失敗する場合があるので注意してください。
次の関数では、ノードパスの最後のノード以外の上位の中間ノードがすべて一意に特定できる必要があります。中間ノードが一意に特定できないときは、XML_NOT_UNIQUE_INTERMEDIATE_NODEエラーとなり関数が失敗します。
例えば、次の例では、フルパスで"ship_order/orders/order/name"を指定すると中間ノードの"order"を一意に特定できないため、XML_NOT_UNIQUE_INTERMEDIATE_NODEエラーが発生します。
<request_message> ← ルートノード <issuer>SALES0001</issuer> <ship_order> <orders> <order> ← "order"のノードが一意でない <productID>PID0000100</productID> <name>A product</name> </order> <order> ← "order"のノードが一意でない <productID>PID0000200</productID> <name>B product</name> </order> </orders> </ship_order> </request_message>
このように中間ノードが一意に特定できないデータをノードパスを使用してアクセスするには、まずノードパスの最後のノード以外の上位の中間ノードがすべて一意に特定できるパスでノードを検索します。次に、得られたノードを指定して次のノード（兄弟ノード）や子ノードをアクセスするようにします。
例えば、次の例では、フルパスで"ship_order/orders/order"を指定してXML_FindNodeByPath関数を呼び出すと、一番目の"order"ノードを取得できます。 XML_NextNode関数にこのノードを渡して次のノード（兄弟ノード）を取得したり、このノードを親ノードに指定して相対パスで子ノードをアクセスすることができます。
<request_message> ← ルートノード
<issuer>SALES0001</issuer>
<ship_order>
<date>2021/09/10</date>
<customer>
<customerID>C00001</customerID>
<name>A corporation</name>
</customer>
<orders>
<order> ← 検索結果のノード
<productID>PID0000100</productID> ← 子ノード
<name>A product</name> ← 子ノード
</order>
<order> ← 次のノード（兄弟ノード）
<productID>PID0000200</productID>
<name>B product</name>
</order>
</orders>
</ship_order>
</request_message>
次の関数では、ノードパスの全ての階層のノードが一意に特定できる必要があります。中間ノードが一意に特定できないときは、前記と同様にXML_NOT_UNIQUE_INTERMEDIATE_NODEエラー、最後のノードが一意に特定できないときにはXML_NOT_UNIQUE_NODEエラーとなり、関数が失敗します。
XML_SetNodeValueByPath関数
XML_GetChildNodeValueByPath関数
XML_SetChildNodeValueByPath関数
例えば、次の例では、フルパスで"ship_order/comments/comment"を指定すると最後のノードの"comment"を一意に特定できないため、XML_NOT_UNIQUE_NODEエラーが発生します。
<request_message> ← ルートノード <issuer>SALES0001</issuer> <ship_order> <comments> <comment>Sample</comment> ← "comment"のノードが一意でない <comment>Opticon</comment> ← "comment"のノードが一意でない </comments> <orders> </orders> </ship_order> </request_message>
ルートノードの情報を取得する
ルートノードに関する情報を取得するには次の関数を使用します。- XML_GetRootNode関数
- ルートノードのXML_Node構造体を取得します。
- XML_GetRootNodeName関数
- ルートノードの名前を取得します。
ノードを検索する
ノードパスを指定してノードを検索するには次の関数を使用します。これらの関数では、ノードパスにワイルドカード（*）を指定することもできます。- XML_FindNodeByPath関数
- フルパスを指定してノードを検索します。
- XML_FindChildNodeByPath関数
- 親ノードと相対パスを指定してノードを検索します。
ノードのXML_Node構造体が既知の場合は、次の関数を使用してノードのリンクを直接たどることができます。
- XML_NextNode関数
- 次のノード（兄弟ノード）を取得します。
- XML_ParentNode関数
- 親ノードを取得します。
- XML_FindChildNodeByPath関数
- childNodePathに"*"を指定すると指定のノードの最初の子ノードを取得できます。
ノードの値を取得する
ノードパスで指定したノードの値を取得するには次の関数を使用します。- XML_GetNodeValueByPath関数
- フルパスで指定したノードの値を取得します。
- XML_GetChildNodeValueByPath関数
- 親ノードと相対パスで指定したノードの値を取得します。
- XML_GetNodeValue関数
- 指定のノードの値を取得します。
ノードの値を設定する
ノードパスで指定したノードの値を設定するには次の関数を使用します。- XML_SetNodeValueByPath関数
- フルパスで指定したノードの値を設定します。
- XML_SetChildNodeValueByPath関数
- 親ノードと相対パスで指定したノードの値を設定します。
ノードのXML_Node構造体が既知の場合は、次の関数でノードの値を設定できます。
- XML_SetNodeValue関数
- 指定のノードの値を設定します。
ノードを追加する
ノードを追加するには次の関数を使用します。
- XML_AddChildNode関数
- 指定のノードに子ノードを追加します。
- XML_SetNodeValueByPath関数
- フルパスで指定したノードの値を設定します。ノードパスの最後に指定したノードが存在しなけれが自動的に追加されます。
- XML_SetChildNodeValueByPath関数
- 親ノードと相対パスで指定したノードの値を設定します。ノードパスの最後に指定したノードが存在しなけれが自動的に追加されます。
ノードを削除する
ノードを削除するには次の関数を使用します。- XML_DeleteNode関数
- 指定のノードを削除します。指定のノードが子ノードを持っている場合、それらも同時に削除することができます。
ノードの属性を取得する
ノードの属性のXML_Attribute構造体を取得するには次の関数を使用します。- XML_FindAttribute関数
- 名前を指定してノードの属性を検索します。
- XML_GetAttribute関数
- ノードにリンクされた最初の属性のXML_Attribute構造体を取得します。
- XML_NextAttribute関数
- 指定の属性に次の属性がリンクされていればその属性のXML_Attribute構造体を取得します。
属性の名前と値は、XML_Attribute構造体のnameメンバとvalueメンバから取得します。
ノードの属性を設定する
ノードに属性を設定するには次の関数を使用します。- XML_SetAttribute関数
- 指定のノードに属性を設定します。
ノードの属性を削除する
ノードに属性を削除するには次の関数を使用します。- XML_DeleteAttributes関数
- 指定のノードの属性を削除します。
最終更新日：2021/10/20