Parsing.subproj/CFXMLNode.h

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