/* $RCSfile: oraxml.h $ $Date: 2008/12/01 22:44:38 $ Copyright (c) 1999, 2008, Oracle and/or its affiliates.All rights reserved. ######################################################################## # WARNING!! This header is used to generate documentation directly! # # exact structure and syntax of this file must be maintained properly # # in order for documentation to be produced automatically! # ######################################################################## !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! _ _ _ ___ _ __ __ _ __ __ _ __ ___ | | | |__ (_) ___ / _ \ | '__| / _` | \ \/ / | '_ ` _ \ | | | '_ \ | | / __| | (_) | | | | (_| | > < | | | | | | | | _ | | | | | | \__ \ \___/ |_| \__,_| /_/\_\ |_| |_| |_| |_| (_) |_| |_| |_| |___/ _ _ _ __| | ___ _ __ _ __ ___ ___ __ _ | |_ ___ __| | / _` | / _ \ | '_ \ | '__| / _ \ / __| / _` | | __| / _ \ / _` | | (_| | | __/ | |_) | | | | __/ | (__ | (_| | | |_ | __/ | (_| | \__,_| \___| | .__/ |_| \___| \___| \__,_| \__| \___| \__,_| |_| !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! oraxml.h HAS BEEN DEPRECATED DO NOT WRITE ANY NEW CODE USING THIS INTERFACE SEE xml.h FOR REPLACEMENT API !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! FILE oraxml.h DESCRIPTION DEPRECATED Public header for the Oracle XML parser PUBLIC FUNCTION(S) Top-level parser APIs, plus DOM (1.0 and partial 2.0) and SAX APIs */ #ifndef ORAXML_ORACLE # define ORAXML_ORACLE #ifndef STDIO_ORACLE # define STDIO_ORACLE # include #endif #ifndef ORASTRUC # include #endif /*--------------------------------------------------------------------------- PUBLIC TYPES AND CONSTANTS ---------------------------------------------------------------------------*/ #ifndef XML_TYPES #define XML_TYPES /* DATATYPE xmlnode - DOM node A basic DOM node, could be any type. */ typedef struct xmlnode xmlnode; typedef xmlnode xmlentnode; typedef xmlnode xmlfragnode; typedef xmlnode xmlentrefnode; typedef xmlnode xmldocnode; typedef xmlnode xmltextnode; typedef xmlnode xmlcdatanode; typedef xmlnode xmlcommentnode; typedef xmlnode xmlattrnode; typedef xmlnode xmlpinode; typedef xmlnode xmlelemnode; typedef xmlnode xmlnotenode; typedef xmlnode xmldtdnode; #endif /* DATATYPE boolean - Basic TRUE/FALSE type The basic flag type, which has one of the values TRUE or FALSE. */ /* typedef int boolean; */ /* DATATYPE oratext - Character pointer (all encodings) The basic character-pointer type, used for all data encodings. It should be cast as required, especially for Unicode strings, whose type will be lxuchar (2 byte). */ /* typedef unsigned char oratext; */ /* DATATYPE uword - Native unsigned word The basic unsigned scalar value, size depends on architecture. Used primary for returning error codes. */ /* typedef unsigned int uword; */ #ifndef XML_ORACLE # ifndef XMLCTX_DEFINED # define XMLCTX_DEFINED /* DATATYPE xmlctx - XML parser context The XML parser's context. Created by xmlinit and passed to most functions. */ struct xmlctx; typedef struct xmlctx xmlctx; # endif /* DATATYPE xslctx - XSL processor context The XSL processor's context. Created by xslinit and passed to many XSLT functions. */ typedef struct xslctx xslctx; /* DATATYPE xpctx - XPath context The XPath context. Created by xpmakexpathctx and passed to most of the XPath functions. */ typedef struct xpctx xpctx; /* DATATYPE xpexpr - XPath expression A parsed XPath expression, as returned by xpparsexpathexpr. */ typedef struct xpexpr xpexpr; /* DATATYPE xpobj - XPath object An XPath object. See xpobjtyp for the possible types. */ typedef struct xpobj xpobj; #endif /* DATATYPE xpnset - XPath node-set An XPath node-set, as returned by xpgetnsetval. */ typedef struct xpnset xpnset; /* DATATYPE xpnsetele - XPath node-set element An XPath node-set element. See xpgetfirstnsetelem, xpgetnextnsetelem, and xpgetnsetelemnode. */ typedef struct xpnsetele xpnsetele; /* DATATYPE xmlihdl - I/O input handle Input handle union, for user-specified input callbacks */ typedef union { void *ptr_xmlihdl; /* generic pointer (cast as needed) */ struct { int fd; /* integral file descriptor */ int fd2; /* second file descriptor (FTP data proto) */ int fd3; /* third file descriptor (FTP actual data) */ } fds_xmlihdl; } xmlihdl; /* DATATYPE xmlacctype - XML URI access types URI access methods. */ typedef enum { XMLACCESS_NONE = 0, /* not specified */ XMLACCESS_UNK = 1, /* specified but unknown */ XMLACCESS_FILE = 2, /* filesystem access */ XMLACCESS_HTTP = 3, /* HTTP */ XMLACCESS_FTP = 4, /* FTP */ XMLACCESS_GOPHER = 5, /* Gopher */ XMLACCESS_ORADB = 6, /* Oracle DB */ XMLACCESS_STREAM = 7 /* user-defined stream */ } xmlacctype; #define XMLACCESS_MAX 7 /* range is 0 to XMLACCESS_MAX */ /* DATATYPE xmldomimp - DOM implementation The DOMImplementation structure. Returned by getImplementation and required by functions in the DOMImplementation interface. */ typedef struct xmldomimp xmldomimp; /* DATATYPE xmlnodes - DOM NamedNodeMap/NodeList A list of nodes; the underlying implementation of NodeList and NamedNodeMap. */ typedef struct xmlnodes xmlnodes; /* DATATYPE xsloutputmethod - XSL output method Choice of output method for XSL processing */ typedef enum { XSLMETHOD_UNKNOWN = 0, XSLMETHOD_XML, XSLMETHOD_TEXT, XSLMETHOD_HTML } xsloutputmethod; /* DATATYPE xpobjtyp - XPath object type XSL object types */ typedef enum xpobjtyp { XPOBJTYP_BOOL, /* boolean */ XPOBJTYP_NUM, /* number */ XPOBJTYP_STR, /* string */ XPOBJTYP_NSET, /* node set */ XPOBJTYP_RTFRAG /* result tree fragment */ } xpobjtyp; /* DATATYPE xmlflags - XML parser flags Flag bits for xmlparse functions. */ #define XML_FLAG_VALIDATE 0x01 #define XML_FLAG_DISCARD_WHITESPACE 0x02 #define XML_FLAG_DTD_ONLY 0x04 #define XML_FLAG_STOP_ON_WARNING 0x08 #define XML_FLAG_WARN_DUPLICATE_ENTITY 0x10 #define XML_FLAG_FORCE_INCODING 0x20 #define XML_FLAG_DONT_EXPAND_CHAR_REF 0x40 typedef ub4 xmlflags; /* DATATYPE xmlpflags - XML printer flags Flag bits for print functions. */ #define XML_FLAG_PRINT_XMLDECL 0x01 typedef ub4 xmlpflags; /* DATATYPE xmlntype - DOM node types Parse tree node types. Names & values through #12 match DOM specification. */ #define ELEMENT_NODE 1 /* element */ #define ATTRIBUTE_NODE 2 /* attribute */ #define TEXT_NODE 3 /* char data (not CDATA) */ #define CDATA_SECTION_NODE 4 /* char data (CDATA) */ #define ENTITY_REFERENCE_NODE 5 /* entity reference */ #define ENTITY_NODE 6 /* entity */ #define PROCESSING_INSTRUCTION_NODE 7 /* */ #define COMMENT_NODE 8 /* */ #define DOCUMENT_NODE 9 /* Document */ #define DOCUMENT_TYPE_NODE 10 /* DTD */ #define DOCUMENT_FRAGMENT_NODE 11 /* Document fragment */ #define NOTATION_NODE 12 /* notation */ #define ELEMENT_DECL_NODE 13 /* declaration */ #define ATTR_DECL_NODE 14 /* attr decl */ #define CP_ELEMENT_NODE 15 /* element */ #define CP_CHOICE_NODE 16 /* choice (a|b) */ #define CP_SEQUENCE_NODE 17 /* sequence (a,b) */ #define CP_PCDATA_NODE 18 /* #PCDATA */ #define CP_STAR_NODE 19 /* '*' (zero or more) */ #define CP_PLUS_NODE 20 /* '+' (one or more) */ #define CP_OPT_NODE 21 /* '?' (optional) */ typedef ub1 xmlntype; /* forward declare */ struct xmlstream; typedef struct xmlstream xmlstream; /* obsolete, do not use */ #define XML_PRINTF(func) \ boolean func(void *ctx, oratext *s, uword len) /*--------------------------------------------------------------------------- ERROR CODES, XMLERR_xxx 0000 0099 Generic 0100 0199 VC and other Warnings 0200 0299 Parser 0300 0399 XSL 0400 0499 XPath ---------------------------------------------------------------------------*/ /* Errors in the following range are considered "warnings" and may continue */ #define XMLERR_WARN_MIN 100 /* minimum warning code */ #define XMLERR_WARN_MAX 199 /* maximum warning code */ #define XMLERR_OK 0 /* success return */ #define XMLERR_NULL_PTR 1 /* NULL pointer */ #define XMLERR_NO_MEMORY 2 /* out of memory */ #define XMLERR_HASH_DUP 3 /* duplicate entry in hash table */ #define XMLERR_INTERNAL 4 /* internal error */ #define XMLERR_BUFFER_OVERFLOW 5 /* name/quoted string too long */ #define XMLERR_INVALID_CHILD 6 /* invalid child for parent */ #define XMLERR_EOI 7 /* unexpected End Of Information */ #define XMLERR_INVALID_MEMCB 8 /* invalid memory callbacks */ #define XMLERR_UNICODE_ALIGN 12 /* Unicode data misalignment */ #define XMLERR_NODE_TYPE 13 /* wrong node type */ #define XMLERR_UNCLEAN 14 /* context is not clean */ /* Errors 50 99 are reserved for lpxinit errors and have no associated error messages since they are assumed to be due to errors made by the caller. */ #define XMLERR_NLS_MISMATCH 50 /* specify both lxglo/lxd or neither*/ #define XMLERR_NLS_INIT 51 /* error during NLS initialization */ #define XMLERR_LEH_INIT 52 /* error during LEH initialization */ #define XMLERR_VC_ROOT_ELEM 100 /* root element mismatch */ #define XMLERR_VC_DECL_PE_NEST 101 /* improper decl/pe nesting */ #define XMLERR_VC_STDALONE_DOC 102 /* bogus standalone doc decl */ #define XMLERR_VC_INVALID_ELEM 103 /* invalid element (mismatch DTD) */ #define XMLERR_VC_UNDEF_ELEM 104 /* element is not defined */ #define XMLERR_VC_NOT_EMPTY 105 /* element should be empty */ #define XMLERR_VC_UNDEF_ATTR 106 /* undefined attribute */ #define XMLERR_VC_UNIQUE_ELEM 107 /* element multiply defined */ #define XMLERR_VC_GROUP_PE_NEST 108 /* improper group/pe nesting */ #define XMLERR_VC_DUP_TYPE 109 /* duplicate name in mixed decl */ #define XMLERR_VC_BAD_NAME 110 /* bad Name */ #define XMLERR_VC_BAD_NMTOKEN 111 /* bad Nmtoken */ #define XMLERR_VC_ONE_ID 112 /* multiple ID attributes */ #define XMLERR_VC_ID_ATTR_DEF 113 /* ID not IMPLIED or REQUIRED */ #define XMLERR_VC_ENUM 114 /* attr val not in enumeration */ #define XMLERR_VC_REQ_ATTR 115 /* missing required attribute */ #define XMLERR_VC_FIXED_ATTR 116 /* wrong val for fixed attribute */ #define XMLERR_VC_UNDEF_ENTITY 118 /* undefined entity */ #define XMLERR_VC_ENTITY_PARSE 119 /* entity attribute not unparsed */ #define XMLERR_VC_ENTITY_NDATA 120 /* undefined entity NDATA */ #define XMLERR_VC_UNDEF_NOTE 121 /* undefined notation */ #define XMLERR_VC_UNDEF_ID 122 /* undefined ID (in IDREF) */ #define XMLERR_VC_DUP_ID 123 /* duplicate ID */ #define XMLERR_VC_ATTR_REFS 124 /* attr value missing refs */ #define XMLERR_DUP_ENTITY 125 /* duplicate entity */ #define XMLERR_CONVERT 200 /* encoding conversion problem */ #define XMLERR_BAD_ENCODING 201 /* invalid encoding */ #define XMLERR_OPEN_FILE 202 /* could not open file */ #define XMLERR_READ_FILE 203 /* could not read from file */ #define XMLERR_SYNTAX 204 /* generic syntax error */ #define XMLERR_COMMENT_SYNTAX 205 /* comment syntax error */ #define XMLERR_CDATA_SYNTAX 206 /* CDATA syntax error */ #define XMLERR_COND_SYNTAX 207 /* conditional section syntax error */ #define XMLERR_DTD_KEYWORD 208 /* unknown keyword found in DTD */ #define XMLERR_XML_RESERVED 209 /* XML cannot be used in a PI */ #define XMLERR_NOT_EXPECTED 210 /* syntax error */ #define XMLERR_DEF_DECL 211 /* error in default declaration */ #define XMLERR_COMMENT_END 212 /* comment syntax error */ #define XMLERR_COMMENT_NOEND 213 /* comment syntax error */ #define XMLERR_CDATA_NOEND 214 /* CDATA syntax error */ #define XMLERR_PIDATA_NOEND 215 /* PIDATA syntax error */ #define XMLERR_INVALID_WIDE_CHAR 216 /* Invalid lxwchar */ #define XMLERR_INVALID_UNICODE_CHAR 217 /* Invalid lxuchar */ #define XMLERR_INVALID_NATIVE_CHAR 218 /* Invalid ASCII/EBCDIC character */ #define XMLERR_BAD_CHARREF 219 /* Invalid character */ #define XMLERR_CHARDATA 220 /* Error while processing text */ #define XMLERR_ATTR_VALUE 221 /* Invalid char in attribute value */ #define XMLERR_SAX 222 /* Error from SAX callback */ #define XMLERR_WFC_EXT_ENTITY 223 /* No external entity in attrib val */ #define XMLERR_WFC_UNIQUE_ATTR 224 /* Attributes must be unique */ #define XMLERR_WFC_ELEM_MATCH 225 /* Start tag and end tag of elem */ #define XMLERR_WFC_ENTITY_DECL 226 /* Entity not declared */ #define XMLERR_WFC_PARSED_ENT 227 /* Must be a parsed entity */ #define XMLERR_WFC_RECUR 228 /* No recursion in entity refs */ #define XMLERR_EMPTY_FILE 229 /* Empty file */ #define XMLERR_INVALID_NM_UNICODE_CHAR \ 230 /* Invalid character in NAME/NMTOKEN */ #define XMLERR_INVALID_NM_NATIVE_CHAR \ 231 /* Invalid character in NAME/NMTOKEN */ #define XMLERR_WFC_INVALID_PE 232 /* PE improperly used in internal DTD*/ #define XMLERR_NSC_LEADING_XML 233 /* Leading XML for namespace prefix */ #define XMLERR_NSC_PREFIX_DECL 234 /* Namespace prefix not declared */ #define XMLERR_BAD_VERSION 235 /* XML Version not supported */ #define XMLERR_INVALID_PUB_CHAR 236 /* Invalid pubid character */ #define XMLERR_COND_KEYWORD 237 /* condition section keyword invalid */ #define XMLERR_COND_UNFINISHED 238 /* condition is unfinished (open) */ #define XMLERR_ATTR_TYPE 239 /* invalid attribute type */ #define XMLERR_NWF_ELEM_START 240 /* element-start tag is NWF */ #define XMLERR_NWF_ENTREF 241 /* entity reference is NWF */ #define XMLERR_AMPERSAND 242 /* invalid use of ampersand char */ #define XMLERR_ATTR_QUOTE 243 /* elem attr value not in quotes */ #define XMLERR_LESSTHAN 244 /* invalid use of '<' character */ #define XMLERR_EXTRA_DATA 245 /* extra data at end of document */ #define XMLERR_NO_SYSID 246 /* missing SYSID after PUBID */ #define XMLERR_BAD_DTD 247 /* bad DTD declaration */ #define XMLERR_BAD_ENTITY_DECL 248 /* bad entity declaration */ #define XMLERR_BAD_EXTID 249 /* bad external ID declaration */ #define XMLERR_BAD_ATTR_DECL 250 /* bad attribute declaration */ #define XMLERR_INT_COND 251 /* no conditionals in internal DTD */ #define XMLERR_ENTITY_NESTING 252 /* improper entity nesting */ #define XMLERR_NO_VERSION 253 /* missing required version# */ #define XMLERR_BAD_XML_DECL 254 /* bad XML declaration */ #define XMLERR_STANDALONE_YN 255 /* invalid standalone yes/no */ #define XMLERR_ELEMENT_DECL 256 /* invalid element declaration */ #define XMLERR_CHILDREN_DECL 257 /* invalid children declaration */ #define XMLERR_MIXED_DECL 258 /* invalid mixed declaration */ #define XMLERR_NOTATION_DECL 259 /* invalid notation declaration */ #define XMLERR_XMLSPACE_DECL 260 /* invalid xml:space declaration */ #define XMLERR_INVALID_URL 261 /* invalid URL */ #define XMLERR_UNSUP_PROT 262 /* unsupported protocol */ #define XMLERR_OPEN_TCP 263 /* failed to open TCP connection */ #define XMLERR_SEND_TCP 264 /* failed to send to TCP connection */ #define XMLERR_RECV_TCP 265 /* failed to read from TCP conn. */ #define XMLERR_INVALID_LANG 266 /* invalid language specification */ #define XMLERR_RESOLVE_URL 267 /* couldn't resolve relative URL */ #define XMLERR_INVALID_ACCESS 268 /* invalid access method */ #define XMLERR_ACCESS_FUNCS 269 /* all access funcs must be provided */ #define XMLERR_FTP_CMD 270 /* FTP command failed */ #define XMLERR_FTP_LOGIN 271 /* FTP login failed */ #define XMLERR_FTP_UNAVAIL 272 /* FTP server unavailable */ #define XMLERR_INIT_TCP 273 /* failed to initialize TCP/IP */ #define XMLERR_CANT_IMPORT 274 /* can't import that node type */ #define XMLERR_CANT_SET_ENC 275 /* can't set output encoding */ #define XMLERR_BAD_HTTP_MIME 276 /* bad Mime header in HTTP reply */ #define XMLERR_END_QUOTE 277 /* No ending quote was seen */ #define XMLERR_INVALID_PROXY 278 /* Invalid protocol proxy */ #define XMLERR_INVALID_NO_PROXY 279 /* Invalid no-proxy specification */ #define XMLERR_HTTP_ERROR 280 /* HTTP protocol error */ #define XMLERR_UNSUP_ENCODING 281 /* unsupported encoding */ #define XMLERR_SHARED_DTD_MIX 282 /* doc can't have DTD if set shared */ #define XMLERR_WRONG_ENCODING 283 /* input document in wrong encoding */ #define XMLERR_NULL_URI 284 /* NULL URI in namespace pfx decl */ /* XSL error codes */ #define XMLERR_NONAMEINATTRSET 300 /* no name in attribute set */ #define XMLERR_ERROR_IN_XPATH 301 /* The XPATH function returns an error */ #define XMLERR_CANNOT_TRANSFORM 302 /* The child node is of invalid type or has invalid name */ #define XMLERR_ATTRIBUTE_NOT_EXPECTED 303 /* Attribute is found but its value is not the expected value */ #define XMLERR_NULL_INPUT_STRING 304 /* input string is null */ #define XMLERR_MISSING_TOKEN 305 /* expected token is missing */ #define XMLERR_INCOM_ATTR_VAL_TMPL 306 /* inputed string ended with no corresponding closing } */ #define XMLERR_NS_PREFIX_NOT_DECLARED 307 /* Namespace prefix used but not not declared */ #define XMLERR_ATTRIBUTE_NOT_FOUND 308 /* The expected attribute for this node is not found. */ #define XMLERR_CANNOT_INIT_XPATH 309 /* XPATH context could not be initialized */ #define XMLERR_ELEMENT_NOT_FOUND 310 /* The expected element is not found. */ #define XMLERR_FEATURE_NOT_SUPPORTED 311 /* feature not supported */ #define XMLERR_CANNOT_CONS_PI 312 /* The content of XML PI node might be invalid. */ #define XMLERR_CANNOT_CONS_COMMENT 313 /* The content of XML comment node might be invalid. */ #define XMLERR_FAIL 314 /* An internal error occurred in the code. */ #define XMLERR_EXT_FUNC_NOT_SUPPORTED 315 /* extension function not supported */ #define XMLERR_INVALID_ATTR_VALUE 316 /* invalid value for attr */ #define XMLERR_UNDEF_DECIMAL_FORMAT 317 /* undefined decimal-format */ #define XMLERR_DUP_DEC_FORMAT 318 /* duplicate decimal-format */ #define XMLERR_INVALID_DATA 319 /* The data is not allowed */ #define XMLERR_OUTOFORDERATTRIBUTE 320 /* Cant add more attributes */ #define XMLERR_NULL_OUTPUT 321 /* No mechanism for output */ #define XMLERR_DOCUMENTNOTFOUND 322 /* Could not open doc */ #define XMLERR_APPLY_IMPORTS 323 /* Cant apply imports */ #define XMLERR_INV_LANG 324 /* Invalid LANG for xsl:sort */ /* XPATH error codes */ #define XMLERR_XPATH_INTERNAL 400 /* Internal error */ #define XMLERR_XPATH_INVNAME 401 /* Invalid QName */ #define XMLERR_XPATH_INVAXIS 402 /* Invalid axis name */ #define XMLERR_XPATH_QTNOTMATCH 403 /* Unmatched quote */ #define XMLERR_XPATH_NSERR 404 /* Unable to resolve namespace */ #define XMLERR_XPATH_MEMERR 405 /* Unable to allocate memory */ #define XMLERR_XPATH_INVOBJTYP 406 /* Incorrect object type */ #define XMLERR_XPATH_NOTRSQB 407 /* Right square bracket missing */ #define XMLERR_XPATH_NOTRPAREN 408 /* Right parenthesis missing */ #define XMLERR_XPATH_INVTOK 409 /* Invalid token */ #define XMLERR_XPATH_VARREF 410 /* Unable to resolve the variable */ #define XMLERR_XPATH_UNKFUNC 411 /* Unknown function */ #define XMLERR_ENCODING_MISMATCH 412 /* encoding mismatch in Inc/Import*/ /* The range 470 499 are internal error codes. There would not be any error mesgs corresponding to this in the mesg file. The error mesg given to the user should be internal error. */ #define XMLERR_XPATH_INVEXPRTREE 497 /* Invalid expression tree */ #define XMLERR_XPATH_INVOP 498 /* Invalid operator */ #define XMLERR_XPATH_INVCTX 499 /* Invalid context list/node */ /*--------------------------------------------------------------------------- Package Callback - User callback functions This package defines macros which declare functions (or function pointers) for XML callbacks. Callbacks are used for error-message handling, memory allocation & freeing, and stream operations. ---------------------------------------------------------------------------*/ /**************************************************************************** Interface Callbacks ****************************************************************************/ /*--------------------------------------------------------------------------- NAME XML_ALLOC [xmlmemcb] FUNCTION Memory allocation callback DESCRIPTION This macro defines a prototype for the low-level memory allocation function used in a xmlmemcb memory-callback structure. If no memory callbacks are provided, malloc and free are used; if provided, the callbacks will be used instead. Note allocated memory does not need to be initialized. RETURNS (void *) pointer to allocated memory [unitialized] ARGUMENTS ctx (IN) user-defined memory context size (OUT) number of bytes to allocate SEE ALSO xmlmemcb, xmlinit, xmlinitenc, XML_FREE */ #define XML_ALLOC(func) void *func(void *ctx, ub4 size) /*--------------------------------------------------------------------------- NAME XML_FREE [xmlmemcb] FUNCTION Memory freeing callback DESCRIPTION This macro defines a prototype for the low-level memory freeing function used in a xmlmemcb memory-callback structure. If no memory callbacks are provided, malloc and free are used; if provided, the user's callbacks will be used instead. RETURNS (void) ARGUMENTS ctx (IN) user-defined memory context ptr (OUT) pointer to memory to be freed SEE ALSO xmlmemcb, xmlinit, xmlinitenc, XML_ALLOC */ #define XML_FREE(func) void func(void *ctx, void *ptr) /* DATATYPE xmlmemcb - Memory callbacks The parser allocates memory in large chunks, which are then doled out internally in small pieces. The default system memory allocator (malloc, free) will be used to allocate and free the chunks unless a memory callback structure is provided. To override the defaults, a xmlmemcb containing function pointers to alloc & free functions can be passed to xmlinit; the user's function will be used instead. The memory callback context memcbctx is passed to the callback functions. */ struct xmlmemcb { XML_ALLOC((*alloc)); XML_FREE((*free)); }; typedef struct xmlmemcb xmlmemcb; /*--------------------------------------------------------------------------- NAME XML_OPENF [xmlaccess] FUNCTION I/O open callback DESCRIPTION This macro defines a prototype for the open function callback, which is called once to open the input source. It should set its persistent handle in the xmlihdl union, which has two choices, a generic pointer (void *), and an integer (as Unix file or socket handle). This function should return XMLERR_OK on success. Args: RETURNS (uword) numeric error code, XMLERR_OK [0] on success ARGUMENTS ctx (IN) XML context path (IN) full path of the URI to be opened parts (IN) URI broken down into components (opaque pointer) length (OUT) total length of input data if known, 0 if not ih (OUT) the opened handle is placed here SEE ALSO xmlaccess, XML_CLOSEF, XML_READF */ #define XML_OPENF(func) \ uword func(xmlctx *ctx, oratext *path, void *parts, \ ubig_ora *length, xmlihdl *ih) typedef XML_OPENF((*xml_openf)); /*--------------------------------------------------------------------------- NAME XML_CLOSEF [xmlaccess] FUNCTION I/O close callback DESCRIPTION This macro defines a prototype for the close function callback, called to close an open source and free its resources. Args: RETURNS (void) ARGUMENTS ctx (IN) XML context ih (IN) input handle union SEE ALSO xmlaccess, XML_OPENF, XML_READF */ #define XML_CLOSEF(func) \ void func(xmlctx *ctx, xmlihdl *ih) typedef XML_CLOSEF((*xml_closef)); /*--------------------------------------------------------------------------- NAME XML_READF [xmlaccess] FUNCTION I/O read callback DESCRIPTION This macro defines a prototype for the read function callback, called to read data from an open source into a buffer, returning the number of bytes read: if 0, an EOI condition is indicated; if > 0, then the EOI flag determines if this is the final data. On EOI, the matching close function will be called automatically. RETURNS (uword) number of bytes read [0 on EOI] ARGUMENTS ctx (IN) XML context path (IN) full URI of the open source (for error messages) ih (IN) input handle union dest (OUT) destination buffer to read data into destsize (IN) size of dest buffer nraw (OUT) number of bytes read eoi (OUT) End of Information? (last chunk of data) SEE ALSO xmlaccess, XML_OPENF, XML_CLOSEF */ #define XML_READF(func) \ uword func(xmlctx *ctx, oratext *path, xmlihdl *ih, oratext *dest, \ size_t destsize, sbig_ora *nraw, ub1 *eoi) typedef XML_READF((*xml_readf)); /*--------------------------------------------------------------------------- NAME XMLSTREAM_OPENF [xmlstream] FUNCTION Stream open callback DESCRIPTION Macro which defines the prototype for a stream open function. RETURNS (uword) error code, XMLERR_OK [0] for success ARGUMENTS stream (IN) stream descriptor rsvd (IN) reserved for future use [must be 0] SEE ALSO xmlstream, XMLSTREAM_WRITEF, XMLSTREAM_CLOSEF, xslsetoutputstream, xslgetoutputstream */ #define XMLSTREAM_OPENF(func) \ uword func(xmlstream *stream, ub4 rsvd) /*--------------------------------------------------------------------------- NAME XMLSTREAM_WRITEF [xmlstream] FUNCTION Stream write callback DESCRIPTION Macro which defines the prototype for a stream write function. RETURNS (uword) error code, XMLERR_OK [0] for success ARGUMENTS stream (IN) stream descriptor len (IN) number of bytes to write buf (IN) buffer to write lenwritten (OUT) bytes actually written rsvd (IN) reserved for future use [must be 0] SEE ALSO xmlstream, XMLSTREAM_OPENF, XMLSTREAM_CLOSEF, xslsetoutputstream, xslgetoutputstream */ #define XMLSTREAM_WRITEF(func) \ uword func(xmlstream *stream, size_t len, oratext *buf, \ size_t *lenwritten, ub4 rsvd) /*--------------------------------------------------------------------------- NAME XMLSTREAM_CLOSEF [xmlstream] FUNCTION Stream close callback DESCRIPTION Macro which defines the prototype for a stream close function. RETURNS (uword) error code, XMLERR_OK [0] for success ARGUMENTS stream (IN) stream descriptor rsvd (IN) reserved for future use [must be 0] SEE ALSO xmlstream, XMLSTREAM_OPENF, XMLSTREAM_WRITEF, xslsetoutputstream, xslgetoutputstream */ #define XMLSTREAM_CLOSEF(func) \ uword func(xmlstream *stream, ub4 rsvd) /*---------------------------------------------------------------------------*/ /* DATATYPE xmlstream - User-defined stream Generic user-defined stream object */ struct xmlstream { XMLSTREAM_OPENF((*open)); XMLSTREAM_WRITEF((*write)); XMLSTREAM_CLOSEF((*close)); /* User can associate any data to xmlstream structure using this member so that he can access that inside the callbacks which will always have xmlstream as the first argument. */ void *userdata; }; /*--------------------------------------------------------------------------- NAME XML_MSGHDLRF [xmlinit] FUNCTION Error message handler DESCRIPTION This macro is used to define an error-message-handling function to be passed to xmlinit or xmlinitenc; if not defined, errors will be printed to stderr. RETURNS (void) ARGUMENTS msgctx (IN) user-define message handler context msg (IN) text of error message errcode (IN) numeric error code SEE ALSO xmlinit, xmlinitenc */ #define XML_MSGHDLRF(func) \ void func(void *msgctx, const oratext *msg, uword errcode) typedef XML_MSGHDLRF((*xml_msghdlr)); /*--------------------------------------------------------------------------- Package SAX - SAX APIs SAX is a standard interface for event-based XML parsing, developed collaboratively by the members of the XML-DEV mailing list. To use SAX, an xmlsaxcb structure is initialized with function pointers and passed to the xmlinit call. A pointer to a user-defined context structure may also be included; that context pointer will be passed to each SAX function. ---------------------------------------------------------------------------*/ #ifndef XMLSAXCB_DEFINED # define XMLSAXCB_DEFINED /**************************************************************************** Interface SAX ****************************************************************************/ /* SAX callback structure. Set function pointers for those events you wish to receive, and make the rest NULL. The entire structure should be initialized to zeros so that unused pointers at the end of the struct are NULL (to avoid future problems when they are defined to new events) All SAX functions return a (sword) error code. A zero values means success and processing will continue; any non-zero value indicates a failure and parsing stops. Pointers passed to SAX callbacks (names, character data, etc), are only valid for the duration of the callback! Once it has returned, the memory pointed to will be recycled and written over. If you need to persistently keep the datums, you must copy them. */ struct xmlsaxcb { /*--------------------------------------------------------------------------- NAME startDocument [SAX 1] FUNCTION Receives SAX start-of document notification DESCRIPTION The first SAX event, called once per document, indicating the start of the document. Matching event is endDocument. EXAMPLE -SAX-> xmlDecl(version="1.0", encoding=NULL) startDocument() ... RETURNS (sword) error code, XMLERR_OK [0] for success ARGUMENTS ctx (IN) user's SAX context [see xmlinit] SEE ALSO xmlinit, endDocument */ sword (*startDocument)(void *ctx); /*--------------------------------------------------------------------------- NAME endDocument [SAX 1] FUNCTION Receives SAX end-of-document notification DESCRIPTION The last SAX event, called once per document, indicating the end of the document. Matching event is startDocument. EXAMPLE -SAX-> xmlDecl(version="1.0", encoding=NULL) ... endDocument() RETURNS (sword) error code, XMLERR_OK [0] for success ARGUMENTS ctx (IN) user's SAX context [see xmlinit] SEE ALSO xmlinit, startDocument */ sword (*endDocument)(void *ctx); /*--------------------------------------------------------------------------- NAME startElement [SAX 1] FUNCTION Receives SAX start-of-element notification DESCRIPTION This event marks the start of an element. Note this is the original SAX 1 non-namespace-aware version; startElementNS is the SAX 2 namespace-aware version. If both are registered, only the NS version will be called. The element's name will be in the data encoding, as are all the attribute parts. See the functions in the NamedNodeMap interface for operating on the attributes map. The matching function is endElement (there is no endElementNS). EXAMPLE -SAX-> xmlDecl(version="1.0", encoding=NULL) ... startElement(name="top", attrs=NULL) endElement(name="top") ... RETURNS (sword) error code, XMLERR_OK [0] for success ARGUMENTS ctx (IN) user's SAX context [see xmlinit] name (IN) name of element [in data encoding] attrs (IN) NamedNodeMap of element's attributes, or NULL SEE ALSO xmlinit, endElement, getNodeMapLength, getNamedItem, getChildNode */ sword (*startElement)(void *ctx, const oratext *name, const struct xmlnodes *attrs); /*--------------------------------------------------------------------------- NAME endElement [SAX 1] FUNCTION Receives SAX end-of-element notification DESCRIPTION This event marks the close of an element; it matches the startElement or startElementNS events. The name is the tagName of the element (which may be a QName for namespace-aware elements) and is in the data encoding. EXAMPLE -SAX-> xmlDecl(version="1.0", encoding=NULL) ... startElement(name="top", attrs=NULL) endElement(name="top") ... RETURNS (sword) error code, XMLERR_OK [0] for success ARGUMENTS ctx (IN) user's SAX context [see xmlinit] name (IN) name of ending element [in data encoding] SEE ALSO xmlinit, endElement */ sword (*endElement)(void *ctx, const oratext *name); /*--------------------------------------------------------------------------- NAME characters [SAX 1] FUNCTION Receives SAX notification of character data DESCRIPTION This event marks character data, either Text or CDATA. If a cdata callback is provided, then CDATA will be send to that instead; with no cdata callback, both Text and CDATA go to the characters callback. The data will be in the data encoding, and the returned length is in characters, not bytes. See also ignorableWhitespace, which receiving notification about ignorable (whitespace formatting) character data. EXAMPLE junk -SAX-> xmlDecl(version="1.0", encoding=NULL) ... characters(ch="junk", len=4) ... RETURNS (sword) error code, XMLERR_OK [0] for success ARGUMENTS ctx (IN) user's SAX context [see xmlinit] ch (IN) pointer to data [in data encoding] len (IN) length of data [in characters] SEE ALSO xmlinit, ignorableWhitespace */ sword (*characters)(void *ctx, const oratext *ch, size_t len); /*--------------------------------------------------------------------------- NAME ignorableWhitespace [SAX 1] FUNCTION Receives SAX notification of ignorable (whitespace) data DESCRIPTION This event marks ignorable whitespace data such as newlines, and indentation between lines. The matching function is characters, which receives notification of normal character data. The data is in the data encoding, and the returned length is in characters, not bytes. EXAMPLE junk -SAX-> xmlDecl(version="1.0", encoding=NULL) ... startElement(name="top", attrs=NULL) ignorableWhitespace(ch="\n ", len=5) startElement(name="sub", attrs=NULL) ... RETURNS (sword) error code, XMLERR_OK [0] for success ARGUMENTS ctx (IN) user's SAX context [see xmlinit] ch (IN) pointer to data [in data encoding] len (IN) length of data [in characters] SEE ALSO xmlinit, characters */ sword (*ignorableWhitespace)(void *ctx, const oratext *ch, size_t len); /*--------------------------------------------------------------------------- NAME processingInstruction [SAX 1] FUNCTION Receives SAX notification of a processing instruction DESCRIPTION This event marks a processing instruction. The PI's target and data will be in the data encoding. There is always a target, but the data may be NULL. EXAMPLE -SAX-> xmlDecl(version="1.0", encoding=NULL) processingInstruction(target="keywords", data="sax example") ... RETURNS (sword) error code, XMLERR_OK [0] for success ARGUMENTS ctx (IN) user's SAX context [see xmlinit] target (IN) PI's target [in data encoding] data (IN) PI's data [in data encoding] or NULL SEE ALSO xmlinit */ sword (*processingInstruction)(void *ctx, const oratext *target, const oratext *data); /*--------------------------------------------------------------------------- NAME notationDecl [SAX 1] FUNCTION Receives SAX notification of a notation declaration DESCRIPTION The even marks the declaration of a notation in the DTD. The notation's name, public ID, and system ID will all be in the data encoding. Both IDs are optional and may be NULL. EXAMPLE ]> ... -SAX-> xmlDecl(version="1.0", encoding=NULL) notationDecl(name="foo", publicID="[", systemID="null.ent") RETURNS (sword) error code, XMLERR_OK [0] for success ARGUMENTS ctx (IN) user's SAX context [see xmlinit] name (IN) notation's name [in data encoding] publicID (IN) notation's public ID [in data encoding] or NULL systemID (IN) notation's system ID [in data encoding] or NULL SEE ALSO xmlinit */ sword (*notationDecl)(void *ctx, const oratext *name, const oratext *publicId, const oratext *systemId); /*--------------------------------------------------------------------------- NAME unparsedEntityDecl [SAX 1] FUNCTION Receives SAX notification of a unparsed entity declaration DESCRIPTION Marks an unparsed entity declaration in the DTD; see parsedEntityDecl for parsed entity notification. The unparsed entity's name, public ID, system ID, and notation name will all be in the data encoding. EXAMPLE ]> ... -SAX-> xmlDecl(version="1.0", encoding=NULL) unparsedEntityDecl(name="e", publicID="p-p-pub-id", systemID="entity.dat", notationName="endayta") RETURNS (sword) error code, XMLERR_OK [0] for success ARGUMENTS ctx (IN) user's SAX context [see xmlinit] name (IN) entity's name [in data encoding] publicID (IN) entity's public ID [in data encoding] or NULL systemID (IN) entity's system ID [in data encoding] notationName (IN) entity's notation name [in data encoding] SEE ALSO xmlinit, parsedEntityDecl */ sword (*unparsedEntityDecl)(void *ctx, const oratext *name, const oratext *publicId, const oratext *systemId, const oratext *notationName); /*--------------------------------------------------------------------------- NAME nsStartElement [SAX 2] FUNCTION Receives SAX namespace-aware start-of-element notification DESCRIPTION This event marks the start of an element. Note this is the new SAX 2 namespace-aware version; startElement is the SAX 1 non-namespace-aware version. If both are registered, only the NS version will be called. The element's QName, local name, and namespace URI will be in the data encoding, as are all the attribute parts. See the functions in the NamedNodeMap interface for operating on the attributes map. The matching function is endElement (there is no endElementNS). EXAMPLE -SAX-> xmlDecl(version="1.0", encoding=NULL) ... startElement(qname="foo:top", local="top", nsp="/foo/bar", attrs=NULL) endElement(name="foo:top") ... RETURNS (sword) error code, XMLERR_OK [0] for success ARGUMENTS ctx (IN) user's SAX context [see xmlinit] qname (IN) element's qualified name [in data encoding] local (IN) element's namespace local name [in data encoding] nsp (IN) element's namespace URI [in data encoding] attrs (IN) NamedNodeMap of element's attributes, or NULL SEE ALSO xmlinit, startElement */ sword (*nsStartElement)(void *ctx, const oratext *qname, const oratext *local, const oratext *nsp, const struct xmlnodes *attrs); /*--------------------------------------------------------------------------- NAME comment [SAX 2] FUNCTION Receives SAX notification of a comment DESCRIPTION This event marks a comment in the XML document. The comment's data will be in the data encoding. EXAMPLE -SAX-> xmlDecl(version="1.0", encoding=NULL) comment(data="Just a comment") ... RETURNS (sword) error code, XMLERR_OK [0] for success ARGUMENTS ctx (IN) user's SAX context [see xmlinit] data (IN) comment's data [in data encoding] SEE ALSO xmlinit */ sword (*comment)(void *ctx, const oratext *data); /*--------------------------------------------------------------------------- NAME elementDecl [SAX X] FUNCTION Receives SAX notification of an element's declaration DESCRIPTION This event marks an element declaration in the DTD. The element's name and content will be in the data encoding. EXAMPLE ]> ... -SAX-> xmlDecl(version="1.0", encoding=NULL) elementDecl(name="e", content="(#PCDATA)") ... RETURNS (sword) error code, XMLERR_OK [0] for success ARGUMENTS ctx (IN) user's SAX context [see xmlinit] name (IN) element's name content (IN) element's context model SEE ALSO xmlinit, attributeDecl */ sword (*elementDecl)(void *ctx, const oratext *name,const oratext *content); /*--------------------------------------------------------------------------- NAME attributeDecl [SAX X] FUNCTION Receives SAX notification of an attribute's declaration DESCRIPTION This event marks an element declaration in the DTD. The element's name and content will be in the data encoding. Note that an attribute may be declared before the element it belongs to! EXAMPLE ]> ... -SAX-> xmlDecl(version="1.0", encoding=NULL) attributeDecl(elem="a", name="id", body="ID #IMPLIED") ... RETURNS (sword) error code, XMLERR_OK [0] for success ARGUMENTS ctx (IN) user's SAX context [see xmlinit] elem (IN) element that attribute is declared for [in data encoding] attr (IN) attribute's name [in data encoding] body (IN) body of attribute declaration [in data encoding] SEE ALSO xmlinit, attributeDecl */ sword (*attributeDecl)(void *ctx, const oratext *elem, const oratext *attr, const oratext *body); /*--------------------------------------------------------------------------- NAME xmlDecl [SAX X] FUNCTION Receives SAX notification of an XML declaration DESCRIPTION This event marks an XML declaration (XMLDecl). The startDocument event is always first; if this callback is registered and an XMLDecl exists, it will be the second event. The encoding flag says whether an encoding was specified. Since the document's own encoding specification may be overridden, and the input will be converted to the data encoding anyway, the actual encoding specified is not provided. getEncoding returns the name of the data encoding. For the standalone flag, -1 will be returned if it was not specified, otherwise 0 for FALSE, 1 for TRUE. EXAMPLE -SAX-> xmlDecl(version="1.0", encoding=FALSE) ... RETURNS (sword) error code, XMLERR_OK [0] for success ARGUMENTS ctx (IN) user's SAX context [see xmlinit] version (IN) version string from XMLDecl [in data encoding] encoding (IN) encoding was specified? standalone (IN) value of standalone-document flag [< 0 not specified] SEE ALSO xmlinit, getEncoding */ sword (*xmlDecl)(void *ctx, const oratext *version, boolean encoding, sword standalone); /*--------------------------------------------------------------------------- NAME cdata [SAX 1] FUNCTION Receives SAX notification of CDATA DESCRIPTION This event marks CDATA, as distinct from Text. If no CDATA callback is provided, the Text callback will be invoked. The data will be in the data encoding, and the returned length is in characters, not bytes. See also ignorableWhitespace, which receiving notification about ignorable (whitespace formatting) character data. EXAMPLE -SAX-> xmlDecl(version="1.0", encoding=NULL) ... cdata(ch=" stuff", len=6) ... RETURNS (sword) error code, XMLERR_OK [0] for success ARGUMENTS ctx (IN) user's SAX context [see xmlinit] ch (IN) pointer to CDATA [in data encoding] len (IN) length of CDATA [in characters] SEE ALSO xmlinit, ignorableWhitespace */ sword (*cdata)(void *ctx, const oratext *ch, size_t len); /*--------------------------------------------------------------------------- NAME parsedEntityDecl FUNCTION Receives SAX notification of a parsed entity declaration STATUS SAX 1 DESCRIPTION Marks an parsed entity declaration in the DTD. The parsed entity's name, public ID, system ID, and notation name will all be in the data encoding. EXAMPLE ]> ... -SAX-> xmlDecl(version="1.0", encoding=NULL) parsedEntityDecl(name="e1", value="foobar", pubID=NULL, sysID=NULL, general=TRUE) parsedEntityDecl(name="e2", value=NULL, pubID=NULL, sysID="nop.ent", general=TRUE) parsedEntityDecl(name="e3", value="parameter_entity_value", pubID=NULL, sysID=NULL, general=FALSE) RETURNS (sword) error code, XMLERR_OK [0] for success ARGUMENTS ctx (IN) user's SAX context [see xmlinit] name (IN) entity's name [data encoding] value (IN) entity's value if internal [data encoding] pubId (IN) entity's public ID [data encoding] or NULL sysId (IN) entity's system ID [data encoding] general (IN) general entity? parameter entity if FALSE. SEE ALSO unparsedEntityDecl */ sword (*parsedEntityDecl)(void *ctx, const oratext *name, const oratext *value, const oratext *pubId, const oratext *sysId, boolean general); /* The following 2 fields are reserved for future use. */ void (*empty1)(); void (*empty2)(); }; typedef struct xmlsaxcb xmlsaxcb; #endif /* ifndef XMLSAXCB_DEFINED */ /*--------------------------------------------------------------------------- Package Parser - Top-Level APIs This C implementation of the XML processor (or parser) follows the W3C XML specification (rev REC-xml-19980210) and implements the required behavior of an XML processor in terms of how it must read XML data and the information it must provide to the application. ---------------------------------------------------------------------------*/ /**************************************************************************** Interface XMLParser ****************************************************************************/ /*--------------------------------------------------------------------------- NAME xmlinit [DOM X] FUNCTION Initializes XML parser DESCRIPTION Initializes the C XML parser and returns a new parser context. Must be called before any parsing can take place. If this call is not successful, do not call any other XML parser functions! xmlinitenc is the same as xmlinit except that the DOM/SAX data encoding may be specified. For xmlinit, the data encoding will match that of the first document parsed. This function should only be called once before parsing any XML files. xmlterm should be called after all parsing and DOM use has completed. Multiple parses should call xmlclean between runs if only the current document needs to be available. Until clean is called, data pointers from all previous parses will continue to be valid. All arguments may be NULL except for err, which is required. On success, an XML context (xmlctx *) is returned. If this is NULL, a failure occurred: the error code is stored in *err, and depending on how far along in the initialization it got, an error message may be produced. DATA ENCODING: The encoding of input documents is detected automatically (by BOM, XMLDecl, etc). If the encoding cannot be determined, 'incoding' is assumed. If 'incoding' is not specified (NULL), UTF-8 is assumed. 'incoding' should be an IANA/Mine encoding name, e.g. "UTF-16", "ASCII", etc. The presentation encoding (via DOM/SAX) is automatically set to the encoding of the first document parsed. See also the xmlinitenc function, which allows the data encoding to explicitly set. DOM vs SAX: By default, a DOM parse tree is built. To use SAX instead, specify a SAX callback structure (saxcb); the presence of the callback struct acts as a flag. The callbacks will be invoked with the given SAX context pointer. If any of the SAX functions returns a non-zero error code, parsing stops immediately. ERROR MESSAGES: By default, error messages are printed to stderr. To handle messages yourself, specify a handler function pointer. The formatted error string and numeric error code will be passed to your function, along with the user-defined message context msgctx. The error strings will be UTF-8; any data included as part of the error message will be converted to UTF-8. The location where an error occurred may be fetched with the xmlwhere function. The error handler function should be declared with the XML_MSGHDLRF function prototype macro. ERROR LANGUAGE: The error language is specified as lang, e.g. "AMERICAN", JAPANESE", "FRENCH", etc, and defaults to American. PERFORMANCE: A separate, fast code path exists for single-byte encodings (ASCII, ISO-8859, EBCDIC, etc). This path is considerably faster than the multibyte and Unicode paths, so if you are sure your input documents are single-byte, you are strongly encouraged to tell the parser by setting the 'incoding' hint properly. Since all multibyte/Unicode inputs are converted to UTF-16 internally for homogenization, choosing UTF-16 output is next fastest since no extra conversion is needed. The slowest code path is multibyte input with multibyte output, since there is a round trip to UTF-16 between. RETURNS (xmlctx *) XML context or NULL ARGUMENTS err (OUT) Numeric error code, XMLERR_OK [0] on success incoding (IN) Default input encoding [in compiler encoding] msghdlr (IN) Error message handler function msgctx (IN) Context for the error message handler saxcb (IN) SAX callback structure filled with function pointers saxcbctx (IN) Context for SAX callbacks memcb (IN) Memory function callbacks memcbctx (IN) Context for the memory function callbacks lang (IN) Language for error messages [in compiler encoding] SEE ALSO xmlinitenc, xmlclean, xmlterm, xmlmemcb */ xmlctx *xmlinit(uword *err, const oratext *incoding, XML_MSGHDLRF((*msghdlr)), void *msgctx, const xmlsaxcb *saxcb, void *saxcbctx, const xmlmemcb *memcb, void *memcbctx, const oratext *lang); /*--------------------------------------------------------------------------- NAME xmlinitenc [DOM X] FUNCTION Initalizes XML parser (specifying data encoding) DESCRIPTION Initializes the C XML parser and returns a new parser context. Details are the same as for xmlinit except that an additional argument is supplied: the data encoding. All DOM and SAX data will be presented in the given data encoding. See the documentation for xmlinit. RETURNS (xmlctx *) XML context or NULL ARGUMENTS err (OUT) Numeric error code, XMLERR_OK [0] on success incoding (IN) Default input encoding [in compiler encoding] outcoding (IN) Output [DOM/SAX data] encoding [in compiler encoding] msghdlr (IN) Error message handler function msgctx (IN) Context for the error message handler saxcb (IN) SAX callback structure filled with function pointers saxcbctx (IN) Context for SAX callbacks memcb (IN) Memory function callbacks memcbctx (IN) Context for the memory function callbacks lang (IN) Language for error messages [in compiler encoding] SEE ALSO xmlinit, xmlclean, xmlterm, xmlmemcb */ xmlctx *xmlinitenc(uword *err, const oratext *incoding, const oratext *outcoding, XML_MSGHDLRF((*msghdlr)), void *msgctx, const xmlsaxcb *saxcb, void *saxcbctx, const xmlmemcb *memcb, void *memcbctx, const oratext *lang); /*--------------------------------------------------------------------------- NAME xmlterm [DOM X] FUNCTION Terminates XML parser DESCRIPTION Terminates (shuts down) the XML parser. It should be called after xmlinit, and before exiting the main program. All allocated memory is freed, giving it back to the system (through free or the user's memory callback). Contrast to xmlclean, which recycles memory internally without giving it back to the system. No additional XML parser calls can be made until xmlinit is called again to get a new context. RETURNS (uword) numeric error code, XMLERR_OK [0] on success ARGUMENTS ctx (IN) XML context SEE ALSO xmlinit, xmlinitenc, xmlclean */ uword xmlterm(xmlctx *ctx); /*--------------------------------------------------------------------------- NAME xmlclean [DOM X] FUNCTION Cleans up an XML context between parses DESCRIPTION Recycles memory within the XML parser, but does not free it to the system-- only xmlterm finally releases all memory back to the system. If xmlclean is not called between parses, then the data used by the previous documents remains allocated, and pointers to it are valid. Thus, the data for multiple documents can be accessible simultaneously, although only the current document can be manipulated with DOM. If you just want to access one document's data at a time (within a single context), then call xmlclean before each new parse. RETURNS (void) ARGUMENTS ctx (IN) XML context SEE ALSO xmlterm */ void xmlclean(xmlctx *ctx); /*--------------------------------------------------------------------------- NAME xmlparse [DOM X] FUNCTION Parses XML document from a URI DESCRIPTION Parses an XML given specified by a URI. The parser must have been initialized successfully with a call to xmlinit or xmlinitenc first. Data pointers returned by DOM APIs remain valid until xmlclean or xmlterm is called. For SAX, the data pointers only remain valid for the duration of the user's callback function. That is, once the callback function has returned, the data pointers become invalid. If longer access is needed, the data must be saved, either in the user's own store, or in the XML memory's pool using stringSave (or stringSave2 for UCS2 data). Parser options are specified as flag bits OR'd together into the "flags" mask. Flags are: XML_FLAG_VALIDATE turns validation on. By default, the parser does not validate the input. To validate against a DTD, set this flag. Validation problems are considered warnings, not errors, and by default validation will continue after warnings have occurred. To treat warnings as errors set the flag XML_FLAG_STOP_ON_WARNING. XML_FLAG_DISCARD_WHITESPACE causes extraneous whitespace to be discarded. The default behavior for whitespace processing is to be fully conformant to the XML 1.0 spec, i.e. all whitespace is reported back to the application, but it is indicated which whitespace is "ignorable". However, some applications may prefer to set the XML_FLAG_DISCARD_WHITESPACE which will discard all whitespace between an end-element tag and the following start-element tag. XML_FLAG_STOP_ON_WARNING stops validation on warnings. Validation problems are considered warnings (non-fatal) unless this flag is set. If set, validation will stop after the first warning. XML_FLAG_DTD_ONLY parse an external subset. This is the same as calling xmlparsedtd; it parses an external subset (DTD) instead of a complete XML document. Used primarily by the Class Generator so that it may generate classes from a DTD without need of a complete document. XML_FLAG_WARN_DUPLICATE_ENTITY causes a warning to be emitted if a duplicate entity declaration is found. A duplicate entity declaration is usually silently ignored. When set, this flag causes a warning to be emitted instead. XML_FLAG_FORCE_INCODING forced input documents to be interpreted in the encoding "incoding". The default input encoding may be specified as incoding, which overrides the incoding given to xmlinit. If the input's encoding cannot be determined automatically (based on BOM, XMLDecl, etc) then it is assumed to be incoding. IANA/Mime encoding names should be used, "UTF-8", "ASCII", etc. If XML_FLAG_FORCE_INCODING is set, the document will be interpreted as "incoding" regardless. XML_FLAG_DONT_EXPAND_CHAR_REF when set causes character references to be left verbatim and not expanded. For example, "&20;" normally turns into the space character, but when this flag is set, it would remain the four characters '&' '2' '0' and ';'. RETURNS (uword) numeric error code, XMLERR_OK [0] on success ARGUMENTS ctx (I/O) XML context uri (IN) input URI incoding (IN) default input encoding flags (IN) parse options [mask of flag bits] SEE ALSO xmlparsebuf, xmlparsefile, xmlparsestream, xmlparsedtd, xmlflags */ uword xmlparse(xmlctx *ctx, const oratext *uri, const oratext *incoding, xmlflags flags); /*--------------------------------------------------------------------------- NAME xmlparsebuf [DOM X] FUNCTION Parses XML document from a memory buffer DESCRIPTION Parses an XML given a buffer and its length. The parser must have been initialized successfully with a call to xmlinit or xmlinitenc first. See the notes for xmlparse for full documentation. RETURNS (uword) numeric error code, XMLERR_OK [0] on success ARGUMENTS ctx (I/O) XML context buffer (IN) input buffer len (IN) length of buffer in bytes incoding (IN) default input encoding flags (IN) parse options [mask of flag bits] SEE ALSO xmlparse, xmlparsefile, xmlparsestream, xmlparsedtd, xmlflags */ uword xmlparsebuf(xmlctx *ctx, const oratext *buffer, size_t len, const oratext *incoding, xmlflags flags); /*--------------------------------------------------------------------------- NAME xmlparsefile [DOM X] FUNCTION Parses XML document from a disk file DESCRIPTION Parses an XML given the path to a disk file. The parser must have been initialized successfully with a call to xmlinit or xmlinitenc first. See the notes for xmlparse for full documentation. RETURNS (uword) numeric error code, XMLERR_OK [0] on success ARGUMENTS ctx (I/O) XML context path (IN) disk file path incoding (IN) default input encoding flags (IN) parse options [mask of flag bits] SEE ALSO xmlparse, xmlparsebuf, xmlparsestream, xmlparsedtd, xmlflags */ uword xmlparsefile(xmlctx *ctx, const oratext *path, const oratext *incoding, xmlflags flags); /*--------------------------------------------------------------------------- NAME xmlparsestream [DOM X] FUNCTION Parses XML document from a user-defined stream DESCRIPTION Parses an XML given the path from a user-defined stream. The parser must have been initialized successfully with a call to xmlinit or xmlinitenc first. See the notes for xmlparse for full documentation. RETURNS (uword) numeric error code, XMLERR_OK [0] on success ARGUMENTS ctx (I/O) XML context stream (IN) user-defined stream incoding (IN) default input encoding flags (IN) parse options [mask of flag bits] SEE ALSO xmlparse, xmlparsebuf, xmlparsefile, xmlparsedtd, xmlflags */ uword xmlparsestream(xmlctx *ctx, const void *stream, const oratext *incoding, xmlflags flags); /*--------------------------------------------------------------------------- NAME xmlparseorastream [DOM X] FUNCTION Parses XML document from an orastream DESCRIPTION Parses an XML given the path from an orastream (see orastruc.h). The parser must have been initialized successfully with a call to xmlinit or xmlinitenc first. See the notes for xmlparse for full documentation. RETURNS (uword) numeric error code, XMLERR_OK [0] on success ARGUMENTS ctx (I/O) XML context istream (IN) input orastream incoding (IN) default input encoding flags (IN) parse options [mask of flag bits] SEE ALSO xmlparse, xmlparsebuf, xmlparsefile, xmlparsedtd, xmlflags */ uword xmlparseorastream(xmlctx *ctx, orastream *istream, const oratext *incoding, xmlflags flags); /*--------------------------------------------------------------------------- NAME xmlparsedtd [DOM X] FUNCTION Parses an external subset (DTD) specified by a URI DESCRIPTION Parses an external subset (DTD) specified by a URI. Using this API is the same as calling xmlparse with XML_FLAG_DTD_ONLY set. The parser must have been initialized successfully with a call to xmlinit or xmlinitenc first. See the notes for xmlparse for full documentation. RETURNS (uword) numeric error code, XMLERR_OK [0] on success ARGUMENTS ctx (I/O) XML context uri (IN) input URI name (IN) name of DTD incoding (IN) default input encoding flags (IN) parse options [mask of flag bits] SEE ALSO xmlparse, xmlparsebuf, xmlparsefile, xmlparsestream, xmlflags */ uword xmlparsedtd(xmlctx *ctx, const oratext *filename, oratext *name, const oratext *incoding, xmlflags flags); /*--------------------------------------------------------------------------- NAME xmlaccess [DOM X] FUNCTION Sets I/O callbacks for URI access method DESCRIPTION Sets the I/O callback functions for the given URI access type. All three functions must be provided, and should be declared using the function prototype macros XML_OPENF, XML_CLOSEF and XML_READF. RETURNS (uword) numeric error code, XMLERR_OK [0] on success ARGUMENTS ctx (IN) XML context access (IN) the XMLACCESS_xxx code openf (IN) pointer to open function closef (IN) pointer to close function readf (IN) pointer to read function SEE ALSO xmlacctype, XML_OPENF, XML_CLOSEF, XML_READF */ uword xmlaccess(xmlctx *ctx, xmlacctype access, XML_OPENF((*openf)), XML_CLOSEF((*closef)), XML_READF((*readf))); /*--------------------------------------------------------------------------- NAME isStandalone [DOM X] FUNCTION Returns value of standalone flag DESCRIPTION Returns the value of the standalone flag as specified in the document's XMLDecl. RETURNS (boolean) value of standalone flag ARGUMENTS ctx (IN) XML context */ boolean isStandalone(xmlctx *ctx); /*--------------------------------------------------------------------------- NAME isSingleChar [DOM X] FUNCTION Returns single-byte data encoding flag DESCRIPTION Returns a flag specifying if the data encoding is single-byte (ASCII, ISO-8859, EBCDIC, etc). If FALSE, the data encoding may be multibyte or Unicode. RETURNS (boolean) value of single-char flag ARGUMENTS ctx (IN) XML context SEE ALSO isUnicode, getEncoding */ boolean isSingleChar(xmlctx *ctx); /*--------------------------------------------------------------------------- NAME isUnicode [DOM X] FUNCTION Returns Unicode data flag DESCRIPTION Returns a flag specifying whether the data encoding is Unicode (UCS2). If FALSE, the data may be either single-byte or multibyte. RETURNS (boolean) value of Unicode flag ARGUMENTS ctx (IN) XML context SEE ALSO isSingleChar, getEncoding */ boolean isUnicode(xmlctx *ctx); /*--------------------------------------------------------------------------- NAME getEncoding [DOM X] FUNCTION Returns name of data encoding. DESCRIPTION This function returns the IANA/Mime name of the data encoding, e.g. "UTF-8", "ASCII", etc. RETURNS (oratext *) name of encoding ARGUMENTS ctx (IN) XML context SEE ALSO isSingleChar, isUnicode */ oratext *getEncoding(xmlctx *ctx); /*--------------------------------------------------------------------------- NAME saveString [DOM X] FUNCTION Saves single/multibyte string in XML context memory DESCRIPTION Allocates memory and saves the NULL-terminated single- or multi-byte string in the XML string pool. Strings saved this way cannot be freed individually since they are stored head-to-tail in a single pool, for maximum compactness. The memory is reused only when the entire pool is freed, after an xmlclean or xmlterm call. Use saveString2 for saving Unicode strings. RETURNS (oratext *) pointer to saved string ARGUMENTS ctx (IN) XML context str (IN) pointer to single- or multi-byte string SEE ALSO saveString2 */ oratext *saveString(xmlctx *ctx, oratext *str); /*--------------------------------------------------------------------------- NAME saveString2 [DOM X] FUNCTION Saves Unicode string in XML context memory DESCRIPTION Allocates memory and saves the NULL-terminated Unicode string in the XML string pool. Note that a Unicode string is terminated with TWO NULL bytes, not just one! Strings saved this way cannot be freed individually since they are stored head-to-tail in a single pool, for maximum compactness. The memory is reused only when the entire pool is freed, after an xmlclean or xmlterm call. Use saveString for saving single- or multi-byte strings. RETURNS (oratext *) pointer to saved Unicode string ARGUMENTS ctx (IN) XML context ustr (IN) pointer to Unicode string SEE ALSO saveString */ ub2 *saveString2(xmlctx *ctx, ub2 *ustr); /*--------------------------------------------------------------------------- NAME printStream [DOM X] FUNCTION Prints XML tree to stdio stream DESCRIPTION Pretty-prints (formats) an XML document rooted at the given node to a stdio stream. The top level is indented step*level spaces, the next level step*(level+1) spaces, etc. Output will be in the data encoding. RETURNS (void) ARGUMENTS stream (IN) output stdio stream [stdout, etc] node (IN) root node to print step (IN) spaces to indent each level [0-4] level (IN) initial nesting level [0 for root] SEE ALSO printStreamEnc, printOraStream, printBuffer, printSize */ void printStream(FILE *stream, xmlnode *node, uword step, uword level); /*--------------------------------------------------------------------------- NAME printStreamEnc [DOM X] FUNCTION Prints XML tree to stdio stream in specified encoding DESCRIPTION Pretty-prints (formats) an XML document rooted at the given node to a stdio stream. The entire document will be in the encoding specified (by name); if no encoding is given, the document is output in its current (data) encoding. The top level is indented step*level spaces, the next level step*(level+1) spaces, etc. Flags: XML_FLAG_PRINT_XMLDECL says to always print an XMLDecl before the root element. If (node==DOC), an XMLDecl is always printed. RETURNS (size_t) total number of bytes written to stream ARGUMENTS stream (IN) output stdio stream [stdout, etc] node (IN) root node to print step (IN) spaces to indent each level [0-4] level (IN) initial nesting level [0 for root] encoding (IN) printed encoding [NULL for data current encoding] flags (IN) mask of flag bits SEE ALSO printStreamEnc, printOraStream, printBuffer, printSize */ size_t printStreamEnc(FILE *stream, xmlnode *node, uword step, uword level, oratext *encoding, xmlpflags flags); /*--------------------------------------------------------------------------- NAME printOraStream [DOM X] FUNCTION Prints XML tree to orastream in specified encoding DESCRIPTION Pretty-prints (formats) an XML document rooted at the given node to an orastream. The entire document will be in the encoding specified (by name); if no encoding is given, the document is output in its current (data) encoding. The top level is indented step*level spaces, the next level step*(level+1) spaces, etc. Flags: XML_FLAG_PRINT_XMLDECL says to always print an XMLDecl before the root element. If (node==DOC), an XMLDecl is always printed. RETURNS (size_t) total number of bytes written to stream ARGUMENTS ostream (IN) output orastream node (IN) root node to print step (IN) spaces to indent each level [0-4] level (IN) initial nesting level [0 for root] encoding (IN) printed encoding [NULL for data current encoding] flags (IN) mask of flag bits SEE ALSO printStream, printStreamEnc, printBuffer, printSize */ size_t printOraStream(orastream *ostream, xmlnode *node, uword step, uword level, oratext *encoding, xmlpflags flags); /*--------------------------------------------------------------------------- NAME printBuffer [DOM X] FUNCTION Prints XML tree to memory buffer DESCRIPTION Pretty-prints an XML document rooted at the given node to a buffer. The top level is indented step*level spaces, the next level step*(level+1) spaces, etc. Output will be in the data encoding. RETURNS (void) ARGUMENTS buffer (IN) output buffer bufsiz (IN) size of buffer node (IN) root node to print step (IN) spaces to indent each level [0-4] level (IN) initial nesting level [0 for root] SEE ALSO printBufferEnc, printCallbackEnc, printStream, printStreamEnc, printOraStream, printSize */ void printBuffer(oratext *buffer, size_t bufsiz, xmlnode *node, uword step, uword level); /*--------------------------------------------------------------------------- NAME printBufferEnc [DOM X] FUNCTION Prints XML tree to memory buffer in specified encoding DESCRIPTION Pretty-prints an XML document rooted at the given node to a buffer. The entire document will be in the encoding specified (by name); if no encoding is given, the document is output in its current (data) encoding. The top level is indented step*level spaces, the next level step*(level+1) spaces, etc. Output will be in the data encoding. Flags: XML_FLAG_PRINT_XMLDECL says to always print an XMLDecl before the root element. If (node==DOC), an XMLDecl is always printed. RETURNS (size_t) total number of bytes written to stream ARGUMENTS buffer (IN) output buffer bufsiz (IN) size of buffer node (IN) root node to print step (IN) spaces to indent each level [0-4] level (IN) initial nesting level [0 for root] encoding (IN) printed encoding [NULL for data current encoding] flags (IN) mask of flag bits SEE ALSO printBuffer, printCallbackEnc, printStream, printStream, printStreamEnc, printOraStream, printSize */ size_t printBufferEnc(oratext *buffer, size_t bufsiz, xmlnode *node, uword step, uword level, oratext *encoding, xmlpflags flags); /*--------------------------------------------------------------------------- NAME printSize [DOM X] FUNCTION Returns size of formatted XML tree DESCRIPTION Returns the length of XML printed representation, without actually outputting anything. Can be used to calculate the size of the buffer needed for allocation. Caution, about as expensive as formatting it in the first place! The top level is indented step*level spaces, the next level step*(level+1) spaces, etc. Formatting is in the data encoding, however size is returned in BYTES, not characters. RETURNS (size_t) formatted length in bytes ARGUMENTS node (IN) root node step (IN) spaces to indent each level [0-4] level (IN) initial nesting level [0 for root] SEE ALSO printSizeEnc, printStream, printBuffer */ size_t printSize(xmlnode *node, uword step, uword level); /*--------------------------------------------------------------------------- NAME printSizeEnc [DOM X] FUNCTION Returns size of formatted XML tree in specified encoding DESCRIPTION Returns the length of the XML printed representation of a subtree (in the specified encoding), without actually printing anything. If no encoding is given, the current (data) encoding is used. Caution, about as expensive as formatting it in the first place! The top level is indented step*level spaces, the next level step*(level+1) spaces, etc. Formatting is in the data encoding, however size is returned in BYTES, not characters. XML_FLAG_PRINT_XMLDECL says to always print an XMLDecl before the root element. If (node==DOC), an XMLDecl is always printed. RETURNS (size_t) size of formatted subtree in bytes ARGUMENTS node (IN) root node step (IN) spaces to indent each level [0-4] level (IN) initial nesting level [0 for root] encoding (IN) printed encoding [NULL for data current encoding] flags (IN) mask of flag bits SEE ALSO printSize, printStream, printBuffer */ size_t printSizeEnc(xmlnode *node, uword step, uword level, oratext *encoding, xmlpflags flags); /*--------------------------------------------------------------------------- NAME freeElements [DOM X] FUNCTION Frees an allocated list of element nodes DESCRIPTION Frees an allocated list of element nodes. Used primarily to free the lists created by getElementsByTagName. RETURNS (void) ARGUMENTS ctx (IN) XML context list (IN) list of nodes to free SEE ALSO getElementsByTagName */ void freeElements(xmlctx *ctx, xmlnodes *list); /*--------------------------------------------------------------------------- NAME setDocOrder [DOM X] FUNCTION Sets the document order for each node in a Document DESCRIPTION Sets the document order for each node in the current document. Must be called once on the final document before XSLT processing can occur. Note this is called automatically by the XSLT processor, so ordinarily the user need not make this call. RETURNS (ub4) last ID# assigned ARGUMENTS ctx (IN) XML context start_id (IN) initial ID# to assign SEE ALSO getDocOrder */ ub4 setDocOrder(xmlctx *ctx, ub4 start_id); /*--------------------------------------------------------------------------- NAME xmlWhere [DOM X] FUNCTION Returns the location where an error occured DESCRIPTION Returns the location (line#, path) where an error occurred. The error location is a stack: to fetch all items, set index=0 and call repeatedly, incrementing index until FALSE is returned. This function must be called from the user's own error callback function, while the error stack is current. It will NOT return valid information after the top-level parse functions have returned, only during the commission of an error! RETURNS (boolean) idx is valid, an error occurred ARGUMENTS ctx (IN) XML context line (OUT) line# where err occurred path (OUT) path/URL where err occurred idx (IN) location in error stack (starting at 0) SEE ALSO xmlLocation */ boolean xmlwhere(xmlctx *ctx, ub4 *line, oratext **path, uword idx); #define xmlWhere xmlwhere /*--------------------------------------------------------------------------- NAME xmlLocation [DOM X] FUNCTION Returns the current location while parsing DESCRIPTION Returns the current location (line#, path) while parsing. If called before or after parsing, 0 and NULL will be returned respectively. The path will be either the URL or filespec; for other parsing methods (from stream or buffer), NULL is returned. RETURNS (void) ARGUMENTS ctx (IN) XML context line (OUT) current line# path (OUT) current path/URL SEE ALSO xmlWhere */ void xmlLocation(xmlctx *ctx, ub4 *line, oratext **path); /*--------------------------------------------------------------------------- NAME associateDomDocument [DOM X] FUNCTION Mechanism to associate xdkdomdoc with xmlctx DESCRIPTION Associates an xdkdomdoc to a given xmlctx. This association allows usage of the XSLT, XPath, and XML Schema Validator APIs with an xdkdomdoc. The XDB DOM (OCIDomDocument) object is one particular type of xdkdomdoc. xdkdomdoc is defined in xdkdomdoc.h. RETURNS (void) ARGUMENTS ctx (IN) XML context doc (IN) xdkdomdoc to be associated */ void associateDomDocument(xmlctx *ctx, void *doc); /*--------------------------------------------------------------------------- Package DOM - DOM APIs Since the DOM standard is object-oriented, for this C adaptation, some changes had to be made: Reused function names had to be expanded, e.g. getValue in the attribute class is given the unique name getAttrValue, matching the pattern established by getNodeValue. Also, some functions were added to extend the DOM. For example, there is no function defined which returns the number of children of a node, so numChildNodes was invented, etc. The implementation of this DOM interface follows REC-DOM-Level-1-19981001. ---------------------------------------------------------------------------*/ /**************************************************************************** Interface Node ****************************************************************************/ /*--------------------------------------------------------------------------- NAME getNodeName [DOM 1] FUNCTION Returns name of a node DESCRIPTION Returns the (fully-qualified) name of a node (in the data encoding), for example "bar" or "foo:bar". These functions are synonyms and return the same thing. Note that some node types have fixed names: "#text", "#cdata-section", "#comment", "#document", "#document-fragment". RETURNS (oratext *) node's QName [in data encoding] ARGUMENTS node (IN) node whose QName to return SEE ALSO getNodeQualifiedName, getNodeNamespace, getNodePrefix, getNodeLocal */ const oratext *getNodeName(const xmlnode *node); /*--------------------------------------------------------------------------- NAME getNodeQualifiedName [DOM 2 Node.nodeName attribute] FUNCTION Returns name of a node DESCRIPTION Returns the (fully-qualified) name of a node (in the data encoding), for example "bar" or "foo:bar". These functions are synonyms and return the same thing. Note that some node types have fixed names: "#text", "#cdata-section", "#comment", "#document", "#document-fragment". RETURNS (oratext *) node's QName [in data encoding] ARGUMENTS node (IN) node whose QName to return SEE ALSO getNodeName, getNodeNamespace, getNodePrefix, getNodeLocal */ const oratext *getNodeQualifiedName(const xmlnode *node); /*--------------------------------------------------------------------------- NAME getNodeNamespace [DOM 2 Node.namespaceURI attribute] FUNCTION Returns namespace URI of a node DESCRIPTION Returns the namespace URI for a node (in the data encoding). If the node's name is not qualified (does not contain a namespace prefix), it will have the default namespace in effect when the node was created (which may be NULL). EXAMPLE getNodeNamespace(element pfx:foo) --> "example_namespace" RETURNS (oratext *) node's namespace URI [in data encoding] or NULL ARGUMENTS node (IN) node whose namespace URI to return SEE ALSO getNodeQualifiedName, getNodePrefix, getNodeLocal */ const oratext *getNodeNamespace(const xmlnode *node); /*--------------------------------------------------------------------------- NAME getNodePrefix [DOM 2 Node.prefix attribute] FUNCTION Returns namespace prefix of a node DESCRIPTION Returns the namespace prefix for a node. If the node's name is not fully qualified (has no prefix), NULL is returned. EXAMPLE getNodePrefix(element pfx:foo) --> "pfx" RETURNS (oratext *) node's namespace prefix [in data encoding] or NULL ARGUMENTS node (IN) node whose namespace prefix to return SEE ALSO getNodeQualifiedName, getNodeNamespace, getNodeLocal, prefixToURI */ const oratext *getNodePrefix(const xmlnode *node); /*--------------------------------------------------------------------------- NAME getNodeLocal [DOM 2 Node.localName attribute] FUNCTION Returns namespace local name of a node DESCRIPTION Returns the namespace local name for a node. If the node's name is not fully qualified (has no prefix), then the local name is the same as the name. EXAMPLE getNodeLocal(element pfx:foo) --> "foo" RETURNS (oratext *) node's namespace local name [in data encoding] ARGUMENTS node (IN) node whose namespace local name to return SEE ALSO getNodeQualifiedName, getNodeNamespace, getNodeLocal */ const oratext *getNodeLocal(const xmlnode *node); /*--------------------------------------------------------------------------- NAME getNodeValue [DOM 1] FUNCTION Returns value (character data) of a node DESCRIPTION Returns the "value" (associated character data) for a node. Character and general entities will have been replaced. Only Attr, CDATA, Comment, PI and Text nodes have values, all other node types have NULL value. EXAMPLE "data" getNodeValue(node foo) --> NULL getNodeValue(foo's first child) --> "data" RETURNS (oratext *) node's value [in data encoding] or NULL ARGUMENTS node (IN) node whose value to return SEE ALSO setNodeValue, getAttrValue, setAttrValue */ const oratext* getNodeValue(const xmlnode *node); /*--------------------------------------------------------------------------- NAME setNodeValue [DOM 1] FUNCTION Sets the new value (character data) of a node DESCRIPTION Sets a node's "value" (associated character data). Does not allow setting the value to NULL. Only Attr, CDATA, Comment, PI and Text nodes have values; trying to set the value of another type of node is a no-op. Note that the new value must be in the data encoding! It is not verified, converted, or checked. If bad data is set for a node, bad things may happen-- GIGO! RETURNS (void) ARGUMENTS node (IN) node whose value to set data (IN) new data for node [in data encoding] SEE ALSO getNodeValue, getAttrValue, setAttrValue */ void setNodeValue(xmlnode *node, const oratext *data); /*--------------------------------------------------------------------------- NAME getNodeType [DOM 1] FUNCTION Returns the type code of a node DESCRIPTION Returns the type code of a node. The type names and numeric values match the DOM specification (and are #defined in oraxml.h): ELEMENT_NODE, ATTRIBUTE_NODE, TEXT_NODE, CDATA_SECTION_NODE, ENTITY_REFERENCE_NODE, ENTITY_NODE, PROCESSING_INSTRUCTION_NODE, COMMENT_NODE, DOCUMENT_NODE, DOCUMENT_TYPE_NODE, DOCUMENT_FRAGMENT_NODE, NOTATION_NODE Additional node types (not in the DOM standard) are as follows: ELEMENT_DECL_NODE, ATTR_DECL_NODE, CP_ELEMENT_NODE, CP_CHOICE_NODE, CP_SEQUENCE_NODE, CP_PCDATA_NODE, CP_STAR_NODE, CP_PLUS_NODE, CP_OPT_NODE RETURNS (xmlntype) node's type code ARGUMENTS node (IN) node whose type to return SEE ALSO xmlntype */ xmlntype getNodeType(const xmlnode *node); /*--------------------------------------------------------------------------- NAME getParentNode [DOM 1] FUNCTION Returns a node's parent DESCRIPTION Returns a node's parent node. All nodes types except Attr, Document, DocumentFragment, Entity, and Notation may have a parent (these five exceptions have a NULL parent). If a node has just been created and has not yet added to the tree, or if it has been removed from the tree, its parent is also NULL. RETURNS (xmlnode *) node's parent node ARGUMENTS node (IN) node whose parent to return */ xmlnode *getParentNode(const xmlnode *node); /*--------------------------------------------------------------------------- NAME getChildNodes [DOM 1] FUNCTION Returns a node's children DESCRIPTION Returns a list of the node's children, or NULL if it has no children. Only Element, Document, DTD, and DocumentFragment nodes may have children; all other types will return NULL. Note that an empty list may be returned if the node once had children, but all have been removed! So, presense of the list alone does not mean the node has children. You must check the size of the list with numChildNodes or use hasChildNodes first. The xmlnodes structure is opaque and can only be manipulated with functions in the NamedNodeMap interface. RETURNS (xmlnodes *) list of node's children or NULL ARGUMENTS node (IN) node whose children to return SEE ALSO hasChildNodes, numChildNodes, getNamedItem, setNamedItem, removeNamedItem, getChildNode, getNodeMapLength */ xmlnodes* getChildNodes(const xmlnode *node); /*--------------------------------------------------------------------------- NAME getFirstChild [DOM 1] FUNCTION Returns the first child of a node DESCRIPTION Returns the first child of a node, or NULL if the node has no children. Only Element, Document, DTD, and DocumentFragment nodes may have children; all other types will return NULL. RETURNS (xmlnode *) node's first child ARGUMENTS node (IN) node whose first child to return SEE ALSO getChildNodes, getLastChild */ xmlnode *getFirstChild(const xmlnode *node); /*--------------------------------------------------------------------------- NAME getLastChild [DOM 1] FUNCTION Returns the last child of a node DESCRIPTION Returns the last child of a node, or NULL if the node has no children. Only Element, Document, DTD, and DocumentFragment nodes may have children; all other types will return NULL. RETURNS (xmlnode *) node's last child ARGUMENTS node (IN) node whose last child to return SEE ALSO getChildNodes, getFirstChild */ xmlnode *getLastChild(const xmlnode *node); /*--------------------------------------------------------------------------- NAME getPreviousSibling [DOM 1] FUNCTION Returns the previous sibling of a node DESCRIPTION Returns the node preceding a node at the same level in the DOM tree. That is, for each child of a parent node, the previous sibling of that child is the child which came before it. If a node is the first child of its parent, or has no parent, NULL is returned. RETURNS (xmlnode *) node's previous sibling ARGUMENTS node (IN) node whose previous sibling to return SEE ALSO getNextSibling */ xmlnode *getPreviousSibling(const xmlnode *node); /*--------------------------------------------------------------------------- NAME getNextSibling [DOM 1] FUNCTION Returns the next sibling of a node DESCRIPTION Returns the node following a node at the same level in the DOM tree. That is, for each child of a parent node, the next sibling of that child is the child which comes after it. If a node is the last child of its parent, or has no parent, NULL is returned. RETURNS (xmlnode *) node's next sibling ARGUMENTS node (IN) node whose next sibling to return SEE ALSO getPreviousSibling */ xmlnode *getNextSibling(const xmlnode *node); /*--------------------------------------------------------------------------- NAME getAttributes [DOM 1] FUNCTION Returns the attributes of an element DESCRIPTION Returns a NamedNodeMap of attributes of an element node, or NULL if it has no attributes. For other node types, NULL is returned. Note that if an element once had attributes, but they have all been removed, an empty list will be returned. So, presense of the list does not mean the element has attributes. You must check the size of the list with numAttributes or use hasChildNodes first. RETURNS (xmlnodes *) element node's attributes ARGUMENTS node (IN) element node whose attributes to return */ xmlnodes *getAttributes(const xmlnode *node); /*--------------------------------------------------------------------------- NAME getOwnerDocument [DOM 1] FUNCTION Returns the document containing a node DESCRIPTION Returns the Document node associated with a node. Each node belongs to a single xmlctx, and each xmlctx contains only one top-level Document node. That Document node is returned, even if the given node has not yet been added to the DOM tree. If no Document has been created yet, NULL is returned. RETURNS (xmlnode *) Document associated with the node ARGUMENTS node (IN) node whose associated Document to return SEE ALSO createDocument, createDocumentNS */ xmlnode *getOwnerDocument(xmlnode *node); /*--------------------------------------------------------------------------- NAME insertBefore [DOM 1] FUNCTION Inserts a new child into a parent DESCRIPTION Inserts the node newChild before the existing child node refChild in the parent node. If refChild is NULL, appends to parent's children as per appendChild; otherwise it must be a child of the given parent. If newChild is a DocumentFragment, all of its children are inserted (in the same order) before refChild; the DocumentFragment node itself is not. If newChild is already in the DOM tree, it is first removed from its current position. RETURNS (xmlnode *) the new node inserted ARGUMENTS ctx (IN) XML context parent (IN) parent node newChild (IN) new node to insert refChild (IN) reference node, or NULL to append SEE ALSO appendChild, replaceChild, removeChild */ xmlnode *insertBefore(xmlctx *ctx, xmlnode *parent, xmlnode *newChild, xmlnode *refChild); /*--------------------------------------------------------------------------- NAME replaceChild [DOM 1] FUNCTION Replaces one child node with another DESCRIPTION Replaces the child node oldChild with the new node newChild in oldChild's parent, and returns oldChild (which is now orphaned, with a NULL parent). If newChild is a DocumentFragment, all of its children are inserted in place of oldChild; the DocumentFragment node itself is not. If newChild is already in the DOM tree, it is first removed from its current position. RETURNS (xmlnode *) oldChild, the node replaced ARGUMENTS ctx (IN) XML context newChild (IN) new node to replace with oldChild (IN) old node being replaced SEE ALSO insertBefore, appendChild, removeChild */ xmlnode *replaceChild(xmlctx *ctx, xmlnode *newChild, xmlnode *oldChild); /*--------------------------------------------------------------------------- NAME removeChild [DOM 1] FUNCTION Removes a child node DESCRIPTION Removes a node from its parent's list of children and returns it. The node is orphaned; its parent will be NULL after removal. RETURNS (xmlnode *) the node removed ARGUMENTS node (IN) node being removed SEE ALSO appendChild, insertBefore, replaceChild */ xmlnode *removeChild(xmlnode *node); /*--------------------------------------------------------------------------- NAME appendChild [DOM 1] FUNCTION Appends a new child to a parent DESCRIPTION Appends the node to the end of the parent's list of children and returns the new node. If newChild is a DocumentFragment, all of its children are appended in original order; the DocumentFragment node itself is not. RETURNS (xmlnode *) the node appended ARGUMENTS ctx (IN) XML context parent (IN) parent node newChild (IN) new node to append SEE ALSO insertBefore, replaceChild, removeChild */ xmlnode *appendChild(xmlctx *ctx, xmlnode *parent, xmlnode *newChild); /*--------------------------------------------------------------------------- NAME hasChildNodes [DOM 1] FUNCTION Determines if a node has children DESCRIPTION Test if a node has children. Only Element, Document, DTD, and DocumentFragment nodes may have children. Note that just because getChildNodes returns a list does not mean the node actually has children, since the list may be empty. RETURNS (boolean) TRUE if there are children, FALSE if not ARGUMENTS node (IN) node to test SEE ALSO getChildNodes, numChildNodes */ boolean hasChildNodes(const xmlnode *node); /*--------------------------------------------------------------------------- NAME numChildNodes [DOM X] FUNCTION Returns the number of children of a node DESCRIPTION Returns the number of children in a xmlnodes list (as returned by getChildNodes). Only Element, Document, DTD, and DocumentFragment nodes may have children, all other types return 0. Note that just because getChildNodes returns a list does not mean that it contains any children; it may be an empty list with zero length. RETURNS (size_t) number of children ARGUMENTS nodes (IN) list of nodes from getChildNodes SEE ALSO getChildNodes, hasChildNodes */ size_t numChildNodes(const xmlnodes *nodes); /*--------------------------------------------------------------------------- NAME hasAttributes [DOM X] FUNCTION Determines if an element has attributes DESCRIPTION Tests whether an element node has any defined attributes. Only an element node may have attributes; all other types will return FALSE. RETURNS (boolean) TRUE if element has attributes, FALSE if not ARGUMENTS node (IN) element node to check for attributes SEE ALSO getAttributes, numAttributes, getAttribute, getAttributeIndex */ boolean hasAttributes(const xmlnode *node); /*--------------------------------------------------------------------------- NAME numAttributes [DOM X] FUNCTION Returns the number of attributes of an element DESCRIPTION Returns the number of attributes in an xmlnodes list. Note that just because a list is returned by getAttributes does not necessarily mean it contains any attributes; it may be an empty list with zero length. RETURNS (size_t) number of attributes in list ARGUMENTS attrs (IN) list of attributes from getAttributes SEE ALSO getAttributes, hasAttributes, getAttribute, getAttributeIndex */ size_t numAttributes(const xmlnodes *attrs); /*--------------------------------------------------------------------------- NAME cloneNode [DOM 1] FUNCTION Creates a duplicate of a node DESCRIPTION Creates and returns a duplicate of a node. The duplicate node has no parent. Cloning an Element copies all attributes and their values, including those generated by the XML processor to represent defaulted attributes, but it does not copy any text it contains unless it is a deep clone, since the text is contained in a child Text node. Cloning any other type of node simply returns a copy of the node. Note that a clone of an unspecified Attr node is specified. If deep is TRUE, all children of the node are recursively cloned, and the cloned node will have cloned children; a non-deep clone will have no children. RETURNS (xmlnode *) new, cloned node ARGUMENTS ctx (IN) XML context old (IN) node to clone deep (IN) recursively clone children? SEE ALSO importNode */ xmlnode *cloneNode(xmlctx *ctx, const xmlnode *old, boolean deep); /*--------------------------------------------------------------------------- NAME getDocOrder [DOM X] FUNCTION Returns the document order of a node DESCRIPTION Returns the document order cardinal for a node. setDocOrder must have been called first or all nodes will have a 0 order! Used primarily by the XSLT processor, which requires document order for node comparisons. Nodes are numbered by the order in which they would be encountered in a preorder traversal of the tree. The root node's order is specified to setDocOrder, but regardless of the absolute numbering, a node which comes first in the document will have a lower order than a node which comes later. RETURNS (ub4) document order cardinal for node ARGUMENTS node (IN) node whose doc order to return SEE ALSO setDocOrder */ ub4 getDocOrder(xmlnode *node); /*--------------------------------------------------------------------------- NAME prefixToURI [DOM X] FUNCTION Maps a namespace prefix to a URI DESCRIPTION Given a namespace prefix and a node, returns the namespace URI mapped to that prefix. If the given node doesn't have a matching prefix, its parent is tried, then its parent, and so on, all the way to the root node. If the prefix is undefined, NULL is returned. RETURNS (oratext *) namespace URI for prefix ARGUMENTS node (IN) node whose prefix to return prefix (IN) prefix to match SEE ALSO getNodePrefix, getNodeNamespace, getAttrPrefix, getAttrNamespace */ oratext *prefixToURI(xmlnode *node, oratext *prefix); /*--------------------------------------------------------------------------- NAME freeNode [DOM X] FUNCTION Frees memory allocated by a node DESCRIPTION Frees a node. That is, frees all the space allocated by a single node. Does NOT recurse to children. The node should already have been removed from the document. RETURNS (void) ARGUMENTS node (IN) node to be freed */ void freeNode(xmlnode *node); /**************************************************************************** Interface Attr ****************************************************************************/ /*--------------------------------------------------------------------------- NAME getAttrName [DOM 1 Attr.getName] FUNCTION Returns an attribute's name DESCRIPTION Returns the fully-qualified name of an attribute (in the data encoding), for example "bar" or "foo:bar". These functions are synonyms and return the same thing. RETURNS (oratext *) attribute's QName [in data encoding] ARGUMENTS attr (IN) attribute node whose name to return SEE ALSO getAttrQualifiedName, getAttrNamespace, getAttrPrefix, getAttrLocal */ const oratext *getAttrName(const xmlnode *attr); /*--------------------------------------------------------------------------- NAME getAttrQualifiedName [DOM X] FUNCTION Returns an attribute's name DESCRIPTION Returns the fully-qualified name of an attribute (in the data encoding), for example "bar" or "foo:bar". These functions are synonyms and return the same thing. RETURNS (oratext *) attribute's QName [in data encoding] ARGUMENTS attr (IN) attribute node whose name to return SEE ALSO getAttrName, getAttrNamespace, getAttrPrefix, getAttrLocal */ const oratext *getAttrQualifiedName(const xmlnode *attr); /*--------------------------------------------------------------------------- NAME getAttrNamespace [DOM X] FUNCTION Returns an attribute's namespace URI DESCRIPTION Returns an attribute's namespace URI (in the data encoding). If the attribute's name is not qualified (does not contain a namespace prefix), it will have the default namespace in effect when the node was created (which may be NULL). EXAMPLE getAttrNamespace(attr pfx:bar) --> "example_namespace" RETURNS (oratext *) attribute's namespace URI [in data encoding] or NULL ARGUMENTS attr (IN) attribute whose namespace URI to return SEE ALSO getAttrQualifiedName, getAttrPrefix, getAttrLocal */ const oratext *getAttrNamespace(const xmlnode *attr); /*--------------------------------------------------------------------------- NAME getAttrPrefix [DOM X] FUNCTION Returns an attribute's namespace prefix DESCRIPTION Returns an attribute's namespace prefix (in the data encoding). If the attribute's name is not fully qualified (has no prefix), NULL is returned. EXAMPLE getAttrPrefix(attr pfx:bar) --> "pfx" RETURNS (oratext *) attribute's namespace prefix [in data encoding] or NULL ARGUMENTS attr (IN) attribute whose namespace prefix to return SEE ALSO getAttrQualifiedName, getAttrNamespace, getAttrLocal */ const oratext *getAttrPrefix(const xmlnode *attr); /*--------------------------------------------------------------------------- NAME getAttrLocal [DOM X] FUNCTION Returns an attribute's namespace local name DESCRIPTION Returns an attribute's namespace local name (in the data encoding). If the attribute's name is not fully qualified (has no prefix), then the local name is the same as the name. EXAMPLE getAttrLocal(attr pfx:bar) --> "bar" RETURNS (oratext *) string of local name [in data encoding] ARGUMENTS attr (IN) attribute whose local name to return */ const oratext *getAttrLocal(const xmlnode *attr); /*--------------------------------------------------------------------------- NAME getAttrSpecified [DOM 1 Attr.getSpecified] FUNCTION Returns an attribute's specified flag DESCRIPTION Return the 'specified' flag for an attribute. If the attribute was explicitly given a value in the original document, this is TRUE; otherwise, it is FALSE. If the node is not an attribute, returns FALSE. If the user sets an attribute's value through DOM, its specified flag will be TRUE. To return an attribute to its default value (if it has one), the attribute should be deleted-- it will then be re-created automatically with the default value (and specified will be FALSE). RETURNS (boolean) value of attribute's specified flag ARGUMENTS attr (IN) attribute node whose specified flag to return SEE ALSO setAttrValue */ boolean getAttrSpecified(const xmlnode *attr); /*--------------------------------------------------------------------------- NAME setAttrValue [DOM 1 Attr.value attribute] FUNCTION Sets an attribute's value DESCRIPTION Sets the given attribute's value to data. If the node is not an attribute, does nothing. Note that the new value must be in the data encoding! It is not verified, converted, or checked. If bad data is set for the attribute, bad things may happen-- GIGO! The attribute's specified flag will be TRUE after setting a new value. RETURNS (void) ARGUMENTS attr (IN) pointer to attribute node data (IN) new value for attribute [in data encoding] SEE ALSO getAttrSpecified, getAttrValue */ void setAttrValue(xmlnode *attr, const oratext *data); /*--------------------------------------------------------------------------- NAME getAttrValue [DOM 1 Attr.value attribute] FUNCTION Returns an attribute's value DESCRIPTION Returns the "value" (character data) of an attribute (in the data encoding). Character and general entities will have been replaced. RETURNS (oratext *) value of attribute [in data encoding] ARGUMENTS attr (IN) attribute whose value to return SEE ALSO setAttrValue */ const oratext *getAttrValue(const xmlnode *attr); /**************************************************************************** Interface Element ****************************************************************************/ /*--------------------------------------------------------------------------- NAME nodeValid [DOM X] FUNCTION Determines if a node is valid again a DTD DESCRIPTION Validates an element node (and its children) against the current DTD. If the node is not an Element, returns XMLERR_NODE_TYPE and does nothing. Only works on a DOM tree created by parsing with validation enabled; without initial validation, just returns success (no-op). RETURNS (uword) error code, XMLERR_OK [0] on success ARGUMENTS ctx (IN) XML context node (IN) root node to validate SEE ALSO xmlparse */ uword nodeValid(xmlctx *ctx, xmlnode *node); /*--------------------------------------------------------------------------- NAME getTagName [DOM 1] FUNCTION Returns the tagName of a node DESCRIPTION Returns the "tagName" of a node, which is the same as its name for now. The DOM says "...even though there is a generic nodeName attribute on the Node interface, there is still a tagName attribute on the Element interface; these two attributes must contain the same value, but the Working Group considers it worthwhile to support both, given the different constituencies the DOM API must satisfy." RETURNS (oratext *) node's tagname [in data encoding] ARGUMENTS node (IN) node whose tagname to return SEE ALSO getNodeName */ const oratext *getTagName(const xmlnode *node); /*--------------------------------------------------------------------------- NAME getAttribute [DOM 1] FUNCTION Returns an attribute's value given its name DESCRIPTION Returns the value of an element's attribute (specified by name). Note that an attribute may have the empty string as its value, but cannot be NULL. If the element does not have an attribute with the given name, NULL is returned. RETURNS (oratext *) attribute's value [in data encoding] or NULL ARGUMENTS node (IN) element whose attributes to check name (IN) name of attribute SEE ALSO getAttributes, getAttributeIndex, getAttributeNode */ const oratext *getAttribute(const xmlnode *node, const oratext *name); /*--------------------------------------------------------------------------- NAME getAttributeIndex [DOM X] FUNCTION Returns an attribute by index DESCRIPTION Given an xmlnodes list of attributes (from getAttributes), returns an attribute specified by index (position). The first attribute is index 0, the second is index 1, etc. If specified attribute does not exist (index is too large), returns NULL. RETURNS (xmlnode *) specified attribute or NULL ARGUMENTS attrs (IN) list of attributes from getAttributes index (IN) index of attribute to return (zero-based) SEE ALSO getAttributes, numAttributes, getAttribute */ xmlnode *getAttributeIndex(const xmlnodes *attrs, size_t index); /*--------------------------------------------------------------------------- NAME setAttribute [DOM 1] FUNCTION Creates an attribute for an element DESCRIPTION Creates a new attribute for an element with the given name and value (which should be in the data encoding). If the named attribute already exists, its value is simply replaced. The name and value are not verified, converted, or checked. If bad data is set, bad things may happen-- GIGO! The value is not parsed, so entity references will not be expanded. The attribute's Specified flag will be set. RETURNS (xmlnode *) pointer to (new or old) attribute node, or NULL ARGUMENTS ctx (IN) XML context elem (IN) element node name (IN) new attribute's name [in data encoding] value (IN) new attribute's value [in data encoding] SEE ALSO createAttribute, setAttrValue, removeAttribute */ xmlnode *setAttribute(xmlctx *ctx, xmlnode *elem, const oratext *name, const oratext *value); /*--------------------------------------------------------------------------- NAME setAttributeNode [DOM 1] FUNCTION Adds an attribute node to an element DESCRIPTION Adds a new attribute to an element. If an attribute with newNode's name already exists, it is replaced and the old attribute is returned through oldNode. If the attribute has a new name, it is added to the element's list and oldNode is set to NULL. RETURNS (boolean) success ARGUMENTS ctx (IN) XML context elem (IN) element node newNode (IN) new attribute node oldNode (OUT) replaced attribute or NULL SEE ALSO createAttribute, setAttrValue */ boolean setAttributeNode(xmlctx *ctx, xmlnode *elem, xmlnode *newNode, xmlnode **oldNode); /*--------------------------------------------------------------------------- NAME removeAttribute [DOM 1] FUNCTION Removes an attribute from an element (by name) DESCRIPTION Removes an attribute (specified by name). If the removed attribute has a default value it is immediately re-created with that default. Note that the attribute is removed from the element's list of attributes, but the Attr node itself is not destroyed. RETURNS (void) ARGUMENTS elem (IN) element node name (IN) name of attribute to remove [in data encoding] SEE ALSO removeAttributeNode */ void removeAttribute(xmlnode *elem, const oratext *name); /*--------------------------------------------------------------------------- NAME getAttributeNode [DOM 1] FUNCTION Returns the named attribute of an element DESCRIPTION Returns an element's attribute specified by name. If the node is not an element or the named attribute does not exist, returns NULL. RETURNS (xmlnode *) named attribute or NULL ARGUMENTS elem (IN) element node name (IN) name of attribute to get [in data encoding] SEE ALSO getAttribute, getAttributeIndex */ xmlnode *getAttributeNode(const xmlnode *elem, const oratext *name); /*--------------------------------------------------------------------------- NAME removeAttributeNode [DOM 1] FUNCTION Removes an attribute from an element (by pointer) DESCRIPTION Removes an attribute from an element. If the attribute has a default value, it is immediately re-created with that value (Specified set to FALSE). Returns the removed attribute on success, else NULL. RETURNS (xmlnode *) pointer to old attribute, or NULL on error ARGUMENTS elem (IN) element node attr (IN) removed attribute node or NULL SEE ALSO removeAttribute */ xmlnode *removeAttributeNode(xmlnode *elem, xmlnode *attr); /*--------------------------------------------------------------------------- NAME normalize [DOM 1] FUNCTION Merges adjacent text nodes in an element DESCRIPTION "Normalizes" the subtree rooted at an element, i.e. merges adjacent Text nodes children of elements. Note that adjacent Text nodes will never be created during a normal parse, only after manipulation of the document with DOM calls. EXAMPLE "XXX" "YYY""111" "222" normalize(node a) --> "XXXYYY""111222" RETURNS (void) ARGUMENTS ctx (IN) XML context elem (IN) root of subtree to normalize */ void normalize(xmlctx *ctx, xmlnode *elem); /**************************************************************************** Interface DOMImplementation ****************************************************************************/ /*--------------------------------------------------------------------------- NAME createDocument [DOM X] FUNCTION Creates a new Document node (non-namespace) DESCRIPTION Creates the top-level Document node in an xmlctx. Each context can only contain a single document, rooted in a Document node. If the context already contains a document, it is returned. Otherwise a new Document node is created and set in the context. This is a non-namespace-aware function; the Document will have NULL namespace URI and prefix and have the name "#document". If a DTD (as created by createDocumentType) is specified (not NULL), it is added as a child of the document. The DTD must not already be a child of another document! RETURNS (xmlnode *) existing or created Document node ARGUMENTS ctx (IN) XML context SEE ALSO createDocumentNS, createDocumentType */ xmlnode* createDocument(xmlctx *ctx); /*--------------------------------------------------------------------------- NAME createDocumentNS [DOM 2 createDocument] FUNCTION Creates a new Document node (namespace-aware) DESCRIPTION Creates the top-level Document node in an xmlctx. Each context can only contain a single document, rooted in a Document node. If the context already contains a document, it is returned. Otherwise a new Document node is created and set in the context. This is a namespace-aware function; the Document's namespace URI and QName should be specified (but may be NULL). If no name is provided, the document will be named "#document". If a DTD (as created by createDocumentType) is specified (not NULL), it is added as a child of the document. The DTD must not already be a child of another document! RETURNS (xmlnode *) existing or created Document node ARGUMENTS ctx (IN) XML context imp (IN) DOMImplementation structure uri (IN) document's namespace URI [in data encoding] or NULL qname (IN) document's qualified name [in data encoding] or NULL dtd (IN) document type (DTD) SEE ALSO createDocument, createDocumentType */ xmlnode* createDocumentNS(xmldomimp *imp, oratext *uri, oratext *qname, xmlnode *dtd); /*--------------------------------------------------------------------------- NAME createDocumentType [DOM 2] FUNCTION Creates a new DTD node DESCRIPTION Creates and returns a DOCUMENT_TYPE (DTD) node. Currently there is no way to populate the DTD; this function is provided in anticipation of future DOM versions. The DTD may be associated with a new Document by createDocument or createDocumentNS. RETURNS (xmlnode *) created DTD node ARGUMENTS imp (IN) DOMImplementation structure qname (IN) DTD's qualified name [in data encoding] pubid (IN) DTD's public identifier [in data encoding] sysid (IN) DTD's system identifier [in data encoding] SEE ALSO createDocument, createDocumentNS */ xmlnode* createDocumentType(xmldomimp *imp, oratext *qname, oratext *pubid, oratext *sysid); /*--------------------------------------------------------------------------- NAME hasFeature [DOM 1] FUNCTION Tests if the DOM implementation supports a feature DESCRIPTION Tests if the DOM implementation supports a named feature with a certain version. Note that version can only be "1.0" or "2.0" at present. If omitted, supporting any version of the feature returns TRUE. DOM 1.0 FEATURES "XML" XML module "HTML" HTML module DOM 2.0 FEATURES "Core" Core module "XML" XML module "HTML" HTML module "Views" Views module "StyleSheets" Style Sheets module "CSS" CSS module "CSS2" CSS2 module "Events" Events module "UIEvents" User interface Events module "MouseEvents" Mouse Events module "MutationEvents" Mutation Events module "HTMLEvents" HTML Events module "Range" Range module "Traversal" Traversal module RETURNS (boolean) Feature is implemented in the specified version ARGUMENTS imp (IN) XML DOMImplementation structure feature (IN) case-insensitive name of the feature [in data encoding] version (IN) version of feature [in data encoding] */ boolean hasFeature(xmldomimp *imp, const oratext *feature, const oratext *version); /**************************************************************************** Interface Document ****************************************************************************/ /*--------------------------------------------------------------------------- NAME getDocType [DOM 1 Document.DocumentType attribute] FUNCTION Returns the current document's DTD DESCRIPTION Returns the DTD node associated with current document. The DTD cannot be edited, but its children may be retrieved with getChildNodes as for other node types. RETURNS (xmlnode *) DTD node ARGUMENTS ctx (IN) XML context SEE ALSO createDocumentType, createDocument, createDocumentNS, getDocTypeName, getDocTypeEntities, getDocTypeNotations */ xmlnode* getDocType(xmlctx *ctx); /*--------------------------------------------------------------------------- NAME getImplementation [DOM 1] FUNCTION Returns a DOM implementation structure DESCRIPTION Returns the DOM-implementation-specific descriptor. Used to probe the implementation with hasFeature, or to create new Document or DTDs. RETURNS (xmldomimp *) DOM implementation ARGUMENTS ctx (IN) XML context SEE ALSO createDocument, createDocumentNS, createDocumentType, hasFeature */ xmldomimp* getImplementation(xmlctx *ctx); /*--------------------------------------------------------------------------- NAME getDocument [DOM X] FUNCTION Returns the Document node DESCRIPTION Returns the root node of the DOM tree, which is a Document node, or NULL if there is none. The Document node is created automatically when a document is parsed successfully, or manually by createDocument or createDocumentNS. RETURNS (xmlnode *) Document node or NULL ARGUMENTS ctx (IN) XML context SEE ALSO createDocument, createDocumentNS */ xmlnode* getDocument(xmlctx *ctx); /*--------------------------------------------------------------------------- NAME getDocumentElement [DOM 1] FUNCTION Returns the root element node DESCRIPTION Returns the root element (node) of the DOM tree, or NULL if there is none. Each document has only one uppermost Element node, called the root element. It is created after a document is parsed successfully, or manually by createElement then appendChild, etc. RETURNS (xmlnode *) root element node or NULL ARGUMENTS ctx (IN) XML context SEE ALSO createElement */ xmlnode* getDocumentElement(xmlctx *ctx); /*--------------------------------------------------------------------------- NAME createElement [DOM 1] FUNCTION Creates an element node (non-namespace) DESCRIPTION Creates an element node with the given tag name (which should be in the data encoding). Note that the tag name of an element is CASE SENSITIVE. This is the non-namespace aware function: the new node will have NULL namespace URI and prefix, and its local name will be the same as its tag name, even if the tag name specified is a QName. The new node is an orphan with no parent; it must be added to the DOM tree with appendChild etc. RETURNS (xmlnode *) new element node ARGUMENTS ctx (IN) XML context tagName (IN) new element's name [in data encoding] SEE ALSO createElementNS */ xmlnode *createElement(xmlctx *ctx, const oratext *tagName); /*--------------------------------------------------------------------------- NAME createElementNS [DOM 2] FUNCTION Creates an element node (namespace-aware) DESCRIPTION Creates an element with the given namespace URI and QName. Note that element names are CASE SENSITIVE, and the QName is required though the URI may be NULL. The QName will be split into prefix and local parts, retrievable with getNodePrefix, getNodeLocal, etc; the tagName will be the full QName. The new node is an orphan with no parent; it must be added to the DOM tree with appendChild etc. RETURNS (xmlnode *) new element node ARGUMENTS ctx (IN) XML context uri (IN) new element's namespace URI [in data encoding] qname (IN) new element's QName [in data encoding] SEE ALSO createElement */ xmlnode *createElementNS(xmlctx *ctx, const oratext *uri, const oratext*qname); /*--------------------------------------------------------------------------- NAME createDocumentFragment [DOM 1] FUNCTION Creates an empty document fragment node DESCRIPTION Creates an empty Document Fragment node. A document fragment is treated specially when it is inserted into a DOM tree: the children of the fragment are inserted in order instead of the fragment node itself. After insertion, the fragment node will still exist, but have no children. See insertBefore, replaceChild, appendChild, etc. The name of a fragment node is always "#document-fragment". RETURNS (xmlnode *) new document fragment node ARGUMENTS ctx (IN) XML context SEE ALSO insertBefore, replaceChild, appendChild */ xmlnode *createDocumentFragment(xmlctx *ctx); /*--------------------------------------------------------------------------- NAME createTextNode [DOM 1] FUNCTION Creates a text node DESCRIPTION Creates a Text node with the given initial data (which must be non-NULL and in the data encoding). The data may be NULL; if provided, it is not verified, converted, checked, or parsed (entities will not be expanded). If bad data is set, bad things may happen-- GIGO! The name of a fragment node is always "#text". New data for a Text node can be set with setNodeValue; see the CharacterData interface for editing methods. The new node is an orphan with no parent; it must be added to the DOM tree with appendChild etc. RETURNS (xmlnode *) new Text node ARGUMENTS ctx (IN) XML context data (IN) initial data [in data encoding] or NULL SEE ALSO setNodeValue, getNodeValue, setCharData, getCharData, getCharLength, substringData, appendData, insertData, deleteData, replaceData */ xmlnode *createTextNode(xmlctx *ctx, const oratext *data); /*--------------------------------------------------------------------------- NAME createComment [DOM 1] FUNCTION Creates a comment node DESCRIPTION Creates a Comment node with the given initial data (which must be in the data encoding). The data may be NULL; if provided, it is not verified, converted, or checked. If bad data is set, bad things may happen-- GIGO! The name of a Comment node is always "#comment". The new node is an orphan with no parent; it must be added to the DOM tree with appendChild etc. RETURNS (xmlnode *) new Comment node ARGUMENTS ctx (IN) XML context data (IN) initial data [in data encoding] or NULL */ xmlnode *createComment(xmlctx *ctx, const oratext *data); /*--------------------------------------------------------------------------- NAME createCDATASection [DOM 1] FUNCTION Creates a CDATA node DESCRIPTION Creates a CDATASection node with the given initial data (which should be in the data encoding). A CDATA section is considered verbatim and is never parsed; it will not be joined with adjacent Text nodes by the normalize operation. The initial data may be NULL; if provided, it is not verified, converted, or checked. If bad data is set, bad things may happen-- GIGO! The name of a CDATA node is always "#cdata-section". The new node is an orphan with no parent; it must be added to the DOM tree with appendChild etc. RETURNS (xmlnode *) new CDATA node ARGUMENTS ctx (IN) XML context data (IN) initial data [in data encoding] SEE ALSO createTextNode */ xmlnode *createCDATASection(xmlctx *ctx, const oratext *data); /*--------------------------------------------------------------------------- NAME createProcessingInstruction [DOM 1] FUNCTION Creates a PI node DESCRIPTION Creates a Processing Instruction node with the given target and data (which should be in the data encoding). The data may be NULL initially, and may be changed later (with setPIData), but the target is required and cannot be changed. Note the target and data are not verified, converted, or checked. If bad data is set, bad things may happen-- GIGO! The name of a PI node is the same as the target. The new node is an orphan with no parent; it must be added to the DOM tree with appendChild etc. RETURNS (xmlnode *) new PI node ARGUMENTS ctx (IN) XML context target (IN) PI's target [in data encoding] data (IN) PI's data [in data encoding] or NULL SEE ALSO getPITarget, getPIData, setPIData */ xmlnode *createProcessingInstruction(xmlctx *ctx, const oratext *target, const oratext *data); /*--------------------------------------------------------------------------- NAME createAttribute [DOM 1] FUNCTION Creates an attribute node (non-namespace) DESCRIPTION Creates an attribute node with the given name and value (in the data encoding). Note this function differs from the DOM specification, which does not allow the initial value of the attribute to be set (see setAttrValue). The name is required, but the value may be NULL; neither is verified, converted, or checked. If bad data is set, bad things may happen-- GIGO! This is the non-namespace aware function (see createAttributeNS): the new attribute will have NULL namespace URI and prefix, and its local name will be the same as its name, even if the name specified is a QName. See the Attr interface for more attribute manipulation methods. If given an initial value, the attribute's specified flag will be TRUE. The new node is an orphan with no parent; it must be added to the DOM tree with appendChild etc. See setAttribute which creates and adds an attribute in a single operation. RETURNS (xmlnode *) new attribute node ARGUMENTS ctx (IN) XML context name (IN) attribute's name [in data encoding] value (IN) attribute's value [in data encoding] or NULL SEE ALSO setAttrValue, createAttributeNS, setAttribute */ xmlnode *createAttribute(xmlctx *ctx, const oratext *name, const oratext *value); /*--------------------------------------------------------------------------- NAME createAttributeNS [DOM 2] FUNCTION Creates an attribute node (namespace-aware) DESCRIPTION Creates an attribute node with the given namespace URI and QName; this is the namespace-aware version of createAttribute. Note this function differs from the DOM specification, which does not allow the initial value of the attribute to be set (see setAttrValue). The name is required, but the value may be NULL; neither is verified, converted, or checked. If bad data is set, bad things may happen-- GIGO! If given an initial value, the attribute's specified flag will be TRUE. The new node is an orphan with no parent; it must be added to the DOM tree with appendChild etc. See setAttribute which creates and adds an attribute in a single operation. RETURNS (xmlnode *) new attribute node ARGUMENTS ctx (IN) XML context uri (IN) attribute's namespace URI [in data encoding] or NULL qname (IN) attribute's qualified name [in data encoding] value (IN) attribute's initial value [in data encoding] or NULL SEE ALSO setAttrValue, createAttribute, setAttribute */ xmlnode *createAttributeNS(xmlctx *ctx, const oratext *uri, const oratext *qname, const oratext *value); /*--------------------------------------------------------------------------- NAME createEntityReference [DOM 1] FUNCTION Creates an entity reference node DESCRIPTION Creates an Entity Reference node; the name (which should be in the data encoding) is the name of the entity to be referenced. The named entity does not have to exist. The name is not verified, converted, or checked. If bad data is set, bad things may happen-- GIGO! Entity Reference nodes are never generated by the parser; instead, entity references are expanded as encountered. On output, an entity reference node will turn into a "&name;" style reference. The new node is an orphan with no parent; it must be added to the DOM tree with appendChild etc. RETURNS (xmlnode *) new entity reference node ARGUMENTS ctx (IN) XML context name (IN) name of referenced entity [in data encoding] */ xmlnode *createEntityReference(xmlctx *ctx, const oratext *name); /*--------------------------------------------------------------------------- NAME getElementsByTagName [DOM 1] FUNCTION Returns the elements matching a name (non-namespace) DESCRIPTION Returns a list of all elements (in the document tree rooted at the root node) with a given tag name, in the order in which they would be encountered in a preorder traversal of the tree. If root is NULL, the entire document is searched. The tag name should be in the data encoding. The special name "*" matches all tag names; a NULL name matches nothing. Note that tag names are CASE SENSITIVE. This function is not namespace aware; the full tag names are compared. If two prefixes which map to the same URI are compared, the comparison will fail. See getElementsByTagNameNS for the namespace- aware version. The returned list can be freed with freeElements. RETURNS (xmlnodes *) list of matching nodes ARGUMENTS ctx (IN) XML context root (IN) root of search tree tagName (IN) tagName to match or "*" [in data encoding] SEE ALSO getElementsByTagNameNS, freeElements */ xmlnodes *getElementsByTagName(xmlctx *ctx, xmlnode *node, const oratext *tagName); /*--------------------------------------------------------------------------- NAME getElementsByTagNameNS [DOM 2] FUNCTION Returns the elements matching a namespace URI and local DESCRIPTION Returns a list of all elements (in the document tree rooted at the given node) with a given namespace URI and local name, in the order in which they would be encountered in a preorder traversal of the tree. If root is NULL, the entire document is searched. The URI and local name should be in the data encoding. The special local name "*" matches all local names; a NULL local name matches nothing. Namespace URIs must always match, however. Note that comparisons are CASE SENSITIVE. See getElementsByTagName for the non-namespace aware version. The returned list can be freed with freeElements. RETURNS (xmlnodes *) list of nodes containing all the matched elements ARGUMENTS ctx (IN) XML context root (IN) root node uri (IN) namespace URI [in data encoding] local (IN) namespace local name or "*" [in data encoding] SEE ALSO getElementsByTagName, freeElements */ xmlnodes *getElementsByTagNameNS(xmlctx *ctx, xmlnode *node, const oratext *uri, const oratext *local); /*--------------------------------------------------------------------------- NAME getElementByID [DOM 2] FUNCTION Returns the element with the given ID DESCRIPTION Returns the element node which has the given ID. If no such ID is defined, returns NULL. Note that attributes named "ID" are not automatically of type ID; ID attributes (which can have any name) must be declared as type ID in the DTD. RETURNS (xmlnode *) matching element node or NULL ARGUMENTS ctx (IN) XML context id (IN) element ID [in data encoding] */ xmlnode *getElementByID(xmlctx *ctx, oratext *id); /*--------------------------------------------------------------------------- NAME importNode [DOM 2] FUNCTION Copies a node from one document to another DESCRIPTION Imports a node from one Document to another. The new node is an orphan and has no parent; it must be added to the DOM tree with appendChild, etc. The original node is not modified in any way or removed from its document; instead, a new node is created with copies of all the original node's QName, prefix, namespace URI, and local name. As with cloneNode, the deep controls whether the children of the node are recursively imported. If FALSE, only the node itself is imported, and it will have no children. If TRUE, all descendents of the node will be imported as well, and an entire new subtree created. Document and DocumentType nodes cannot be imported. Imported attributes will have their specified flags set to TRUE. Elements will have only their specified attributes imported; non-specified (default) attributes are omitted. New default attributes (for the destination document) are then added. RETURNS (xmlnode *) element node with given ID ARGUMENTS ctx (IN) XML context import (IN) node to import deep (IN) recursively import children? SEE ALSO cloneNode */ xmlnode *importNode(xmlctx *ctx, xmlnode *import, boolean deep); /**************************************************************************** Interface NamedNodeMap ****************************************************************************/ /*--------------------------------------------------------------------------- NAME getNamedItem [DOM 1] FUNCTION Returns an item from a node map by name DESCRIPTION Retrieves an item from a NamedNodeMap, specified by name (which should be in the data encoding). This is a non-namespace-aware function; it just matches (case sensitively) on the whole QName. Note this function differs from the DOM spec in that the index of the matching item is also returned. RETURNS (xmlnode *) matching node or NULL ARGUMENTS nodes (IN) node map name (IN) name of node to retrieve [in data encoding] index (OUT) index of node, if found SEE ALSO setNamedItem, removeNamedItem, getChildNode */ xmlnode *getNamedItem(const xmlnodes *nodes, const oratext *name, size_t *index); /*--------------------------------------------------------------------------- NAME setNamedItem [DOM 1] FUNCTION Add a new item to a node map DESCRIPTION Adds a new node to a NamedNodeMap. If a node already exists with the given name, replaces the old node and returns it. If no such named node exists, adds the new node to the map and sets old to NULL. This is a non-namespace-aware function; it just matches (case sensitively) on the whole QName. Since some node types have fixed names (Text, Comment, etc), trying to set another of the same type will always cause replacement. RETURNS (boolean) success, node added or replaced ARGUMENTS ctx (IN) XML context nodes (IN) node map node (IN) new node to set old (OUT) replaced node or NULL SEE ALSO getNamedItem, removeNamedItem */ boolean setNamedItem(xmlctx *ctx, xmlnodes *nodes, xmlnode *node, xmlnode **old); /*--------------------------------------------------------------------------- NAME removeNamedItem [DOM 1] FUNCTION Removes an item from a node map by name DESCRIPTION Removes a node from a NamedNodeMap, specified by name. This is a non-namespace-aware function; it just matches (case sensitively) on the whole QName. If the removed node is an attribute with default value (not specified), it is immediately replaced. The removed node is returned; if no removal took place, NULL is returned. RETURNS (xmlnode *) the removed node or NULL ARGUMENTS nodes (IN) node map name (IN) name of node to remove [in data encoding] SEE ALSO getNamedItem, setNamedItem */ xmlnode *removeNamedItem(xmlnodes *nodes, const oratext *name); /*--------------------------------------------------------------------------- NAME getChildNode [DOM 1 item] FUNCTION Return an item from a node map by index DESCRIPTION Returns the indexth node in a NamedNodeMap, or NULL if there is no such node. Indexes are zero-based, so the first node is index 0. RETURNS (xmlnode *) indexth node or NULL ARGUMENTS nodes (IN) node map index (IN) index of node to return (0-based) SEE ALSO getNamedItem */ xmlnode *getChildNode(const xmlnodes *nodes, size_t index); /*--------------------------------------------------------------------------- NAME getNodeMapLength [DOM 1 NamedNodeMap.length attribute] FUNCTION Returns the length of a node map DESCRIPTION Returns the number of nodes in a NamedNodeMap (the length). Note that nodes are referred to by index, and the range of valid indexes is 0 through length-1. RETURNS (size_t) number of nodes in map ARGUMENTS nodes (IN) node map SEE ALSO getChildNode */ size_t getNodeMapLength(const xmlnodes *nodes); /**************************************************************************** Interface CharacterData ****************************************************************************/ /*--------------------------------------------------------------------------- NAME getCharData [DOM 1 getData] FUNCTION Returns the data for a character node DESCRIPTION Returns the data for a CharacterData node (type Text, Comment or CDATASection) in the data encoding. For other node types, or if there is no data, returns NULL. RETURNS (oratext *) node's data [in the data encoding] ARGUMENTS node (IN) node whose data to return SEE ALSO setCharData, createTextNode, createComment, createCDATASection */ const oratext *getCharData(const xmlnode *node); /*--------------------------------------------------------------------------- NAME setCharData [DOM 1 setData] FUNCTION Sets the data for a character node DESCRIPTION Sets data for a CharacterData node (type Text, Comment or CDATASection), replacing the old data. For other node types, does nothing. The new data is not verified, converted, or checked-- it should be in the data encoding. If bad data is set, bad things may happen-- GIGO! RETURNS (void) ARGUMENTS node (IN) node whose data to set data (IN) new data for node [in data encoding] SEE ALSO getCharData */ void setCharData(xmlnode *node, const oratext *data); /*--------------------------------------------------------------------------- NAME getCharLength [DOM 1 getLength] FUNCTION Returns the length of a character node's data DESCRIPTION Returns the length of the data for a CharacterData node (type Text, Comment or CDATASection). For other node types, returns 0. Note the the data is the data encoding, and the returned length is in characters, not bytes. RETURNS (size_t) length of data [in characters] ARGUMENTS node (IN) node whose data length to return SEE ALSO getCharData */ size_t getCharLength(const xmlnode *node); /*--------------------------------------------------------------------------- NAME substringData [DOM 1] FUNCTION Returns a substring of a character node's data DESCRIPTION Returns a range of character data from a CharacterData node (type Text, Comment or CDATASection). For other node types, or if count is zero, returns NULL. Since the data is in the data encoding, offset and count are in characters, not bytes. The beginning of the string is offset 0. If the sum of offset and count exceeds the length, then all characters to the end of the data are returned. EXAMPLE Given a node with data "abcdefgh", substringData(offset=0, length=1) --> "a" substringData(offset=5, length=5) --> "fgh" RETURNS (oratext *) specified substring or NULL ARGUMENTS ctx (IN) XML context node (IN) node whose substring to extract offset (IN) starting offset of substring [zero based, in characters] count (IN) length of substring [in characters] SEE ALSO appendData, insertData, deleteData, replaceData, splitText */ const oratext *substringData(xmlctx *ctx, const xmlnode *node, ub4 offset, ub4 count); /*--------------------------------------------------------------------------- NAME appendData [DOM 1] FUNCTION Appends to a character node's data DESCRIPTION Append a string to the end of a CharacterData node's data. If the node is not Text, Comment or CDATASection, or if the string to append is NULL, does nothing. The appended data should be in the data encoding. It will not be verified, converted, or checked. If bad data is appended, bad things may happen-- GIGO! RETURNS (void) ARGUMENTS ctx (IN) XML context node (IN) node whose data to append to arg (IN) string to append [in data encoding] SEE ALSO getCharData, insertData, deleteData, replaceData, splitText */ void appendData(xmlctx *ctx, xmlnode *node, const oratext *arg); /*--------------------------------------------------------------------------- NAME insertData [DOM 1] FUNCTION Inserts into a character node's data DESCRIPTION Insert a string into a CharacterData node's data at the specified position. If the node is not Text, Comment or CDATASection, or if the data to be inserted is NULL, or the offset is outside the original data, does nothing. The inserted data must be in the data encoding. It will not be verified, converted, or checked. If bad data is appended, bad things may happen-- GIGO! The offset is specified as characters, not bytes. The offset is zero-based, so inserting at offset zero prepends the data. EXAMPLE Given a node with data "abcdefgh", insertData(offset=0, arg="FOO") --> "FOOabcdefgh" insertData(offset=5, arg="*") --> "abcde*fgh" RETURNS (void) ARGUMENTS ctx (IN) XML context node (IN) node whose data to insert string to offset (IN) offset at which to insert [in characters] arg (IN) string to insert [in data encoding] SEE ALSO getCharData, appendData, deleteData, replaceData, splitText */ void insertData(xmlctx *ctx, xmlnode *node, ub4 offset, const oratext *arg); /*--------------------------------------------------------------------------- NAME deleteData [DOM 1] FUNCTION Removes part of a character node's data DESCRIPTION Remove a range of characters from a CharacterData node's data. If the node is not Text, Comment or CDATASection, or if the offset is outside of the original data, does nothing. The offset is zero-based, so offset zero refers to the start of the data. Both offset and count are in characters, not bytes. If the sum of offset and count exceeds the data length then all characters from offset to the end of the data are deleted. EXAMPLE Given a node with data "abcdefgh", deleteData(offset=0, count=2) --> "cdefgh" deleteData(offset=5, count=5) --> "abcde" RETURNS (void) ARGUMENTS ctx (IN) XML context node (IN) node whose data to delete string from offset (IN) offset to remove from [in characters] count (IN) number of characters to remove SEE ALSO getCharData, appendData, insertData, replaceData, splitText */ void deleteData(xmlctx *ctx, xmlnode *node, ub4 offset, ub4 count); /*--------------------------------------------------------------------------- NAME replaceData [DOM 1] FUNCTION Replaces part of a character node's data DESCRIPTION Replaces a range of characters in a CharacterData node's data with a new string. If the node is not Text, Comment or CDATASection, or if the offset is outside of the original data, or if the replacement string is NULL, does nothing. If the count is zero, acts just as insertData. The offset is zero-based, so offset zero refers to the start of the data. The replacement data must be in the data encoding. It will not be verified, converted, or checked. If bad data is set, bad things may happen-- GIGO! The offset and count are both in characters, not bytes. If the sum of offset and count exceeds length, then all characters to the end of the data are replaced. EXAMPLE Given a node with data "abcdefgh", replaceData(offset=0, count=1, arg="FOO") --> "FOObcdefgh" replaceData(offset=2, count=2, arg="*") --> "ab*efgh" replaceData(offset=5, count=5, arg="*") --> "abcde*" RETURNS (void) ARGUMENTS ctx (IN) XML context node (IN) node whose data to edit offset (IN) offset of original substring count (IN) length of substring [in characters] arg (IN) string to replace with [in data encoding] SEE ALSO getCharData, appendData, insertData, deleteData, splitText */ void replaceData(xmlctx *ctx, xmlnode *node, ub4 offset, ub4 count, const oratext *arg); /**************************************************************************** Interface Text ****************************************************************************/ /*--------------------------------------------------------------------------- NAME splitText [DOM 1] FUNCTION Splits one text node into two DESCRIPTION Splits a single Text node into two Text nodes; the original data is split between them. If the given node is not type Text, or the offset is outside of the original data, does nothing and returns NULL. The offset is zero-based, and is in characters, not bytes. The original node is retained, its data is just truncated. A new Text node is created which contains the remainder of the original data, and is inserted as the next sibling of the original. The new Text node is returned. EXAMPLE Given a Text node with data "abcdefgh", splitText(1) --> Text("a"), Text("bcdefgh") splitText(5) --> Text("abcde"), Text("fgh") RETURNS (xmlnode *) new Text node or NULL ARGUMENTS ctx (IN) XML context old (IN) Text node to split offset (IN) split point [zero based] SEE ALSO getCharData, appendData, insertData, deleteData, replaceData */ xmlnode *splitText(xmlctx *ctx, xmlnode *old, uword offset); /**************************************************************************** Interface DocumentType ****************************************************************************/ /*--------------------------------------------------------------------------- NAME getDocTypeName [DOM 1 DocumentType.getName] FUNCTION Returns the name of a DTD DESCRIPTION Returns a DTD's name (specified immediately after the DOCTYPE keyword), or NULL if the node is not DocumentType. RETURNS (oratext *) name of DTD [in data encoding] or NULL ARGUMENTS node (IN) DTD node SEE ALSO getDocType, getDocTypeEntities, getDocTypeNotations, getContentModel */ const oratext *getDocTypeName(xmlnode* node); /*--------------------------------------------------------------------------- NAME getDocTypeEntities [DOM 1 DocumentType.getEntities] FUNCTION Returns a DTD's general entities DESCRIPTION Returns a NamedNodeMap of general entities defined by the DTD. If the node is not DocumentType, or has no general entities, returns NULL. The nodes in the map will be of type Entity. RETURNS (xmlnodes *) pointer to (general) entities for DTD ARGUMENTS node (IN) map of DTD's entities SEE ALSO getDocType, getDocTypeName, getDocTypeNotations, getContentModel */ xmlnodes *getDocTypeEntities(xmlnode* node); /*--------------------------------------------------------------------------- NAME getDocTypeNotations [DOM 1 DocumentType.getNotations] FUNCTION Returns a DTD's notations DESCRIPTION Returns NamedNodeMap of notations declared by the DTD. If the node is not DocumentType or has no notations, returns NULL. Nodes in the map will be of type Notation. RETURNS (xmlnodes *) map of DTD's notations ARGUMENTS node (IN) pointer to DTD node (as returned by getDocType) SEE ALSO getDocType, getDocTypeName, getDocTypeEntities, getContentModel */ xmlnodes *getDocTypeNotations(xmlnode* node); /*--------------------------------------------------------------------------- NAME getContentModel [DOM X] FUNCTION Returns the content model of the named element DESCRIPTION Returns the root node of the content model tree for a named element. If an element by the given name does not exist, returns NULL. The name must be in the data encoding, and is case sensitive. Nodes in the content model subtree will be one of the following Content Particle (CP) types: CP_ELEMENT_NODE, CP_CHOICE_NODE, CP_SEQUENCE_NODE, CP_PCDATA_NODE, CP_STAR_NODE, CP_PLUS_NODE, or CP_OPT_NODE RETURNS (xmlnode *) pointer to root CP node ARGUMENTS node (IN) DTD node name (IN) element's name [in data encoding] SEE ALSO getDocType, getDocTypeName, getDocTypeEntities, getDocTypeNotations */ xmlnode *getContentModel(xmlnode *node, oratext *name); /**************************************************************************** Interface Notation ****************************************************************************/ /*--------------------------------------------------------------------------- NAME getNotationPubID [DOM 1 Notation.publicId attribute] FUNCTION Returns the public ID of a notation DESCRIPTION Return a notation's public identifier (in the data encoding). If the node is not a Notation, or has no defined public ID, returns NULL. RETURNS (oratext *) node's public ID [in data encoding] or NULL ARGUMENTS note (IN) Notation node SEE ALSO getNotationSysID */ const oratext *getNotationPubID(const xmlnode *note); /*--------------------------------------------------------------------------- NAME getNotationSysID [DOM 1 Notation.systemId attribute] FUNCTION Returns the system ID of a notation DESCRIPTION Return a notation's system identifier (in the data encoding). If the node is not a Notation, or has no defined system ID, returns NULL. RETURNS (oratext *) node's system ID [in data encoding] or NULL ARGUMENTS note (IN) Notation node SEE ALSO getNotationPubID */ const oratext *getNotationSysID(const xmlnode *note); /**************************************************************************** Interface Entity ****************************************************************************/ /*--------------------------------------------------------------------------- NAME getEntityPubID [DOM 1 Entity.getPublicId] FUNCTION Returns the public ID of an entity DESCRIPTION Returns an entity's public identifier (in the data encoding). If the node is not an Entity, or has no defined public ID, returns NULL. RETURNS (oratext *) entity's public ID [in data encoding] or NULL ARGUMENTS ent (IN) Entity node SEE ALSO getEntitySysID, getEntityNotation */ const oratext *getEntityPubID(const xmlnode *ent); /*--------------------------------------------------------------------------- NAME getEntitySysID [DOM 1 Entity.getSystemId] FUNCTION Returns the system ID of an entity DESCRIPTION Returns an entity's system identifier (in the data encoding). If the node is not an Entity, or has no defined system ID, returns NULL. RETURNS (oratext *) entity's system ID [in data encoding] or NULL ARGUMENTS ent (IN) Entity node SEE ALSO getEntityPubID, getEntityNotation */ const oratext *getEntitySysID(const xmlnode *ent); /*--------------------------------------------------------------------------- NAME getEntityNotation [DOM 1 Entity.getNotationName] FUNCTION Returns the notation name of an entity DESCRIPTION For unparsed entities, returns the name of its notation (in the data encoding). For parsed entities and other node types, returns NULL. RETURNS (oratext *) entity's NDATA [in data encoding] or NULL ARGUMENTS ent (IN) Entity node SEE ALSO getEntityPubID, getEntitySysID */ const oratext *getEntityNotation(const xmlnode *ent); /**************************************************************************** Interface ProcessingInstruction ****************************************************************************/ /*--------------------------------------------------------------------------- NAME getPITarget [DOM 1 ProcessingInstruction.getTarget] FUNCTION Returns the target of a PI DESCRIPTION Returns a Processing Instruction's (PI) target string. If the node is not a PI, returns NULL. The target is the first token following the markup that begins the PI. All PIs must have a target, though the data part is optional. EXAMPLE getPITarget --> "rating" RETURNS (oratext *) PI's target [in data encoding] ARGUMENTS pi (IN) PI node SEE ALSO getPIData, setPIData */ const oratext *getPITarget(const xmlnode *pi); /*--------------------------------------------------------------------------- NAME getPIData [DOM 1 ProcessingInstruction.getData] FUNCTION Returns the data of a PI DESCRIPTION Returns the content (data) of a Processing Instruction (in the data encoding). If the node is not a PI, returns NULL. The content is the part from the first non-whitespace character after the target until the ending "?>". EXAMPLE getPIData --> "extra saucy" RETURNS (oratext *) PI's data [in data encoding] ARGUMENTS pi (IN) PI node SEE ALSO setPIData, getPITarget */ const oratext *getPIData(const xmlnode *pi); /*--------------------------------------------------------------------------- NAME setPIData [DOM 1 ProcessingInstruction.setData] FUNCTION Sets the data of a PI DESCRIPTION Set's a Processing Instruction's (PI) data (content), which must be in the data encoding. It is not permitted to set the data to NULL. If the node is not a PI, does nothing. The new data is not verified, converted, or checked. If bad data is set, bad things may happen-- GIGO! RETURNS (void) ARGUMENTS pi (IN) PI node data (IN) new content [in data encoding] SEE ALSO getPIData, getPITarget */ void setPIData(xmlnode *pi, const oratext *data); /*--------------------------------------------------------------------------- Package XSLT - XSLT and XPath APIs A software module called an XSL processor is used to read XML documents and transform them into other XML documents with different styles. The C implementation of the XSL processor follows the XSL Transformations standard (version 1.0, November 16, 1999) and implements the required behavior of an XSL processor as specified in the XSLT specification. ---------------------------------------------------------------------------*/ /**************************************************************************** Interface XSLProcessor ****************************************************************************/ /*--------------------------------------------------------------------------- NAME xslprocess FUNCTION Process XSL DESCRIPTION This function processes XSL Stylesheet with XML document source. Since this function returns a DOM document fragment node, it doesn't support xsl:output. To use xsl:output, call xslsetoutputstream and xslprocessxml. RETURNS (uword) error code, XMLERR_OK [0] on success ARGUMENTS xmlctx (I/O) XML document context xsl (IN) XSL stylesheet context resctx (IN) result document fragment context result (I/O) result document fragment node */ uword xslprocess(xmlctx *docctx, xmlctx *xsl, xmlctx *resctx, xmlnode **result); /*--------------------------------------------------------------------------- NAME xslprocessex FUNCTION Process XSL DESCRIPTION This function processes XSL Stylesheet with XML document source. User can specify a list of top-level parameters to be set before parsing begins. Since this function returns a DOM document fragment node, it doesn't support xsl:output. To use xsl:output, call xslsetoutputstream and xslprocessxml. RETURNS (uword) error code, XMLERR_OK [0] on success ARGUMENTS xmlctx (I/O) XML document context xsl (IN) XSL stylesheet context resctx (IN) result document fragment context nparams (IN) number of [params,vals] pairs to be passed params (IN) array of name of pars [must be nparams in count] vals (IN) array of value of pars [must be nparams in count] baseuri (IN) string giving the base uri for style sheet result (I/O) result document fragment node */ uword xslprocessex(xmlctx *docctx, xmlctx *xsl, xmlctx *resctx, size_t nparams, oratext * params[], oratext * vals[], oratext * baseuri, xmlnode **result); /*--------------------------------------------------------------------------- NAME xslinit FUNCTION Initialize XSL context DESCRIPTION This routine is used to create the XSL processing context to process one or more input XML DOM tree (specified through a XML context). This context holds all the variables, states and global parameters required to process a given XML DOM tree. Depending on the choice of the user, processing can generate its output in any one of following 3 forms: SAX based events, a stream output or a DOM tree. During the processing of the input XSL stylesheet is translated in to an internal format and stored in xslctx. This transformation is done on as is needed basis and can be used again during subsequent processing if the same xslctx is used again. Hence the user can create a single xslctx for a stylesheet which is being used again and again and cache it to speedup processing of successive input XML trees which are using same XSL stylesheet again and again. The caching will ensure the usage of already translated intermediate format of the XSL stylesheet available from a prior processing, instead of need to generate it again. RETURNS (xslctx *) pointer to new XSL context, or NULL ARGUMENTS err (OUT) error code, XMLERR_OK [0] on success xsl (IN) XNL context of the input stylesheet baseURI(IN) base URI for include and import statements resvd (IN) reserved for future use [must be set to 0] */ xslctx *xslinit(uword *err, xmlctx *xsl, const oratext *baseURI, ub4 resvd); /*--------------------------------------------------------------------------- NAME xslgetbaseuri FUNCTION Get base URI associated with XSL context DESCRIPTION Get base URI associated with XSL context RETURNS (const oratext *) base URI or NULL. ARGUMENTS xslSSctx (IN) the XSL processing context to be inquired upon */ const oratext *xslgetbaseuri(xslctx *xslSSctx); /*--------------------------------------------------------------------------- NAME xslgetxslctx FUNCTION Get the input stylesheet DOM context with XSL context DESCRIPTION Get XML context for XSL stylesheet associated with XSL context RETURNS (xmlctx *) XML context if successful, or NULL. ARGUMENTS xslSSctx (IN) the XSL processing context to be inquired upon */ xmlctx *xslgetxslctx(xslctx *xslSSctx); /*--------------------------------------------------------------------------- NAME xslsettextparam FUNCTION Set a top-level XSL parameter DESCRIPTION xslsettextparam is used to create a top level parameter (or variable) to be used during the subsequent processing of XML DOM trees. User can call it any number of times, to set as many variables as he wants. A subsequent call with preexisting parameter name will override the old value with the new value supplied. User can use the xslgettextparam to inquire the value of a preexisting variable. A value specified to be NULL will reset the variable as if it was never added. RETURNS (uword) error code, XMLERR_OK [0] on success ARGUMENTS xslSSctx (IN) XSL processing context param_name (IN) name of parameter [variable] to be set. param_val (IN) parameter value the parameter is to be set to. */ uword xslsettextparam(xslctx *xslSSctx, const oratext *param_name, const oratext *param_value); /*--------------------------------------------------------------------------- NAME xslgettextparam FUNCTION Enquire about the preexisting top level parameter or value DESCRIPTION Given the parameter pull up the current value it is set to. RETURNS (const oratext *) String giving parameter value, or NULL ARGUMENTS xslSSctx (IN) XSL processing context to be inquired upon param_name (IN) parameter whose value is to be inquired. */ const oratext *xslgettextparam(xslctx *xslSSctx, const oratext *param_name); /*--------------------------------------------------------------------------- NAME xslresetallparams FUNCTION Reset all the top level XSL parameters added DESCRIPTION Reset all the top level XSL parameters added RETURNS (uword) error code, XMLERR_OK [0] on success ARGUMENTS xslSSctx (IN) the XSL processing context to be inquired upon */ uword xslresetallparams(xslctx *xslSSctx); /*--------------------------------------------------------------------------- NAME xslsetoutputmethod FUNCTION Set overriding XSL output method DESCRIPTION This call is used to set an output method equivalent to XSL processing direction . If the xsl stylesheet contains one or more similar statements then this function will override the effect of any previously present statements in XSL stylesheet. RETURNS (uword) error code, XMLERR_OK [0] on success ARGUMENTS xslSSctx (IN) XSL processing context method (IN) selected output method resvd (IN) reserved for future use [must be set to 0] */ uword xslsetoutputmethod(xslctx *xslSSctx, xsloutputmethod method, ub4 resvd); /*--------------------------------------------------------------------------- NAME xslsetoutputencoding FUNCTION Set encoding for XSL output DESCRIPTION This call is used to set an output method equivalent to XSL processing direction . If the xsl stylesheet contains one or more similar statements then this function will override the effect of any previously present statements in XSL stylesheet. RETURNS (uword) error code, XMLERR_OK [0] on success ARGUMENTS xslSSctx (IN) XSL processing context outcoding (IN) output encoding name */ uword xslsetoutputencoding(xslctx *xslSSctx, oratext *outcoding); /*--------------------------------------------------------------------------- NAME xslsetoutputdomctx FUNCTION Set XML context for storing XSL processing result DESCRIPTION xslsetoutputdomctx is used for setting the xmlctx which will be used to store the output DOM tree. A call to xslsetoutputdomctx overrides any previous output method set using any previous calls to xslsetoutputdomctx or xslsetoutputstream or xslsetoutputsax. Any subsequent processing of the XML input will be stored in form of a Document fragment in xmlctx specified by resctx. xslgetoutputdomctx can be used to inquire presently set resctx. If no DOM context is set or a call to xslsetoutputdomctx has been overridden by a subsequent call to xslsetoutputstream or xslsetoutputsax then xslgetoutputdomctx will return NULL context indicating that present output mode is not a DOM output mode. RETURNS (uword) error code, XMLERR_OK [0] on success ARGUMENTS xslSSctx (IN) XSL processing context resCtx (IN) XML context for output document fragment */ uword xslsetoutputdomctx(xslctx *xslSSctx, xmlctx *resctx); /*--------------------------------------------------------------------------- NAME xslgetoutputdomctx FUNCTION Returns XML context for storing XSL output DESCRIPTION Returns the XML context set by a previous call to xslsetoutputdomctx. RETURNS (xmlctx *) XML context if successful, Otherwise returns NULL. ARGUMENTS xslSSctx (IN) XSL processing context */ xmlctx *xslgetoutputdomctx(xslctx *xslSSctx); /*--------------------------------------------------------------------------- NAME xslsetoutputstream FUNCTION DEPRECATED Set the XSL output stream DESCRIPTION DEPRECATED - DO NOT USE THIS FUNCTION FOR NEW WORK. ALL STREAMING CODE SHOULD USE THE NEW orastream STRUCTURE DEFINED IN orastruc.h xslsetoutputstream is used for setting the xmlstream to be used for redirecting the text output of the XSL processing. A call to xslsetoutputstream overrides any previous output method set using any previous calls to xslsetoutputdomctx or xslsetoutputstream or xslsetoutputsax. Any subsequent processing of the XML input will be redirected in text format to the callbacks specified by stream. xslgetoutputstream can be used to inquire presently set stream. If no output stream is set or a call to xslsetoutputstream has been overridden by a subsequent call to xslsetoutputdomctx or xslsetoutputsax then xslgetoutputstream will return NULL indicating that present output mode is not a stream based output mode. RETURNS (uword) error code, XMLERR_OK [0] on success ARGUMENTS xslSSctx (IN) XSL processing context stream (IN) stream structure */ uword xslsetoutputstream(xslctx *xslSSctx, xmlstream *stream); /*--------------------------------------------------------------------------- NAME xslsetoutputorastream FUNCTION Set the XSL output orastream DESCRIPTION xslsetoutputstream is used for setting the orastream to be used for redirecting the text output of the XSL processing. A call to xslsetoutputstream overrides any previous output method set using any previous calls to xslsetoutputdomctx or xslsetoutputstream or xslsetoutputsax. Any subsequent processing of the XML input will be redirected in text format to the callbacks specified by stream. xslgetoutputstream can be used to inquire presently set stream. If no output stream is set or a call to xslsetoutputstream has been overridden by a subsequent call to xslsetoutputdomctx or xslsetoutputsax then xslgetoutputstream will return NULL indicating that present output mode is not a stream based output mode. RETURNS (uword) error code, XMLERR_OK [0] on success ARGUMENTS xslSSctx (IN) XSL processing context stream (IN) orastream structure */ uword xslsetoutputorastream(xslctx *xslSSctx, orastream *ostream); /*--------------------------------------------------------------------------- NAME xslgetoutputstream FUNCTION Returns the XSL output stream DESCRIPTION Returns the xmlstream set by a previous call to xslsetoutputstream RETURNS (xmlstream *) stream or NULL. ARGUMENTS xslSSctx (IN) XSL processing context */ xmlstream *xslgetoutputstream(xslctx *xslSSctx); /*--------------------------------------------------------------------------- NAME xslgetoutputorastream FUNCTION Returns the XSL output orastream DESCRIPTION Returns the orastream set by a previous call to xslsetoutputorastream RETURNS (orastream *) stream or NULL. ARGUMENTS xslSSctx (IN) XSL processing context */ orastream *xslgetoutputorastream(xslctx *xslSSctx); /*--------------------------------------------------------------------------- NAME xslsetoutputsax FUNCTION Sets the SAX based events to be generated DESCRIPTION Sets the SAX callback structure which describes SAX event to be be invoked as the processing progresses to generate output nodes. The context to be passed to the SAX event handler is set with a call to xslsetoutputsaxctx (or the context will be NULL). A call to xslsetoutputsax overrides any previous output method set using any previous calls to xslsetoutputdomctx or xslsetoutputstream or xslsetoutputsax. Any subsequent processing of the XML input will generate SAX events specified by the SAX context. xslgetoutputsax can be used to inquire presently set SAX context. If no SAX context is set or a call to xslsetoutputsax has been overridden by a subsequent call to xslsetoutputdomctx or xslsetoutputstream then xslgetoutputsax will return NULL indicating that present output mode is not a SAX based output mode. Note: User can make a call to xslsetoutputsaxctx to set the SAX context to be used by the SAX callbacks. If none is set, then a NULL will be passed to the SAX callbacks as SAX context. Also note that just setting the callbacks is sufficient to invoke the SAX callbacks. RETURNS (uword) error code, XMLERR_OK [0] on success ARGUMENTS xslSSctx (IN) XSL processing context to be inquired upon s (IN) SAX callbacks structure SEE ALSO xslsetoutputsaxctx */ uword xslsetoutputsax(xslctx *xslSSctx, xmlsaxcb *s); /*--------------------------------------------------------------------------- NAME xslsetoutputsaxctx FUNCTION Sets the context for SAX events DESCRIPTION Sets the context to be passed to SAX event handlers. If not specified, it will be NULL. RETURNS (uword) error code, XMLERR_OK [0] on success ARGUMENTS xslSSctx (IN) XSL processing context to be inquired upon ctx (IN) user-defined SAX context SEE ALSO xslsetoutputsax */ uword xslsetoutputsaxctx(xslctx *xslSSctx, void *ctx); /*--------------------------------------------------------------------------- NAME xslgetoutputsax FUNCTION Returns SAX callbacks DESCRIPTION Returns the xmlsaxcbset by a previous call to xslsetoutputsax. RETURNS (xmlsaxcb *) SAX callback structure or NULL ARGUMENTS xslSSctx (IN) XSL processing context */ xmlsaxcb *xslgetoutputsax(xslctx *xslSSctx); /*--------------------------------------------------------------------------- NAME xslprocessxml FUNCTION Processes XML DESCRIPTION Once user have created the xslctx (the XSL processing context using LpxXSLCreatCtx), have set the base URI, set all the top level parameters (using one or more calls to xslsettextparam), have selected an output method (using one of the calls to xslsetoutputdomctx or xslsetoutputstream or xslsetoutputsax).. .. .. then this is the function call to make to carry out all the action. This function will process the given XML file (specified by its DOM context) according to the XSL stylesheet, parameters and, output method set in the xslctx. Once this call returns, depending on the output scheme which user might have selected: For Stream based output: The output text has been redirected using the stream callbacks. For SAX based output: User would have already got all the SAX events executed. For DOM based output: User can make a call to xslgetresultdocfrag function to access the final Document Fragment created in context of the resCtx set by a call to xslsetoutputdomctx. The XSL processor expects a normalized DOM tree as an input. If user is not sure whether the XML tree is normalized or not, then he should set this flag to TRUE and this call will normalize the DOM; Otherwise set it to FALSE. xsl:output is supported only for stream based output. RETURNS (uword) error code, XMLERR_OK [0] on success ARGUMENTS xslSSctx (IN) XSL processing context xmlCtx (IN) XML context of the input XML tree normalize (IN) normalize input document? resvd (IN) reserved for future use [must be set to 0] */ uword xslprocessxml(xslctx *xslSSctx, xmlctx *xmlctx, boolean normalize, ub4 resvd); /*--------------------------------------------------------------------------- NAME xslprocessxmldocfrag FUNCTION Processs an XML document fragment DESCRIPTION Once user have created the xslctx (the XSL processing context using LpxXSLCreatCtx), have set the base URI, set all the top level parameters (using one or more calls to xslsettextparam), have selected an output method (using one of the calls to xslsetoutputdomctx or xslsetoutputstream or xslsetoutputsax).. .. .. then this is the function call to make to carry out all the action. This function will process the given XML document fragment according to the XSL stylesheet, parameters and, output method set in the xslctx. Once this call returns, depending on the output scheme which user might have selected: For Stream based output: The output text has been redirected using the stream callbacks. For SAX based output: User would have already got all the SAX events executed. For DOM based output: User can make a call to xslgetresultdocfrag function to access the final Document Fragment created in context of the resCtx set by a call to xslsetoutputdomctx. The XSL processor expects a normalized DOM tree as an input. If user is not sure whether the XML tree is normalized or not, then he should set this flag to TRUE and this call will normalize the DOM; Otherwise set it to FALSE. xsl:output is supported only for stream based output. RETURNS (uword) error code, XMLERR_OK [0] on success ARGUMENTS xslSSctx (IN) XSL processing context xmlCtx (IN) XML context for the input XML Doc Frag docFrag (IN) document fragment normalize (IN) normalize input document? resvd (IN) reserved for future use [must be set to 0] */ uword xslprocessxmldocfrag(xslctx *xslSSctx, xmlctx *xmlctx, xmlnode *docFrag, boolean normalize, /* ARGUSED */ ub4 resvd); /*--------------------------------------------------------------------------- NAME xslgetresultdocfrag FUNCTION Gets resulting document fragment DESCRIPTION This function should be called after a call to xslprocessxml for the DOM based output method. If the output method for the last call to xslprocessxml was DOM based, this function will return the Document Fragment created by XSL processing of the given XML tree, otherwise this function will return NULL indicating that the output method selected was not DOM based or no XML processing has been carried out since either the creation of xslSSctx or since last selecting an output method for the specified xslctx. RETURNS (xmlnode *) resulting DOM tree. ARGUMENTS xslSSctx (IN) XSL processing context */ xmlnode *xslgetresultdocfrag(xslctx *xslSSctx); /*--------------------------------------------------------------------------- NAME xslterm FUNCTION Terminates XSL context DESCRIPTION This function will terminate the XSL context and free all the intermediate data structures created for it during any previous processing using this context. Once terminated, the XSL context is no more valid and must not be used any further. RETURNS (uword) error code, XMLERR_OK [0] on success ARGUMENTS xslSSctx (IN) XSL processing context */ uword xslterm(xslctx *xslSSctx); /**************************************************************************** Interface XPath ****************************************************************************/ /*--------------------------------------------------------------------------- NAME xpmakexpathctx FUNCTION Makes an XPath context DESCRIPTION Creates, initializes and returns an XPath context. The XPath context makes use of an internally created dummy XSL and XML context. When you are done executing the XPath related function calls, free this context with xpfreexpathctx. If ctx is NULL, we internally create a dummy xml context. This context is used to obtain the encoding, memory management, access routines and error handlers. If xslnode is NULL, no name space expansion will be done at the time of parsing. xml_node should be NULL for parsing. baseURI sets the base URI for document function calls which might be made internally. Set nctxels to the number of context nodes to follow (or 0 if no context list is available). RETURNS (xpctx *) the created XPath context ARGUMENTS ctx (IN) XML parser context xslnode (IN) XSL node used for namespace expansion xml_node (IN) context node for expression evaluation. baseURI (IN) base URI for document nctxels (IN) number of context nodes to follow ctxnodes (IN) array of nctxels nodes SEE ALSO xpfreexpathctx */ xpctx *xpmakexpathctx(xmlctx *ctx, xmlnode *xslnode, xmlnode *xml_node, oratext *baseURI, size_t nctxels, xmlnode **ctxnodes); /*--------------------------------------------------------------------------- NAME xpfreexpathctx FUNCTION Frees an XPath context DESCRIPTION Frees an XPath context allocated by a prior call to xpmakexpathctx. Once freed the xctx pointer is no more valid and must not be used further. RETURNS (void) ARGUMENTS xctx (I/O) XPath context to be freed. SEE ALSO xpmakexpathctx */ void xpfreexpathctx(xpctx *xctx); /*--------------------------------------------------------------------------- NAME xpparsexpathexpr FUNCTION Parses an XPath expression DESCRIPTION Take an expression in the form of a string and parses it. The result is in the form of an expression tree. The encoding should be in the data encoding. RETURNS (xpexpr *) expression tree or NULL ARGUMENTS xctx (I/O) XPath context expr (IN) expression [in data encoding] err (OUT) error code, XMLERR_OK [0] on success SEE ALSO xpevalxpathexpr */ xpexpr *xpparsexpathexpr(xpctx *xctx, oratext *expr, sword *err); /*--------------------------------------------------------------------------- NAME xpevalxpathexpr FUNCTION Evaluates an XPath expression DESCRIPTION Evaluates the previously parsed expression and returns the result. The exprtree is obtained by making a call to xpparsexpathexpr to parse the given XPath expression string. RETURNS (xpobj *) result object or NULL ARGUMENTS xctx (I/O) XPath context expr (IN) parsed expression. err (OUT) error code, XMLERR_OK [0] on success SEE ALSO xpparsexpathexpr */ xpobj *xpevalxpathexpr(xpctx *xctx, xpexpr *exprtree, sword *err); /*--------------------------------------------------------------------------- NAME xpgetxpobjtyp FUNCTION Returns the type code of an XPath object DESCRIPTION Returns the type code of an XPath object RETURNS (xpobjtyp) object type ARGUMENTS xobj (IN) XPath object SEE ALSO xpgetbooleanval, xpgetnumval, xpgetstrval, xpgetnsetval, xpgetrtfragval */ xpobjtyp xpgetxpobjtyp(xpobj * xobj); /*--------------------------------------------------------------------------- NAME xpgetbooleanval FUNCTION Returns the value of a boolean XPath object DESCRIPTION For bool XPath object (type XPOBJTYP_BOOL), returns its boolean value, TRUE or FALSE. RETURNS (boolean) boolean object's value ARGUMENTS xobj (IN) XPath object SEE ALSO xpgetnumval, xpgetstrval, xpgetnsetval, xpgetrtfragval */ boolean xpgetbooleanval(xpobj *xobj); /*--------------------------------------------------------------------------- NAME xpgetnumval FUNCTION Returns the value of a numeric XPath object DESCRIPTION For numeric XPath objects (type XPOBJTYP_NUM), returns its numeric value RETURNS (double) numeric object's value ARGUMENTS xobj (IN) XPath object SEE ALSO xpgetbooleanval, xpgetstrval, xpgetnsetval, xpgetrtfragval */ double xpgetnumval(xpobj *xobj); /*--------------------------------------------------------------------------- NAME xpgetstrval FUNCTION Returns the value of a string XPath object DESCRIPTION For string-type XPath objects (type XPOBJTYP_STR), returns its string value. RETURNS (oratext *) string object's value ARGUMENTS xobj (IN) XPath object SEE ALSO xpgetbooleanval, xpgetnumval, xpgetnsetval, xpgetrtfragval */ oratext *xpgetstrval(xpobj *xobj); /*--------------------------------------------------------------------------- NAME xpgetnsetval FUNCTION Returns the node-set of a node-set XPath object DESCRIPTION For node-set XPath objects (type XPOBJTYP_NSET), returns its node-set value. EXAMPLE nsetval = xpgetnsetval(xobj); for (nsetele = xpgetfirstnsetelem(nsetval); nsetelem; nsetelem = xpgetnextnsetelem(nsetval)) { node = xpgetnsetelemnode(nsetele); ....use node ... } RETURNS (xpnset *) XPath object's node-set value ARGUMENTS xobj (IN) XPath object SEE ALSO xpgetfirstnsetelem, xpgetnextnsetelem, xpgetnsetelemnode */ xpnset *xpgetnsetval(xpobj *xobj); /*--------------------------------------------------------------------------- NAME xpgetfirstnsetelem FUNCTION Returns first element in a node-set DESCRIPTION Returns first element in a node-set. See xpgetnsetval for typical usage. RETURNS (xpnsetele *) node-set element ARGUMENTS nset (IN) XPath node-set SEE ALSO xpgetnextnsetelem, xpgetnsetelemnode */ xpnsetele *xpgetfirstnsetelem(xpnset *nset); /*--------------------------------------------------------------------------- NAME xpgetnextnsetelem FUNCTION Returns next element in a node-set DESCRIPTION Returns next element in a node-set, given an element in that node-set. See xpgetnsetval for sample usage. RETURNS (xpnsetele *) next node-set element ARGUMENTS nsetele (IN) current node-set element SEE ALSO xpgetfirstnsetelem, xpgetnsetelemnode */ xpnsetele *xpgetnextnsetelem(xpnsetele *nsetele); /*--------------------------------------------------------------------------- NAME xpgetnsetelemnode FUNCTION Returns the XML node for a node-set element DESCRIPTION Returns the XML node corresponding to a node-set element. See xpgetnsetval for sample usage. RETURNS (xmlnode *) XML node ARGUMENTS nsetele (IN) node-set element SEE ALSO xpgetfirstnsetelem, xpgetnextnsetelem, xpgetnsetelemnode */ xmlnode *xpgetnsetelemnode(xpnsetele *nsetele); /*--------------------------------------------------------------------------- NAME xpgetrtfragval FUNCTION Returns the XML node of a result-tree fragment DESCRIPTION Returns the XML node corresponding to a result-tree fragment XPath object (type XPOBJTYP_RTFRAG). RETURNS (xmlnode *) XML node ARGUMENTS xobj (IN) XPath object */ xmlnode *xpgetrtfragval(xpobj *xobj); #endif /* ORAXML_ORACLE */