ISpStream::BindToFile (Windows CE 5.0)

Article
09/14/2012

This method binds the input stream to the file that it identifies. For Speech Recognition, this is typically a standard wave file. For Text to Speech, it is typically a text or XML file. ISpVoice::SpeakStream has a flag which allows the text to be rendered as XML or pure text (default is XML).

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

Parameters

pszFileName
[in] Pointer to a null-terminated string specifying the name of the file to which to bind the stream.
eMode
[in] Flag of type SPFILEMODE to define the file opening mode. When opening an audio wave file, this must be SPFM_OPEN_READONLY or SPFM_CREATE_ALWAYS, otherwise the call will fail.
pguidFormatId
[in] Pointer to 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
[in] Pointer to 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
[in] Flags of type SPEVENTENUM for the format converter to watch.

Return Values

The following table shows the possible return values.

Value	Description
S_OK	Function completed successfully.
E_INVALIDARG	Exceeded available memory. 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

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 this method 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: Because 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

Requirements

OS Versions: Windows CE .NET 4.1 and later.
Header: Sapi.h, Sapi.idl.
Link Library: Sapilib.lib.

Share via