1/* 2 * Copyright (c) 2014 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-2013, 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 41CF_EXTERN_C_BEGIN 42 43typedef 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 51kCFXMLParserValidateDocument - 52 validate the document against its grammar from the DTD, reporting any errors. 53 Currently not supported. 54 55kCFXMLParserSkipMetaData - 56 silently skip over metadata constructs (the DTD and comments) 57 58kCFXMLParserReplacePhysicalEntities - 59 replace declared entities like <. 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 63kCFXMLParserSkipWhitespace - 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 69kCFXMLParserAddImpliedAttributes - 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 75typedef 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 */ 87typedef 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 111createXMLStructure - 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 122addChild - 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 127endXMLStructure - 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 133createXMLStructure, addChild, and endXMLStructure are all REQUIRED TO BE NON-NULL. 134 135resolveExternalEntity - 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 142handleError - 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 150typedef void * (*CFXMLParserCreateXMLStructureCallBack)(CFXMLParserRef parser, CFXMLNodeRef nodeDesc, void *info); 151typedef void (*CFXMLParserAddChildCallBack)(CFXMLParserRef parser, void *parent, void *child, void *info); 152typedef void (*CFXMLParserEndXMLStructureCallBack)(CFXMLParserRef parser, void *xmlType, void *info); 153typedef CFDataRef (*CFXMLParserResolveExternalEntityCallBack)(CFXMLParserRef parser, CFXMLExternalID *extID, void *info); 154typedef Boolean (*CFXMLParserHandleErrorCallBack)(CFXMLParserRef parser, CFXMLParserStatusCode error, void *info); 155typedef struct { 156 CFIndex version; 157 CFXMLParserCreateXMLStructureCallBack createXMLStructure; 158 CFXMLParserAddChildCallBack addChild; 159 CFXMLParserEndXMLStructureCallBack endXMLStructure; 160 CFXMLParserResolveExternalEntityCallBack resolveExternalEntity; 161 CFXMLParserHandleErrorCallBack handleError; 162} CFXMLParserCallBacks; 163 164typedef const void * (*CFXMLParserRetainCallBack)(const void *info); 165typedef void (*CFXMLParserReleaseCallBack)(const void *info); 166typedef CFStringRef (*CFXMLParserCopyDescriptionCallBack)(const void *info); 167typedef struct { 168 CFIndex version; 169 void * info; 170 CFXMLParserRetainCallBack retain; 171 CFXMLParserReleaseCallBack release; 172 CFXMLParserCopyDescriptionCallBack copyDescription; 173} CFXMLParserContext; 174 175CF_EXPORT 176CFTypeID 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. */ 185CF_EXPORT 186CFXMLParserRef 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. */ 190CF_EXPORT 191CFXMLParserRef CFXMLParserCreateWithDataFromURL(CFAllocatorRef allocator, CFURLRef dataSource, CFOptionFlags parseOptions, CFIndex versionOfNodes, CFXMLParserCallBacks *callBacks, CFXMLParserContext *context) CF_DEPRECATED(10_0, 10_8, 2_0, 6_0); 192 193CF_EXPORT 194void CFXMLParserGetContext(CFXMLParserRef parser, CFXMLParserContext *context) CF_DEPRECATED(10_0, 10_8, 2_0, 6_0); 195 196CF_EXPORT 197void CFXMLParserGetCallBacks(CFXMLParserRef parser, CFXMLParserCallBacks *callBacks) CF_DEPRECATED(10_0, 10_8, 2_0, 6_0); 198 199CF_EXPORT 200CFURLRef CFXMLParserGetSourceURL(CFXMLParserRef parser) CF_DEPRECATED(10_0, 10_8, 2_0, 6_0); 201 202/* Returns the character index of the current parse location */ 203CF_EXPORT 204CFIndex CFXMLParserGetLocation(CFXMLParserRef parser) CF_DEPRECATED(10_0, 10_8, 2_0, 6_0); 205 206/* Returns the line number of the current parse location */ 207CF_EXPORT 208CFIndex 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 */ 211CF_EXPORT 212void *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 */ 217CF_EXPORT 218CFXMLParserStatusCode CFXMLParserGetStatusCode(CFXMLParserRef parser) CF_DEPRECATED(10_0, 10_8, 2_0, 6_0); 219 220CF_EXPORT 221CFStringRef 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) */ 226CF_EXPORT 227void 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. */ 234CF_EXPORT 235Boolean 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. */ 243CF_EXPORT 244CFXMLTreeRef 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. */ 249CF_EXPORT 250CFXMLTreeRef 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. */ 253CF_EXPORT 254CFXMLTreeRef 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. */ 261CF_EXPORT 262CFDataRef 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. */ 270CF_EXPORT 271CFStringRef CFXMLCreateStringByEscapingEntities(CFAllocatorRef allocator, CFStringRef string, CFDictionaryRef entitiesDictionary); 272 273CF_EXPORT 274CFStringRef CFXMLCreateStringByUnescapingEntities(CFAllocatorRef allocator, CFStringRef string, CFDictionaryRef entitiesDictionary); 275 276/* CFXMLTreeCreateFromDataWithError error dictionary key constants. */ 277CF_EXPORT const CFStringRef kCFXMLTreeErrorDescription; 278 /* value is a CFString containing the readable error string. */ 279 280CF_EXPORT const CFStringRef kCFXMLTreeErrorLineNumber; 281 /* value is a CFNumber containing the line on which the error appears. */ 282 283CF_EXPORT const CFStringRef kCFXMLTreeErrorLocation; 284 /* value is a CFNumber containing the byte location at which the error occurred. */ 285 286CF_EXPORT const CFStringRef kCFXMLTreeErrorStatusCode; 287 /* value is a CFNumber containing the error status code. */ 288 289CF_EXTERN_C_END 290 291#endif /* ! __COREFOUNDATION_CFXMLPARSER__ */ 292 293