ISpSREngine::SetWordSequenceData (SAPI 5.4)

Microsoft Speech API 5.4

ISpSREngine::SetWordSequenceData

ISpSREngine::SetWordSequenceData sets a text buffer that the engine can use for recognition.

  
    HRESULT SetWordSequenceData(
   void                         *pvEngineGrammar,
   const WCHAR                  *pText,
   ULONG                         cchText,
   const  SPTEXTSELECTIONINFO   *pInfo
);

Parameters

• pvEngineGrammar
  [in] The engine's grammar pointer for this grammar, as returned from a previous call to the OnCreateGrammar method.
• pText
  [in] The text buffer.
• cchText
  [in] The length, in characters, of the text buffer.
• pInfo
  [in] Address of the SPTEXTSELECTIONINFO structure that contains information of which parts of the buffer are active and currently selected.

Return values

Remarks

Whenever a text-buffer transition is reached in a CFG, the engine should attempt to recognize a sub-string of words from the current text buffer. This provides a very simple way for applications to select from a set of text.

This method is called when an application calls ISpRecoGrammar::SetWordSequenceData. The format of the text in the buffer that is passed to the pText parameter is a sequence of one or more strings. The engine recognizes any sub-string of words from any of the strings in the buffer. It is up to the SR engines to perform word breaking and text normalization for better performance.

It is also possible for the application to alter the areas of the buffer that are used for recognition. The initial range can be set with the structure SPTEXTSELECTIONINFO, and later calls to ISpSREngine::SetTextSelection can alter this without changing the actual buffer. The ulStartActiveOffset and cchActiveChars indicate which area of the buffer should be active for recognition.

The other two fields of the SPTEXTSELECTIONINFO, ulStartSelection and cchSelection can be used with dictation. These could indicate, on screen for example, which area of the buffer is currently selected. If cchSelection is zero, this could display the current location of the insertion point. The engine can use SPTEXTSELECTIONINFO to get extra language model context from the preceding words in the dictated text.

This text buffer feature is optional for engines, and support for it is determined using the TextBuffer attribute in the engine object token. If this method is called on an engine that does not support this feature, the engine should return E_NOTIMPL.