Using MFC to Automate SAPI

Introduction

The Microsoft Foundation Classes (MFC) provides an easy and convenient way to automate calls to SAPI using its Class Wizard to generate wrappers for the SAPI layer from the SAPI Type Library.

In order to accomplish this, perform the following steps:

1. Create a new MFCAppWizard(exe) project in Visual C++.
2. Based on the type of application you are creating, follow the wizard prompts. In Step 3 of the wizard prompts, (or Step 2 if you are creating a Dialog Based application) make sure that the Automation check box is selected under the heading, What other support would you like to include?

Once the new project is ready, access Class Wizard.

1. Click the Automation tab, and then click Add Class and select From a type library in the drop-down list.
2. Browse for the sapi.dll file and open it.
3. Select the classes you would like Class Wizard to generate a wrapper for. The resulting default header and implementation files are sapi.h and sapi.cpp respectively. The rest of this document assumes that you have chosen to use these default file names. Click OK.
4. You should now be back in the Class Wizard window. Click OK.

After you are done with the above steps, Visual C++ will automatically add the Class Wizard generated files sapi.cpp and sapi.h to your project.

Upon viewing the sapi.h file, you should notice that it is nothing more than an automation wrapper that has been generated for all the classes you selected. Notice that all the classes inherit from COleDispatchDriver, hence the dispatch interface needs to be set up. This only requires a few lines of simple code, after which the wrapper class can be used just like any other C++ class.

Example

This example assumes that you chose to generate a wrapper for the ISpeechVoice class from among any other classes you may have selected. Using the project created above, include the sapi.h file within a source file in the project that will make automation calls to SAPI using the wrapper. In that source file, type the following code.

CLSID CLSID_SpVoice;    // class ID for the SAPI SpVoice object
LPDISPATCH pDisp;       // dispatch interface for the class
ISpeechVoice voice;     // use the MFC Class Wizard generated wrapper

CLSIDFromProgID(L"SAPI.SpVoice", &CLSID;_SpVoice);
voice.CreateDispatch(CLSID_SpVoice);
pDisp = voice.m_lpDispatch;

HRESULT hr = pDisp->QueryInterface(CLSID_SpVoice, (void**)&voice;.m_lpDispatch);

if (hr == S_OK) {
    pDisp->Release();
}
else {
    voice.AttachDispatch(pDisp, TRUE);
}

voice.Speak("hello world", 1);   // asynchronous call to Speak method of ISpeechVoice interface

If you have been following the steps outlined above properly, you should hear your computer say "hello world!" That's all there is to using MFC to make automation calls to SAPI. Currently however, not all the wrapper classes generated by MFC's Class Wizard work properly. For instance, the ISpeechLexicon interface does not work. The work around for this is to implement your own automation wrapper classes using C++. The steps to do that are beyond the scope of this document. Of course, you can always use the COM interfaces in C++ and Automation in Visual Basic to ensure that every interface in SAPI works easily and flawlessly.