ITextStoreACP::GetText method (textstor.h)

The ITextStoreACP::GetText method returns information about text at a specified character position. This method returns the visible and hidden text and indicates if embedded data is attached to the text.

Syntax

HRESULT GetText(
  [in]  LONG       acpStart,
  [in]  LONG       acpEnd,
  [out] WCHAR      *pchPlain,
  [in]  ULONG      cchPlainReq,
  [out] ULONG      *pcchPlainRet,
  [out] TS_RUNINFO *prgRunInfo,
  [in]  ULONG      cRunInfoReq,
  [out] ULONG      *pcRunInfoRet,
  [out] LONG       *pacpNext
);

Parameters

[in] acpStart

Specifies the starting character position.

[in] acpEnd

Specifies the ending character position. If this parameter is -1, then return all text in the text store.

[out] pchPlain

Specifies the buffer to receive the plain text data. If this parameter is NULL, then the cchPlainReq parameter must be 0.

[in] cchPlainReq

Specifies the number of plain text characters passed to the method.

[out] pcchPlainRet

Receives the number of characters copied into the plain text buffer. This parameter cannot be NULL. Use a parameter if values are not required.

[out] prgRunInfo

Receives an array of TS_RUNINFO structures. May be NULL only if cRunInfoReq = 0.

[in] cRunInfoReq

Specifies the size, in characters, of the text run buffer.

[out] pcRunInfoRet

Receives the number of TS_RUNINFO structures written to the text run buffer. This parameter cannot be NULL.

[out] pacpNext

Receives the character position of the next unread character. Cannot be NULL.

Return value

This method can return one of these values.

Value Description
S_OK
The method was successful.
TF_E_INVALIDPOS
The acpStart or acpEnd parameters are outside of the document text.
TF_E_NOLOCK
The caller does not have a read-only lock on the document.

Remarks

Callers that use this method must have a read-only lock on the document by calling the ITextStoreACP::RequestLock method. Without a read-only lock, the method fails and returns TF_E_NOLOCK.

Applications can also truncate the method return values for internal reasons. Callers should carefully examine the return characters and text run counts to get the required return values. If the return values are incomplete, repeatedly call the method until the return values are complete.

The caller can request plain text only by setting the cRunInfoReq parameter to 0 and the prgRunInfo parameter to NULL. The caller can request only text run data by setting the cchPlainReq parameter to 0 and the pchPlain parameter to NULL. However, the caller must still supply valid non-null values for pcchPlainRet, even if this parameter is not used.

If acpEnd is -1, then it should be handled as if set at the end of the stream. Otherwise, it will be greater than or equal to zero.

On exit, pacpNext should be set to the character position of the next character in the stream not referenced by the return values. A caller would use this to quickly scan text with multiple ITextStoreACP::GetText calls.

Requirements

Requirement Value
Minimum supported client Windows 2000 Professional [desktop apps only]
Minimum supported server Windows 2000 Server [desktop apps only]
Target Platform Windows
Header textstor.h
DLL Msctf.dll
Redistributable TSF 1.0 on Windows 2000 Professional

See also

ITextStoreACP

ITextStoreACP::RequestLock

Manager Return Values

TS_RUNINFO