characters Method

  • Article

 

Receives notification of character data.

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.

Visual Basic Implementation Syntax

Sub characters(strChars As String)

Visual Basic 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.

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.

C/C++ 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.

Versioning

Implemented in: MSXML 3.0 and later

Applies to

ISAXContentHandler Interface