CFXMLParser.h

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