CFXMLNode.h

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