ISpRecoResult::GetAlternates (SAPI 5.3)

Speech API 5.3
Microsoft Speech API 5.3


ISpRecoResult::GetAlternates retrieves an array of pointers to ISpPhraseAlt objects containing alternate phrases.

HRESULT GetAlternates(
   ULONG           ulStartElement,
   ULONG           cElements,
   ULONG           ulRequestCount,
   ISpPhraseAlt  **ppPhrases,
   ULONG          *pcPhrasesReturned


[in] The starting element to consider for the alternates. This is a zero-based value.
[in] The number of elements to consider. All elements can be requested using the enumeration value SPPR_ALL_ELEMENTS of type SPPHRASERNG.
[in] The number of requested alternate phrase elements.
[out] Address of an array of ISpPhraseAlt interface pointers that contain the alternate phrases. The elements between the start of the ulStartElement element and the end of the ulStartElement and cElements element combined is the portion that will change. The rest of the elements will be included in each alternate phrase.
[out] Pointer to a ULONG that receives the actual number of alternate phrases retrieved.

Return values

S_OKFunction completed successfully.
E_POINTERpcPhrasesReturned is an invalid pointer. However, ppPhrases does not contain ulRequestCount allocations.
E_OUTOFMEMORYExceeded available memory.
E_INVALIDARGulStartElement is not less than the number of elements in the owning interface. However, the number of expected elements exceeds the number of available elements in the owning interface.
S_FALSENo analyzer is present or there is no driver data.
FAILED(hr)Appropriate error message.


The following code snippet illustrates the use ISpRecoResult::GetAlternates to retrieve and commit an alternate phrase.

// Declare local identifiers:
HRESULT                    hr = S_OK;
const USHORT               MY_MAX_ALTERNATES = 10;
CComPtr<ISpRecoResult>     cpRecoResult;
CComPtr<ISpPhrase>         cpPhrase;
CComPtr<ISpPhraseAlt>      pcpPhraseAlt[MY_MAX_ALTERNATES];
SPPHRASE                   *pPhrase;
WCHAR                      *pwszText;
WCHAR                      *pwszAlternate;
BOOL                       fMoreAppropriate;
LONG                       ulCount;

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

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

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

if (SUCCEEDED(hr))
   // Check the phrase's text... Assume that
   // the phrase isn't a correct recognition.

   // Get the top MY_MAX_ALTERNATES alternates
   // to the entire recognized phrase.
   hr = cpRecoResult->GetAlternates(pPhrase->Rule.ulFirstElement,

if (SUCCEEDED(hr))
   // Check each alternate in order of highest likelihood.
   for (int i = 0; i < ulCount; i++)
      hr = pcpPhraseAlt[i]->GetText(SP_GETWHOLEPHRASE, SP_GETWHOLEPHRASE, TRUE, &pwszAlternate;, NULL);

      if (SUCCEEDED(hr))
         // ... Check if this alternate is more appropriate ...

         // If it is more appropriate, then commit the alternate--
         if (fMoreAppropriate)
            hr = pcpPhraseAlt[i]->Commit();

         if (SUCCEEDED(hr))
            // Release system resources:
            if (pwszAlternate) ::CoTaskMemFree(pwszAlternate);
            if (pwszText) ::CoTaskMemFree(pwszText);

// Free the initial phrase object.
if (pPhrase) ::CoTaskMemFree(pPhrase);