[apple/cf.git] / CFXMLNode.h

/*
 * Copyright (c) 2011 Apple Inc. All rights reserved.
 *
 * @APPLE_LICENSE_HEADER_START@
 * 
 * This file contains Original Code and/or Modifications of Original Code
 * as defined in and that are subject to the Apple Public Source License
 * Version 2.0 (the 'License'). You may not use this file except in
 * compliance with the License. Please obtain a copy of the License at
 * http://www.opensource.apple.com/apsl/ and read it before using this
 * file.
 * 
 * The Original Code and all software distributed under the License are
 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
 * Please see the License for the specific language governing rights and
 * limitations under the License.
 * 
 * @APPLE_LICENSE_HEADER_END@
 */

/*	CFXMLNode.h
	Copyright (c) 1998-2011, Apple Inc. All rights reserved.
*/

/*  CFXMLParser (and thus CFXMLNode) are deprecated. Clients should be aware of the fact that CFXMLParser has 
    some serious deficiencies in terms of both performance and standards compliance and should migrate their 
    XML parsing to NSXMLParser, NSXMLDocument, or other XML parsing technologies.
 */

#if !defined(__COREFOUNDATION_CFXMLNODE__)
#define __COREFOUNDATION_CFXMLNODE__ 1

#include <CoreFoundation/CFArray.h>
#include <CoreFoundation/CFDictionary.h>
#include <CoreFoundation/CFString.h>
#include <CoreFoundation/CFTree.h>
#include <CoreFoundation/CFURL.h>

CF_EXTERN_C_BEGIN

enum {
	kCFXMLNodeCurrentVersion = 1
};

typedef const struct __CFXMLNode * CFXMLNodeRef;
typedef CFTreeRef CFXMLTreeRef;

/*  An CFXMLNode describes an individual XML construct - like a tag, or a comment, or a string
    of character data.  Each CFXMLNode contains 3 main pieces of information - the node's type,
    the data string, and a pointer to an additional data structure.  The node's type ID is an enum
    value of type CFXMLNodeTypeID.  The data string is always a CFStringRef; the meaning of the
    string is dependent on the node's type ID. The format of the additional data is also dependent
    on the node's type; in general, there is a custom structure for each type that requires
    additional data.  See below for the mapping from type ID to meaning of the data string and
    structure of the additional data.  Note that these structures are versioned, and may change
    as the parser changes.  The current version can always be identified by kCFXMLNodeCurrentVersion;
    earlier versions can be identified and used by passing earlier values for the version number
    (although the older structures would have been removed from the header).

    An CFXMLTree is simply a CFTree whose context data is known to be an CFXMLNodeRef.  As
    such, an CFXMLTree can be used to represent an entire XML document; the CFTree
    provides the tree structure of the document, while the CFXMLNodes identify and describe
    the nodes of the tree.  An XML document can be parsed to a CFXMLTree, and a CFXMLTree
    can generate the data for the equivalent XML document - see CFXMLParser.h for more
    information on parsing XML.
    */

/* Type codes for the different possible XML nodes; this list may grow.*/
enum {
    kCFXMLNodeTypeDocument = 1,
    kCFXMLNodeTypeElement = 2,
    kCFXMLNodeTypeAttribute = 3,
    kCFXMLNodeTypeProcessingInstruction = 4,
    kCFXMLNodeTypeComment = 5,
    kCFXMLNodeTypeText = 6,
    kCFXMLNodeTypeCDATASection = 7,
    kCFXMLNodeTypeDocumentFragment = 8,
    kCFXMLNodeTypeEntity = 9,
    kCFXMLNodeTypeEntityReference = 10,
    kCFXMLNodeTypeDocumentType = 11,
    kCFXMLNodeTypeWhitespace = 12,
    kCFXMLNodeTypeNotation = 13,
    kCFXMLNodeTypeElementTypeDeclaration = 14,
    kCFXMLNodeTypeAttributeListDeclaration = 15
};
typedef CFIndex CFXMLNodeTypeCode;

typedef struct {
    CFDictionaryRef attributes;
    CFArrayRef attributeOrder;
    Boolean isEmpty;
    char _reserved[3];
} CFXMLElementInfo;

typedef struct {
    CFStringRef dataString;
} CFXMLProcessingInstructionInfo;

typedef struct {
    CFURLRef sourceURL;
    CFStringEncoding encoding;
} CFXMLDocumentInfo;

typedef struct {
    CFURLRef systemID;
    CFStringRef publicID;
} CFXMLExternalID;

typedef struct {
    CFXMLExternalID externalID;
} CFXMLDocumentTypeInfo;

typedef struct {
    CFXMLExternalID externalID;
} CFXMLNotationInfo;

typedef struct {
    /* This is expected to change in future versions */
    CFStringRef contentDescription;
} CFXMLElementTypeDeclarationInfo;

typedef struct {
    /* This is expected to change in future versions */
    CFStringRef attributeName;
    CFStringRef typeString;
    CFStringRef defaultString;
} CFXMLAttributeDeclarationInfo;

typedef struct {
    CFIndex numberOfAttributes;
    CFXMLAttributeDeclarationInfo *attributes;
} CFXMLAttributeListDeclarationInfo;

enum {
    kCFXMLEntityTypeParameter,       /* Implies parsed, internal */
    kCFXMLEntityTypeParsedInternal,
    kCFXMLEntityTypeParsedExternal,
    kCFXMLEntityTypeUnparsed,
    kCFXMLEntityTypeCharacter
};
typedef CFIndex CFXMLEntityTypeCode;

typedef struct {
    CFXMLEntityTypeCode entityType;
    CFStringRef replacementText;     /* NULL if entityType is external or unparsed */
    CFXMLExternalID entityID;          /* entityID.systemID will be NULL if entityType is internal */
    CFStringRef notationName;        /* NULL if entityType is parsed */
} CFXMLEntityInfo;

typedef struct {
    CFXMLEntityTypeCode entityType;
} CFXMLEntityReferenceInfo;

/*
 dataTypeCode                       meaning of dataString                format of infoPtr
 ===========                        =====================                =================
 kCFXMLNodeTypeDocument             <currently unused>                   CFXMLDocumentInfo *
 kCFXMLNodeTypeElement              tag name                             CFXMLElementInfo *
 kCFXMLNodeTypeAttribute            <currently unused>                   <currently unused>
 kCFXMLNodeTypeProcessingInstruction   name of the target                   CFXMLProcessingInstructionInfo *
 kCFXMLNodeTypeComment              text of the comment                  NULL
 kCFXMLNodeTypeText                 the text's contents                  NULL
 kCFXMLNodeTypeCDATASection         text of the CDATA                    NULL
 kCFXMLNodeTypeDocumentFragment     <currently unused>                   <currently unused>
 kCFXMLNodeTypeEntity               name of the entity                   CFXMLEntityInfo *
 kCFXMLNodeTypeEntityReference      name of the referenced entity        CFXMLEntityReferenceInfo *
 kCFXMLNodeTypeDocumentType         name given as top-level element      CFXMLDocumentTypeInfo *
 kCFXMLNodeTypeWhitespace           text of the whitespace               NULL
 kCFXMLNodeTypeNotation             notation name                        CFXMLNotationInfo *
 kCFXMLNodeTypeElementTypeDeclaration     tag name                       CFXMLElementTypeDeclarationInfo *
 kCFXMLNodeTypeAttributeListDeclaration   tag name                       CFXMLAttributeListDeclarationInfo *
*/

CF_EXPORT
CFTypeID CFXMLNodeGetTypeID(void);

/* Creates a new node based on xmlType, dataString, and additionalInfoPtr.  version (together with xmlType) determines the expected structure of additionalInfoPtr */
CF_EXPORT
CFXMLNodeRef CFXMLNodeCreate(CFAllocatorRef alloc, CFXMLNodeTypeCode xmlType, CFStringRef dataString, const void *additionalInfoPtr, CFIndex version);

/* Creates a copy of origNode (which may not be NULL). */
CF_EXPORT
CFXMLNodeRef CFXMLNodeCreateCopy(CFAllocatorRef alloc, CFXMLNodeRef origNode);

CF_EXPORT
CFXMLNodeTypeCode CFXMLNodeGetTypeCode(CFXMLNodeRef node);

CF_EXPORT
CFStringRef CFXMLNodeGetString(CFXMLNodeRef node);

CF_EXPORT
const void *CFXMLNodeGetInfoPtr(CFXMLNodeRef node);

CF_EXPORT
CFIndex CFXMLNodeGetVersion(CFXMLNodeRef node);

/* CFXMLTreeRef */

/* Creates a childless, parentless tree from node */
CF_EXPORT
CFXMLTreeRef CFXMLTreeCreateWithNode(CFAllocatorRef allocator, CFXMLNodeRef node);

/* Extracts and returns the node stored in xmlTree */
CF_EXPORT
CFXMLNodeRef CFXMLTreeGetNode(CFXMLTreeRef xmlTree);

CF_EXTERN_C_END

#endif /* ! __COREFOUNDATION_CFXMLNODE__ */
Commit	Line	Data
9ce05555	1	/*
8ca704e1	2	* Copyright (c) 2011 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	/* CFXMLNode.h
8ca704e1	25	Copyright (c) 1998-2011, Apple Inc. All rights reserved.
9ce05555 A	26	*/
9ce05555 A	27
8ca704e1 A	28	/* CFXMLParser (and thus CFXMLNode) are deprecated. Clients should be aware of the fact that CFXMLParser has
	29	some serious deficiencies in terms of both performance and standards compliance and should migrate their
	30	XML parsing to NSXMLParser, NSXMLDocument, or other XML parsing technologies.
cf7d2af9 A	31	*/
cf7d2af9 A	32
9ce05555 A	33	#if !defined(__COREFOUNDATION_CFXMLNODE__)
	34	#define __COREFOUNDATION_CFXMLNODE__ 1
	35
	36	#include <CoreFoundation/CFArray.h>
	37	#include <CoreFoundation/CFDictionary.h>
	38	#include <CoreFoundation/CFString.h>
	39	#include <CoreFoundation/CFTree.h>
	40	#include <CoreFoundation/CFURL.h>
	41
bd5b749c	42	CF_EXTERN_C_BEGIN
9ce05555 A	43
	44	enum {
	45	kCFXMLNodeCurrentVersion = 1
	46	};
	47
	48	typedef const struct __CFXMLNode * CFXMLNodeRef;
	49	typedef CFTreeRef CFXMLTreeRef;
	50
	51	/* An CFXMLNode describes an individual XML construct - like a tag, or a comment, or a string
	52	of character data. Each CFXMLNode contains 3 main pieces of information - the node's type,
	53	the data string, and a pointer to an additional data structure. The node's type ID is an enum
	54	value of type CFXMLNodeTypeID. The data string is always a CFStringRef; the meaning of the
	55	string is dependent on the node's type ID. The format of the additional data is also dependent
	56	on the node's type; in general, there is a custom structure for each type that requires
	57	additional data. See below for the mapping from type ID to meaning of the data string and
	58	structure of the additional data. Note that these structures are versioned, and may change
	59	as the parser changes. The current version can always be identified by kCFXMLNodeCurrentVersion;
	60	earlier versions can be identified and used by passing earlier values for the version number
	61	(although the older structures would have been removed from the header).
	62
	63	An CFXMLTree is simply a CFTree whose context data is known to be an CFXMLNodeRef. As
	64	such, an CFXMLTree can be used to represent an entire XML document; the CFTree
	65	provides the tree structure of the document, while the CFXMLNodes identify and describe
	66	the nodes of the tree. An XML document can be parsed to a CFXMLTree, and a CFXMLTree
	67	can generate the data for the equivalent XML document - see CFXMLParser.h for more
	68	information on parsing XML.
	69	*/
	70
	71	/* Type codes for the different possible XML nodes; this list may grow.*/
bd5b749c	72	enum {
9ce05555 A	73	kCFXMLNodeTypeDocument = 1,
	74	kCFXMLNodeTypeElement = 2,
	75	kCFXMLNodeTypeAttribute = 3,
	76	kCFXMLNodeTypeProcessingInstruction = 4,
	77	kCFXMLNodeTypeComment = 5,
	78	kCFXMLNodeTypeText = 6,
	79	kCFXMLNodeTypeCDATASection = 7,
	80	kCFXMLNodeTypeDocumentFragment = 8,
	81	kCFXMLNodeTypeEntity = 9,
	82	kCFXMLNodeTypeEntityReference = 10,
	83	kCFXMLNodeTypeDocumentType = 11,
	84	kCFXMLNodeTypeWhitespace = 12,
	85	kCFXMLNodeTypeNotation = 13,
	86	kCFXMLNodeTypeElementTypeDeclaration = 14,
	87	kCFXMLNodeTypeAttributeListDeclaration = 15
bd5b749c A	88	};
bd5b749c A	89	typedef CFIndex CFXMLNodeTypeCode;
9ce05555 A	90
	91	typedef struct {
	92	CFDictionaryRef attributes;
	93	CFArrayRef attributeOrder;
	94	Boolean isEmpty;
	95	char _reserved[3];
	96	} CFXMLElementInfo;
	97
	98	typedef struct {
	99	CFStringRef dataString;
	100	} CFXMLProcessingInstructionInfo;
	101
	102	typedef struct {
	103	CFURLRef sourceURL;
	104	CFStringEncoding encoding;
	105	} CFXMLDocumentInfo;
	106
	107	typedef struct {
	108	CFURLRef systemID;
	109	CFStringRef publicID;
	110	} CFXMLExternalID;
	111
	112	typedef struct {
	113	CFXMLExternalID externalID;
	114	} CFXMLDocumentTypeInfo;
	115
	116	typedef struct {
	117	CFXMLExternalID externalID;
	118	} CFXMLNotationInfo;
	119
	120	typedef struct {
	121	/* This is expected to change in future versions */
	122	CFStringRef contentDescription;
	123	} CFXMLElementTypeDeclarationInfo;
	124
	125	typedef struct {
	126	/* This is expected to change in future versions */
	127	CFStringRef attributeName;
	128	CFStringRef typeString;
	129	CFStringRef defaultString;
	130	} CFXMLAttributeDeclarationInfo;
	131
	132	typedef struct {
	133	CFIndex numberOfAttributes;
	134	CFXMLAttributeDeclarationInfo *attributes;
	135	} CFXMLAttributeListDeclarationInfo;
	136
bd5b749c	137	enum {
9ce05555 A	138	kCFXMLEntityTypeParameter, /* Implies parsed, internal */
	139	kCFXMLEntityTypeParsedInternal,
	140	kCFXMLEntityTypeParsedExternal,
	141	kCFXMLEntityTypeUnparsed,
	142	kCFXMLEntityTypeCharacter
bd5b749c A	143	};
bd5b749c A	144	typedef CFIndex CFXMLEntityTypeCode;
9ce05555 A	145
	146	typedef struct {
	147	CFXMLEntityTypeCode entityType;
	148	CFStringRef replacementText; /* NULL if entityType is external or unparsed */
	149	CFXMLExternalID entityID; /* entityID.systemID will be NULL if entityType is internal */
	150	CFStringRef notationName; /* NULL if entityType is parsed */
	151	} CFXMLEntityInfo;
	152
	153	typedef struct {
	154	CFXMLEntityTypeCode entityType;
	155	} CFXMLEntityReferenceInfo;
	156
	157	/*
	158	dataTypeCode meaning of dataString format of infoPtr
	159	=========== ===================== =================
	160	kCFXMLNodeTypeDocument <currently unused> CFXMLDocumentInfo *
	161	kCFXMLNodeTypeElement tag name CFXMLElementInfo *
	162	kCFXMLNodeTypeAttribute <currently unused> <currently unused>
d8925383	163	kCFXMLNodeTypeProcessingInstruction name of the target CFXMLProcessingInstructionInfo *
9ce05555 A	164	kCFXMLNodeTypeComment text of the comment NULL
	165	kCFXMLNodeTypeText the text's contents NULL
	166	kCFXMLNodeTypeCDATASection text of the CDATA NULL
	167	kCFXMLNodeTypeDocumentFragment <currently unused> <currently unused>
	168	kCFXMLNodeTypeEntity name of the entity CFXMLEntityInfo *
	169	kCFXMLNodeTypeEntityReference name of the referenced entity CFXMLEntityReferenceInfo *
	170	kCFXMLNodeTypeDocumentType name given as top-level element CFXMLDocumentTypeInfo *
	171	kCFXMLNodeTypeWhitespace text of the whitespace NULL
	172	kCFXMLNodeTypeNotation notation name CFXMLNotationInfo *
	173	kCFXMLNodeTypeElementTypeDeclaration tag name CFXMLElementTypeDeclarationInfo *
	174	kCFXMLNodeTypeAttributeListDeclaration tag name CFXMLAttributeListDeclarationInfo *
	175	*/
	176
	177	CF_EXPORT
	178	CFTypeID CFXMLNodeGetTypeID(void);
	179
	180	/* Creates a new node based on xmlType, dataString, and additionalInfoPtr. version (together with xmlType) determines the expected structure of additionalInfoPtr */
	181	CF_EXPORT
	182	CFXMLNodeRef CFXMLNodeCreate(CFAllocatorRef alloc, CFXMLNodeTypeCode xmlType, CFStringRef dataString, const void *additionalInfoPtr, CFIndex version);
	183
	184	/* Creates a copy of origNode (which may not be NULL). */
	185	CF_EXPORT
	186	CFXMLNodeRef CFXMLNodeCreateCopy(CFAllocatorRef alloc, CFXMLNodeRef origNode);
	187
	188	CF_EXPORT
	189	CFXMLNodeTypeCode CFXMLNodeGetTypeCode(CFXMLNodeRef node);
	190
	191	CF_EXPORT
	192	CFStringRef CFXMLNodeGetString(CFXMLNodeRef node);
	193
	194	CF_EXPORT
	195	const void *CFXMLNodeGetInfoPtr(CFXMLNodeRef node);
	196
	197	CF_EXPORT
	198	CFIndex CFXMLNodeGetVersion(CFXMLNodeRef node);
	199
	200	/* CFXMLTreeRef */
	201
	202	/* Creates a childless, parentless tree from node */
	203	CF_EXPORT
	204	CFXMLTreeRef CFXMLTreeCreateWithNode(CFAllocatorRef allocator, CFXMLNodeRef node);
	205
	206	/* Extracts and returns the node stored in xmlTree */
	207	CF_EXPORT
	208	CFXMLNodeRef CFXMLTreeGetNode(CFXMLTreeRef xmlTree);
	209
bd5b749c	210	CF_EXTERN_C_END
9ce05555 A	211
	212	#endif /* ! __COREFOUNDATION_CFXMLNODE__ */
	213