ISpStream::BindToFile

ISpStream::BindToFile binds the input stream to the file that it identifies.

HRESULT BindToFile(
   const WCHAR          *pszFileName,
   SPFILEMODE            eMode,
   const GUID           *pguidFormatId,
   const WAVEFORMATEX	*pWaveFormatEx, 
   ULONGLONG             ullEventInterest
);     

Parameters

pszFileName

Address of a null-terminated string containing the file name of the file to bind the stream to.

eMode

Flag of the type SPFILEMODE to define the file opening mode. When opening an audio wave file, eMode must be SPFM_OPEN_READONLY or SPFM_CREATE_ALWAYS, otherwise the call will fail.

pguidFormatId

The data format identifier associated with the stream. This can be NULL and the format will be determined from the supplied wave file, if the file has the wav extension. If it does not, the file is assumed to be a text file.

pWaveFormatEx

Address of the WAVEFORMATEX structure that contains the wave file format information. If guidFormatId is SPDFID_WaveFormatEx, this must point to a valid WAVEFORMATEX structure. For other formats, it should be NULL.

ullEventInterest

Flags of type SPEVENTENUM for the format converter to watch.

Return values

Remarks

In speech recognition, ::BindToFile supports only wave audio files. It passes SAPI an audio file to pass to the engine. In text-to-speech, ::BindToFile supports both audio and text files. See ISpVoice::SpeakStream for more information.

The helper class CSpStreamFormat and the SPSTREAMFORMAT enumeration can be used to avoid the possibility of typos or mistakes when filling in the WAVEFORMATEX structure.

Example

The following code snippet illustrates the use of ISpStream::BindToFile for creating a writable wave file

    HRESULT hr = S_OK;

    // create the stream object
    hr = cpSpStream.CoCreateInstance(CLSID_SpStream);
    // Check hr

    // create a stream format helper for 22khzm 16-bit, mono wave stream
    CSpStreamFormat Fmt(SPSF_22kHz16BitMono, &hr);
    // Check hr
 
    // create the new stream and its corresponding file on the hard disk
    // NOTE: Specify the file format when creating the file 
    hr = cpSpStream->BindToFile(WAVE_FILENAME, SPFM_CREATE_ALWAYS, &Fmt.FormatId(), Fmt.WaveFormatExPtr(), NULL);
    // Check hr

    // write some data to the stream
    hr = cpSpStream->Write(WAVE_DATA_CHUNK, SIZEOF_WAVE_DATA_CHUNK, &cbWritten);
    // Check hr

The following code snippet illustrates the use of ISpStream::BindToFile for creating a read-only wave file

    HRESULT hr = S_OK;

    // create the stream object
    hr = cpSpStream.CoCreateInstance(CLSID_SpStream);
    // Check hr
 
    // create a new stream, by opening a wave file from the hard disk
    // NOTE: Since an existing file is being read, SAPI will read the wave stream format automatically
    hr = cpSpStream->BindToFile(WAVE_FILENAME, SPFM_OPEN_READONLY, NULL, NULL, NULL);
    // Check hr

    // read some data from the stream
    hr = cpSpStream->Read(&bData, SIZEOF_WAVE_DATA_CHUNK, &cbWritten);
    // Check hr