ISpPhrase::GetText

ISpPhrase::GetText retrieves elements from a text phrase.

HRESULT GetText(
   ULONG     ulStart,
   ULONG     ulCount,
   BOOL      fUseTextReplacements,
   WCHAR   **ppszCoMemText,
   BYTE     *pbDisplayAttributes
);

Parameters

ulStart: [in] Specifies the first element in the text phrase to retrieve.
ulCount: [in] Specifies the number of elements to retrieve from the text phrase.
fUseTextReplacements: [in] Boolean value that indicates if replacement text should be used. An example of a text replacement is saying "write new check for twenty dollars" and retrieving the replaced text as "write new check for $20". For more information on replacements, see the SR Engine White Paper.
ppszCoMemText: [out] Address of a pointer to the data structure that contains the display text information. It is the caller's responsibility to call ::CoTaskMemFree to free the memory.
pbDisplayAttributes: [out] Address of the SPDISPLAYATTRIBUTES enumeration that contains the text display attribute information. Text display attribute information can be used by the application to display the text to the user in a reasonable manner. For example, speaking "hello comma world period" includes a trailing period, so the recognition might include SPAF_TWO_TRAILING_SPACES to inform the application without requiring extra text processing logic for the application.

Return values

Value	Description
S_OK	Function completed successfully.
S_FALSE	A phrase that does not contain text or ppszCoMemText is NULL.
E_INVALIDARG	One or more parameters are invalid.
E_POINTER	Invalid pointer.
E_OUTOFMEMORY	Exceeded available memory.

Remarks

The text is the display text of the elements for the phrase and constructs a text string created by CoTaskMemAlloc by applying the pbDisplayAttributes of each SPPHRASEELEMENT.

Example

The following code snippet illustrates the use ISpPhrase::GetText to retrieve parts of the recognized phrase.

    HRESULT hr = S_OK;

    // ... obtain a recognition result object from the recognizer...

    // get the recognized phrase object
    hr = cpRecoResult->GetPhrase(&pPhrase);
    // Check hr

    // get the phrase's entire text string, including replacements
    hr = pPhrase->GetText(SP_GETWHOLEPHRASE, SP_GETWHOLEPHRASE, TRUE, &pwszText, NULL);
    // Check hr

    // get the phrase's first 2 words, excluding replacements
    hr = pPhrase->GetText(pPhrase->Rule.ulFirstElement, 2, FALSE, &pwszText, NULL);