イベント構造には、19 個の ENTRY 変数があります。これらの変数は、さまざまなイベントでパーサーが呼び出す関数をポイントしています。
このトピックの各イベントの説明は、次の XML ドキュメントの例を参照しています。
xmlDocument =
'<?xml version="1.0" standalone="yes"?>'
|| '<!--This document is just an example-->'
|| '<sandwich>'
|| '<bread type="baker"s best"/>'
|| '<?spread please use real mayonnaise ?>'
|| '<meat>Ham & turkey</meat>'
|| '<filling>Cheese, lettuce, tomato, etc.</filling>'
|| 'We should add a <relish> element in future!'
|| '</sandwich>'
|| 'junk';
説明の中の XML テキストという用語は、イベントに渡されるポインターおよび長さに基づいて構成された文字列です。この構造体での出現順に、パーサーは次のイベントを認識することができます。
- start_of_document
- ドキュメントの構文解析が開始されるときに、1 回発生します。パーサーは、このイベントにはパラメーターを渡しません (ユーザー トークンを除く)。
- version_information
- オプションの XML 宣言内のバージョン情報に対して発生します。パーサーは、バージョン値 (上記の例では "1.0") が入ったテキストのアドレスと長さを渡します。
- encoding_declaration
- XML 宣言内のオプションのエンコーディング宣言に対して発生します。パーサーは、エンコーディング値が含まれたテキストのアドレスと長さを渡します。
- standalone_declaration
- XML 宣言内のオプションのスタンドアロン宣言に対して発生します。パーサーは、スタンドアロン値 (上記の例では "yes") が入ったテキストのアドレスと長さを渡します。
- document_type_declaration
- パーサーがドキュメント タイプ宣言を検出したときに発生します。ドキュメント タイプ宣言は、文字シーケンス <!DOCTYPE" から始まり、> 文字で終わります。この間には、内容を記述するやや複雑な文法規則が入ります。
パーサーは、宣言全体が含まれたテキストのアドレスと長さを渡します。これには、開始と終了の文字シーケンスが含まれます。このイベントは、XML テキストに区切り文字が含まれる唯一のイベントです。上記の例には、ドキュメント タイプ宣言はありません。
- end_of_document
- ドキュメントの構文解析が完了したときに 1 回発生します。パーサーは、このイベントにはパラメーターを渡しません (ユーザー トークンを除く)。
- start_of_element
- エレメント開始タグまたは空エレメント タグごとに 1 回発生します。パーサーは、エレメント名および該当するネームスペース情報を含んでいるテキストのアドレスと長さを渡します。上記の例では、構文解析で最初に発生する start_of_element イベントに、文字列 sandwich が含まれています。
- attribute_name
- エレメント開始タグまたは空エレメント タグ内の属性ごとに、有効な名前を認識した後に発生します。パーサーは、属性名および該当するネームスペース情報を含んでいるテキストのアドレスと長さを渡します。上記の例に含まれる属性名は、type だけです。
- attribute_characters
-
属性値のフラグメントごとに発生します。パーサーは、フラグメントが含まれたテキストのアドレスと長さを渡します。属性値は通常、次のように複数の行に分割されている場合でも、ただ 1 つの文字列で構成されます。
<element attribute="This attribute value is
split across two lines"/>
- end_of_element
- エレメント終了タグまたは空エレメント タグごとに、パーサーがタグの終了不等号かっこを認識したときに 1 回発生します。パーサーは、エレメント名および該当するネームスペース情報を含んでいるテキストのアドレスと長さを渡します。
- start_of_CDATA_section
- CDATA セクションの開始時に発生します。CDATA セクションは文字列 <![CDATA[ で始まり、文字列 ]] で終わります。これは、XML マークアップとして認識される文字を含むテキストのブロックをエスケープするために使用します。パーサーは、このイベントにはパラメーターを渡しません (ユーザー トークンを除く)。
このイベントの後で、パーサーはこれらの区切り文字間にある CDATA セクションの内容を、1 つまたは複数の content-characters イベントとして渡します。上記の例では、content-characters イベントとしてWe should add a <relish> element in future! が渡されます。
- end_of_CDATA_section
- パーサーが CDATA セクションの終了を認識したときに発生します。パーサーは、このイベントにはパラメーターを渡しません (ユーザー トークンを除く)。
- content_characters
-
このイベントは、XML ドキュメントの本体を表します。これは、エレメント開始タグとエレメント終了タグの間にある文字データです。パーサーは、このデータが含まれたテキストのアドレスと長さを渡します。これは、次のように複数の行に分割されている場合でも、ただ 1 つの文字列で構成されます。
<element1>This character content is
split across two lines"</element1>
パーサーは、次のイベントによって内容の一部を構成する他の文字が提供されるかどうかを示す、フラグ バイトも渡します。開始と終了のタグ間に多くのデータがあるときが、これに該当します。
また、パーサーは content_characters イベントを使用して CDATA セクションのテキストをアプリケーションに渡します。
- processing_instruction
- 処理命令 (Processing Instruction; PI) を使用すると、XML ドキュメントにアプリケーション用の特別な命令を含めることができます。このイベントは、パーサーが PI 開始文字シーケンス <? に続く名前を認識したときに発生します。また、このイベントは、PI ターゲットに続く PI 終了文字シーケンス ?> までのデータ (?> 自体は含まない) も対象とします。データの末尾にある空白文字は含まれますが、先頭にある空白文字は含まれません。パーサーは、ターゲットが含まれるテキスト (上記の例では spread) のアドレスと長さ、およびデータが入ったテキスト (上記の例では please use real mayonnaise) のアドレスと長さを渡します。
- comment
- XML ドキュメント内のコメントに対して発生します。パーサーは、開始および終了コメント区切り文字 (それぞれ <!-- と -->) の間にあるテキストのアドレスと長さを渡します。上記の例では、This document is just an example だけがコメントのテキストです。
- namespace_declare
- XML ドキュメントのすべてのネームスペース宣言に発生します。パーサーは、ネームスペース プレフィックス (ある場合) のアドレスと長さ、およびネームスペース URI のアドレスと長さを渡します。ネームスペース プレフィックスがない場合、渡される長さはゼロでアドレスの値は使用されません。PLIXSAXA と PLISAXB ビルトインには、対応するイベントはありません。
- end_of_input
- このイベントは、パーサーが現在の入力バッファーの終わりに達すると発生します。パーサーは、(BYVALUE ユーザー トークンとともに) 2 つの BYADDR パラメーター、つまり次のバッファーのアドレスと長さを渡し、処理されるようにします。BYADDR パラメーターを持つイベントは、このイベントとコンテンツ文字イベントに限られますが、このイベントは呼び出されたイベントによって変更されるパラメーターを持つ唯一のイベントです。PLIXSAXA と PLISAXB ビルトインには対応するイベントはなく、このイベントが PLISAXC による任意サイズの XML ドキュメントの解析を許可するイベントです。
- unresolved_reference
- このイベントは、XML ドキュメントですべての未解決リファレンスに発生します。パーサーは、未解決リファレンスのアドレスと長さを渡します。
- unknown_attribute_reference
- 属性値の中で、定義済みエンティティ参照 (イベント attribute_predefined_reference の説明で示したもの) 以外のエンティティ参照に対して発生します。パーサーは、エンティティ名が含まれたテキストのアドレスと長さを渡します。
- exception
- XML ドキュメントの処理中にエラーを検出すると、パーサーはこのイベントを生成します。