characters Method

MSXML 5.0 SDK

Microsoft XML Core Services (MSXML) 5.0 for Microsoft Office - SAX2 Reference

characters Method

Receives notification of character data.

[Visual Basic]

The reader calls the characters method and passes it character data. The reader can pass all contiguous character data in a single chunk or split it into several chunks. All characters in a single event, however, must come from the same external entity, so that the Locator object provides useful information. The ContentHandler must not attempt to read from the array outside the specified range. The reader calls the characters method between the startElement and endElement methods. The reader passes strings to the characters method by reference (ByRef), not by value (ByVal). This improves performance and avoids extra string copying.

Implementation Syntax

Sub characters(strChars As String)

Usage Syntax

Dim strChars As String
strChars = "Some character data as content for the reader to handle."
oContentHandler.characters strChars

Parameters

strChars
The character data.

Return Values

If failed, the ContentHandler raises a trappable error.

Example

The following example uses the characters method to insert a carriage return (CR) character for each line feed (LF) character in the character data. The string that results is then appended to the current text of a text box (Text1) on the main application form (Form1).

Private Sub IVBSAXContentHandler_characters(strChars As String)
    strChars = Replace(strChars, vbLf, vbCrLf)
    Form1.Text1.Text = Form1.Text1.Text & strChars
End Sub
Note   This code technique can be used to preserve any CRs in your XML document input when your Microsoft® Visual Basic® application displays or prints it as output.. Otherwise, carriage return/line feed (CR/LF) occurrences are converted to LF-only data by the reader.
[C/C++]

The reader calls the characters method to report each chunk of character data. The reader can return all contiguous character data in a single chunk or split it into several chunks. All characters in a single event, however, must come from the same external entity so that the Locator object can provide useful information. The application must not attempt to read from the array outside the specified range.

Syntax

HRESULT characters(
   [in] const wchar_t * pwchChars,
   [in] int cchChars);

Parameters

pwchChars [in]
The character data.
cchChars [in]
The length of the character string.

Return Values

S_OK
The value returned if the character data is returned successfully.
E_FAIL
The value returned if an internal error occurs.

Remarks

To view reference information for Visual Basic or C/C++ only, click the Language Filter button Language Filter in the upper-left corner of the page.

See Also

Applies to: ISAXContentHandler/IVBSAXContentHandler Interface