ISpRecoResult::GetAlternates

Article
03/19/2010

Other versions of this page are also available for the following:

Windows Embedded CE 6.0 R3

Windows Mobile Not Supported Windows Embedded CE Supported

8/28/2008

This method gets an array of pointers to alternate phrases.

Syntax

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

Parameters

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

cElements
[in] Number of elements to consider. All elements can be requested by using the enumeration value SPPR_ALL_ELEMENTS of type SPPHRASERNG.

ulRequestCount
[in] Number of requested alternate phrase elements.

ppPhrases
[out] Address of a pointer to an array of ISpPhraseAlt objects representing 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 the actual number of alternate phrases retrieved.

Return Value

The following table shows the possible return values.

Value	Description
S_OK	Function completed successfully.
E_POINTER	pcPhrasesReturned is an invalid pointer. However, ppPhrases does not contain ulRequestCount allocations.
E_OUTOFMEMORY	Exceeded available memory.
E_INVALIDARG	ulStartElement is not less than the number of elements in owning interface. However, the number of expected elements exceeds the number of available elements in the owning interface.
S_FALSE	No analyzer is present or there is no driver data.
FAILED(hr)	Appropriate error message.

Remarks

Call the method ISpRecoContext::SetMaxAlternates before using ISpRecoResult::GetAlternates in order to get dictation alternates on command and control grammars.

Example

The following code snippet illustrates the use of this method 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 is not 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);

Requirements

Header	sapi.h, sapi.idl
Library	sapilib.lib
Windows Embedded CE	Windows CE .NET 4.1 and later

Share via