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 &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
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