ISpPhrase::GetText (SAPI 5.4)

Speech API 5.4
Microsoft Speech API 5.4


ISpPhrase::GetText retrieves elements from a text phrase.

   ULONG                                          ulStart,
   ULONG                                          ulCount,
   BOOL                                           fUseTextReplacements,
   [annotation ("__deref_out")] LPWSTR          **ppszCoMemText,
   [annotation ("__out_ecount_opt(1)")] BYTE     *pbDisplayAttributes


[in] Specifies the first element in the text phrase to retrieve.
[in] Specifies the number of elements to retrieve from the text phrase.
[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.
[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.
[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

S_OKFunction completed successfully.
S_FALSEA phrase that does not contain text or ppszCoMemText is NULL.
E_INVALIDARGOne or more parameters are invalid.
E_POINTERInvalid pointer.
E_OUTOFMEMORYExceeded available memory.


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.


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

// Declare local identifiers:
HRESULT                   hr = S_OK;
CComPtr<ISpRecoResult>    cpRecoResult;
SPPHRASE                  *pPhrase;
WCHAR                     *pwszText;

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

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

if (SUCCEEDED (hr))
   // Get the phrase's entire text string, including replacements.
   hr = cpRecoResult->GetText(SP_GETWHOLEPHRASE, SP_GETWHOLEPHRASE, TRUE, &pwszText;, NULL);

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

if (SUCCEEDED (hr))
   // Do some more stuff.