HRESULT Select(GUID gModeID, PITTSCENTRAL *ppiTTSCentral,
PIUNKNOWN pIUnknownForAudio);
Selects a text-to-speech mode and creates an engine object to represent the selected mode.
· Returns NOERROR if successful, or one of these error values:
<E_INVALIDARG>
<E_OUTOFMEMORY>
<TTSERR_INVALIDMODE>
<TTSERR_OUTOFDISK>
<TTSERR_WAVEFORMATNOTSUPPORTED>
gModeID
[in] Globally unique identifier (GUID) from the TTSMODEINFO structure for the currently selected text-to-speech mode. The function creates an engine object to represent this mode.
ppiTTSCentral
[out] Address of a variable that receives a pointer to the ITTSCentral interface for the newly created engine object.
pIUnknownForAudio
[out] Address of the IUnknown interface for the audio-destination object that provides digital-audio data for the engine object. The engine will AddRef the interface, and release the interface when the engine is destroyed. Because of this the application will need to call Release on the audio object after the select call or audio objects will be leaked.
After the application enumerates the text-to-speech modes and determines which one to use, it calls Select to create the engine object.
As the engine object initializes, it calls the IAudio interface of the audio-destination object specified by pIUnknownForAudio to determine whether it can use that audio destination. If it can, the function returns an ITTSCentral interface for the newly created engine object. If it cannot, the engine object releases itself and the Select function returns an error.
After the object is created, it calls the IAudio::PassNotify member function to pass its own notification sink to the audio-destination object. Passing the notification sink to the audio-destination object allows the object to notify the engine when audio data is played. When all references to the engine object are released, the engine object calls the IAudio::Release member function.
The multimedia audio-destination object can be used to send audio to a wave-out device. The Select function passes the IUnknown interface rather than the IAudioDest interface because, although all engines should support IAudioDest, some engines may use custom interfaces for dealing with special hardware or drivers and IUnknown can be used to obtain such interfaces. For more information about the multimedia audio-destination object, see the section, "Multimedia Audio Objects ."
The pIUnknownForAudio parameter is obtained by using the CoCreateInstance function. As such, the reference count for the IUnknown interface begins at 1, and the interface should be released after Select has returned.
The negotiation with the audio-destination object occurs within the call to Select, so if Select returns without an error, the negotiation succeeded.