CFXMLNode.h

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