Interface: ISpeechRecognizer

GetProfiles Method

The GetProfiles method returns a selection of the available user speech profiles.

Profiles are stored in the speech configuration database as a series of tokens, with each token representing one profile. GetProfiles retrieves all available profile tokens. The returned list is an ISpeechObjectTokens object. Additional or more detailed information about the tokens is available in methods associated with ISpeechObjectTokens.

The token search may be further refined using the RequiredAttributes and OptionalAttributes search attributes. Only tokens matching the specified RequiredAttributes search attributes are returned. Of those tokens matching the RequiredAttributes key, OptionalAttributes lists devices in the order matching OptionalAttributes. If no search attributes are offered, all tokens are returned. If no audio devices match the criteria, GetAudioInputs returns an empty selection, that is, an ISpeechObjectTokens collection with an ISpeechObjectTokens::Count property of zero.

See Object Tokens and Registry Settings White Paper for a list of SAPI 5-defined attributes.

SpeechRecognizer.GetProfiles(
     [RequiredAttributes As String = ""],
     [OptionalAttributes As String = ""]
) As ISpeechObjectTokens

Parameters

RequiredAttributes

[Optional] Specifies the RequiredAttributes. To be returned by GetProfiles, profile tokens must contain all of the specific required attributes. If no profiles match the selection, the selection returned will not contain any elements. By default, no attributes are required and so returns all the tokens discovered.

OptionalAttributes

[Optional] Specifies the OptionalAttributes. Returned tokens containing the RequiredAttributes are sorted by OptionalAttributes. If OptionalAttributes is specified, the tokens are listed with the OptionalAttributes first. By default, no attribute is specified and the list returned from the speech configuration database is in the order that attributes were discovered.

Return Value

An ISpeechObjectTokens object.

Remarks

The format of selection criteria may either be Value or "Attribute = Value". Values may be excluded by "Attribute != Value".

Example

This code sample demonstrates the GetProfiles and Profile method. After creating an instance for a recognizer, GetProfiles polls the computer for available profile tokens. The results are displayed. The first one listed is the current profile. Clicking the button will change the current profile to the first different profile found.

To run this code, create a form with the following control:

• A command button called Command1

Paste this code into the Declarations section of the form.

It is possible for your computer to have only one profile. To fully demonstrate this method, additional profiles should be added. Add new profiles through the Speech properties of Control Panel.

Option Explicit

Public SharedRecognizer As SpSharedRecognizer
Public theRecognizers As ISpeechObjectTokens

Private Sub Command1_Click()
    On Error GoTo EH

    Dim currentProfile As SpObjectToken
    Dim i As Integer
    Dim T As String
    Dim TokenObject As ISpeechObjectToken
    Set currentProfile = SharedRecognizer.Profile

    For i = 0 To theRecognizers.Count - 1
        Set TokenObject = theRecognizers.Item(i)

        If tokenObject.Id <> currentProfile.Id Then
            Set SharedRecognizer.Profile = TokenObject
            T = "New Profile installed: "
            T = T & SharedRecognizer.Profile.GetDescription
            Exit For
        Else
            T = "No new profile has been installed."
        End If
    Next i

    MsgBox T, vbInformation

EH:
    If Err.Number Then ShowErrMsg
End Sub

Private Sub Form_Load()
    On Error GoTo EH

    Const NL = vbNewLine
    Dim i, idPosition As Long
    Dim T As String
    Dim TokenObject As SpObjectToken

    Set SharedRecognizer = CreateObject("SAPI.SpSharedRecognizer")
    Set theRecognizers = SharedRecognizer.GetProfiles

    For i = 0 To theRecognizers.Count - 1
        Set TokenObject = theRecognizers.Item(i)
        T = T & TokenObject.GetDescription & "--" & NL & NL
        idPosition = InStrRev(TokenObject.Id, "\")
        T = T & Mid(TokenObject.Id, idPosition + 1) & NL
    Next i

    MsgBox T, vbInformation

EH:
    If Err.Number Then ShowErrMsg
End Sub

Private Sub ShowErrMsg()

    ' Declare identifiers:
    Dim T As String

    T = "Desc: " & Err.Description & vbNewLine
    T = T & "Err #: " & Err.Number
    MsgBox T, vbExclamation, "Run-Time Error"
    End

End Sub