Protocol: NSXMLParserDelegate

Overview

The NSXMLParserDelegate protocol defines the optional methods implemented by delegates of NSXMLParser objects.Sent by a parser object to its delegate when it encounters an end tag for a specific element.Sent by a parser object to its delegate when a given namespace prefix goes out of scope.Sent by a parser object to its delegate when it encounters a start tag for a given element.Sent by a parser object to its delegate the first time it encounters a given namespace prefix, which is mapped to a URI.Sent by a parser object to its delegate when it encounters a declaration of an attribute that is associated with a specific element.Sent by a parser object to its delegate when it encounters a CDATA block.Sent by a parser object to provide its delegate with a string representing all or part of the characters of the current element.Sent by a parser object to its delegate when it encounters a comment in the XML.Sent by a parser object to its delegate when it encounters a declaration of an element with a given model.Sent by a parser object to its delegate when it encounters an external entity declaration.Reported by a parser object to provide its delegate with a string representing all or part of the ignorable whitespace characters of the current element.Sent by a parser object to the delegate when it encounters an internal entity declaration.Sent by a parser object to its delegate when it encounters a notation declaration.Sent by a parser object to its delegate when it encounters a processing instruction.Sent by a parser object to its delegate when it encounters an unparsed entity declaration.Sent by a parser object to its delegate when it encounters a fatal error.Sent by a parser object to its delegate when it encounters a given external entity with a specific system ID.Sent by a parser object to its delegate when it encounters a fatal validation error. NSXMLParser currently does not invoke this method and does not perform validation.Sent by the parser object to the delegate when it has successfully completed parsing.Sent by the parser object to the delegate when it begins parsing a document.

Instance Method Summary (collapse)

Instance Method Details

- (Object) parser(parser, didEndElement:elementName, namespaceURI:namespaceURI, qualifiedName:qName)

Sent by a parser object to its delegate when it encounters an end tag for a specific element.

Parameters:

  • parser (NSXMLParser) —

    A parser object.

  • elementName (String) —

    A string that is the name of an element (in its end tag).

  • namespaceURI (String) —

    If namespace processing is turned on, contains the URI for the current namespace as a string object.

  • qName (String) —

    If namespace processing is turned on, contains the qualified name for the current namespace as a string object.

Returns:

- (Object) parser(parser, didEndMappingPrefix:prefix)

Sent by a parser object to its delegate when a given namespace prefix goes out of scope. The parser sends this message only when namespace-prefix reporting is turned on through the setShouldReportNamespacePrefixes: method.

Parameters:

  • parser (NSXMLParser) —

    A parser object.

  • prefix (String) —

    A string that is a namespace prefix.

Returns:

- (Object) parser(parser, didStartElement:elementName, namespaceURI:namespaceURI, qualifiedName:qualifiedName, attributes:attributeDict)

Sent by a parser object to its delegate when it encounters a start tag for a given element.

Parameters:

  • parser (NSXMLParser) —

    A parser object.

  • elementName (String) —

    A string that is the name of an element (in its start tag).

  • namespaceURI (String) —

    If namespace processing is turned on, contains the URI for the current namespace as a string object.

  • qualifiedName (String) —

    If namespace processing is turned on, contains the qualified name for the current namespace as a string object..

  • attributeDict (Hash) —

    A dictionary that contains any attributes associated with the element. Keys are the names of attributes, and values are attribute values.

Returns:

- (Object) parser(parser, didStartMappingPrefix:prefix, toURI:namespaceURI)

Sent by a parser object to its delegate the first time it encounters a given namespace prefix, which is mapped to a URI. The parser object sends this message only when namespace-prefix reporting is turned on through the setShouldReportNamespacePrefixes: method.

Parameters:

  • parser (NSXMLParser) —

    A parser object.

  • prefix (String) —

    A string that is a namespace prefix.

  • namespaceURI (String) —

    A string that specifies a namespace URI.

Returns:

- (Object) parser(parser, foundAttributeDeclarationWithName:attributeName, forElement:elementName, type:type, defaultValue:defaultValue)

Sent by a parser object to its delegate when it encounters a declaration of an attribute that is associated with a specific element.

Parameters:

  • parser (NSXMLParser) —

    An NSXMLParser object parsing XML.

  • attributeName (String) —

    A string that is the name of an attribute.

  • elementName (String) —

    A string that is the name of an element that has the attribute attributeName.

  • type (String) —

    A string, such as "ENTITY", "NOTATION", or "ID", that indicates the type of the attribute.

  • defaultValue (String) —

    A string that specifies the default value of the attribute.

Returns:

- (Object) parser(parser, foundCDATA:CDATABlock)

Sent by a parser object to its delegate when it encounters a CDATA block. Through this method the parser object passes the contents of the block to its delegate in an NSData object. The CDATA block is character data that is ignored by the parser. The encoding of the character data is UTF-8. To convert the data object to a string object, use the NSString method initWithData:encoding:.

Parameters:

Returns:

- (Object) parser(parser, foundCharacters:string)

Sent by a parser object to provide its delegate with a string representing all or part of the characters of the current element. The parser object may send the delegate several parser:foundCharacters: messages to report the characters of an element. Because string may be only part of the total character content for the current element, you should append it to the current accumulation of characters until the element changes.

Parameters:

  • parser (NSXMLParser) —

    A parser object.

  • string (String) —

    A string representing the complete or partial textual content of the current element.

Returns:

- (Object) parser(parser, foundComment:comment)

Sent by a parser object to its delegate when it encounters a comment in the XML.

Parameters:

Returns:

- (Object) parser(parser, foundElementDeclarationWithName:elementName, model:model)

Sent by a parser object to its delegate when it encounters a declaration of an element with a given model.

Parameters:

  • parser (NSXMLParser) —

    An NSXMLParser object parsing XML.

  • elementName (String) —

    A string that is the name of an element.

  • model (String) —

    A string that specifies a model for elementName.

Returns:

- (Object) parser(parser, foundExternalEntityDeclarationWithName:entityName, publicID:publicID, systemID:systemID)

Sent by a parser object to its delegate when it encounters an external entity declaration.

Parameters:

  • parser (NSXMLParser) —

    An NSXMLParser object parsing XML.

  • entityName (String) —

    A string that is the name of an entity.

  • publicID (String) —

    A string that specifies the public ID associated with entityName.

  • systemID (String) —

    A string that specifies the system ID associated with entityName.

Returns:

- (Object) parser(parser, foundIgnorableWhitespace:whitespaceString)

Reported by a parser object to provide its delegate with a string representing all or part of the ignorable whitespace characters of the current element. All the whitespace characters of the element (including carriage returns, tabs, and new-line characters) may not be provided through an individual invocation of this method. The parser may send the delegate several parser:foundIgnorableWhitespace: messages to report the whitespace characters of an element. You should append the characters in each invocation to the current accumulation of characters.

Parameters:

  • parser (NSXMLParser) —

    A parser object.

  • whitespaceString (String) —

    A string representing all or part of the ignorable whitespace characters of the current element.

Returns:

- (Object) parser(parser, foundInternalEntityDeclarationWithName:name, value:value)

Sent by a parser object to the delegate when it encounters an internal entity declaration.

Parameters:

  • parser (NSXMLParser) —

    An NSXMLParser object parsing XML.

  • name (String) —

    A string that is the declared name of an internal entity.

  • value (String) —

    A string that is the value of entity name.

Returns:

- (Object) parser(parser, foundNotationDeclarationWithName:name, publicID:publicID, systemID:systemID)

Sent by a parser object to its delegate when it encounters a notation declaration.

Parameters:

  • parser (NSXMLParser) —

    An NSXMLParser object parsing XML.

  • name (String) —

    A string that is the name of the notation.

  • publicID (String) —

    A string specifying the public ID associated with the notation name.

  • systemID (String) —

    A string specifying the system ID associated with the notation name.

Returns:

- (Object) parser(parser, foundProcessingInstructionWithTarget:target, data:data)

Sent by a parser object to its delegate when it encounters a processing instruction.

Parameters:

  • parser (NSXMLParser) —

    A parser object.

  • target (String) —

    A string representing the target of a processing instruction.

  • data (String) —

    A string representing the data for a processing instruction.

Returns:

- (Object) parser(parser, foundUnparsedEntityDeclarationWithName:name, publicID:publicID, systemID:systemID, notationName:notationName)

Sent by a parser object to its delegate when it encounters an unparsed entity declaration.

Parameters:

  • parser (NSXMLParser) —

    An NSXMLParser object parsing XML.

  • name (String) —

    A string that is the name of the unparsed entity in the declaration.

  • publicID (String) —

    A string specifying the public ID associated with the entity name.

  • systemID (String) —

    A string specifying the system ID associated with the entity name.

  • notationName (String) —

    A string specifying a notation of the declaration of entity name.

Returns:

- (Object) parser(parser, parseErrorOccurred:parseError)

Sent by a parser object to its delegate when it encounters a fatal error. When this method is invoked, parsing is stopped. For further information about the error, you can query parseError or you can send the parser a parserError message. You can also send the parser lineNumber and columnNumber messages to further isolate where the error occurred. Typically you implement this method to display information about the error to the user.

Parameters:

  • parser (NSXMLParser) —

    A parser object.

  • parseError (NSError) —

    An NSError object describing the parsing error that occurred.

Returns:

- (NSData) parser(parser, resolveExternalEntityName:entityName, systemID:systemID)

Sent by a parser object to its delegate when it encounters a given external entity with a specific system ID. The delegate can resolve the external entity (for example, locating and reading an externally declared DTD) and provide the result to the parser object as an NSData object.

Parameters:

  • parser (NSXMLParser) —

    A parser object.

  • entityName (String) —

    A string that specifies the external name of an entity.

  • systemID (String) —

    A string that specifies the system ID for the external entity.

Returns:

  • (NSData) —

    An NSData object that contains the resolution of the given external entity.

- (Object) parser(parser, validationErrorOccurred:validError)

Sent by a parser object to its delegate when it encounters a fatal validation error. NSXMLParser currently does not invoke this method and does not perform validation. If you want to validate an XML document, use the validation features of the NSXMLDocument class.

Parameters:

  • parser (NSXMLParser) —

    A parser object.

  • validError (NSError) —

    An NSError object describing the validation error that occurred.

Returns:

- (Object) parserDidEndDocument(parser)

Sent by the parser object to the delegate when it has successfully completed parsing.

Parameters:

Returns:

- (Object) parserDidStartDocument(parser)

Sent by the parser object to the delegate when it begins parsing a document.

Parameters:

Returns: