CFXMLParser.h

   1 /*
   2  * Copyright (c) 2015 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-2014, 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_IMPLICIT_BRIDGING_ENABLED
  42 CF_EXTERN_C_BEGIN
  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 CF_OPTIONS(CFOptionFlags, CFXMLParserOptions) {
  77     kCFXMLParserValidateDocument = (1UL << 0),
  78     kCFXMLParserSkipMetaData = (1UL << 1),
  79     kCFXMLParserReplacePhysicalEntities = (1UL << 2),
  80     kCFXMLParserSkipWhitespace = (1UL << 3),
  81     kCFXMLParserResolveExternalEntities = (1UL << 4),
  82     kCFXMLParserAddImpliedAttributes = (1UL << 5),
  83     kCFXMLParserAllOptions = 0x00FFFFFF,
  84     kCFXMLParserNoOptions = 0
  85 };
  86
  87 /* This list is expected to grow */
  88 typedef CF_OPTIONS(CFIndex, CFXMLParserStatusCode) {
  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 };
 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) CF_DEPRECATED(10_0, 10_8, 2_0, 6_0);
 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) CF_DEPRECATED(10_0, 10_8, 2_0, 6_0);
 188
 189 /* Arguments as above, except that the data to be parsed is loaded directly
 190    from dataSource.  dataSource may not be NULL.  */
 191 CF_EXPORT
 192 CFXMLParserRef CFXMLParserCreateWithDataFromURL(CFAllocatorRef allocator, CFURLRef dataSource, CFOptionFlags parseOptions, CFIndex versionOfNodes, CFXMLParserCallBacks *callBacks, CFXMLParserContext *context) CF_DEPRECATED(10_0, 10_8, 2_0, 6_0);
 193
 194 CF_EXPORT
 195 void CFXMLParserGetContext(CFXMLParserRef parser, CFXMLParserContext *context) CF_DEPRECATED(10_0, 10_8, 2_0, 6_0);
 196
 197 CF_EXPORT
 198 void CFXMLParserGetCallBacks(CFXMLParserRef parser, CFXMLParserCallBacks *callBacks) CF_DEPRECATED(10_0, 10_8, 2_0, 6_0);
 199
 200 CF_EXPORT
 201 CFURLRef CFXMLParserGetSourceURL(CFXMLParserRef parser) CF_DEPRECATED(10_0, 10_8, 2_0, 6_0);
 202
 203 /* Returns the character index of the current parse location */
 204 CF_EXPORT
 205 CFIndex CFXMLParserGetLocation(CFXMLParserRef parser) CF_DEPRECATED(10_0, 10_8, 2_0, 6_0);
 206
 207 /* Returns the line number of the current parse location */
 208 CF_EXPORT
 209 CFIndex CFXMLParserGetLineNumber(CFXMLParserRef parser) CF_DEPRECATED(10_0, 10_8, 2_0, 6_0);
 210
 211 /* Returns the top-most object returned by the createXMLStructure callback */
 212 CF_EXPORT
 213 void *CFXMLParserGetDocument(CFXMLParserRef parser) CF_DEPRECATED(10_0, 10_8, 2_0, 6_0);
 214
 215 /* Get the status code or a user-readable description of the last error that occurred in a parse.
 216    If no error has occurred, a null description string is returned.  See the enum above for
 217    possible status returns */
 218 CF_EXPORT
 219 CFXMLParserStatusCode CFXMLParserGetStatusCode(CFXMLParserRef parser) CF_DEPRECATED(10_0, 10_8, 2_0, 6_0);
 220
 221 CF_EXPORT
 222 CFStringRef CFXMLParserCopyErrorDescription(CFXMLParserRef parser) CF_DEPRECATED(10_0, 10_8, 2_0, 6_0);
 223
 224 /* Cause any in-progress parse to abort with the given error code and description.  errorCode
 225    must be positive, and errorDescription may not be NULL.  Cannot be called asynchronously
 226    (i.e. must be called from within a parser callback) */
 227 CF_EXPORT
 228 void CFXMLParserAbort(CFXMLParserRef parser, CFXMLParserStatusCode errorCode, CFStringRef errorDescription) CF_DEPRECATED(10_0, 10_8, 2_0, 6_0);
 229
 230 /* Starts a parse of the data the parser was created with; returns success or failure.
 231    Upon success, use CFXMLParserGetDocument() to get the product of the parse.  Upon
 232    failure, use CFXMLParserGetErrorCode() or CFXMLParserCopyErrorDescription() to get
 233    information about the error.  It is an error to call CFXMLParserParse() while a
 234    parse is already underway. */
 235 CF_EXPORT
 236 Boolean CFXMLParserParse(CFXMLParserRef parser) CF_DEPRECATED(10_0, 10_8, 2_0, 6_0);
 237
 238 /* These functions provide a higher-level interface.  The XML data is parsed to a
 239    special CFTree (an CFXMLTree) with known contexts and callbacks.  See CFXMLNode.h
 240    for full details on using an CFXMLTree and the CFXMLNodes contained therein.
 241 */
 242 /* Parse to an CFXMLTreeRef.  parseOptions are as above. versionOfNodes determines
 243    what version CFXMLNodes are used to populate the tree.  */
 244 CF_EXPORT
 245 CFXMLTreeRef CFXMLTreeCreateFromData(CFAllocatorRef allocator, CFDataRef xmlData, CFURLRef dataSource, CFOptionFlags parseOptions, CFIndex versionOfNodes) CF_DEPRECATED(10_0, 10_8, 2_0, 6_0);
 246
 247 /* As above, with the additional by-reference pass of a CFDictionaryRef containing
 248    various error information (see below). The caller is responsible for releasing the
 249    returned dictionary. If the error dictionary is not desired, pass NULL. */
 250 CF_EXPORT
 251 CFXMLTreeRef CFXMLTreeCreateFromDataWithError(CFAllocatorRef allocator, CFDataRef xmlData, CFURLRef dataSource, CFOptionFlags parseOptions, CFIndex versionOfNodes, CFDictionaryRef *errorDict) CF_DEPRECATED(10_0, 10_8, 2_0, 6_0);
 252
 253 /* Loads the data to be parsed directly from dataSource.  Arguments as above. */
 254 CF_EXPORT
 255 CFXMLTreeRef CFXMLTreeCreateWithDataFromURL(CFAllocatorRef allocator, CFURLRef dataSource, CFOptionFlags parseOptions, CFIndex versionOfNodes) CF_DEPRECATED(10_0, 10_8, 2_0, 6_0);
 256
 257 /* Generate the XMLData (ready to be written to whatever permanent storage is to be
 258    used) from an CFXMLTree.  Will NOT regenerate entity references (except those
 259    required for syntactic correctness) if they were replaced at the parse time;
 260    clients that wish this should walk the tree and re-insert any entity references
 261    that should appear in the final output file. */
 262 CF_EXPORT
 263 CFDataRef CFXMLTreeCreateXMLData(CFAllocatorRef allocator, CFXMLTreeRef xmlTree) CF_DEPRECATED(10_0, 10_8, 2_0, 6_0);
 264
 265 /* Escaping and unescaping XML entities in CFStrings. The standard XML entities
 266    are always replaced.  */
 267 /* Creates a CFString by replacing entities that appear in the entities dictionary.
 268    Dictionary keys are the entities themselves, and the values should be CFStrings
 269    containing the expansion. Pass NULL for entitiesDictionary to indicate no entities
 270    other than the standard five. */
 271 CF_EXPORT
 272 CFStringRef CFXMLCreateStringByEscapingEntities(CFAllocatorRef allocator, CFStringRef string, CFDictionaryRef entitiesDictionary);
 273
 274 CF_EXPORT
 275 CFStringRef CFXMLCreateStringByUnescapingEntities(CFAllocatorRef allocator, CFStringRef string, CFDictionaryRef entitiesDictionary);
 276
 277 /* CFXMLTreeCreateFromDataWithError error dictionary key constants. */
 278 CF_EXPORT const CFStringRef kCFXMLTreeErrorDescription;
 279     /* value is a CFString containing the readable error string. */
 280
 281 CF_EXPORT const CFStringRef kCFXMLTreeErrorLineNumber;
 282     /* value is a CFNumber containing the line on which the error appears. */
 283
 284 CF_EXPORT const CFStringRef kCFXMLTreeErrorLocation;
 285     /* value is a CFNumber containing the byte location at which the error occurred. */
 286
 287 CF_EXPORT const CFStringRef kCFXMLTreeErrorStatusCode;
 288     /* value is a CFNumber containing the error status code. */
 289
 290 CF_EXTERN_C_END
 291 CF_IMPLICIT_BRIDGING_DISABLED
 292
 293 #endif /* ! __COREFOUNDATION_CFXMLPARSER__ */
 294