ISpRecoResult::GetAlternates

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
);

Parameters

ulStartElement

[in] The starting element to consider for the alternates. This is a zero-based value.

cElements

[in] The number of elements to consider. All elements can be requested using the enumeration value SPPR_ALL_ELEMENTS of type SPPHRASERNG.

ulRequestCount

[in] The number of requested alternate phrase elements.

ppPhrases

[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.

pcPhrasesReturned

[out] Pointer to a ULONG that receives the actual number of alternate phrases retrieved.

Return values

Example

The following code snippet illustrates the use ISpRecoResult::GetAlternates to retrieve and commit an alternate 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 text
    hr = pPhrase->GetText(SP_GETWHOLEPHRASE, SP_GETWHOLEPHRASE, TRUE, &pwszText, NULL);
    // Check hr

    // ... check the phrase's text... assume the phrase isn't a correct recognition

    // setup MY_MAX_ALTERNATES phrase alternate objects 
    CComPtr<ISpPhraseAlt>   pcpPhrase[MY_MAX_ALTERNATES];
    ULONG ulCount;

    // get the top MY_MAX_ALTERNATES alternates to the entire recognized phrase
    hr = cpRecoResult->GetAlternates(pPhrase->Rule.ulFirstElement,
                                     pPhrase->Rule.ulCountOfElements, 
                                     MY_MAX_ALTERNATES,
                                     pcpPhraseAlt,
                                     &ulCount);
    // Check 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);
         // Check hr

         // ... check if this alternate is more appropriate ...

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

         // free the alternate text
         if (pwszAlternate) ::CoTaskMemFree(pwszAlternate);
         
    }

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