ISpLexicon::GetGenerationChange
ISpLexicon::GetGenerationChange passes back a list of words which have changed between the current and a specified generation.
HRESULT GetGenerationChange(
DWORD dwFlags,
DWORD *pdwGeneration,
SPWORDLIST *pWordList
);
Parameters
- dwFlags
- [in] The lexicon category of type SPLEXICONTYPE. Currently it must be zero for the SpLexicon (container lexicon) object, and must be the correct flag for the type of SpUnCompressedLexicon object (either eLEXTYPE_USER or eLEXTYPE_APP).
- pdwGeneration
- [in, out] The generation ID of client when passed in. The current generation ID is passed back on successful completion of the call.
- pWordList
- [in, out] The buffer containing the word list and its related information. This must be initialized (memset to zero) before first use. If pWordList is successfully returned, CoTaskMemFree must be used to free the list (pWordList->pvBuffer) when no longer needed.
Return values
| Value | Description |
|---|---|
| S_OK | Function completed successfully. |
| SP_LEX_NOTHING_TO_SYNC | Nothing changed since the passed in generation ID. |
| SPERR_LEX_VERY_OUT_OF_SYNC | There are too many changes since the passed in generation ID, 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
An application can determine what has been done to a lexicon over a given period of time using ISpLexicon::GetGenerationChange and ISpLexicon::GetGeneration. That is, it can back out of changes it has made due to a user cancel. To do this, before it starts modifying the lexicon, the application would call ISpLexicon::GetGeneration and store the generation ID. Later, when the application wants to see what words in the lexicon it has modified, it would call ISpLexicon::GetGenerationChanges with the stored ID. This can only be done for small changes because, past a certain point, SPERR_LEX_VERY_OUT_OF_SYNC will be returned and the change history will not be available from the original generation.
Example
The following is an example of GetGenerationChange.
// Declare local identifiers:
HRESULT hr = S_OK;
CComPtr<ISpLexicon> cpSpLexicon;
DWORD dwGeneration;
SPWORDLIST spwordlist;
SPWORD *pword;
SPWORDPRONUNCIATION *pwordpron;
for (;;)
{
hr = cpSpLexicon->GetGenerationChange(eLEXTYPE_USER, &dwGeneration;, &spwordlist;);
// If, for example, a new application lexicon was
// added, we'll have to rebuild from scratch.
if (hr == SPERR_LEX_VERY_OUT_OF_SYNC)
{
// Call ISpLexicon::GetWords to get
// a list of all words in the lexicon.
}
else if (FAILED(hr))
{
// Pass hr to some error-handling routine you have written.
}
else
{
// Loop thru the changed words, and their new pronunciations--
for (pword = spwordlist.pFirstWord;
pword != NULL;
pword = pword->pNextWord)
{
for (pwordpron = pword->pFirstWordPronunciation;
pwordpron != NULL;
pwordpron = pwordpron->pNextWordPronunciation)
{
if(pword->eWordType == eWORDTYPE_ADDED)
{
// Call routine named something like
// AddPronunciationToEngineDataStructures,
// passing it these 3 parameters:
// 1. pword->pszWord
// 2. pwordpron->ePartOfSpeech
// 3. pwordpron->szPronunciation[]
}
else // pword->eWordType == eWORDTYPE_DELETED
{
// Call routine named something like
// RemovePronunciationFromEngineDataStructures,
// passing it these 3 parameters:
// 1. pword->pszWord
// 2. pwordpron->ePartOfSpeech
// 3. pwordpron->szPronunciation[]
}
}
}
}
}