reference - Expat翻訳 Wiki - Expat翻訳

上: Expat翻訳 トップ

前: Expatを使用する

Expatのリファレンス

パーサの生成関数

XML_Parser XMLCALL
XML_ParserCreate(const XML_Char *encoding);

新しいパーサを生成します。encodingがnullではない場合、 XMLドキュメントに対して使用する文字コードを指定して下さい。 これは、XMLドキュメントのエンコーディング宣言を上書きします。 組込みのエンコーディングには以下の4つがあります。

・US-ASCII
・UTF-8
・UTF-16
・ISO-8859-1

他の値の場合、UnknownEncodingHandlerの呼び出しが引き起こされます。

XML_Parser XMLCALL
XML_ParserCreateNS(const XML_Char *encoding,
XML_Char sep);

有効な名前空間の処理を持つ新しいパーサを生成します。 名前空間は要素名と属性名を拡張し、名前空間URI、sep、名前のローカル部分 を連結したものが返されます。 これは、sepに対する文字にはURIの一部にはできないものを選択する必要があることを意味します。 Expatは適合性に対する名前空間URIのチェックを行わないため、 名前空間の区切り文字に対しての安全な選択は、XMLでの違法な文字だけです。 例えば、'\xFF'はUTF-8では違法な文字であり、'\xFFFF'は UTF-16では違法な文字です。 sepが'\0'文字（null文字）の場合、名前空間URIとローカル部分は 区切り文字なしで連結されます。これはRDFプロセッサをサポートすることを意図しています。 名前空間トリプレットを使用する場合、nullの区切り文字 を使用することはプログラミングエラーです。

XML_Parser XMLCALL
XML_ParserCreate_MM(const XML_Char *encoding,
const XML_Memory_Handling_Suite *ms,
const XML_Char *sep);

 typedef struct {
   void *(XMLCALL *malloc_fcn)(size_t size);
   void *(XMLCALL *realloc_fcn)(void *ptr, size_t size);
   void (XMLCALL *free_fcn)(void *ptr);
 } XML_Memory_Handling_Suite;

msで指定されたメモリハンドリング関数の組を使用して新しいパーサを生成します。 msがNULLの場合、標準のメモリ管理関数のセットが使用されます。 sepがNULLではない場合、名前空間処理がパーサ生成時に有効となり、 sepによって指定された文字が名前空間URIと名前のローカル部分の区切り文字として使用されます。

XML_Parser XMLCALL
XML_ExternalEntityParserCreate(XML_Parser p,
const XML_Char *context,
const XML_Char *encoding);

一般的な外部エンティティを解析するための新しいXML_Parserオブジェクト を生成します。コンテキストはExternalEntityRefHandlerを呼ぶときのcontext引数です。 例えばハンドラ関数、ユーザデータ、名前空間処理のような他の状態の情報は 第一引数としてパーサから継承されます。 そのため、（親パーサよりも異なる動作をさせたい場合を除き） いかようなこのパーサの動作変更関数を呼ぶ必要はありません。

void XMLCALL
XML_ParserFree(XML_Parser p);

パーサによって使用されているメモリを解放します。 アプリケーションは、ユーザデータで確保しているすべてのメモリを解放する責任があります。

XML_Bool XMLCALL
XML_ParserReset(XML_Parser p,
const XML_Char *encoding);

パーサが再度使用できるよう、パーサで管理していたメモリ構造をクリーンアップします。 これの呼び出し後、parserは新しいXMLドキュメントを解析し始める準備ができています。 すべてのハンドラ関数はunknownEncodingHandlerを除き、パーサからクリアされます。 パーサの外部状態は名前空間と名前空間トリプレットの値を除いて再初期化されます。 この関数はXML_ExternalEntityParserCreateを使用して生成されたパーサに対して使用することはできません。 その場合はXML_FALSEを返します。 成功時はXML_TRUEを返します。 アプリケーションはユーザデータで確保したすべてのメモリを取り扱う責任があります。

解析関数

明白なことについての言及：XML_Parse、XML_ParseBuffer、XML_GetBufferの3つの解析関数は（ハンドラ関数を呼ばなかった） 異なるパーサインスタンス上で動作する限りハンドラ関数内から呼び出してはなりません。 例えば、XML_ExternalEntityParserCreateによって生成されたパーサに適用する場合、 XML_ExternalEntityRefHandler内から解析関数を呼ぶことはOKです。

注：これらの関数で渡されるlen引数は、 追加されたバッファの長さと、前のバッファの未処理部分が整数値の最大を超えた場合に 数値のオーバフローの条件が生成できるようにする必要があるため、 整数値の最大値よりかなり小さい必要があります。 末尾がそのバッファの一部ではないXMLトークンの一部の場合、バッファの末尾に入力したデータは 未処理のままとなります。

enum XML_Status XMLCALL
XML_Parse(XML_Parser p,
const char *s,
int len,
int isFinal);

 enum XML_Status {
   XML_STATUS_ERROR = 0,
   XML_STATUS_OK = 1
 };

XMLドキュメントをさらに解析します。文字列sはXMLドキュメントの一部（あるいは全部） を含むバッファです。XMLドキュメントの一部であるsのバイト数はlenで示されます。 これはsはnull終端である必要はないことを意味します。 また、lenがsで指すメモリブロックのバイト数より大きい場合、 メモリフォルト（fault：障害）があることを意味します。 isFinalパラメータはこれがXMLドキュメントの最後の部分であることをパーサに通知します。 しばしば、最後の部分は空になります（つまり、lenが0）。 解析エラーが発生した場合、XML_STATUS_ERRORを返します。 それ以外の場合はXML_STATUS_OK値を返します。

enum XML_Status XMLCALL
XML_ParseBuffer(XML_Parser p,
int len,
int isFinal);

これは、Expatがバッファを提供することを除きXML_Parse に似ています。XML_GetBuffer関数にてExpatからバッファを取得し、 アプリケーションは入力の２重コピーを避けることができます。

void * XMLCALL
XML_GetBuffer(XML_Parser p,
int len);

XMLドキュメントの一部を読み込むためにサイズlenのバッファを取得します。 Expatがこのバッファのために十分なメモリを確保できなかった場合、NULL値が返されます。 これはXML_ParseBufferの呼出し毎に 呼ぶ必要があります。 典型的な使用法は次のようになります：

 for (;;) {
   int bytes_read;
   void *buff = XML_GetBuffer(p, BUFF_SIZE);
   if (buff == NULL) {
     /* handle error */
   }
 
   bytes_read = read(docfd, buff, BUFF_SIZE);
   if (bytes_read < 0) {
     /* handle error */
   }
 
   if (! XML_ParseBuffer(p, bytes_read, bytes_read == 0)) {
     /* handle parse error */
   }
 
   if (bytes_read == 0)
     break;
 }

enum XML_Status XMLCALL
XML_StopParser(XML_Parser p,
XML_Bool resumable);

解析を停止し、XML_Parseあるいは、XML_ParseBufferが返るようにします。 既にサスペンド状態にあるパーサを中止（resumableがXML_FALSE）する場合を除き、 コールバックハンドラ内から呼び出さなければなりません。 いくつかのコールバック関数はそうでなければ失われるため、まだ続く可能性があります。 以下を含みます。

・開始要素ハンドラ関数にて停止した場合、空要素に対しての終了要素ハンドラ関数、
・終了要素ハンドラ関数にて停止した場合、終了名前空間定義ハンドラ関数、
・文字の連続した塊で複数のコールバック関数が呼ばれている間に文字データハンドラ関数内で停止された場合、文字データハンドラ関数、

恐らく、その他も。

外部パラメータエンティティの解析中かつresumableはXML_TRUEの場合を除き、 これは多くのハンドラ関数から呼び出すことができ、コールバックに関連するDTDを含めることができます。 成功した場合はXML_STATUS_OKを返します。 そうでない場合はXML_STATUS_ERRORを返します。 可能性のあるエラーコードは：

・XML_ERROR_SUSPENDED
既にサスペンドされているパーサをサスペンドしようとしたとき。
・XML_ERROR_FINISHED
パーサがすでに終了しているとき。
・XML_ERROR_SUSPEND_PE
外部パラメータエンティティの解析中にサスペンドしようとしたとき。

停止/再開機能は外部の解析ループでのアプリケーションのサポートを必要とするため 適切に処理されていないパーサに対してこの関数を呼ぶとエラーになります。 より詳細については解析の一時停止を見てください。

resumableがXML_TRUEの場合、解析はサスペンドされ、 すなわち、XML_ParseとXML_ParseBufferはXML_STATUS_SUSPENDEDを返します。 そうでない場合、解析は中断（aborted）され、 XML_ParseとXML_ParseBufferはエラーコードXML_ERROR_ABORTEDで、XML_STATUS_ERRORを返します。

注： 親パーサが存在し、外部エンティティ参照ハンドラ関数を返すときにそれが解析を続行するなら、 これは現在のパーサインスタンスのみに対して適用されます。 いずれかの解析を停止させたい場合、（再帰的に）親パーサでのXML_StopParserを呼ぶことはハンドラ関数の実装に任されています。

サスペンドさせた場合、XML_ResumeParserを呼ぶことで解析を再開できます。

Expatの1.95.8の新機能。

enum XML_Status XMLCALL
XML_ResumeParser(XML_Parser p);

XML_StopParserにてサスペンドされた解析を再開します。 コールバック関数の中から呼び出してはなりません。 XML_Parseあるいは、XML_ParseBufferと同じステータスコードを返します。 パーサが現在サスペンドされていない場合、追加のエラーコードXML_ERROR_NOT_SUSPENDEDが返されます。

注： これは最初に最も深くネストされた子パーサインスタンスに対して呼び出す必要があります。 そして、子パーサが終了した後でのみ親パーサ上で、 XMLドキュメントエンティティパーサが戻るまで再帰的に適用される必要があります。 つまり、親パーサはそれ自体では再開せず、適切な時点でXML_ResumeParserを呼ぶことが アプリケーションに任されています。

Expatの1.95.8の新機能。

void XMLCALL
XML_GetParsingStatus(XML_Parser p,
XML_ParsingStatus *status);

 enum XML_Parsing {
   XML_INITIALIZED,
   XML_PARSING,
   XML_FINISHED,
   XML_SUSPENDED
 };
 
 typedef struct {
   enum XML_Parsing parsing;
   XML_Bool finalBuffer;
 } XML_ParsingStatus;

初期化、解析中、終了、サスペンドあるいは最後のバッファが処理されているかどうかについて パーサの状態を返します。 statusパラメータはNULLであってはなりません。

Expatの1.95.8の新機能。

ハンドラ関数設定関数

ハンドラ関数は一般的には解析をする前に設定され、そのままにされますが、 アプリケーションは解析中に解析イベントに対するハンドラ関数を設定あるいは変更することができます。 例えば、アプリケーションはpara要素から派生していないすべてのテキストを無視することもできます。 これを行うことができる方法の１つはpara開始タグが見つかった時に 文字ハンドラ関数を設定し、対応する終了タグのときにハンドラ関数を設定解除することです。

ハンドラ関数は適切なハンドラ関数の設定関数へNULLポインタを渡すことで解除できます。 ハンドラ関数の設定関数は戻り値はありません。

ハンドラ関数はXML_Char型の配列で文字列を受け取ります。 この型は条件に応じてchar、wchar_tあるいはunsigned short のいずれかでexpat.hにて定義されています。 前者はUTF-8エンコーディングを意味し、後者の2つはUTF-16エンコーディングを意味します。 XMLドキュメントの元のエンコーディングに依存しないこの形式で受け取ることに注意してください。

void XMLCALL
XML_SetStartElementHandler(XML_Parser p,
XML_StartElementHandler start);

 typedef void
 (XMLCALL *XML_StartElementHandler)(void *userData,
                                    const XML_Char *name,
                                    const XML_Char **atts);

開始（と空）タグに対するハンドラ関数を設定します。 属性はcharのポインタの配列へのポインタとして開始ハンドラ関数に渡されます。 開始（もしくは空）タグで見られる各タグは、この配列内の2つの連続した場所を占めます（属性名、属性値が続く）。 これらのペアはNULLポインタで終端されています。

空のタグは開始、終了のハンドラ関数の両方の呼び出しを（この順で）発生させることに注意してください。

void XMLCALL
XML_SetEndElementHandler(XML_Parser p,
XML_EndElementHandler);

 typedef void
 (XMLCALL *XML_EndElementHandler)(void *userData,
                                  const XML_Char *name);

終了（と空）タグに対するハンドラ関数を設定します。 上で述べたように、空タグは開始と終了のハンドラ関数の呼び出しを発生させます。

void XMLCALL
XML_SetElementHandler(XML_Parser p,
XML_StartElementHandler start,
XML_EndElementHandler end);

1回の呼び出しで開始と終了のタグに対するハンドラ関数を設定します。

void XMLCALL
XML_SetCharacterDataHandler(XML_Parser p,
XML_CharacterDataHandler charhndl)

 typedef void
 (XMLCALL *XML_CharacterDataHandler)(void *userData,
                                     const XML_Char *s,
                                     int len);

テキストハンドラ関数を設定します。 ハンドラ関数が受けた文字列はNULL終端されていません。 文字の最後に対処するためにはlen引数を使います。 マークアップフリーの連続した単一のブロックはまだ、このハンドラ関数の 呼び出しシーケンスで発生する可能性があります。 つまり、テキスト内のパターンを探している場合、このハンドラ関数の呼び出しに またがって分割される可能性があります。 注意：もし、パーサがブロックの終わりに達するまでコールバックをし続けるように、 パーサが連続するマークアップフリーのテキストの単一ブロックを現在行っている場合、 NULLをこのハンドラに設定してもコールバックがすぐに終了しない可能性があります。

void XMLCALL
XML_SetProcessingInstructionHandler(XML_Parser p,
XML_ProcessingInstructionHandler proc)

 typedef void
 (XMLCALL *XML_ProcessingInstructionHandler)(void *userData,
                                             const XML_Char *target,
                                             const XML_Char *data);

処理命令に対するハンドラ関数を設定します。 targetは処理命令の中の最初の単語です。 dataは最初の単語の後のすべての空白文字をスキップした後の文字の残りです。

void XMLCALL
XML_SetCommentHandler(XML_Parser p,
XML_CommentHandler cmnt)

 typedef void
 (XMLCALL *XML_CommentHandler)(void *userData,
                               const XML_Char *data);

コメントに対するハンドラ関数を設定します。 dataはコメントの区切りの中のすべてのテキストです。

void XMLCALL
XML_SetStartCdataSectionHandler(XML_Parser p,
XML_StartCdataSectionHandler start);

 typedef void
 (XMLCALL *XML_StartCdataSectionHandler)(void *userData);

CDATAセクションの開始時に呼び出されるハンドラ関数を設定します。

void XMLCALL
XML_SetEndCdataSectionHandler(XML_Parser p,
XML_EndCdataSectionHandler end);

 typedef void
 (XMLCALL *XML_EndCdataSectionHandler)(void *userData);

CDATAセクションの終了時に呼び出されるハンドラ関数を設定します。

void XMLCALL
XML_SetCdataSectionHandler(XML_Parser p,
XML_StartCdataSectionHandler start,
XML_EndCdataSectionHandler end)

1回の呼び出しで両方のCDATAセクションのハンドラ関数を設定します。

void XMLCALL
XML_SetDefaultHandler(XML_Parser p,
XML_DefaultHandler hndl)

 typedef void
 (XMLCALL *XML_DefaultHandler)(void *userData,
                               const XML_Char *s,
                               int len);

XMLドキュメント内の他でハンドルされないであろうすべての文字に対する ハンドル関数を設定します。 これは、ハンドラが設定できない（ある種のDTD宣言のような）データと、 報告可能だが、現在、ハンドラが設定されていないデータの両方を含みます。 文字はそれらがUTF-8かUTF-16でエンコードされていることを除き、 XMLドキュメント内に存在していた通りに正確に渡されます。 行の境界は正規化されません。BOM文字はデフォルトハンドラに渡されないことに注意してください。 文字がデフォルトハンドラへの呼び出しの間でどのように分割されるかについての保障はありません。 例えば、コメントが複数の呼び出し間で分割される可能性があります。 この呼び出しでハンドラ関数を設定することは、内部的に定義された一般エンティティ への参照の拡張をオフにする副作用があります。 代わりにこれらの参照は、デフォルトのハンドラ関数へ渡されます。

XML_DefaultCurrentも参照してください。

void XMLCALL
XML_SetDefaultHandlerExpand(XML_Parser p,
XML_DefaultHandler hndl)

 typedef void
 (XMLCALL *XML_DefaultHandler)(void *userData,
                               const XML_Char *s,
                               int len);

これはデフォルトのハンドラ関数を設定しますが、内部エンティティ参照の展開を阻害しません。 エンティティはデフォルトのハンドラ関数に渡されることはありません。

XML_DefaultCurrentも参照してください。

void XMLCALL
XML_SetExternalEntityRefHandler(XML_Parser p,
XML_ExternalEntityRefHandler hndl)

 typedef int
 (XMLCALL *XML_ExternalEntityRefHandler)(XML_Parser p,
                                         const XML_Char *context,
                                         const XML_Char *base,
                                         const XML_Char *systemId,
                                         const XML_Char *publicId);

外部エンティティ参照のハンドラ関数を設定します。 パラメータエンティティの解析が有効である場合、 このハンドラ関数は、外部のDTDサブセットを処理するために呼び出されます。（XML_SetParamEntityParsingを参照してください。）

context引数はXML_ExternalEntityParserCreateへのcontext引数によって 期待されるフォーマットで解析コンテキストを指定します。 参照されるエンティティが後で解析される場合、それがコピーされる必要があるため、 codeはハンドラ関数が戻るまで有効です。 エンティティがパラメータエンティティの場合のみ、 contextはNULLです。それは、一般エンティティ、パラメータエンティティの両方を区別する方法です。

base引数は相対的なシステム識別子を使用するための元となります。 それはXML_SetBaseにより設定され、NULLの場合もあります。 publicId引数はエンティティ宣言で指定されたパブリックIDであり、NULLの場合もあります。 systemIdはエンティティ宣言で指定されたシステム識別子であり、NULLの場合もあります。

このハンドラは他と異るしきたりが2つあります。 まず、ハンドラ関数は状態標識（整数）を返します。 XML_STATUS_OKは外部エンティティ参照のハンドリングを正常にするために返すべきです。 XML_STATUS_ERRORを返すことは失敗を示し、 XML_ERROR_EXTERNAL_ENTITY_HANDLINGエラーを返すためにパーサの呼び出しを引き起こします。

次に、その第一引数としてユーザデータを持つ代わりに エンティティ参照に遭遇したパーサを受け取ります。 これはcontext引数と一緒にXML_ExternalEntityParserCreateへの呼び出しの引数として使用することができます。 返されたパーサを使用して、外部エンティティの本体が再帰的に解析されます。

このハンドラ関数が再帰的に呼ばれる可能性があるため、グローバル変数やstatic変数に情報を保存するべきではありません。

void XMLCALL
XML_SetExternalEntityRefHandlerArg(XML_Parser p,
void *arg)

ExternalEntityRefHandlerに渡す引数を設定します。 argがNULLではない場合、それはXML_SetExternalEntityRefHandlerを使用して設定されるハンドラ関数に渡される新しい値です。 argがNULLの場合、ハンドラ関数へ渡される引数は自分自身のパーサオブジェクトとなるでしょう。

注意： argの型とExternalEntityRefHandlerの第一引数の型は一致しません。 この関数はハンドラ関数がXML_Parserを受ける入れるハンドラ関数 へ渡されるためにvoid *を取ります。 これは歴史的な偶然ですが、このAPIを使用して動作することが知られているコード に対して、コンパイラの警告の原因を避けるために（早ければ）Expat 2.0より前に修正されることはありません。 ハンドラ関数へ渡される引数の実際の型を知ること、それを適切に管理することはアプリケーションコードの責任です。

void XMLCALL
XML_SetSkippedEntityHandler(XML_Parser p,
XML_SkippedEntityHandler handler)

 typedef void
 (XMLCALL *XML_SkippedEntityHandler)(void *userData,
                                     const XML_Char *entityName,
                                     int is_parameter_entity);

スキップされたエンティティのハンドラ関数を設定します。これは2つの状況で呼び出されます。

1. エンティティ参照が、宣言が読まれていない、かつ、エラーでないに遭遇する。
2. 内部エンティティ参照は読まれたが、展開されていない。なぜなら、XML_SetDefaultHandlerが呼び出されたため。

is_parameter_entity引数は、パラメータエンティティに対しては0ではなく、一般エンティティに対しては0です。

注意： 宣言でのスキップされたパラメータエンティティと 属性値でのスキップされた一般エンティティは報告されません。 なぜなら、イベントは宣言あるいは属性値の報告と同期しなくなるためです。

void XMLCALL
XML_SetUnknownEncodingHandler(XML_Parser p,
XML_UnknownEncodingHandler enchandler,
void *encodingHandlerData)

 typedef int
 (XMLCALL *XML_UnknownEncodingHandler)(void *encodingHandlerData,
                                       const XML_Char *name,
                                       XML_Encoding *info);
 
 typedef struct {
   int map[256];
   void *data;
   int (XMLCALL *convert)(void *data, const char *s);
   void (XMLCALL *release)(void *data);
 } XML_Encoding;

組込みのエンコード以外の他のエンコードで処理するためのハンドラ関数を設定します。 これは、与えられたパーサで呼び出されたXML_Parseあるいは XML_ParseBufferを呼ぶ前にされるべきです。

もし、ハンドラ関数が与えられた名前でエンコードの扱い方を知っている場合、 infoデータ構造体で埋め、XML_STATUS_OKを返します。 そうでなければXML_STATUS_ERRORを返します。 ハンドラ関数は1回の解析された（外部の）エンティティで大抵1回呼ばれます。 オプションのアプリケーションデータポインタ encodingHandlerDataは、 ハンドラ関数に渡されます。

map配列はバイトシーケンス内のすべての考えられる先頭バイトに対する情報を含みます。 もし、対応する値が0以上の場合、それは単一バイトシーケンスであり、 バイトはUnicode値をエンコードします。 もし、値が-1の場合、バイトはシーケンスで最初のバイトとして無効です。 もし、値が-nの場合、ここでnは1より大きい整数とする、nはシーケンスのバイト数であり、 実際の変換はconvertによって指し示された関数への呼び出しによって達成されます。 シーケンス自身が無効な場合、この関数は-1を返す可能性があります。 単一バイトコードの場合、convertポインタはnullの可能性があります。 convert関数に渡される、data引数はXML_Encodingからのdataポインタです。 文字列sはnull終端ではなく、また、変換されるバイトのシーケンスを指しています。

エンコーディングが終了するとき、 releaseで指し示される関数がパーサによって呼び出されます。 それはNULLでもかまいません。

void XMLCALL
XML_SetStartNamespaceDeclHandler(XML_Parser p,
XML_StartNamespaceDeclHandler start);

 typedef void
 (XMLCALL *XML_StartNamespaceDeclHandler)(void *userData,
                                          const XML_Char *prefix,
                                          const XML_Char *uri);

名前空間が宣言されたときに呼び出されるハンドラ関数を設定します。 名前空間の宣言は開始タグの内部で発生します。 しかし、名前空間の宣言の開始ハンドラ関数は、 その開始タグ内で宣言された各名前空間に対する開始タグハンドラ関数の前に 呼び出されます。

void XMLCALL
XML_SetEndNamespaceDeclHandler(XML_Parser p,
XML_EndNamespaceDeclHandler end);

 typedef void
 (XMLCALL *XML_EndNamespaceDeclHandler)(void *userData,
                                        const XML_Char *prefix);

名前空間の宣言のスコープが終了するときに呼び出されるハンドラ関数を設定します。 これは、各名前空間の宣言に対して、名前空間が宣言されていた要素の終了タグに対するハンドラ関数 の後で呼び出されます。

void XMLCALL
XML_SetNamespaceDeclHandler(XML_Parser p,
XML_StartNamespaceDeclHandler start,
XML_EndNamespaceDeclHandler end)

1回の呼び出しで、両方の名前空間宣言のハンドラ関数を設定します。

void XMLCALL
XML_SetXmlDeclHandler(XML_Parser p,
XML_XmlDeclHandler xmldecl);

 typedef void
 (XMLCALL *XML_XmlDeclHandler)(void            *userData,
                               const XML_Char  *version,
                               const XML_Char  *encoding,
                               int             standalone);

XML宣言と、外部エンティティで発見されたテキスト宣言に対して呼び出される ハンドラ関数を設定します。 区別する方法は、version引数がテキスト宣言に対してはNULLになります。 encoding引数はXML宣言に対してはNULLになります。 standalone引数は宣言内で、それぞれ、standaloneパラメータが存在しない noが与えられている、yesが与えられているを意味する -1,0,1が入ります。

void XMLCALL
XML_SetStartDoctypeDeclHandler(XML_Parser p,
XML_StartDoctypeDeclHandler start);

 typedef void
 (XMLCALL *XML_StartDoctypeDeclHandler)(void           *userData,
                                        const XML_Char *doctypeName,
                                        const XML_Char *sysid,
                                        const XML_Char *pubid,
                                        int            has_internal_subset);

任意の外部あるいは内部サブセットが解析される前に、DOCTYPE宣言の開始時に 呼び出されるハンドラ関数を設定します。 sysidとpubidの両方はNULLになる場合があります。 has_internal_subsetは、DOCTYPE宣言が内部サブセットを持つ場合、0ではない値です。

void XMLCALL
XML_SetEndDoctypeDeclHandler(XML_Parser p,
XML_EndDoctypeDeclHandler end);

 typedef void
 (XMLCALL *XML_EndDoctypeDeclHandler)(void *userData);

任意の外部サブセットを解析した後、DOCTYPE宣言の終了時に呼び出されるハンドラ関数を設定します。

void XMLCALL
XML_SetDoctypeDeclHandler(XML_Parser p,
XML_StartDoctypeDeclHandler start,
XML_EndDoctypeDeclHandler end);

1回の呼び出しで両方のdoctypeハンドラ関数を設定します。

void XMLCALL
XML_SetElementDeclHandler(XML_Parser p,
XML_ElementDeclHandler eldecl);

 typedef void
 (XMLCALL *XML_ElementDeclHandler)(void *userData,
                                   const XML_Char *name,
                                   XML_Content *model);
 enum XML_Content_Type {
   XML_CTYPE_EMPTY = 1,
   XML_CTYPE_ANY,
   XML_CTYPE_MIXED,
   XML_CTYPE_NAME,
   XML_CTYPE_CHOICE,
   XML_CTYPE_SEQ
 };
 
 enum XML_Content_Quant {
   XML_CQUANT_NONE,
   XML_CQUANT_OPT,
   XML_CQUANT_REP,
   XML_CQUANT_PLUS
 };
 
 typedef struct XML_cp XML_Content;
 
 struct XML_cp {
   enum XML_Content_Type         type;
   enum XML_Content_Quant        quant;
   const XML_Char *              name;
   unsigned int                  numchildren;
   XML_Content *                 children;
 };

DTD内の要素の宣言に対するハンドラ関数を設定します。ハンドラ関数は 宣言内の要素名と、要素モデルを含む構造体へのポインタとともに呼び出されます。 XML_FreeContentModelを使用してこのデータ構造体を解放することは アプリケーションの責任です。

model引数はXML_Contentノードのツリーのルートです。 typeがXML_CTYPE_EMPTYかXML_CTYPE_ANYに等しい場合、 quantはXML_CQUANT_NONEでしょう。そして、他のフィールドは 0かNULLとなります。 typeがXML_CTYPE_MIXEDの場合、quantは XML_CQUANT_NONEかXML_CQUANT_REPであり、 numchildrenは 混ぜられても良い要素と すべてが定量しないtype、XML_CTYPE_NAMEを持つXML_Content構造体の配列を 指し示すchildrenの個数を含むでしょう。 ルートノードのみはtype、XML_CTYPE_EMPTY、XML_CTYPE_ANY、 あるいはXML_CTYPE_MIXEDとなり得ます。

type、XML_CTYPE_NAMEに対して、 nameフィールドはnameを指し、numchildrenとchildren フィールドは0とNULLになるでしょう。 quantフィールドはnameに置かれた量指定子を示します。

type、XML_CTYPE_CHOICEとXML_CTYPE_SEQは それぞれ、選択、またはシーケンスを示しています。 numchildrenフィールドは選択、あるいはシーケンスでいくつのノードが あるのかを指し、childrenはノードを指し示しています。

void XMLCALL
XML_SetAttlistDeclHandler(XML_Parser p,
XML_AttlistDeclHandler attdecl);

 typedef void
 (XMLCALL *XML_AttlistDeclHandler)(void           *userData,
                                   const XML_Char *elname,
                                   const XML_Char *attname,
                                   const XML_Char *att_type,
                                   const XML_Char *dflt,
                                   int            isrequired);

DTD内の属性リスト(attlist)宣言に対するハンドラ関数を設定します。 このハンドラ関数はそれぞれの属性に対して呼び出されます。 従って、宣言された複数の属性を持つ単一の属性リストはこのハンドラ関数の呼び出しを 複数回生成するでしょう。 elname引数は属性が宣言されている要素名を返します。 属性名はattname引数にあります。 属性の種類はatt_type引数にあります。 それは、空白を除いた宣言型を表す文字列です。

dflt引数はデフォルト値を保持します。 それは"#IMPLIED"あるいは"#REQUIRED"属性の場合にはNULLになります。 isrequired引数をチェックすることによりこれら2つのケースを区別できます。 "#REQUIRED"属性の場合はtrueです。 "#FIXED"である属性はtrueのisrequiredを持ち、しかし、 dflt引数内のNULLでない固定値を持ちます。

void XMLCALL
XML_SetEntityDeclHandler(XML_Parser p,
XML_EntityDeclHandler handler);

 typedef void
 (XMLCALL *XML_EntityDeclHandler)(void           *userData,
                                  const XML_Char *entityName,
                                  int            is_parameter_entity,
                                  const XML_Char *value,
                                  int            value_length, 
                                  const XML_Char *base,
                                  const XML_Char *systemId,
                                  const XML_Char *publicId,
                                  const XML_Char *notationName);

すべてのエンティティ宣言を処理するために呼び出されるハンドラ関数を設定します。 is_parameter_entity引数はパラメータエンティティの場合は0ではない値になり、 それ以外の場合には0になります。

内部エンティティ（<!ENTITY foo "bar">）の場合、 valueはNULLにはならず、systemId、publicId とnotationNameはNULLになります。 value文字列はNULL終端ではありません：長さは value_length引数にて提供されます。 内部エンティティをテストするためにvalue_lengthを使用しないで下さい。 なぜなら、長さが0の値を持つことが合法であるためです。 代わりに、valueがNULLかどうかでチェックしてください。

notationName引数は解析対象ではないエンティティ宣言に対して NULLではない値を持ちます。

void XMLCALL
XML_SetUnparsedEntityDeclHandler(XML_Parser p,
XML_UnparsedEntityDeclHandler h)

 typedef void
 (XMLCALL *XML_UnparsedEntityDeclHandler)(void *userData,
                                          const XML_Char *entityName, 
                                          const XML_Char *base,
                                          const XML_Char *systemId,
                                          const XML_Char *publicId,
                                          const XML_Char *notationName);

解析対象でないエンティティ宣言を受け取るハンドラ関数を設定します。 これらは、記法(NDATA)フィールドを持つエンティティ宣言です：

<!ENTITY logo SYSTEM "images/logo.gif" NDATA gif>

このハンドラ関数は廃止され、後方互換性のために提供されています。 代わりに、XML_SetEntityDeclHandlerを使用してください。

void XMLCALL
XML_SetNotationDeclHandler(XML_Parser p,
XML_NotationDeclHandler h)

 typedef void
 (XMLCALL *XML_NotationDeclHandler)(void *userData, 
                                    const XML_Char *notationName,
                                    const XML_Char *base,
                                    const XML_Char *systemId,
                                    const XML_Char *publicId);

記法宣言を受け取るハンドラ関数を設定します。

void XMLCALL
XML_SetNotStandaloneHandler(XML_Parser p,
XML_NotStandaloneHandler h)

 typedef int 
 (XMLCALL *XML_NotStandaloneHandler)(void *userData);

XMLドキュメントが"standalone"ではないときに呼び出されるハンドラ関数を設定します。 これは、外部サブセットあるいは、パラメータエンティティへの参照があり、 しかし、XML宣言内でのstandaloneが"yes"に設定されていないときに起きます。 このハンドラ関数がXML_STATUS_ERRORを返す場合、 パーサはXML_ERROR_NOT_STANDALONEエラーをスローします。

解析位置とエラー報告関数

これらは、解析関数がXML_STATUS_ERROR（解析エラーが発生）を返す場合に 呼び出したい関数です。位置の報告関数はエラーの外側で便利です。 報告された位置は、現在のイベント（あるいは解析関数がXML_STATUS_ERRORを 返す原因になったエラー）が生成された文字シーケンスの最初のバイト位置（元のXMLドキュメント あるいはエンティティのエンコーディング）です。 例外は、XMLドキュメントのプロローグ内の宣言によって引き起こされたコールバック関数です。 この場合、それらは報告された位置は適切なマークアップ内のどこかにあると期待します。 しかし、必ずしも他のイベントと同じ意味があるわけではありません。

位置の報告関数はDTDの外でのみ正確です。 すなわち、DTD宣言のハンドラ関数内から呼び出されたとき、それらは通常偽りの情報を返します。

enum XML_Error XMLCALL
XML_GetErrorCode(XML_Parser p);

発生したエラーの種類を返します。

const XML_LChar * XMLCALL
XML_ErrorString(enum XML_Error code);

codeに対応するエラーを説明する文字列を返します。 codeはXML_GetErrorCodeから 返されうる列挙値の１つである必要があります。

XML_Index XMLCALL
XML_GetCurrentByteIndex(XML_Parser p);

位置のバイトオフセットを返します。 これは、常に、XML_GetCurrentLineNumber と XML_GetCurrentColumnNumberによって返された値に対応します。

XML_Size XMLCALL
XML_GetCurrentLineNumber(XML_Parser p);

位置の行番号を返します。最初の行は1として返されます。

XML_Size XMLCALL
XML_GetCurrentColumnNumber(XML_Parser p);

位置の、現在の行の先頭からのオフセットを返します。

int XMLCALL
XML_GetCurrentByteCount(XML_Parser p);

現在のイベントのバイト数を返します。 イベントが内部エンティティへの参照の内側と 空要素タグ（後で、別々の開始タグと終了タグを使用して空要素から空要素タグを区別するために使用されうる） に対する終了タグイベントの場合は0を返します。

const char * XMLCALL
XML_GetInputContext(XML_Parser p,
int *offset,
int *size);

パーサの入力バッファを返します。 現在の位置のこのバッファ内のオフセットがoffsetによって指し示された数値に設定されます。 そして、返されたバッファのサイズがsizeによって指し示された数値に設定されます。

これのみはアクティブな解析の中でハンドラ関数から呼び出されるべきであり、 返されたバッファのみは呼び出しを行ったハンドラ関数の中から参照するべきです。 この入力バッファは入力の翻訳バイトが含まれます。

呼び出しのきっかけとなるイベントが非常に大きな入力量にまたがる場合、 コンテキストの量は宣言されたままとなるため、実際の解析位置はバッファの開始前になる可能性があります。

XML_CONTEXT_BYTESが定義されていない場合、これは常にNULLを返します。

その他の関数

このセクション内の関数はパーサからの状態情報を取得するか、 パーサのオプションを動的に設定するために使用されるかのいずれかです。

void XMLCALL
XML_SetUserData(XML_Parser p,
void *userData);

これはハンドラ関数に渡されるユーザデータのポインタを設定します。 このポインタ以前の値は全て上書きされます。 解析終了時、アプリケーションはuserDataで関連付けられたメモリを 解放する責任があることに注意してください。 これを読んだときに、すでにポインタがある場合、それに関連付けられたメモリを解放しなかった場合、 メモリリークが発生します。

void * XMLCALL
XML_GetUserData(XML_Parser p);

これはハンドラ関数に渡されるユーザデータのポインタを返します。 実際にはマクロとして実装されています。

void XMLCALL
XML_UseParserAsHandlerArg(XML_Parser p);

これが呼び出された後、ハンドラ関数はuserData引数で パーサを受け取ります。ユーザデータはまだXML_GetUserData関数を使用して取得することができます。

enum XML_Status XMLCALL
XML_SetBase(XML_Parser p,
const XML_Char *base);

システム識別子内の相対URIを解決するために使用されるベースを設定します。 ペースを格納するメモリがない場合は戻り値はXML_STATUS_ERRORとなり、 それ以外の場合はXML_STATUS_OKとなります。

const XML_Char * XMLCALL
XML_GetBase(XML_Parser p);

相対URIを解決するためのベースを返します。

int XMLCALL
XML_GetSpecifiedAttributeCount(XML_Parser p);

属性がatts配列内にある開始ハンドラ関数に報告されている場合、 明示的に要素内で設定された属性は、属性がATTLIST宣言内のデフォルトの情報から それらの値を受け取る前に発生します。 この関数は、このように、デフォルトのために設定された最初の属性の開始タグハンドラ関数へ 渡されるatts配列内のオフセットを与えて、2倍に設定された属性の数を返します。 開始ハンドラ関数の最後の呼び出しのための情報を提供します。 開始ハンドラ関数の中で呼び出された場合、今の呼び出しを意味します。

int XMLCALL
XML_GetIdAttributeIndex(XML_Parser p);

XML_StartElementHandlerの最後の呼び出しで atts配列内に渡されるID属性のインデックスを返します。 ID属性がない場合は-1を返します。 開始ハンドラ内で呼び出された場合、現在の呼び出しを意味します。

const XML_AttrInfo * XMLCALL
XML_GetAttributeInfo(XML_Parser parser);

 typedef struct {
   XML_Index  nameStart;  /* Offset to beginning of the attribute name. */
   XML_Index  nameEnd;    /* Offset after the attribute name's last byte. */
   XML_Index  valueStart; /* Offset to beginning of the attribute value. */
   XML_Index  valueEnd;   /* Offset after the attribute value's last byte. */
 } XML_AttrInfo;

デフォルトでの指定よりもむしろ、開始タグで指定されたXML_StartElementHandler の最後の呼び出しで渡された属性/値のペアに対するXML_AttrInfo構造体の配列を返します。 それぞれの属性/値のペアは1つとしてカウントします。 従って、配列の要素数はXML_GetSpecifiedAttributeCount(parser) / 2です。

enum XML_Status XMLCALL
XML_SetEncoding(XML_Parser p,
const XML_Char *encoding);

パーサによって使用されるエンコーディングを設定します。 これは、パーサの生成関数にnullではないencoding引数を渡すことと等価です。 XML_Parse あるいは XML_ParseBufferが与えられたパーサ上で呼び出された後に呼び出されてはいけません。 成功の場合はXML_STATUS_OKを、エラーの場合はXML_STATUS_ERRORを返します。

int XMLCALL
XML_SetParamEntityParsing(XML_Parser p,
enum XML_ParamEntityParsing code);

これは、codeに従って、外部DTDサブセットである外部パラメータエンティティを含む、 パラメータエンティティの解析を有効にします。 コードの選択肢は次のとおりです。

・XML_PARAM_ENTITY_PARSING_NEVER
・XML_PARAM_ENTITY_PARSING_UNLESS_STANDALONE
・XML_PARAM_ENTITY_PARSING_ALWAYS

注意： XML_SetParamEntityParsingがXML_Parse あるいは XML_ParseBufferの後で呼び出された場合、 効果は無く、また、常に0を返します。

int XMLCALL
XML_SetHashSalt(XML_Parser p,
unsigned long hash_salt);

内部ハッシュ計算に使用するハッシュソルト（hash salt）を設定します。 ハッシュ関数の挙動の予測に基づいたDoS攻撃を防ぐのに役立ちます。 効果的を持つためには、これは解析が開始される前に呼び出される必要があります。 成功時は1を返します、XML_ParseあるいはXML_ParseBufferの 後で呼び出された場合は0を返します。

注意： 解析開始時、値が設定されていない場合、パーサが新しいランダムなソルト値 を自動で生成するため、この呼び出しは、省略可能です。

enum XML_Error XMLCALL
XML_UseForeignDTD(XML_Parser parser, XML_Bool useDTD);

この関数は、 それ自身が外部サブセットを指定していないXMLドキュメントに対する 文書型宣言（DTD）に対する外部サブセットを提供することをアプリケーションが許可します。 それらのDOCTYPE宣言内の外部サブセットを指定するドキュメントに対しては、 アプリケーションが提供するサブセットは無視されます。 ドキュメントが少しもDOCTYPE宣言を含まず、useDTDはtrueの場合、 アプリケーションが提供するサブセットは解析されます しかし、startDoctypeDeclHandler と endDoctypeDeclHandler関数が設定された場合は 呼び出されません。 パラメータエンティティの解析の設定は、 XML_SetParamEntityParsing を使用することでコントロールされ、受け取られます。

アプリケーションが提供する外部サブセットは publicIdとsystemIdの両方がNULLに設定された XML_SetExternalEntityRefHandler を解して設定される外部エンティティ参照ハンドラ関数の呼び出しによって読み込まれます。

この関数が解析が開始された後で呼び出された場合、 XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSINGを返し、 useDTDは無視されます。 ExpatがDTDサポートなしでコンパイルされた場合で呼び出された場合は、 XML_ERROR_FEATURE_REQUIRES_XML_DTDを返します。 それ以外の場合はXML_ERROR_NONEを返します。

注意： WFCをチェックする目的のために： useDTD == XML_TRUEを渡されて宣言されたエンティティは ドキュメントがまるで外部サブセットと一緒にDTDを持っているかのように パーサを動作させます。 外部エンティティ参照ハンドラ関数が動作なしで返る場合でもこれは当てはまります。

void XMLCALL
XML_SetReturnNSTriplet(XML_Parser parser,
int do_nst);

XML_ParserCreateNSにて生成されたパーサを使用している場合、すなわち、 名前空間の処理が有効となっている場合に、この関数は有効です。 do_nstはプレフィックスが名前空間プレフィックスで 修飾された名前で返されるかどうかを設定します。 もし、do_nstが0以外の値でこの関数が呼び出された場合、 その後、名前空間QName（デフォルトの名前空間に所属しているのとは対照的にプレフィックスで修飾されている）は パーサが生成されたときに指定された名前空間の区切り文字によって 区切られた3つの部分のトリプレットとして返されます。

もし、do_nstが0の場合、名前空間はデフォルトの方法 （名前空間の区切り文字で区切られたURI、ローカル名） で報告されます。

void XMLCALL
XML_DefaultCurrent(XML_Parser parser);

これは開始タグ、終了タグ、命令または文字データの処理に対するハンドラ関数内で呼び出すことができます。 対応するマークアップが XML_SetDefaultHandler もしくは XML_SetDefaultHandlerExpandによって設定されたデフォルトのハンドラ関数へ渡されるようになります。 デフォルトのハンドラ関数がない場合は何もしません。

XML_LChar * XMLCALL
XML_ExpatVersion();

文字列（例えば "expat_1.95.1"）としてライブラリのバージョンを返します。

struct XML_Expat_Version XMLCALL
XML_ExpatVersionInfo();

 typedef struct {
   int major;
   int minor;
   int micro;
 } XML_Expat_Version;

構造体としてライブラリのバージョンを返します。 ライブラリのバージョンをコンパイル時に確認するできるよういくつかのマクロも定義されています。

・XML_MAJOR_VERSION
・XML_MINOR_VERSION
・XML_MICRO_VERSION

Expat APIの特定の部分が利用可能かを判断するのに、 これらの定数を確認することは最良の方法です。

const XML_Feature * XMLCALL
XML_GetFeatureList();

 enum XML_FeatureEnum {
   XML_FEATURE_END = 0,
   XML_FEATURE_UNICODE,
   XML_FEATURE_UNICODE_WCHAR_T,
   XML_FEATURE_DTD,
   XML_FEATURE_CONTEXT_BYTES,
   XML_FEATURE_MIN_SIZE,
   XML_FEATURE_SIZEOF_XML_CHAR,
   XML_FEATURE_SIZEOF_XML_LCHAR,
   XML_FEATURE_NS,
   XML_FEATURE_LARGE_SIZE
 };
 
 typedef struct {
   enum XML_FeatureEnum  feature;
   XML_LChar            *name;
   long int              value;
 } XML_Feature;

Expatのコンパイル時に設定された方法の詳細を提供し、 "機能(feature)"レコードのリストを返します。 ほとんどのアプリケーションでは、このことを心配する必要はありませんが、 この情報は、特にExpatからは利用できません。 この関数は、実行時にこれを行うために、これらの機能を確認する必要がないコードを許可します。

戻り値は、最後がfeatureがXML_FEATURE_ENDで、かつ、 nameがNULLであるレコードであるXML_Feature の配列で、Expatのコンパイル時の機能確認（feature-test）マクロを確認しています。 ともかく、それらが存在している場合、 この種類の情報を必要とするアプリケーションがnameが指し示す 文字の型を決定する必要があるため、 XML_FEATURE_SIZEOF_XML_CHARと XML_FEATURE_SIZEOF_XML_LCHARに対するレコードは XML_FEATURE_UNICODEと XML_FEATURE_UNICODE_WCHAR_Tによって に続いてリストの先頭に配置されます。

一部の機能は、関連付けられた値を持っています。 関連付けられた値がない場合は、valueフィールドは0に設定されます。 この時点では、次の機能が値を持つように定義されています。

・XML_FEATURE_SIZEOF_XML_CHAR

1つのXML_Char文字が占めるバイト数。

・XML_FEATURE_SIZEOF_XML_LCHAR

1つのXML_LChar文字が占めるバイト数。

・XML_FEATURE_CONTEXT_BYTES

XML_GetInputContextによって報告されうるコンテキストの文字の最大数。

void XMLCALL
XML_FreeContentModel(XML_Parser parser, XML_Content *model);

XML_ElementDeclHandlerを使用して 設定されたXML_ElementDeclHandlerコールバック関数へ渡されたmodel 引数を解放する（deallocate）機能を果たします。 この関数は他の目的のために使用すべきではありません。

以下の関数は外部コードがXML_Parserが使用するために設計されている メモリアロケータを共有することを許します。 これはアプリケーションコード、または何重にも階層化されたアプリケーションによって 生成されたパーサオブジェクトと対話する サードパーティ製のライブラリにとって特に便利です。 異なるC標準ライブラリ（少なくともWindows上で発生する可能性があります） を使用するDLLを使用する場合に不可欠です。

void * XMLCALL
XML_MemMalloc(XML_Parser parser, size_t size);

parserオブジェクトが使用するために設計されたアロケータを使用して sizeバイトのメモリを確保します。 メモリへのポインタ、あるいはNULL(失敗時)を返します。 この方法で確保されたメモリはXML_MemFreeを使用して解放されなくてはなりません。

void * XMLCALL
XML_MemRealloc(XML_Parser parser, void *ptr, size_t size);

parserオブジェクトが使用するために設計されたアロケータを使用して sizeバイトのメモリを確保します。 ptrはXML_MemMallocあるいはXML_MemRealloc によって確保されたメモリブロックのポインタかNULLでなくてはなりません。 この関数は、可能な場合、ptrによって指し示されたブロックを拡張することを試みます。 メモリへのポインタ、あるいはNULL(失敗時)を返します。 成功時、元のブロックは拡張されるか解放されます。 失敗時は元のブロックは解放されません。 呼び出し元は元のブロックを解放する責任があります。 この方法で確保されたメモリはXML_MemFreeを使用して解放されなくてはなりません。

void XMLCALL
XML_MemFree(XML_Parser parser, void *ptr);

ptrによって指し示されているメモリのブロックを解放します。 ブロックはXML_MemMallocあるいはXML_MemReallocによって 確保されたもの、あるいはNULLである必要があります。

※このページは、Expat2.1.0内のdoc\reference.html内のExpat Referenceを元に作成しました。

上: Expat翻訳 トップ

前: Expatを使用する