CFXMLNodes

Both of the XML Services parser APIs rely on a single data structure to return XML data to your application, the CFXMLNode . This opaque Core Foundation type describes an individual XML construct, such as a tag, a comment, or a string of character data.

Each CFXMLNode contains three main pieces of information--the node's type, the data string, and a pointer to a data structure with additional information. You extract this data using simple accessor functions. The node's type is encoded as an enumeration constant describing the type of XML structure. The data string is always a CFString; the meaning of the string depends on the node's type ID. The format of the additional data is also depends on the node's type; there is a specific structure for each type that requires additional data.

As an XML document is parsed, each XML structure encountered by the parser is converted into a CFXMLNode that contains the XML data. For example, when parsing the document shown in Listing 1-1, the parser would respond to the tag <birthday> by creating a new CFXMLNode whose node type would be set to the identifier kCFXMLNodeTypeElement . The CFXMLNode data string would contain the CFString "birthday", and the additional data pointer would point to a CFXMLElementInfo structure containing information about the element's attributes.

In order to handle some of the more complex XML entities, Core Foundation XML Services defines several additional data structures. The structures that contain additionhal information are described briefly in Table 1-1.

Table 1-1   XML parser additional inforamtion structures
Structure Content Description
CFXMLElementInfo A list of element attributes.
CFXMLProcessingInstructionInfo The processing instruction.
CFXMLDocumentInfo The source URL for the document along with character encoding information.
CFXMLDocumentTypeInfo The system and public IDs for the DTD.
CFXMLNotationInfo The system and public IDs for the notation.
CFXMLElementTypeDeclarationInfo The string that describes the element's permissible content.
CFXMLAttributeDeclarationInfo The name of the attribute being declared, the string describing the attribute's type, and the attribute's default value.
CFXMLAttributeListDeclarationInfo A list of CFXMLAttributeDeclarationInfo structures.
CFXMLEntityInfo The type of the entity, the text to be substituted for the entity when referenced, the location of the entity (for external entities), and the name of the entity's notation if the entity is not parsed.
CFXMLEntityReferenceInfo The type of the entity reference.

To briefly illustrate how these structures are used by the parser, consider once again the XML document shown in Listing 1-1. The fourth line of the document contains the tag <address region="US"> . The string region="USA" defines an element attribute called region whose value is USA . Element attributes are a way to associate additional data with a given element.

The XML Services parser returns a tag's attributes to your application as a CFXMLElementInfo structure. This structure is shown in Listing 1-2.

Listing 1-2 The CFXMLElementInfo structure
typedef struct { CFDictionaryRef attributes; CFArrayRef attributeOrder; Boolean isEmpty; } CFXMLElementInfo;

When parsing this tag, the parser creates a CFXMLNode whose type code is kCFXMLNodeTypeElement , and whose data string is "address" . The additional information pointer is set to point to a CFXMLElementInfo structure describing the element and its attributes. The attributes field contains a CFDictionary holding the attribute data in the key/value format. The attributeOrder field contains a CFArray holding the attributes dictionary keys in the order they were encountered. The field isEmpty designates whether the element was expressed in closed form. See the chapter "Collection Services" for more information about CFDictionary and CFArray.


© 2000 Apple Computer, Inc. (Last Updated 14 July 2000)