ISpLexicon::GetWords
ISpLexicon::GetWords gets a list of all words in the lexicon.
HRESULT GetWords(
DWORD dwFlags,
DWORD *pdwGeneration,
DWORD *pdwCookie,
SPWORDLIST *pWordList
);
Parameters
- dwFlags
- [in] Bitwise flags of type SPLEXICONTYPE from which words are to be retrieved.
- pdwGeneration
- [out] The current generation ID of the custom lexicon.
- pdwCookie
- [in, out] Cookie passed back by this call. It should subsequently be passed back in to get more data. If the call returns S_FALSE, data is remaining and GetWords should be called again. The initial value of the cookie passed in must be zero or pdwCookie will be a NULL pointer. NULL pdwCookie indicates the method should return all words contained in the lexicon at once. If it cannot, SP_LEX_REQUIRES_COOKIE is returned instead.
- pWordList
- [in, out] The buffer containing the word list and its related information. 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. |
| S_FALSE | Additional words are left in the lexicon(s) to process. |
| SPERR_LEX_REQUIRES_COOKIE | A complete list of words cannot be returned at once from the container lexicon. pdwCookie must not be NULL. |
| E_POINTER | At least one of pdwGeneration, pdwCookie, pWordList is not valid. Alternatively, the block of memory is too small or is not writable. |
| E_INVALIDARG | At least one of the parameters is not valid. |
| E_OUTOFMEMORY | Exceeded available memory. |
| SPERR_UNINITIALIZED | Interface not initialized. |
| FAILED(hr) | Appropriate error message. |
Remarks
To retrieve all of the words in a lexicon, this method typically must be called repeatedly with the cookie (initially set to zero before the first call) until S_OK is returned. S_FALSE is returned to indicate that additional words remain in the lexicon. Optionally, the cookie pointer passed in may be NULL, which indicates that the application is asking to receive all of the words at one time. The lexicon is not required to support this and may return the error SP_LEX_REQUIRES_COOKIE. The SpLexicon object (container lexicon) requires a cookie currently.
Between calls to GetWords it is possible for the GenerationId out parameter to change as the lexicon is updated. The caller of this method should retain the value of GenerationId that is passed out from the first call to GetWords (when the cookie is initially 0). When pdwCookie is nonnull and the cookie value is nonzero, the application should completely ignore the value of GenerationId passed out when GetWords returns.
Example
The following is an example of using GetWords.
// Declare local identifiers:
HRESULT hr = S_OK;
CComPtr<ISpLexicon> cpLexicon;
SPWORDLIST spwordlist;
SPWORDPRONUNCIATIONLIST *pwordpronlist;
SPWORDPRONUNCIATION *pwordpron;
SPWORD *pword;
DWORD dwCookie = 0;
DWORD dwGeneration;
memset(pwordpronlist, 0, sizeof(pwordpronlist));
while (SUCCEEDED(hr = cpLexicon->GetWords(eLEXTYPE_USER | eLEXTYPE_APP, &dwGeneration;, &dwCookie;, &spwordlist;)))
{
for (pword = spwordlist.pFirstWord;
pword != NULL;
pword = pword->pNextWord)
{
for (pwordpron = pword->pFirstWordPronunciation;
pwordpron != NULL;
pwordpron = pwordpron->pNextWordPronunciation)
{
// Do something with the SPWORDPRONUNCIATION structure's
// members (for example, ePartOfSpeech and szPronunciation).
}
}
if (SUCCEEDED (hr))
{
// Nothing more to retrieve.
}
}
// Free all the buffers.
CoTaskMemFree(spwordlist.pvBuffer);