Microsoft Speech Platform

---

ISpStream::BindToFile

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

HRESULT BindToFile(
   LPCWSTR              *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 (that is, the possible events raised by SAPI) for the format converter to watch. Typical events are those to be serialized into the audio stream (for audio output) or those to be deserialized out of the audio stream and fed to SAPI (for audio input).

Return values

Value	Description
S_OK	Function completed successfully.
E_INVALIDARG	At least one of the following was encountered. pszFileName or pguidFormatId is invalid or bad; eMode exceeds SPFM_CREATE_ALWAYS; an operation could not be completed.
E_OUTOFMEMORY	Exceeded available memory.
STG_E_FILENOTFOUND	File pszFileName does not exist.
SPERR_ALREADY_INITIALIZED	The object has already been initialized.
FAILED (hr)	Appropriate error message.

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

// Declare local identifiers:
HRESULT                    hr = S_OK;
CComPtr<ISpStream>         cpSpStream;
CSpStreamFormat            Fmt;
WCHAR                      *WAVE_DATA_CHUNK = L"#$%^&*";
ULONG                      SIZEOF_WAVE_DATA_CHUNK = 12;
ULONG                      cbWritten;

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

if (SUCCEEDED(hr))
{
   // Create a stream format helper for 22khzm 16-bit, mono wave stream.
   CSpStreamFormat Fmt(SPSF_22kHz16BitMono, &hr;);
}

if (SUCCEEDED(hr))
{
   // Create new stream and its corresponding file on hard
   // disk (specify the file format when creating the file).
   hr = cpSpStream->BindToFile(L"C:\\Test.wav", SPFM_CREATE_ALWAYS, &Fmt.FormatId;(), Fmt.WaveFormatExPtr(), NULL);
}

if (SUCCEEDED(hr))
{
   // Write some data to the stream.
   hr = cpSpStream->Write(WAVE_DATA_CHUNK, SIZEOF_WAVE_DATA_CHUNK, &cbWritten;);
}

if (SUCCEEDED(hr))
{
   // Do stuff here.
}

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

// Declare local identifiers:
HRESULT                 hr = S_OK;
CComPtr<ISpStream>      cpSpStream;
ULONG                   bData;
ULONG                   cbWritten;
ULONG                   SIZEOF_WAVE_DATA_CHUNK = 100;

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

if (SUCCEEDED(hr))
{
   // Create new stream and its corresponding file on hard
   // disk (specify the file format when creating the file).
   hr = cpSpStream->BindToFile(L"C:\\Test.wav", SPFM_CREATE_ALWAYS, &Fmt.FormatId;(), Fmt.WaveFormatExPtr(), NULL);
}

if (SUCCEEDED(hr))
{
   // Create a stream format helper for 22khzm 16-bit, mono wave stream.
   CSpStreamFormat Fmt(SPSF_22kHz16BitMono, &hr;);
}

if (SUCCEEDED(hr))
{
   // Write some data to the stream.
   hr = cpSpStream->Write(WAVE_DATA_CHUNK, SIZEOF_WAVE_DATA_CHUNK, &cbWritten;);
}

if (SUCCEEDED(hr))
{
   // Do stuff here.
}