ISpLexicon (Windows CE 5.0)
This interface is used to access lexicons, which contain information about words that can be recognized or spoken. The interface provides a uniform way for applications and engines to access the user lexicon, application lexicon, and private engine lexicons. It is used differently by application and engine developers.
SpLexicon is the SAPI standard lexicon class that implements the ISpLexicon interface. When an object is created, it contains the user lexicon and all application lexicons registered in the system.
When to Implement
The following list shows what classes implement this interface:
- SpLexicon (implements ISpContainerLexicon, which is derived from ISpLexicon)
- SpCompressedLexicon
- SpUncompressedLexicon
Methods
| Method | Description |
|---|---|
| AddPronunciation | Adds pronunciation and parts of speech of a word to the user lexicon. |
| GetGeneration | Gets the generation identifier for a word. |
| GetGenerationChange | Gets a list of words which have changed between the current and a specified generation. |
| GetWords | Gets a list of all words in the lexicon. |
| GetPronunciations | Gets pronunciations and parts of speech for a word. |
| RemovePronunciation | Removes a word from the user lexicon. |
Remarks
ISpLexicon information for application developers
Engines can add their private lexicons through the ISpContainerLexicon interface. However, if an application uses ISpContainerLexicon to add a lexicon to an ISpLexicon object, the lexicon will not be used by the engine.
Your application can use ISpLexicon::GetPronunciations to get pronunciations from both user and application lexicons:
hr = cpLexicon->GetPronunciation(... eLEXTYPE_USER ...);
hr = cpLexicon->GetPronunciation(... eLEXTYPE_APP ...);
hr = cpLexicon->GetPronunciation(... eLEXTYPE_USER | eLEXTYPE_APP ...);
Your application can also add an application lexicon to the system, and remove it later. When an application lexicon is added to the system, it is shared by all applications. Any SpLexicon object created afterward will automatically load the application lexicon. Application lexicons will override engine private lexicons.
To add an application lexicon, let your COM object implement the ISpLexicon and ISpObjectWithToken interfaces, and register the lexicon as illustrated in the following example:
hr = SpCreateNewTokenEx(SPCAT_APPLEXICONS, pszLangIndependentName,
&CLSID_YourLexicon, pszLangIndependentName, langid, pszLangDependentName,
&cpToken, &cpDataKeyAttribs);
// hr = cpDataKeyAttribs->SetStringValue(name1, value1); // optional. Can be
used to find your lexicon later
// hr = cpDataKeyAttribs->SetStringValue(name2, value2); // optional
// ...
Your application can also use the SAPI-provided SpUncompressedLexicon class (CLSID_SpUnCompressedLexicon) to implement your application lexicon as follows. Note that the class SpCompressedLexicon (CLSID_SpCompressedLexicon is intended for engine vendors.
hr = SpCreateNewTokenEx(SPCAT_APPLEXICONS, pszLangIndependentName,
&CLSID_SpUnCompressedLexicon, pszLangIndependentName, langid,
pszLangDependentName, &cpToken, &cpDataKeyAttribs);
// hr = cpDataKeyAttribs->SetStringValue(name1, value1); // optional. Can be
used to find your lexicon later
// hr = cpDataKeyAttribs->SetStringValue(name2, value2); // optional
// ...
hr = SpCreateObjectFromToken(cpToken, &cpAppLexicon);
cpAppLexicon->AddPronunciation(...);
cpAppLexicon->AddPronunciation(...);
cpAppLexicon.Release(); // the CLSID_SpUnCompressedLexicon object will be read-only after this point
To remove an application lexicon from the system, your application should:
- Locate the lexicon with the SpFindBestToken function.
- Call ISpObjectToken::Remove (passing NULL) to remove the lexicon from the system.
ISpLexicon information for engine developers
An engine can use the ISpLexicon interface to add or remove words from the user lexicon. However, the engine developer will not typically use ISpLexicon::AddPronunciation and ISpLexicon::RemovePronunciation to add or remove words from user lexicons.
When the engine implements private lexicons through the ISpLexicon interface, SAPI will only call ISpLexicon::GetPronunciations and ISpLexicon::GetWords on the private lexicon. Private lexicons can be modified by implementing the AddPronunciation or RemovePronunciation methods to populate lexicons.
If the engine caches pronunciations from user or application lexicons, it needs to call ISpLexicon::GetGeneration periodically to determine if the pronunciation has been modified by an application. For optimum efficiency, an engine should maintain synchronization with the user and application lexicons. The SAPI 5.0 compliance test can verify an engine's ability to detect changes in the user or application lexicons.
When the call to GetGeneration retrieves a larger generation number than that retrieved by the previous call, the engine should call ISpLexicon::GetGenerationChange or GetWords to update the cache.
The engine can add private lexicons to the ISpContainerLexicon interface. Alternatively the engine can use a customized method for implementing a private lexicon. However, to ensure consistent behavior among all applications, engines should always use the pronunciations from the user and application lexicons.
CComPtr<ISpContainerLexicon> cpLexicon;
// load user lexicon and all application lexicons registered in the system
automatically
hr = cpLexicon.CoCreateInstance(CLSID_SpLexicon);
// create your private lexicons implementing ISpLexicon, (for example, pMyLex1,
pMyLex2)
hr = cpLexicon->AddLexicon(pMyLex1, eLEXTYPE_PRIVATE1);
hr = cpLexicon->AddLexicon(pMyLex2, eLEXTYPE_PRIVATE2);
...
Engines can access lexicons as shown in the following example:
hr = cpLexicon->GetPronunciations(... eLEXTYPE_USER ...);
hr = cpLexicon->GetPronunciations(... eLEXTYPE_APP ...);
hr = cpLexicon->GetPronunciations(... eLEXTYPE_USER | eLEXTYPE_APP | eLEXTYPE_PRIVATE1 | eLEXTYPE_PRIVATE2 ...);
Requirements
OS Versions: Windows CE .NET 4.1 and later.
Header: Sapi.h, Sapi.idl.
Link Library: Sapilib.lib.
See Also
Send Feedback on this topic to the authors