expat函数指南

  expat函数指南
发信站: BBS 水木清华站 (Fri Jun  8 09:58:16 2001)

解析器创建
XML_ParserCreate
XML_Parser XML_ParserCreate(const XML_Char*encoding)
建立新解析器。如果编码非零，它指示特性给文件的用途编码。这重载编码文件的声明
。有4种内置的编码：US-ASCII UTF-8 UTF-16 ISO-8859-1。任何别的值都将产调用Unk
nownEncodingHandler处理。
XML_ParserCreateNS
XML_Parser XML_ParserCreateNS(const XML_Char*encoding, XML_Char sep)
建立有名域处理的新解析器。名域展开了元素名字，并且，属性名字象名域URI，sep和
名字的本地部分的连结那样被返回。这表示你应该为不能作为正当的URI的部分的sep挖
特性。
XML_ExternalEntityParserCreate
XML_Parser XML_ExternalEntityParserCreate(XML_Parser p, const XML_Char *cont
ext, const XML_Char *encoding)
建立解析外部通用实体的新XML_Parser对象。上下文是在调用中被交给ExternalEntity
RefHandler的上下文自变量。类似句柄的其他的状态的信息，用户数据，名域处理被继
承象第1个自变量那样传给被的解析器的。所以你应该不给变化的行为的某一个基于而进
行活动的调用需要解析器这（你希望它动作不同于父解析器。）
XML_ParserFree
void XML_ParserFree(XML_Parser p)
释放被解析器使用的内存。你的应用程序有责任释放任何与UserData有关联的内存。
解析
XML_Parse
int XML_Parse(XML_Parser p, const char *s, int len, int isFinal)
解析文件的更多一些部分。串s是在包括部分（或者也许是全部）文件的的缓冲器。
作为文件的部分的s的字节的数字用len表示。这s不必零的方法终止了。它也表示如果l
en比s用手指着的记忆的砌块里的字节的数字大，记忆缺点有可能。isFinal的参数使解
析器得知这是文件的最后的部分。经常，最后的部分是空的（即len是零。）解析发生错
误它会返回0。否则它返回非零值。
XML_ParseBuffer
int XML_ParseBuffer(XML_Parser p, int len, int isFinal)
这正好XML_Parse象在这例子除了expat提供的缓冲器。通过从expat用XML_GetBuffer功
能得到缓冲器，应用程序能避开双重输入复制。
XML_GetBuffer
void *XML_GetBuffer(XML_Parser p, int len)
获得读入文件的断片的大小len的缓冲区。如果expat不能把足够的记忆分配给这缓冲区
，零的值被返回。这必须在所有XML_ParseBuffer调用之前被调用。
句柄设定
句柄典型地在分析之前被设定，被丢下不管，尽管应用程序可以选择设定，或者交换句
柄和解析的事件期间解析在进步中有。例如，你的应用程序可以选择不理全部不是para
元素的子孙的文本。它能做这个的一个方法放para开始签条能见到的特性句柄，它把为
对应的结束签条复原。句柄也许通过提供给适当的句柄安装员的零的指示移置。在设置
函数的句柄的任何一个都没有返回值。你的句柄在接收到串加入类型XML_Char的数组。
这类型在xmlparse.h中被定义，以XML_UNICODE宏指令的两个的设定为条件。如果这些的
哪一个都不设定，XML_Char包括在把UTF-8编码的特性。否则你在以任何一个短或wchar
_t被unsigned了的特性的形式收到UTF-16。注意你将接收到他们加入这文件的最初的编
码的形式独立的这一点。在别处在这文件中，我可以通过仅仅给UTF-8加以引用做这点。

XML_SetElementHandler
XML_SetElementHandler(XML_Parser p,
                      XML_StartElementHandler start,
                      XML_EndElementHandler end);
typedef void
(*XML_StartElementHandler)(void *userData,
                           const XML_Char *name,
                           const XML_Char **atts);
typedef void
(*XML_EndElementHandler)(void *userData,
                         const XML_Char *name);
向句柄上设定准备开始和结束签条。属性象给木炭指示的向量的指示那样被交给开始句
柄。每个在（或者空）开始的签条中能见到的属性都在这向量中占2连续的位置：属性名
字跟在属性值后面。这些一对被零指针终止。
XML_SetCharacterDataHandler
XML_SetCharacterDataHandler(XML_Parser p,
                            XML_CharacterDataHandler charhndl)
typedef void
(*XML_CharacterDataHandler)(void *userData,
                            const XML_Char *s,
                            int len);
设定文本句柄。你的句柄接收到的串不是被终止的零。你必须用长度自变量来处理串的
结束。邻近的不受标注拘束的文本的单一的块可以给这句柄还产生调用的连续。换句话
说，如果你是给文本里的型的搜查，它也许通过调用给这句柄被切割。
XML_SetProcessingInstructionHandler
XML_SetProcessingInstructionHandler(XML_Parser p,
                                    XML_ProcessingInstructionHandler proc)
typedef void
(*XML_ProcessingInstructionHandler)(void *userData,
                                    const XML_Char *target,
                                    const XML_Char *data);
向句柄上设定准备处理指令。目标是处理命令里的第一个词。数据是在最初的词后面跳
过全部空格之后的它里的特性的剩余。
XML_SetCommentHandler
XML_SetCommentHandler (XML_Parser p,
                      XML_CommentHandler cmnt)
typedef void
(*XML_CommentHandler)(void *userData,
                      const XML_Char *data);
设定注释句柄。数据是全部注释定界符内的文本。
XML_SetCdataSectionHandler
XML_SetCdataSectionHandler(XML_Parser p,
                           XML_StartCdataSectionHandler start,
                           XML_EndCdataSectionHandler end)
typedef void
(*XML_StartCdataSectionHandler)(void *userData);
typedef void
(*XML_EndCdataSectionHandler)(void *userData);
设定CDATA一部分的在开始和结束被调用的句柄。
XML_SetDefaultHandler
XML_SetDefaultHandler(XML_Parser p,
                      XML_DefaultHandler hndl)
typedef void
(*XML_DefaultHandler)(void *userData,
                      const XML_Char *s,
                      int len);
为任何将不另外地被处理的文件里的特性设定句柄。这包括句柄不能被设定（一些种类
似的DTD声明）的数据和能被报告，但是当前让没句柄设定的数据。注意注定要向缺省句
柄被汇报的数据的邻近的断片可以在几个调用上面向句柄实际上汇报这一点。把这调用
设定入句柄有关上给内部定义的通用的实体的引用扩展的副作用。反而这些参照被传给
给缺省句柄。
XML_SetDefaultHandlerExpand
XML_SetDefaultHandlerExpand(XML_Parser p,
                            XML_DefaultHandler hndl)
这设定缺省句柄，但是不影响内部的实体引用的扩展。
XML_SetExternalEntityRefHandler
XML_SetExternalEntityRefHandler(XML_Parser p,
                                XML_ExternalEntityRefHandler hndl)
typedef int
(*XML_ExternalEntityRefHandler)(XML_Parser parser,
                                const XML_Char *context,
                                const XML_Char *base,
                                const XML_Char *systemId,
                                const XML_Char *publicId);
设定外部的实体引用句柄。如果参数实体分析在实施中是另外， 有人为了处理外部的D
TD子集调用被给这句柄。（看XML_SetParamEntityParsing）基础参数是对有关的系统标
识符的用途的基础。它XML_SetBase设定，可以是零。公共的id参数是在实体声明中被给
的公共的id，可以是零。系统id是在实体声明中被指定的系统标识符，从不为零。从别
的有两个这句柄不同的方向。第一个，这句柄还整数。非零值应该返回被外部的实体引
用处理成功的。还零表示失败，使调用解析器变得还XML_ERROR_EXTERNAL_ENTITY_HAND
LING错误。第二，不是象其第一个自变量那样有userData而是，它接收到经历实体引用
的解析器。和上下文参数一起这也许象自变量那样给XML_ExternalEntityParserCreate
被使用调用。外部的实体的主体使用还的解析器，能递归性地被解析。有人也许递归性
地调用被给这句柄之后，它应该不在保存信息成为全局或者静态变量。
XML_SetUnknownEncodingHandler
XML_SetUnknownEncodingHandler(XML_Parser p,
                              XML_UnknownEncodingHandler enchandler,
         void *encodingHandlerData)
typedef int
(*XML_UnknownEncodingHandler)(void *encodingHandlerData,
                              const XML_Char *name,
                              XML_Encoding *info);
设定处理其他非内建编码而的句柄。如果句柄知道用给的名字处理编码的方法，它应该
记录在info数据结构，返回1。另外地它应该返回0。
typedef struct {
  int map[256];
  void *data;
  int (*convert)(void *data, const char *s);
  void (*release)(void *data);
} XML_Encoding;
地图数组为所有可能的可能的主要的字节在字节连续中包括信息。如果对应的值是>= 0
，它是单一的字节连续，并且，字节把那个Unicode值编码。如果值是-1，那个字节在顺
序中象最初的字节那样无效。如果值是n是整数> 1的-n n是连续里的字节的数字，并且
，实际的转换给转换指向的函数调用完成了。如果顺序本身无效这函数可以返回-1。如
果有仅仅单一的字节编码转换指针可以是零。被交给改变信仰者函数的数据参数是来自
XML_Encoding的数据指针。串s不是被终止的零，用手指着变的字节的连续。当它用编码
被完成的时候，释放指着的函数解析器调用。它可以是零。
XML_SetNamespaceDeclHandler
XML_SetNamespaceDeclHandler(XML_Parser p,
                            XML_StartNamespaceDeclHandler start,
                            XML_EndNamespaceDeclHandler end)
typedef void
(*XML_StartNamespaceDeclHandler)(void *userData,
                                 const XML_Char *prefix,
                                 const XML_Char *uri);
typedef void
(*XML_EndNamespaceDeclHandler)(void *userData,
const XML_Char *prefix);
向句柄上设定准备名域声明。开始标签发生名域声明。但是，在给每个名域的开始标签
句柄都在那个开始标签中宣布之前有人调用被给名域声明开始句柄。有人在结束标签后
面为名域和有关联的元素调用被给对应的名域结束句柄。
XML_SetUnparsedEntityDeclHandler
XML_SetUnparsedEntityDeclHandler(XML_Parser p,
                                 XML_UnparsedEntityDeclHandler h)
typedef void
(*XML_UnparsedEntityDeclHandler)(void *userData,
                                 const XML_Char *entityName,
                                 const XML_Char *base,
                                 const XML_Char *systemId,
                                 const XML_Char *publicId,
                                 const XML_Char *notationName);
设定接受被unparsed了的实体的声明的句柄。
XML_SetNotationDeclHandler
XML_SetNotationDeclHandler(XML_Parser p,
                           XML_NotationDeclHandler h)
typedef void
(*XML_NotationDeclHandler)(void *userData,
                           const XML_Char *notationName,
                           const XML_Char *base,
                           const XML_Char *systemId,
                           const XML_Char *publicId);
设定接受标志法声明的句柄。
XML_SetNotStandaloneHandler
XML_SetNotStandaloneHandler(XML_Parser p,
                            XML_NotStandaloneHandler h)
typedef int
(*XML_NotStandaloneHandler)(void *userData);
如果文件不是"standalone"设定调用被的句柄。当给参数实体有外部的子集或引用的时
候，这发生，但是，别把standalone在XML声明中设定到"yes"上。如果这句柄返回0，解
析器将抛出XML_ERROR_NOT_STANDALONE错误。
解析位置和错误报告函数
这些是你将让调用希望的函数的时候，解析位置的报告的函数是错误的起作用的外部尽
管函数返回0。被报告的位置是产生事件现在的（或者那个引起的错误解析为了返回0的
函数。）的特性的顺序第一个的那个。
XML_GetErrorCode
enum XML_Error XML_GetErrorCode(XML_Parser p)
返回错误的发生的类型。
XML_ErrorString
const XML_LChar *XML_ErrorString(int code)
返回在描述在对代码合适的错误的串。代码应该是能从XML_GetErrorCode被返回的enum
s的1。
XML_GetCurrentByteIndex
long XML_GetCurrentByteIndex(XML_Parser p)
返回位置的字节偏移。
XML_GetCurrentLineNumber
int XML_GetCurrentLineNumber(XML_Parser p)
返回位置的行号。
XML_GetCurrentColumnNumber
int XML_GetCurrentColumnNumber(XML_Parser p)
返回从位置现在的行的开始的偏移。
杂项函数
这一部分里的函数从解析器得到状态的信息或者为了设定解析器任意选择能灵活地被使
用。
XML_SetUserData
XML_SetUserData(XML_Parser p, void *userData)
这设定被交给句柄的用户数据指针。
XML_GetUserData
void * XML_GetUserData(XML_Parser p)
这返回被交给句柄的用户数据指针。它象宏指令那样实际上被实现。
XML_UseParserAsHandlerArg
void XML_UseParserAsHandlerArg(XML_Parser p)
在这调用被之后，句柄在userData自变量中接受解析器。userData信息能通过使用XML_
GetUserData函数还被得到。
XML_SetBase
int XML_SetBase(XML_Parser p, const XML_Char *base)
设定为了在系统标识符中解决有关的URI被使用的基础如果有为了储存底层的这样的记忆
返回值是0 non-zero。
XML_GetBase
const XML_Char * XML_GetBase(XML_Parser p)
为了返回分析有关的URI底层。
XML_GetSpecifiedAttributeCount
int XML_GetSpecifiedAttributeCount(XML_Parser p)
当属性向开始句柄在atts向量中被汇报的时候，在任何接受他们的来自缺省信息的ATTL
IST声明的价值的属性前面发生用元素清楚地被设定的属性。这函数这样给被设定为由于
缺省第一个属性的偏移，返回清楚地被设定的属性的号。它向最后的调用给开始句柄提
供信息。如果你在开始句柄里，那个意味着现在的调用。
XML_SetEncoding
int XML_SetEncoding(XML_Parser p, const XML_Char *encoding)
设定解析器被使用的编码。
它和把作成函数给解析器交给非零的编码的自变量相等。在XML_Parser或XML_ParseBuf
fer在解析器上调用被之后，它肯定不能被调用。
XML_SetParamEntityParsing
int XML_SetParamEntityParsing(XML_Parser p, enum XML_ParamEntityParsing code
)
如果解析器不用被设定的XML_DTD宏指令被编辑，这正好返回0。另外地它返回1，使包括
作为外部的DTD根据代码子集的外部的参数实体的参数实体的分析成为可能。给代码的选
择是如下：
XML_PARAM_ENTITY_PARSING_NEVER
XML_PARAM_ENTITY_PARSING_UNLESS_STANDALONE
XML_PARAM_ENTITY_PARSING_ALWAYS