CFXMLNode Reference

Overview

A CFXMLNode object describes an individual XML construct—like a tag, or a comment, or a string of character data. CFXMLNode is intended to be used with the CFXMLParser and CFXMLTree opaque types.

Each CFXMLNode object contains three main pieces of information—the node's type, the data string, and a pointer to an additional information data structure. A CFXMLNode object’s type is one of the enumerations described in Node Type Code. The data string is always a CFString object; the meaning of the string is dependent on the node's type. The format of the additional data is also dependent on the node's type; in general, there is a custom structure for each type that requires additional data. See Node Type Code for the mapping from a node type to meaning of the data string, and structure of the additional information. Note that these structures are versioned and may change as the parser changes. The current version can always be identified by the kCFXMLNodeCurrentVersion constant; earlier versions can be identified and used by passing earlier values for the version number (although the older structures would have been removed from the header).

You create a CFXMLNode object using one of the create or copy functions. Use the CFXMLNodeGetTypeCode, CFXMLNodeGetString, and CFXMLNodeGetInfoPtr functions to get the node type, data string, and additional information respectively. Use the CFXMLNodeGetVersion function to get a node’s version number.

Functions

CFXMLNodeCreate

Creates a new CFXMLNode.

CFXMLNodeRef CFXMLNodeCreate (
   CFAllocatorRef alloc,
   CFXMLNodeTypeCode xmlType,
   CFStringRef dataString,
   const void *additionalInfoPtr,
   CFIndex version
);

Parameters

alloc

The allocator to use to allocate memory for the new object. Pass NULL or kCFAllocatorDefault to use the current default allocator.

xmlType

Type identifier code for the XML structure you want this node to describe.

dataString

The XML data.

additionalInfoPtr

A pointer to a structure containing additional information about the XML data.

version

The version number of the CFXMLNode object you want to create. Pass one of the pre-defined constants, typically kCFXMLNodeCurrentVersion.

CFXMLNodeCreateCopy

Creates a copy of a CFXMLNode object.

CFXMLNodeRef CFXMLNodeCreateCopy (
   CFAllocatorRef alloc,
   CFXMLNodeRef origNode
);

Parameters

alloc

The allocator to use to allocate memory for the new object. Pass NULL or kCFAllocatorDefault to use the current default allocator.

origNode

The node to copy. Do not pass NULL.

CFXMLNodeGetInfoPtr

Returns the additional information pointer of a CFXMLNode object.

const void * CFXMLNodeGetInfoPtr (
   CFXMLNodeRef node
);

Parameters

node

The CFXMLNode object to examine.

CFXMLNodeGetString

Returns the data string from a CFXMLNode.

CFStringRef CFXMLNodeGetString (
   CFXMLNodeRef node
);

Parameters

node

The CFXMLNode object to examine.

CFXMLNodeGetTypeCode

Returns the XML structure type code for a CFXMLNode object.

CFXMLNodeTypeCode CFXMLNodeGetTypeCode (
   CFXMLNodeRef node
);

Parameters

node

The CFXMLNode object to examine.

CFXMLNodeGetTypeID

Returns the type identifier code for the CFXMLNode opaque type.

CFTypeID CFXMLNodeGetTypeID (
   void
);

CFXMLNodeGetVersion

Returns the version number for a CFXMLNode object.

CFIndex CFXMLNodeGetVersion (
   CFXMLNodeRef node
);

Parameters

node

The CFXMLNode object to examine.

Data Types

CFXMLAttributeDeclarationInfo

Contains information about an element attribute definition.

struct CFXMLAttributeDeclarationInfo {
   CFStringRef attributeName;
   CFStringRef typeString;
   CFStringRef defaultString;
};
typedef struct CFXMLAttributeDeclarationInfo CFXMLAttributeDeclarationInfo;

Fields

attributeName

The name of the attribute.

typeString

Describes the declaration of a single attribute.

defaultString

The attribute's default value.

Discussion

This structure is part of the definition of the CFXMLAttributeListDeclarationInfo structure.

CFXMLAttributeListDeclarationInfo

Contains a list of the attributes associated with an element.

struct CFXMLAttributeListDeclarationInfo {
   CFIndex numberOfAttributes;
   CFXMLAttributeDeclarationInfo *attributes;
};
typedef struct CFXMLAttributeListDeclarationInfo  CFXMLAttributeListDeclarationInfo;

Fields

numberOfAttributes

The number of attributes in the array.

attributes

A C array of attributes.

Discussion

A pointer to this structure is included in the CFXMLNode object passed to your application when the parser encounters an attribute declaration in the DTD. Use the CFXMLNodeGetInfoPtr function to obtain the pointer to this structure.

CFXMLDocumentInfo

Contains the source URL and text encoding information for the XML document.

struct CFXMLDocumentInfo {
   CFURLRef sourceURL;
   CFStringEncoding encoding;
};
typedef struct CFXMLDocumentInfo CFXMLDocumentInfo;

Fields

sourceURL

The source URL of the XML document.

encoding

The text encoding of the XML document.

Discussion

A pointer to this structure is included in the CFXMLNode object passed to your application when the parser encounters the XML declaration. Use the CFXMLNodeGetInfoPtr function to obtain the pointer.

CFXMLDocumentTypeInfo

Contains the external ID of the DTD.

struct CFXMLDocumentTypeInfo {
   CFXMLExternalID externalID;
};
typedef struct CFXMLDocumentTypeInfo CFXMLDocumentTypeInfo;

Fields

externalID

The external ID of the DTD.

Discussion

A pointer to this structure is included in the CFXMLNode object passed to your application when the parser encounters the beginning of the DTD. Use the CFXMLNodeGetInfoPtr function to obtain a pointer to this structure.

CFXMLElementInfo

Contains a list of element attributes packaged as CFDictionary key/value pairs.

struct CFXMLElementInfo {
   CFDictionaryRef attributes;
   CFArrayRef attributeOrder;
   Boolean isEmpty;
};
typedef struct CFXMLElementInfo CFXMLElementInfo;

Fields

attributes

The dictionary of attribute values.

attributeOrder

An array specifying the order in which the attributes appeared in the XML document.

isEmpty

A flag indicating whether the element was expressed in closed form.

Discussion

A pointer to this structure is included in the CFXMLNode object passed to your application when the parser encounters an element containing attributes. Use the CFXMLNodeGetInfoPtr function to obtain the pointer.

CFXMLElementTypeDeclarationInfo

Contains a description of the element type.

struct CFXMLElementTypeDeclarationInfo {
   CFStringRef contentDescription;
};
typedef struct CFXMLElementTypeDeclarationInfo CFXMLElementTypeDeclarationInfo;

Fields

contentDescription

A textual description of the element type.

Discussion

A pointer to this structure is included in the CFXMLNode passed to your application when the parser encounters and element type declaration. Use the CFXMLNodeGetInfoPtr function to obtain a pointer to this structure.

CFXMLEntityInfo

Contains information describing an XML entity.

struct CFXMLEntityInfo {
   CFXMLEntityTypeCode entityType;
   CFStringRef replacementText;
   CFXMLExternalID entityID;
   CFStringRef notationName;
};
typedef struct CFXMLEntityInfo CFXMLEntityInfo;

Fields

entityType

The entity type code.

replacementText

NULL if entityType is external or unparsed, otherwise the text that the entity should be replaced with.

entityID

entityID.systemID will be NULL if entityType is internal.

notationName

NULL if entityType is parsed.

Discussion

A pointer to this structure is included in the CFXMLNode object passed to your application when the parser encounters an entity declaration. Use the CFXMLNodeGetInfoPtr function to obtain a pointer to this structure.

CFXMLEntityReferenceInfo

Contains information describing an XML entity reference.

struct CFXMLEntityReferenceInfo {
   CFXMLEntityTypeCode entityType;
};
typedef struct CFXMLEntityReferenceInfo CFXMLEntityReferenceInfo;

Fields

entityType

The entity type code.

Discussion

A pointer to this structure is included in the CFXMLNode object passed to your application when the parser encounters an entity reference. Use the CFXMLNodeGetInfoPtr function to obtain the pointer.

CFXMLExternalID

Contains the system and public IDs for an external entity reference.

struct CFXMLExternalID {
   CFURLRef systemID;
   CFStringRef publicID;
};
typedef struct CFXMLExternalID CFXMLExternalID;

Fields

systemID

The systemID URL.

publicID

The publicID string.

Discussion

This structure is part of the definition of the CFXMLDocumentTypeInfo, CFXMLNotationInfo, and CFXMLEntityInfo structures.

CFXMLNodeRef

A reference to a CFXMLNode object.

typedef const struct __CFXMLNode *CFXMLNodeRef;

CFXMLNotationInfo

Contains the external ID of the notation.

struct CFXMLNotationInfo {
   CFXMLExternalID externalID;
};
typedef struct CFXMLNotationInfo CFXMLNotationInfo;

Fields

externalID

The external ID of the notation.

Discussion

A pointer to this structure is included in the CFXMLNode object passed to your application when the parser encounters a notation element. Use the CFXMLNodeGetInfoPtr function to obtain a pointer to this structure.

CFXMLProcessingInstructionInfo

Contains the text of the processing instruction.

struct CFXMLProcessingInstructionInfo {
   CFStringRef dataString;
};
typedef struct CFXMLProcessingInstructionInfo CFXMLProcessingInstructionInfo;

Fields

dataString

The text of the processing instruction.

Discussion

A pointer to this structure is included in the CFXMLNode object passed to your application when the parser encounters a processing instruction. Use the CFXMLNodeGetInfoPtr function to obtain the pointer.

Constants

Entity Type Code

The entity type identification codes that the parser uses to describe XML entities.

enum CFXMLEntityTypeCode {
   kCFXMLEntityTypeParameter = 0,
   kCFXMLEntityTypeParsedInternal = 1,
   kCFXMLEntityTypeParsedExternal = 2,
   kCFXMLEntityTypeUnparsed = 3,
   kCFXMLEntityTypeCharacter = 4
};
typedef enum CFXMLEntityTypeCode CFXMLEntityTypeCode;

Constants

kCFXMLEntityTypeParameter

Implies a parsed, internal entity.

Available in Mac OS X v10.0 and later.

Declared in CFXMLNode.h.

kCFXMLEntityTypeParsedInternal

Indicates a parsed, internal entity.

Available in Mac OS X v10.0 and later.

Declared in CFXMLNode.h.

kCFXMLEntityTypeParsedExternal

Indicates a parsed, external entity.

Available in Mac OS X v10.0 and later.

Declared in CFXMLNode.h.

kCFXMLEntityTypeUnparsed

Indicates an unparsed entity.

Available in Mac OS X v10.0 and later.

Declared in CFXMLNode.h.

kCFXMLEntityTypeCharacter

Indicates a character entity type.

Available in Mac OS X v10.0 and later.

Declared in CFXMLNode.h.

Discussion

These codes are used with the CFXMLEntityInfo and CFXMLEntityReferenceInfo structures.

Node Current Version

The version of a CFXMLNode object.

enum {
   kCFXMLNodeCurrentVersion = 1
};

Constants

kCFXMLNodeCurrentVersion

The current version of CFXMLNode objects.

Available in Mac OS X v10.0 and later.

Declared in CFXMLNode.h.

Node Type Code

The various XML data type identification codes that the parser uses to describe XML structures.

enum CFXMLNodeTypeCode {
   kCFXMLNodeTypeDocument = 1,
   kCFXMLNodeTypeElement = 2,
   kCFXMLNodeTypeAttribute = 3,
   kCFXMLNodeTypeProcessingInstruction = 4,
   kCFXMLNodeTypeComment = 5,
   kCFXMLNodeTypeText = 6,
   kCFXMLNodeTypeCDATASection = 7,
   kCFXMLNodeTypeDocumentFragment = 8,
   kCFXMLNodeTypeEntity = 9,
   kCFXMLNodeTypeEntityReference = 10,
   kCFXMLNodeTypeDocumentType = 11,
   kCFXMLNodeTypeWhitespace = 12,
   kCFXMLNodeTypeNotation = 13,
   kCFXMLNodeTypeElementTypeDeclaration = 14,
   kCFXMLNodeTypeAttributeListDeclaration = 15
};
typedef enum CFXMLNodeTypeCode CFXMLNodeTypeCode;

Constants

kCFXMLNodeTypeDocument

Indicates a document where the data string is NULL and the additional information is a pointer to a CFXMLDocumentInfo structure.

Available in Mac OS X v10.0 and later.

Declared in CFXMLNode.h.

kCFXMLNodeTypeElement

Indicates an element where the data string is the name of the tag and the additional information is a pointer to a CFXMLElementInfo structure.

Available in Mac OS X v10.0 and later.

Declared in CFXMLNode.h.

kCFXMLNodeTypeAttribute

Currently not used.

Available in Mac OS X v10.0 and later.

Declared in CFXMLNode.h.

kCFXMLNodeTypeProcessingInstruction

Indicates a processing instruction where the data string is the name of the target and the additional information is a pointer to a CFXMLProcessingInstructionInfo structure.

Available in Mac OS X v10.0 and later.

Declared in CFXMLNode.h.

kCFXMLNodeTypeComment

Indicates a comment section where the data string is the text of the comment and the additional information is NULL.

Available in Mac OS X v10.0 and later.

Declared in CFXMLNode.h.

kCFXMLNodeTypeText

Indicates a text section where the data string is the text’s contents and the additional information is NULL.

Available in Mac OS X v10.0 and later.

Declared in CFXMLNode.h.

kCFXMLNodeTypeCDATASection

Indicates a CDATA section where the data string is the text of the CDATA and the additional information is NULL.

Available in Mac OS X v10.0 and later.

Declared in CFXMLNode.h.

kCFXMLNodeTypeDocumentFragment

Currently not used.

Available in Mac OS X v10.0 and later.

Declared in CFXMLNode.h.

kCFXMLNodeTypeEntity

Indicates an entity where the data string is the name of the entity and the additional information is a pointer to a CFXMLEntityInfo structure.

Available in Mac OS X v10.0 and later.

Declared in CFXMLNode.h.

kCFXMLNodeTypeEntityReference

Indicates an entity reference where the data string is the name of the referenced entity and the additional information is a pointer to a CFXMLEntityReferenceInfo structure.

Available in Mac OS X v10.0 and later.

Declared in CFXMLNode.h.

kCFXMLNodeTypeDocumentType

Indicates a document type where the data string is the name given to the top-level element and the additional information is a pointer to a CFXMLDocumentTypeInfo structure.

Available in Mac OS X v10.0 and later.

Declared in CFXMLNode.h.

kCFXMLNodeTypeWhitespace

Indicates white space where the data string is the text of the white space and the additional information is NULL.

Available in Mac OS X v10.0 and later.

Declared in CFXMLNode.h.

kCFXMLNodeTypeNotation

Indicates a notation where the data string is the notation name and the additional information is a pointer to a CFXMLNotationInfo structure.

Available in Mac OS X v10.0 and later.

Declared in CFXMLNode.h.

kCFXMLNodeTypeElementTypeDeclaration

Indicates an element type declaration where the data string is the tag name and the additional information is a pointer to a CFXMLElementTypeDeclarationInfo structure.

Available in Mac OS X v10.0 and later.

Declared in CFXMLNode.h.

kCFXMLNodeTypeAttributeListDeclaration

Indicates an attribute list declaration where the data string is the tag name and the additional information is a pointer to a CFXMLAttributeListDeclarationInfo structure.

Available in Mac OS X v10.0 and later.

Declared in CFXMLNode.h.

Discussion

When the parser encounters a new XML structure, its data type and contents are placed in a CFXMLNode object.

---