Parsing.subproj/CFXMLParser.h

   1 /*
   2  * Copyright (c) 2003 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * Copyright (c) 1999-2003 Apple Computer, Inc.  All Rights Reserved.
   7  *
   8  * This file contains Original Code and/or Modifications of Original Code
   9  * as defined in and that are subject to the Apple Public Source License
  10  * Version 2.0 (the 'License'). You may not use this file except in
  11  * compliance with the License. Please obtain a copy of the License at
  12  * http://www.opensource.apple.com/apsl/ and read it before using this
  13  * file.
  14  *
  15  * The Original Code and all software distributed under the License are
  16  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  17  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  18  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  19  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  20  * Please see the License for the specific language governing rights and
  21  * limitations under the License.
  22  *
  23  * @APPLE_LICENSE_HEADER_END@
  24  */
  25 /*      CFXMLParser.h
  26         Copyright (c) 1998-2003, Apple, Inc. All rights reserved.
  27 */
  28
  29 #if !defined(__COREFOUNDATION_CFXMLPARSER__)
  30 #define __COREFOUNDATION_CFXMLPARSER__ 1
  31
  32 #include <CoreFoundation/CFBase.h>
  33 #include <CoreFoundation/CFArray.h>
  34 #include <CoreFoundation/CFData.h>
  35 #include <CoreFoundation/CFDictionary.h>
  36 #include <CoreFoundation/CFTree.h>
  37 #include <CoreFoundation/CFURL.h>
  38 #include <CoreFoundation/CFXMLNode.h>
  39
  40 #if defined(__cplusplus)
  41 extern "C" {
  42 #endif
  43
  44 typedef struct __CFXMLParser * CFXMLParserRef;
  45
  46 /* These are the various options you can configure the parser with.  These are
  47    chosen such that an option flag of 0 (kCFXMLParserNoOptions) leaves the XML
  48    as "intact" as possible (reports all structures; performs no replacements).
  49    Hence, to make the parser do the most work, returning only the pure element
  50    tree, set the option flag to kCFXMLParserAllOptions.
  51
  52 kCFXMLParserValidateDocument -
  53    validate the document against its grammar from the DTD, reporting any errors.
  54    Currently not supported.
  55
  56 kCFXMLParserSkipMetaData -
  57    silently skip over metadata constructs (the DTD and comments)
  58
  59 kCFXMLParserReplacePhysicalEntities -
  60    replace declared entities like &lt;.  Note that other than the 5 predefined
  61    entities (lt, gt, quot, amp, apos), these must be defined in the DTD.
  62    Currently not supported.
  63
  64 kCFXMLParserSkipWhitespace -
  65    skip over all whitespace that does not abut non-whitespace character data.
  66    In other words, given <foo>  <bar> blah </bar></foo>, the whitespace between
  67    foo's open tag and bar's open tag would be suppressed, but the whitespace
  68    around blah would be preserved.
  69
  70 kCFXMLParserAddImpliedAttributes -
  71    where the DTD specifies implied attribute-value pairs for a particular element,
  72    add those pairs to any occurances of the element in the element tree.
  73    Currently not supported.
  74 */
  75
  76 typedef enum {
  77     kCFXMLParserValidateDocument = (1 << 0),
  78     kCFXMLParserSkipMetaData = (1 << 1),
  79     kCFXMLParserReplacePhysicalEntities = (1 << 2),
  80     kCFXMLParserSkipWhitespace = (1 << 3),
  81     kCFXMLParserResolveExternalEntities = (1 << 4),
  82     kCFXMLParserAddImpliedAttributes = (1 << 5),
  83     kCFXMLParserAllOptions = 0x00FFFFFF,
  84     kCFXMLParserNoOptions = 0
  85 } CFXMLParserOptions;
  86
  87 /* This list is expected to grow */
  88 typedef enum {
  89     kCFXMLStatusParseNotBegun = -2,
  90     kCFXMLStatusParseInProgress = -1,
  91     kCFXMLStatusParseSuccessful = 0,
  92     kCFXMLErrorUnexpectedEOF = 1,
  93     kCFXMLErrorUnknownEncoding,
  94     kCFXMLErrorEncodingConversionFailure,
  95     kCFXMLErrorMalformedProcessingInstruction,
  96     kCFXMLErrorMalformedDTD,
  97     kCFXMLErrorMalformedName,
  98     kCFXMLErrorMalformedCDSect,
  99     kCFXMLErrorMalformedCloseTag,
 100     kCFXMLErrorMalformedStartTag,
 101     kCFXMLErrorMalformedDocument,
 102     kCFXMLErrorElementlessDocument,
 103     kCFXMLErrorMalformedComment,
 104     kCFXMLErrorMalformedCharacterReference,
 105     kCFXMLErrorMalformedParsedCharacterData,
 106     kCFXMLErrorNoData
 107 } CFXMLParserStatusCode;
 108
 109
 110 /*  These functions are called as a parse progresses.
 111
 112 createXMLStructure -
 113   called as new XML structures are encountered by the parser.  May return NULL to indicate
 114   that the given structure should be skipped; if NULL is returned for a given structure,
 115   only minimal parsing is done for that structure (enough to correctly determine its end,
 116   and to extract any data necessary for the remainder of the parse, such as Entity definitions).
 117   createXMLStructure (or indeed, any of the tree-creation callbacks) will not be called for any
 118   children of the skipped structure.  The only exception is that the top-most element will always
 119   be reported even if NULL was returned for the document as a whole.  NOTE: for performance reasons,
 120   the node passed to createXMLStructure cannot be safely retained by the client; the node as
 121   a whole must be copied (via CFXMLNodeCreateCopy), or its contents must be extracted and copied.
 122
 123 addChild -
 124   called as children are parsed and are ready to be added to the tree.  If createXMLStructure
 125   returns NULL for a given structure, that structure is omitted entirely, and addChild will
 126   NOT be called for either a NULL child or parent.
 127
 128 endXMLStructure -
 129   called once a structure (and all its children) are completely parsed.  As elements are encountered,
 130   createXMLStructure is called for them first, then addChild to add the new structure to its parent,
 131   then addChild (potentially several times) to add the new structure's children to it, then finally
 132   endXMLStructure to show that the structure has been fully parsed.
 133
 134 createXMLStructure, addChild, and endXMLStructure are all REQUIRED TO BE NON-NULL.
 135
 136 resolveExternalEntity -
 137   called when external entities are referenced (NOT when they are simply defined).  If the function
 138   pointer is NULL, the parser uses its internal routines to try and resolve the entity.  If the
 139   function pointer is set, and the function returns NULL, a place holder for the external entity
 140   is inserted into the tree.  In this manner, the parser's client can prevent any external network
 141   or file accesses.
 142
 143 handleError - called as errors/warnings are encountered in the data stream.  At some point, we will
 144   have an enum of the expected errors, some of which will be fatal, others of which will not.  If
 145   the function pointer is NULL, the parser will silently attempt to recover.  The
 146   handleError function may always return false to force the parser to stop; if handleError returns
 147   true, the parser will attempt to recover (fatal errors will still cause the parse to abort
 148   immediately).
 149 */
 150
 151 typedef void *          (*CFXMLParserCreateXMLStructureCallBack)(CFXMLParserRef parser, CFXMLNodeRef nodeDesc, void *info);
 152 typedef void            (*CFXMLParserAddChildCallBack)(CFXMLParserRef parser, void *parent, void *child, void *info);
 153 typedef void            (*CFXMLParserEndXMLStructureCallBack)(CFXMLParserRef parser, void *xmlType, void *info);
 154 typedef CFDataRef       (*CFXMLParserResolveExternalEntityCallBack)(CFXMLParserRef parser, CFXMLExternalID *extID, void *info);
 155 typedef Boolean         (*CFXMLParserHandleErrorCallBack)(CFXMLParserRef parser, CFXMLParserStatusCode error, void *info);
 156 typedef struct {
 157     CFIndex                                  version;
 158     CFXMLParserCreateXMLStructureCallBack    createXMLStructure;
 159     CFXMLParserAddChildCallBack              addChild;
 160     CFXMLParserEndXMLStructureCallBack       endXMLStructure;
 161     CFXMLParserResolveExternalEntityCallBack resolveExternalEntity;
 162     CFXMLParserHandleErrorCallBack           handleError;
 163 } CFXMLParserCallBacks;
 164
 165 typedef const void *    (*CFXMLParserRetainCallBack)(const void *info);
 166 typedef void            (*CFXMLParserReleaseCallBack)(const void *info);
 167 typedef CFStringRef     (*CFXMLParserCopyDescriptionCallBack)(const void *info);
 168 typedef struct {
 169     CFIndex                             version;
 170     void *                              info;
 171     CFXMLParserRetainCallBack           retain;
 172     CFXMLParserReleaseCallBack          release;
 173     CFXMLParserCopyDescriptionCallBack  copyDescription;
 174 } CFXMLParserContext;
 175
 176 CF_EXPORT
 177 CFTypeID CFXMLParserGetTypeID(void);
 178
 179 /* Creates a parser which will parse the given data with the given options.  xmlData may not be NULL.
 180    dataSource should be the URL from which the data came, and may be NULL; it is used to resolve any
 181    relative references found in xmlData. versionOfNodes determines which version CFXMLNodes are produced
 182    by the parser; see CFXMLNode.h for more details.  callBacks are the callbacks called by the parser as
 183    the parse progresses; callBacks, callBacks->createXMLStructure, callBacks->addChild, and
 184    callBacks->endXMLStructure must all be non-NULL.  context determines what if any info pointer is
 185    passed to the callbacks as the parse progresses; context may be NULL.  */
 186 CF_EXPORT
 187 CFXMLParserRef CFXMLParserCreate(CFAllocatorRef allocator, CFDataRef xmlData, CFURLRef dataSource, CFOptionFlags parseOptions, CFIndex versionOfNodes, CFXMLParserCallBacks *callBacks, CFXMLParserContext *context);
 188
 189
 190 CF_EXPORT
 191 void CFXMLParserGetContext(CFXMLParserRef parser, CFXMLParserContext *context);
 192
 193 CF_EXPORT
 194 void CFXMLParserGetCallBacks(CFXMLParserRef parser, CFXMLParserCallBacks *callBacks);
 195
 196 CF_EXPORT
 197 CFURLRef CFXMLParserGetSourceURL(CFXMLParserRef parser);
 198
 199 /* Returns the character index of the current parse location */
 200 CF_EXPORT
 201 CFIndex CFXMLParserGetLocation(CFXMLParserRef parser);
 202
 203 /* Returns the line number of the current parse location */
 204 CF_EXPORT
 205 CFIndex CFXMLParserGetLineNumber(CFXMLParserRef parser);
 206
 207 /* Returns the top-most object returned by the createXMLStructure callback */
 208 CF_EXPORT
 209 void *CFXMLParserGetDocument(CFXMLParserRef parser);
 210
 211 /* Get the status code or a user-readable description of the last error that occurred in a parse.
 212    If no error has occurred, a null description string is returned.  See the enum above for
 213    possible status returns */
 214 CF_EXPORT
 215 CFXMLParserStatusCode CFXMLParserGetStatusCode(CFXMLParserRef parser);
 216
 217 CF_EXPORT
 218 CFStringRef CFXMLParserCopyErrorDescription(CFXMLParserRef parser);
 219
 220 /* Cause any in-progress parse to abort with the given error code and description.  errorCode
 221    must be positive, and errorDescription may not be NULL.  Cannot be called asynchronously
 222    (i.e. must be called from within a parser callback) */
 223 CF_EXPORT
 224 void CFXMLParserAbort(CFXMLParserRef parser, CFXMLParserStatusCode errorCode, CFStringRef errorDescription);
 225
 226 /* Starts a parse of the data the parser was created with; returns success or failure.
 227    Upon success, use CFXMLParserGetDocument() to get the product of the parse.  Upon
 228    failure, use CFXMLParserGetErrorCode() or CFXMLParserCopyErrorDescription() to get
 229    information about the error.  It is an error to call CFXMLParserParse() while a
 230    parse is already underway. */
 231 CF_EXPORT
 232 Boolean CFXMLParserParse(CFXMLParserRef parser);
 233
 234 /* These functions provide a higher-level interface.  The XML data is parsed to a
 235    special CFTree (an CFXMLTree) with known contexts and callbacks.  See CFXMLNode.h
 236    for full details on using an CFXMLTree and the CFXMLNodes contained therein.
 237 */
 238 /* Parse to an CFXMLTreeRef.  parseOptions are as above. versionOfNodes determines
 239    what version CFXMLNodes are used to populate the tree.  */
 240 CF_EXPORT
 241 CFXMLTreeRef CFXMLTreeCreateFromData(CFAllocatorRef allocator, CFDataRef xmlData, CFURLRef dataSource, CFOptionFlags parseOptions, CFIndex versionOfNodes);
 242
 243 /* As above, with the additional by-reference pass of a CFDictionaryRef containing
 244    various error information (see below). The caller is responsible for releasing the
 245    returned dictionary. If the error dictionary is not desired, pass NULL. */
 246 CF_EXPORT
 247 CFXMLTreeRef CFXMLTreeCreateFromDataWithError(CFAllocatorRef allocator, CFDataRef xmlData, CFURLRef dataSource, CFOptionFlags parseOptions, CFIndex versionOfNodes, CFDictionaryRef *errorDict) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;
 248
 249
 250 /* Generate the XMLData (ready to be written to whatever permanent storage is to be
 251    used) from an CFXMLTree.  Will NOT regenerate entity references (except those
 252    required for syntactic correctness) if they were replaced at the parse time;
 253    clients that wish this should walk the tree and re-insert any entity references
 254    that should appear in the final output file. */
 255 CF_EXPORT
 256 CFDataRef CFXMLTreeCreateXMLData(CFAllocatorRef allocator, CFXMLTreeRef xmlTree);
 257
 258 /* Escaping and unescaping XML entities in CFStrings. The standard XML entities
 259    are always replaced.  */
 260 /* Creates a CFString by replacing entities that appear in the entities dictionary.
 261    Dictionary keys are the entities themselves, and the values should be CFStrings
 262    containing the expansion. Pass NULL for entitiesDictionary to indicate no entities
 263    other than the standard five. */
 264 CF_EXPORT
 265 CFStringRef CFXMLCreateStringByEscapingEntities(CFAllocatorRef allocator, CFStringRef string, CFDictionaryRef entitiesDictionary) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;
 266
 267 CF_EXPORT
 268 CFStringRef CFXMLCreateStringByUnescapingEntities(CFAllocatorRef allocator, CFStringRef string, CFDictionaryRef entitiesDictionary) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;
 269
 270 /* CFXMLTreeCreateFromDataWithError error dictionary key constants. */
 271 CF_EXPORT const CFStringRef kCFXMLTreeErrorDescription          AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;
 272     /* value is a CFString containing the readable error string. */
 273
 274 CF_EXPORT const CFStringRef kCFXMLTreeErrorLineNumber           AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;
 275     /* value is a CFNumber containing the line on which the error appears. */
 276
 277 CF_EXPORT const CFStringRef kCFXMLTreeErrorLocation             AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;
 278     /* value is a CFNumber containing the byte location at which the error occurred. */
 279
 280 CF_EXPORT const CFStringRef kCFXMLTreeErrorStatusCode           AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;
 281     /* value is a CFNumber containing the error status code. */
 282
 283 #if defined(__cplusplus)
 284 }
 285 #endif
 286
 287 #endif /* ! __COREFOUNDATION_CFXMLPARSER__ */
 288