ISpeechDataKey EnumKeys Method (SAPI 5.3)

Microsoft Speech API 5.3

Interface: ISpeechDataKey

EnumKeys Method

The EnumKeys method returns the name of one subkey of the data key, specified by its index.

The starting index is zero. A count of subkeys or an enumeration of subkey names can be performed by calling this method repetitively, starting with an index of zero, and increasing the index until all items are enumerated. This is indicated by an SPERR_NO_MORE_ITEMS error.

  
    ISpeechDataKey.EnumKeys(
     Index As Long
) As String

Parameters

• Index
  The index of the subkey to be returned.

Return Value

A String variable containing the name of the subkey.

Example

The following Visual Basic form code demonstrates several ISpeechDataKey methods, including OpenKey, EnumKeys, SetStringValue, and DeleteValue. It also demonstrates the creation and deletion of custom object token attributes, and the selection of tokens by these custom attributes. A custom attribute called "SenseOfHumor" is created for each voice token. This attribute name is intentionally unrelated to any actual characteristics of a voice or a voice token; it is intended to be obviously meaningless and easily distinguishable from installed voice attributes. To run this code, create a form with the following controls:

• A list box called List1
• Two command buttons called Command1 and Command2

Copy the code below and paste it into the Declarations section of the form.

The Form_Load procedure creates an SpObjectTokenCategory object and sets it to the category of voices in the speech configuration database.

The Command1 procedure sets one data key object to the category of voices, and another data key object to the Tokens subfolder. It then enumerates the voice tokens contained in Tokens and writes a value called SenseOfHumor in the Attributes subfolder of each voice token. The values written are "0" and "1" alternately, so that every second voice has a non-zero SenseOfHumor attribute value. Finally, the procedure calls a subroutine which uses the SenseOfHumor attribute in a GetVoices call.

The Command2 procedure enumerates the voice token "Attributes" subfolders and removes all "SenseOfHumor" attributes. It then calls the subroutine which uses "SenseOfHumor" attributes in a GetVoices call after these attributes have been removed.

  
Option Explicit

Dim C As SpeechLib.SpObjectTokenCategory    'one object token category
Dim T As SpeechLib.SpObjectToken            'one object token
Dim V As SpeechLib.SpVoice                  'Voice used for enumeration

Dim Kc As SpeechLib.ISpeechDataKey          'DataKey of the category
Dim Kf As SpeechLib.ISpeechDataKey          'DataKey of its tokens folder
Dim Kt As SpeechLib.ISpeechDataKey          'DataKey of one token

Const SPERR_NO_MORE_ITEMS = &H80045039;

Private Sub Command1_Click()
    Dim nn As Long
    Dim strKey As String, strValue As String

    Set Kc = C.GetDataKey                   'Get DataKey of voice category
    Set Kf = Kc.OpenKey("Tokens")           'Get DataKey of its "Tokens" subfolder
    nn = 0

    On Error Resume Next
    Do
        strKey = Kf.EnumKeys(nn)
        If Err.Number = SPERR_NO_MORE_ITEMS Then Exit Do

        'Write an attribute for each voice:
        'Attribute "SenseOfHumor" will be true for alternating voices
        Set Kt = Kf.OpenKey(strKey)         'Kt = the DataKey of the voice token
        Set Kt = Kt.OpenKey("Attributes")   'Kt = the DataKey of voice\Attributes

        If nn Mod 2 Then strValue = "1" Else strValue = "0"
        Call Kt.SetStringValue("SenseOfHumor", strValue)
        nn = nn + 1
    Loop
    Err.Clear
    On Error GoTo 0

    Call TestAttributes     'Select voices using this attribute

End Sub

Private Sub Command2_Click()
    Dim nn As Long
    Dim strKey As String

    Set Kc = C.GetDataKey                   'Get DataKey of voice category
    Set Kf = Kc.OpenKey("Tokens")           'Get DataKey of its "Tokens" subfolder

    On Error Resume Next
    Do
        strKey = Kf.EnumKeys(nn)
        If Err.Number = SPERR_NO_MORE_ITEMS Then Exit Do
        Set Kt = Kf.OpenKey(strKey)         'Kt = the DataKey of the voice token
        Set Kt = Kt.OpenKey("Attributes")   'Kt = the DataKey of voice\Attributes
        Call Kt.DeleteValue("SenseOfHumor")
        nn = nn + 1

    Loop
    Err.Clear
    On Error GoTo 0

    Call TestAttributes     'Select voices using this attribute

End Sub

Private Sub Form_Load()
    On Error GoTo EH

    'Create new token object, and set its ID to voice tokens

    Set C = New SpObjectTokenCategory
    C.SetId SpeechCategoryVoices

    Set V = New SpVoice

EH:
    If Err.Number Then ShowErrMsg
End Sub

Private Sub TestAttributes()
    On Error GoTo EH

    List1.Clear
    List1.AddItem "Voices with a sense of humor"

    For Each T In V.GetVoices("senseofhumor=1")
        List1.AddItem "   " & T.GetDescription
    Next

    List1.AddItem ""
    List1.AddItem "Voices with no sense of humor"

    'When the "SenseOfHumor" attribute is not present,
    'the selection "SenseOfHumor!=1" shows all voices,
    'bau the selection "SenseOfHumor=0" would show no voices.

    For Each T In V.GetVoices("senseofhumor!=1")
        List1.AddItem "   " & T.GetDescription
    Next

EH:
    If Err.Number Then ShowErrMsg
End Sub

Private Sub ShowErrMsg()

    ' Declare identifiers:
    Const NL = vbNewLine
    Dim T As String

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

End Sub