IXmlPullParser.NextToken Method

Definition

Namespace:

Org.XmlPull.V1

Assembly:

Mono.Android.dll

This method works similarly to next() but will expose additional event types (COMMENT, CDSECT, DOCDECL, ENTITY_REF, PROCESSING_INSTRUCTION, or IGNORABLE_WHITESPACE) if they are available in input.

[Android.Runtime.Register("nextToken", "()I", "GetNextTokenHandler:Org.XmlPull.V1.IXmlPullParserInvoker, Mono.Android, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null")]
public Org.XmlPull.V1.XmlPullParserNode NextToken ();

[<Android.Runtime.Register("nextToken", "()I", "GetNextTokenHandler:Org.XmlPull.V1.IXmlPullParserInvoker, Mono.Android, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null")>]
abstract member NextToken : unit -> Org.XmlPull.V1.XmlPullParserNode

Returns

XmlPullParserNode

Attributes

RegisterAttribute

Exceptions

XmlPullParserException

IOException

Remarks

This method works similarly to next() but will expose additional event types (COMMENT, CDSECT, DOCDECL, ENTITY_REF, PROCESSING_INSTRUCTION, or IGNORABLE_WHITESPACE) if they are available in input.

If special feature FEATURE_XML_ROUNDTRIP (identified by URI: http://xmlpull.org/v1/doc/features.html#xml-roundtrip) is enabled it is possible to do XML document round trip ie. reproduce exectly on output the XML input using getText(): returned content is always unnormalized (exactly as in input). Otherwise returned content is end-of-line normalized as described XML 1.0 End-of-Line Handling and. Also when this feature is enabled exact content of START_TAG, END_TAG, DOCDECL and PROCESSING_INSTRUCTION is available.

Here is the list of tokens that can be returned from nextToken() and what getText() and getTextCharacters() returns:<dl> <dt>START_DOCUMENT<dd>null <dt>END_DOCUMENT<dd>null <dt>START_TAG<dd>null unless FEATURE_XML_ROUNDTRIP enabled and then returns XML tag, ex: &lt;tag attr='val'> <dt>END_TAG<dd>null unless FEATURE_XML_ROUNDTRIP id enabled and then returns XML tag, ex: &lt;/tag> <dt>TEXT<dd>return element content. <br>Note: that element content may be delivered in multiple consecutive TEXT events. <dt>IGNORABLE_WHITESPACE<dd>return characters that are determined to be ignorable white space. If the FEATURE_XML_ROUNDTRIP is enabled all whitespace content outside root element will always reported as IGNORABLE_WHITESPACE otherwise reporting is optional. <br>Note: that element content may be delivered in multiple consecutive IGNORABLE_WHITESPACE events. <dt>CDSECT<dd> return text <em>inside</em> CDATA (ex. 'fo&lt;o' from &lt;!CDATA[fo&lt;o]]>) <dt>PROCESSING_INSTRUCTION<dd> if FEATURE_XML_ROUNDTRIP is true return exact PI content ex: 'pi foo' from &lt;?pi foo?> otherwise it may be exact PI content or concatenation of PI target, space and data so for example for &lt;?target data?> string &quot;target data&quot; may be returned if FEATURE_XML_ROUNDTRIP is false. <dt>COMMENT<dd>return comment content ex. 'foo bar' from &lt;!--foo bar--> <dt>ENTITY_REF<dd>getText() MUST return entity replacement text if PROCESS_DOCDECL is false otherwise getText() MAY return null, additionally getTextCharacters() MUST return entity name (for example 'entity_name' for &amp;entity_name;). <br><b>NOTE:</b> this is the only place where value returned from getText() and getTextCharacters() <b>are different</b> <br><b>NOTE:</b> it is user responsibility to resolve entity reference if PROCESS_DOCDECL is false and there is no entity replacement text set in defineEntityReplacementText() method (getText() will be null) <br><b>NOTE:</b> character entities (ex. &amp;#32;) and standard entities such as &amp;amp; &amp;lt; &amp;gt; &amp;quot; &amp;apos; are reported as well and are <b>not</b> reported as TEXT tokens but as ENTITY_REF tokens! This requirement is added to allow to do roundtrip of XML documents! <dt>DOCDECL<dd> if FEATURE_XML_ROUNDTRIP is true or PROCESS_DOCDECL is false then return what is inside of DOCDECL for example it returns:

" titlepage SYSTEM "http://www.foo.bar/dtds/typo.dtd"
            [<!ENTITY % active.links "INCLUDE">]"

for input document that contained:

<!DOCTYPE titlepage SYSTEM "http://www.foo.bar/dtds/typo.dtd"
            [<!ENTITY % active.links "INCLUDE">]>

otherwise if FEATURE_XML_ROUNDTRIP is false and PROCESS_DOCDECL is true then what is returned is undefined (it may be even null) </dd> </dl>

<strong>NOTE:</strong> there is no guarantee that there will only one TEXT or IGNORABLE_WHITESPACE event from nextToken() as parser may chose to deliver element content in multiple tokens (dividing element content into chunks)

<strong>NOTE:</strong> whether returned text of token is end-of-line normalized is depending on FEATURE_XML_ROUNDTRIP.

<strong>NOTE:</strong> XMLDecl (&lt;?xml ...?&gt;) is not reported but its content is available through optional properties (see class description above).

Java documentation for org.xmlpull.v1.XmlPullParser.nextToken().

Portions of this page are modifications based on work created and shared by the Android Open Source Project and used according to terms described in the Creative Commons 2.5 Attribution License.