ISpLexicon::GetGenerationChange

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

• Windows Embedded CE 6.0 R3

8/28/2008

This method gets a list of words that have changed between the current generation and a specified generation.

Syntax

HRESULT GetGenerationChange(
  DWORD dwFlags,
  DWORD* pdwGeneration,
  SPWORDLIST* pWordList
);

Parameters

• dwFlags
  [in] Lexicon category. Possible values are defined by the SPLEXICONTYPE enumeration. Currently the value chosen must be zero for the SpLexicon (container lexicon) class. It must be the correct flag for the SpUnCompressedLexicon class, either eLEXTYPE_USER or eLEXTYPE_APP.

• pdwGeneration
  [in, out] Pointer to the generation identifier. On input, the identifier is for the client. On output, the current current generation identifier is provided.

• pWordList
  [in, out] Pointer to an SPWORDLIST structure containing the word list and its related information.

Return Value

The following table shows the possible return values.

Value	Description
S_OK	Function completed successfully.
SP_LEX_NOTHING_TO_SYNC	Nothing changed because the passed in generation identifier.
SPERR_LEX_VERY_OUT_OF_SYNC	There are too many changes because the passed in generation identifier, so that a change history is not available. It could also be returned after installation/uninstallation of an application lexicon. Use ISpLexicon::GetWords if GetGenerationChange returns SPERR_LEX_VERY_OUT_OF_SYNC to regenerate an entire list of words based on the current generation.
E_POINTER	pdwGeneration or pWordList is not a valid write pointer.
E_INVALIDARG	dwFlags is invalid.
SPERR_UNINITIALIZED	Interface has not been initialized.
E_OUTOFMEMORY	Exceeded available memory.
FAILED(hr)	Appropriate error message.

Remarks

This method and ISpLexicon::GetGeneration can be used when an application wants to determine what it has done to the lexicon over a given period of time (for example, to remove changes it has made due to a user cancel). To do this, the application calls ISpLexicon::GetGeneration before it starts modifying the lexicon, and stores that generation identifier. Later, when the application must determine the words in the lexicon it has modified, it calls ISpLexicon::GetGenerationChange with the stored identifier. This can only be done for small changes as SPERR_LEX_VERY_OUT_OF_SYNC will be returned once sufficient changes have been made.

Example

The following is an example of this method.

for (;;)
{
  hr = pISpLexicon->GetGenerationChange(eLEXTYPE_USER,
    &m_dwGeneration,
    &spwordlist);
  // If, for example, a new application lexicon was added, 
  // rebuild from scratch.
  if (hr == SPERR_LEX_VERY_OUT_OF_SYNC)
  {
    Rebuild(); // Call GetWords
  }
  else if (FAILED(hr))
  {
    DealWithOtherErrors();
  }
  else
  {
    // Loop through the changed words, and their new pronunciations
    for (SPWORD *pword = spwordlist.pFirstWord;
      pword != NULL;
      pword = pword->pNextWord)
    {
      for (SPWORDPRON pwordpron = pword->pFirstWordPron;
       pwordpron != NULL;
       pwordpron = pwordpron->pNextWordPron)
      {
        if(pword->eWordType == eWORDTYPE_ADDED)
        {
          AddPronunciationToEngineDataStructures(
            pword->pszWord,
            pwordpron->ePartOfSpeech,
            pwordpron->pszPronIPA);
        }
        else // pword->eWordType == eWORDTYPE_DELETED
        {
          RemovePronunciationFromEngineDataStructures(
            pword->pszWord,
            pwordpron->ePartOfSpeech,
            pwordpron->pszPronIPA);
        } 
      }
    }
  }
}

Requirements

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

See Also

Reference

ISpLexicon
SAPI Interfaces