ISpObjectToken

The ISpObjectToken interface handles object token entries.

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 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 is the name that should be displayed wherever the name of the token is displayed. The implementer of the token may also choose to provide a set of language-dependent names in several languages.
• The CLSID used to instantiate the object from the token.
• A set of Attributes, which are the set of queriable values in a token. SAPI provides a mechanism to query for tokens whose attributes match certain values.

A token may also contain the following:

• If a token has user interfaces (UIs), such as the properties of a Recognizer or a wizard to customize a Voice to display, the token will also contain the CLSID for the COM object used to instantiate each type of UI.
• The set of Files from which SAPI returns the paths to all the associated files for the token. 

Attributes are null-terminated strings forming a series of key-pair entries. This is usually in the form of definition relationships. For example, a token may be defined as:

"vendor=microsoft;language=409;someflag"

In this instance:

• "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 has no additional information. Sometimes the presence or absence of the attribute name itself is indicative.

Implemented By

• SpObjectToken object. This 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 to provide a custom object token implementation. For instance, this could be used to avoid storing object token data in the registry, or to provide the ability for object tokens to be downloaded from a server. In this case IEnumSpObjectTokens would also need to be implemented so that the new object tokens to be enumerated.

How Created

• Applications will normally create object tokens from an object token enumerator or helper function, rather than by directly creating them.
• Various API methods also return an object token referring to a specific type of resource, e.g., ISpRecognizer::GetRecognizer returns the object token associated with the current recognition engine; ISpRecognizer::GetRecoProfile returns the object token referring to the current recognition profile; and ISpVoice::GetVoice returns the object token referring to the current TTS engine.

ISpObjectToken inherits from ISpDataKey.

Object tokens are discussed in more detail in the Object Tokens and Registry Settings White Paper.

Methods in Vtable Order