CFXMLNode.h

   1 /*
   2  * Copyright (c) 2011 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-2011, Apple Inc. All rights reserved.
  26 */
  27
  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.
  31  */
  32
  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
  42 CF_EXTERN_C_BEGIN
  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.*/
  72 enum {
  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
  88 };
  89 typedef CFIndex CFXMLNodeTypeCode;
  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
 137 enum {
 138     kCFXMLEntityTypeParameter,       /* Implies parsed, internal */
 139     kCFXMLEntityTypeParsedInternal,
 140     kCFXMLEntityTypeParsedExternal,
 141     kCFXMLEntityTypeUnparsed,
 142     kCFXMLEntityTypeCharacter
 143 };
 144 typedef CFIndex CFXMLEntityTypeCode;
 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>
 163  kCFXMLNodeTypeProcessingInstruction   name of the target                   CFXMLProcessingInstructionInfo *
 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
 210 CF_EXTERN_C_END
 211
 212 #endif /* ! __COREFOUNDATION_CFXMLNODE__ */
 213