| Previous | Contents |
This section documents the portable XML parser API. This API is
intended to be completely compatible with the eXpat library.
4.1 Entry Points
For the portable API both upper-case (OpenVMS native) and mixed-case (UNIX style) entry points are provided in the run-time library. Therefore the linker will be able to correctly locate names that have been compiled with either the default /NAMES=(UPPERCASE,TRUNCATED) or the UNIX style /NAMES=AS_IS for ported applications.
void XMLCALL XML_DefaultCurrent (XML_Parser parser);
parser
Previously allocated XML parser instance.
This can be called within a handler for a start element, end element, processing instruction or character data. It causes the corresponding markup to be passed to the default handler set by XML_SetDefaultHandler or XML_SetDefaultHandlerExpand. It does nothing if there is not a default handler.
const XML _Char * XMLCALL XML_GetBase (XML_Parser parser);
parser
Previously allocated XML parser instance.
Return the base for resolving relative URIs.
x URI base string.
void * XMLCALL XML_GetBuffer (XML_Parser parser, int len);
parser
Previously allocated XML parser instance.len
Size of buffer, in bytes.
Obtain a buffer of size len to read a piece of the document into. This has to be called prior to every call to XML_ParseBuffer. A typical use would look similar to the following example:
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; }
NULL The parser cannot allocate enough virtual memory. x A virtual memory region of size len.
int XMLCALL XML_GetIdAttributeIndex (XML_Parser parser);
parser
Previously allocated XML parser instance.
Returns the index of the ID attribute passed in the atts array in the last call to the start element handler.
x Index of the ID attribute. -1 No ID attribute present.
int XMLCALL XML_GetSpecifiedAttributeCount (XML_Parser parser);
parser
Previously allocated XML parser instance.
When attributes are reported to the start handler in the atts vector, attributes that were explicitly set in the element occur before any attributes that receive their value from default information in an ATTLIST declaration. This function returns the number of attributes that were explicitly set times two, thus giving the offset in the atts array passed to the start tag handler of the first attribute set due to defaults. It supplies information for the last call to a start handler. If called inside a start handler, then that means the current call.
x Total number of specified attributes also the index to the first default attribute.
void *XMLCALL XML_GetUserData (XML_Parser parser);
parser
Previously allocated XML parser instance.
This function returns the user data pointer that is passed to XML parser event handlers. It is actually implemented as a macro.
x The address of the user data pointer.
void XMLCALL XML_MemFree (XML_Parser parser, void *ptr);
parser
Previously allocated XML parser instance.ptr
Pointer to block to be freed. If the pointer is NULL, no action occurs.
Free a block of memory pointed to by ptr. The block must have been allocated by XML_MemMalloc or XML_MemRealloc, or be NULL.
void * XMLCALL XML_MemMalloc (XML_Parser parser, size_t size);
parser
Previously allocated XML parser instance.size
Total number of bytes to allocate.
Allocate size bytes of memory using the allocator the parser object has been configured to use. Returns a pointer to the memory or NULL on failure.
Memory allocated in this way must be freed using XML_MemFree.
x The address of the first byte of allocated storage. NULL The function was unable to allocate enough memory.
void * XMLCALL XML_MemRealloc (XML_Parser parser, void *ptr,size_t size);
parser
Previously allocated XML parser instance.ptr
Pointer to previously allocate block.size
Total number of bytes to allocate.
Allocate size bytes of memory using the allocator the parser object has been configured to use. ptr must point to a block of memory allocated by XML_MemMalloc or XML_MemRealloc, or be NULL.
This function tries to expand the block pointed to by ptr if possible.
Returns a pointer to the memory or NULL on failure. On success, the original block has either been expanded or freed. On failure, the original block has not been freed; the caller is responsible for freeing the original block.
Memory allocated in this way must be freed using XML_MemFree.
x The address of the first byte of allocated storage. NULL The function was unable to allocate enough memory.
enum XML _Status XMLCALL XML_ParseBuffer (XML_Parser p, int len, int isFinal);
parser
Previously allocated XML parser instance.len
Length of the buffer used.isFinal
This is just like <REFERENCE>(XML_Parse), except ins this case the buffer is provided by XMLRTL. This buffer is obtained with the XML_GetBuffer function.
XML_STATUS_ERROR XML_STATUS_OK XML_STATUS_SUSPENDED
XML _Parser XMLCALL XML_ParserCreate (const XML_Char *encoding);
encoding
Optional. NULL-terminated character string specifying an alternate encoding for the document.
Construct a new parser. If encoding is non-null, it specifies a character encoding to use for the document. This overrides the document encoding declaration. There are four built-in encodings:
- US-ASCII
- UTF-8
- UTF-16
- ISO-8859-1
Any other value will invoke a call to the UnknownEncodingHandler.
x The XML parser instance. NULL The function was unaable to allocate a parser.
XML _Parser XMLCALL XML_ParserCreateNS (const XML_Char *encoding, XML_Char sep);
encoding
Optional. NULL-terminated character string specifying an alternate encoding for the document. See XML_ParserCreate for details.sep
Character to be used as a namespace component separator.
Constructs a new parser that has namespace processing in effect. Namespace expanded element names and attribute names are returned as a concatenation of the namespace URI, sep, and the local part of the name. This means that you should pick a character for sep that can't be part of an URI. Since XMLRTL does not check namespace URIs for conformance, the only safe choice for a namespace separator is a character that is illegal in XML. For instance, %xFF is not legal in UTF-8, and %xFFFF is not legal in UTF-16. There is a special case when sep is the null character %x00: the namespace URI and the local part will be concatenated without any separator - this is intended to support RDF processors. It is a programming error to use the null separator wit namespace triplets.
x The XML parser instance. NULL The function was unaable to allocate a parser.
XML _Parser XMLCALL XML_ParserCreate_MM (const XML_Char *encoding, const XML_Memory_Handling_Suite *ms, XML_Char sep);
encoding
Optional. NULL-terminated character string specifying an alternate encoding for the document. See XML_ParserCreate for details.ms
Address of an XML_Memory_Handling_Suite structure containing pointers to alternate memory management functions.
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;sep
Character to be used as a namespace component separator. See XML_ParserCreateNS for details.
Construct a new parser using the suite of memory handling functions specified in ms. If ms is NULL, then use the standard set of memory management functions. If sep is non-NULL, then namespace processing is enabled in the created parser and the character pointed at by sep is used as the separator between the namespace URI and the local part of the name.
x The XML parser instance. NULL The function was unaable to allocate a parser.
enum XML _Status XMLCALL XML_SetBase (XML_Parser parser, const XML_Char *base);
parser
Previously allocated XML parser instance.base
URI base string.
Set the base to be used for resolving relative URIs in system identifiers.
XML_STATUS_OK base has been set. XML_STATUS_ERROR Insufficient memory to store base.
void XMLCALL XML_SetCdataSectionHandler (XML_Parser parser, XML_StartCdataSectionHandler start, XML_EndCdataSectionHandler end);
parser
Previously allocated XML parser instance.start
A routine to handle start CDATA section events. See XML_SetStartCdataSectionHandler for handler call format.end
A routine to handle end CDATA section events. See XML_SetEndCdataSectionHandler for handler call format.
Set handlers for CDATA section start and end in one call.
void XMLCALL XML_SetCharacterDataHandler (XML_Parser parser, XML_CharacterDataHandler charhndl);
parser
Previously allocated XML parser instance.charhndl
A routine to handle character data events.The call format of a character data handler routine is as follows:
typedef void (XMLCALL *XML_CharacterDataHandler)(void *userData, const XML_Char *s, int len);The string argument, s, the handler receives is not null-terminated. len indicates the number of XML_Char characters found in the string.
Note
A single block of contiguous text, free of markup, may result in a sequence of calls to this handler. It cannot be assumed that all data will be returned in the one event.It also needs to be noted that setting this handler to NULL will not always immediately terminate all calls to the handler when the call-back is part of a sequence. However, following completion of the sequence it will take effect.
Set a character data handler. This handle is called when any block of character data is encountered in the input stream. This also includes character data found outside of element pairs.
void XMLCALL XML_SetCommentHandler (XML_Parser parser, XML_CommentHandler cmnt);
parser
Previously allocated XML parser instance.cmnt
A routine to receive text inside XML comment delimiters.The call format of an XML comment handler routine is as follows:
The comment text is returned as a null-terminated string in data. userData is the user data pointer set by XML_SetUserData.
typedef void (XMLCALL *XML_CommentHandler)(void *userData, const XML_Char *data);
Set a handler for comments. The data is all text inside the comment delimiters.
void XMLCALL XML_SetDefaultHandler (XML_Parser parser, XML_DefaultHandler hndl);
parser
Previously allocated XML parser instance.hndl
A routine to receive unhandled XML data.The call format of an default handler routine is as follows:
typedef void (XMLCALL *XML_DefaultHandler)(void *userData, const XML_Char *s, int len);The string argument, s, the handler receives is not null-terminated. len indicates the number of XML_Char characters found in the string.
Sets a handler for any characters in the document which wouldn't otherwise be handled. This includes both data for which no handlers can be set (like some kinds of DTD declarations) and data which could be reported but which currently has no handler set.
The characters are passed exactly as they are present in the XML document except that they will be encoded in UTF-8 or UTF-16. Line boundaries are not normalized.
Note
A byte order mark character is not passed to the default handler. There are no guarantees about how characters are divided between calls to the default handler: e.g., a comment might be split between multiple calls. Setting the handler with this call has the side effect of turning off expansion of references to internally defined general entities. Instead these references are passed to the default handler.
void XMLCALL XML_SetDefaultHandlerExpand (XML_Parser parser,XML_DefaultHandler hndl);
parser
Previously allocated XML parser instance.hndl
A routine to receive unhandled XML data.The call format of an default handler routine is as follows:
typedef void (XMLCALL *XML_DefaultHandler)(void *userData, const XML_Char *s, int len);The string argument, s, the handler receives is not null-terminated. len indicates the number of XML_Char characters found in the string.
Sets the default handler, like XML_SetDefaultHandler. However, doesn't inhibit the expandsion of internal entity references. The entity reference will not be passed to the default handler.
void XMLCALL XML_SetDoctypeDeclHandler (XML_Parser parser, XML_StartDoctypeDeclHandler start, XML_EndDoctypeDeclHandler end);
parser
Previously allocated XML parser instance.start
A routine to receive DOCTYPE declaration start events. See XML_SetStartDoctypeDeclHandler for handler call format.end
A routine to receive DOCTYPE declaration end events. See XML_SetEndDoctypeDeclHandler for handler call format.
Set both DOCTYPE handlers with one call.
void XMLCALL XML_SetElementHandler (XML_Parser parser, XML_StartElementHandler start, XML_EndElementHandler end);
parser
Previously allocated XML parser instance.start
A routine to handle start element events. See XML_SetStartElementHandler for handler call format.end
A routine to handle end element events. See XML_SetEndElementHandler for handler call format.
Set handlers for start and end tags with one call.
Note
An empty tag will generate a call to both start and end handlers (in that order).
enum XML _Status XMLCALL XML_SetEncoding (XML_Parser parser, const XML_Char *encoding);
parser
Previously allocated XML parser instance.encoding
NULL-terminated character string specifying an alternate encoding for the document. See XML_ParserCreate for details.
Set the encoding to be used by the parser. It is equivalent to passing a non-null encoding argument to the parser creation functions. It must not be called after <REFERENCE>(xml_parse) or XML_ParseBuffer have been called on the given parser.
XML_STATUS_OK Parser encoding has been set. XML_STATUS_ERROR Parsing has already commenced..
| Previous | Next | Contents |