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