ISpObjectToken
This interface handles object token entries. ISpObjectToken inherits from ISpDataKey.
An object token is an object representing a resource that is available on a computer, such as a voice, recognizer, or an audio input device. A token provides an with application a simple way to inspect the various attributes of a resource without having to instantiate it. The Vendor of a Recognizer, and Gender of a Voice are examples of attributes of resources. An application can enumerate the various tokens that exist on the computer by using the SpEnumTokens helper function, or by using the ISpObjectTokenCategory::EnumTokens method to enumerate the tokens of a particular category. Applications can find the best token that matches certain attributes by using the SpFindBestToken function.
Conceptually, a token contains the following information:
- An identifier that uniquely identifies the object token.
- The language-independent name, which is the name that should be displayed wherever the name of the token is displayed. The implementer of the token can also choose to provide a set of language-dependent names in several languages.
- The class ID (CLSID) used to instantiate the object from the token.
- A set of attributes, which are token values that can be queried. SAPI provides a mechanism to query for tokens whose attributes match certain values.
A token can also contain the following:
- CLSID for the COM object used to instantiate each type of UI, if the token has UIs, such as one to display the properties of a Recognizer, or a wizard to customize a voice to display.
- The set of files from which SAPI returns the paths to all the associated files for the token.
Attributes are null-terminated strings forming key-value pairs. A pair is usually in the form of a definition relationship. For example, a token can be defined as:
"vendor=microsoft;language=409;someflag"
In this example:
- "vendor=microsoft" means a string exists under TokenID\attributes with name vendor and value "microsoft";
- "language=409" means a string exists under TokenID\attributes with name language and value "409" (representing US English);
- "someflag" means a string exists under TokenID\attributes with name someflag, but having no additional information. Sometimes the presence or absence of the attribute name itself is indicative.
When to Implement
SpObjectToken is the standard class used for all existing SAPI object tokens. The data for each object token is stored in the registry.
Applications or engines can implement this interface directly if they want to provide a custom object token implementation. For example, such an implementation may be used if an application wishes to avoid storing object token data in the registry, or if it wants to allow object tokens to be downloaded from a server. In this case, IEnumSpObjectTokens will also need to be implemented to allow the new object tokens to be enumerated.
An application will typically create object tokens from an object token enumerator or helper function, instead of by direct creation. Various API methods also retrieve an object token referring to a specific type of resource, for example:
- ISpRecognizer::GetRecognizer returns the object token associated with the current recognition engine.
- ISpRecognizer::GetRecoProfile returns the object token referring to the current recognition profile.
- ISpVoice::GetVoice returns the object token referring to the current TTS engine.
Methods
The following table shows the methods for the ISpObjectToken interface.
| Methods | Description |
|---|---|
| CreateInstance | Creates an instance of an object. |
| DisplayUI | Displays the UI associated with the object. |
| GetCategory | Gets the category for a specified token if one is available. |
| GetId | Gets the object identifier for an object token. |
| GetStorageFileName | Gets the object token file name. |
| IsUISupported | Determines if the UI associated with the object is supported. |
| MatchesAttributes | Determines if an object token supports a specified attribute. |
| Remove | Removes an object token. |
| RemoveStorageFileName | Removes the object token file name. |
| SetId | Sets the category identifier for object token. |
Requirements
OS Versions: Windows CE .NET 4.1 and later.
Header: sapi.h, sapi.idl.
Link Library: Sapilib.lib.
See Also
Last updated on Saturday, April 10, 2004
© 1992-2003 Microsoft Corporation. All rights reserved.