Microsoft Speech Platform

---

Programming Notes for Visual Basic

Hidden members

Certain methods or properties (collectively called members) are designated as hidden. This indicates that member does not display in a browser such as Visual Basic's IntelliSense (or automatic statement completion) menu or in the Object Browser list. Members may be designated as hidden for several reasons. Most commonly, it represents an advanced feature or capability that is not needed in normal situations. Hidden members should be considered carefully before using them.

To view hidden members

1. On the View menu, click Object Browser.
2. Right-click the Object Browser window, and then click Show Hidden Members. Drag the scroll box to view hidden members that appear in gray text. With Show Hidden Members selected, these will appear in the IntelliSense menu as well.
3. Right-click the Object Browser window, and then select Show Hidden Members again to hide the members.

Determining Microsoft Speech Platform's presence

Microsoft Speech Platform requires no special error handling outside of Visual Basic's standard procedures. That is, Microsoft Speech Platform errors may be trapped and handled using the same techniques presented by Visual Basic.

However, there are two special considerations when working with the Microsoft Speech Platform. First, the computer on which the application is being developed must have the SAPI library loaded. Second, the computer running the application with SAPI automation must have SAPI 5.1 or later installed.

The easiest way to determine if an appropriate version of the Microsoft Speech Platform is present on a computer is to simply make calls to the Microsoft Speech Platform and see if they fail. Use error trapping to catch and work around failed Microsoft Speech Platform calls. If all the SAPI calls are caught, it is possible to run Microsoft Speech Platform-enabled applications on computers without a compatible version of Microsoft Speech Platform. Although, those applications cannot use Microsoft Speech Platform functions or functionality, but a separate version of the application does not have to be created or maintained.

For instance, if the following code snippet is executed and the Microsoft Speech Platform is not installed, a run-time error results.

Private Sub Form_Load()
    Set RC = New SpSharedRecoContext

    Set myGrammar = RC.CreateGrammar
    myGrammar.DictationSetState SGDSActive
End Sub

The error would be related to creating an object from nonexistent source. On a computer with no version of the Microsoft Speech Platform loaded, this would commonly display

Run-time error '459':
Object or class does not support the set of events

Therefore, the Microsoft Speech Platform calls need an error handler for them. For example, the same code above could be trapped by the following version. The code intends to use gSAPIPresent as a flag marking Microsoft Speech Platform's presence. If all the Microsoft Speech Platform-related calls are conditional based on gSAPIPresent, the application could run on computers lacking Microsoft Speech Platform support. Although those applications could run, voice features could not be used.

Private Sub Form_Load()
    On Error GoTo SAPINotFound

    Set RC = New SpSharedRecoContext

    Set myGrammar = RC.CreateGrammar
    myGrammar.DictationSetState SGDSActive
    gSAPIPresent = True
    Exit Sub

SAPINotFound:
    If Err.Number = 459 Then
        MsgBox "SAPI not found"
    Else
        MsgBox "Error encountered : " & Err.Number
    End If

    gSAPIPresent = False
End Sub

If an application needs to explicitly test for the presence of a compatible version of the Microsoft Speech Platform, use the following code to load a small Microsoft Speech Platform object. If the call fails, Microsoft Speech Platform is not present.

Private Sub Form_Load()
{
   'Use Visual Basic's built in error checking
   On Error GoTo Err_SAPILoad
	
   Dim PIB As ISpeechPhraseInfoBuilder
   'Now if this call fails Visual Basic's Error handling will kick in and send the program flow to Err_SAPILoad
   Set PIB = New SpPhraseInfoBuilder

Err_SAPILoad:
   MsgBox "Error loading SAPI objects! Please make sure SAPI5.1 or later is correctly installed.", vbCritical
}

Error Codes

Microsoft Speech Platform error codes are listed in Error Codes.

COM Reliance

Microsoft Speech Platform automation is built on a COM foundation. As a result many of the SAPI automation calls are virtually identical to correspondingly named calls the C/C++ section of the Microsoft Speech Platform documentation. It may be helpful read the related sections for additional insight and suggestions for automation calls. While the C/C++ references will specify C-style programming terms and code samples, in many cases the principles will be the same.