XmlReader.ReadValueChunk Method (System.Xml)

ReadValueChunk Method

Switch on low bandwidth view

Collapse All

Language Filter

This page is specific to

Microsoft Visual Studio 2008/.NET Framework 3.5

Other versions are also available for the following:

.NET Framework Class Library

XmlReader..::.ReadValueChunk Method

Reads large streams of text embedded in an XML document.

Namespace: System.Xml
Assembly: System.Xml (in System.Xml.dll)

Syntax

Visual Basic (Declaration)

Public Overridable Function ReadValueChunk ( _
    buffer As Char(), _
    index As Integer, _
    count As Integer _
) As Integer

Visual Basic (Usage)

Dim instance As XmlReader
Dim buffer As Char()
Dim index As Integer
Dim count As Integer
Dim returnValue As Integer

returnValue = instance.ReadValueChunk(buffer, _
    index, count)

public virtual int ReadValueChunk(
    char[] buffer,
    int index,
    int count
)

Visual C++

public:
virtual int ReadValueChunk(
    array<wchar_t>^ buffer, 
    int index, 
    int count
)

JScript

public function ReadValueChunk(
    buffer : char[], 
    index : int, 
    count : int
) : int

Parameters

buffer: Type: array<System..::.Char>[]()[]
The array of characters that serves as the buffer to which the text contents are written. This value cannot be nullNothingnullptra null reference (Nothing in Visual Basic).

index: Type: System..::.Int32
The offset within the buffer where the XmlReader can start to copy the results.

count: Type: System..::.Int32
The maximum number of characters to copy into the buffer. The actual number of characters copied is returned from this method.

Return Value

Type: System..::.Int32
The number of characters read into the buffer. The value zero is returned when there is no more text content.

Exceptions

Exception	Condition
InvalidOperationException	The current node does not have a value (HasValue is false).
ArgumentNullException	The buffer value is nullNothingnullptra null reference (Nothing in Visual Basic).
ArgumentOutOfRangeException	The index into the buffer, or index + count is larger than the allocated buffer size.
NotSupportedException	The XmlReader implementation does not support this method.
XmlException	The XML data is not well-formed.

Remarks

This method enables reading of very large streams of text embedded in an XML document in a streaming fashion, that is, a small number of characters at a time instead of allocating a single string for the whole value. This method can be called on any node that has a value (HasValue is true), however actual streaming of the node value only occurs when called on a text, white space and significant white space nodes. Other node type values are cached, including attributes and CDATA nodes.

This method returns only the content of the Value property and does not move the XmlReader.

This method reads the specified number of characters (count) of the node value into a character buffer (buffer) at a specified offset (index) and returns the number of characters written to the buffer. It returns the 0 when it has reached the end of the value. It cannot be restarted to read through the value again.

In between calls to ReadValueChunk the XmlReader properties do no change except for the Value property. When the Value property is accessed it may either return a partial value (with characters not yet returned by ReadValueChunk) or a full value depending on the implementation. All the XmlReader implementations in the System.Xml namespace return a partial value for the Value property implementation.

Any Read method can be called in between calls to ReadValueChunk. If this occurs, the XmlReader moves to the next XmlNodeType in the stream and any characters not yet returned are skipped.

There may be a case when ReadValueChunk returns less than the requested number of characters. For example, if you had a 200-character long value with a surrogate pair at positions 127 and 128 and you called ReadValueChunk with a 128-character buffer, the method call would return 127 characters instead of the requested 128. The surrogate pair would then be returned in the next ReadValueChunk call. In this case, ReadValueChunk did not return the requested 128 characters because doing so would have resulted in an incomplete surrogate pair at the end of the buffer.

Platforms

Windows 7, Windows Vista, Windows XP SP2, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP Starter Edition, Windows Server 2008 R2, Windows Server 2008, Windows Server 2003, Windows Server 2000 SP4, Windows Millennium Edition, Windows 98, Windows CE, Windows Mobile for Smartphone, Windows Mobile for Pocket PC, Xbox 360, Zune

The .NET Framework and .NET Compact Framework do not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

Version Information

.NET Framework

Supported in: 3.5, 3.0, 2.0

.NET Compact Framework

Supported in: 3.5, 2.0

XNA Framework

Supported in: 3.0, 2.0, 1.0

Reference

XmlReader Class

XmlReader Members

System.Xml Namespace