CFXMLNode.h

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