ISpRecoGrammar::SetWordSequenceData (SAPI 5.4)

Microsoft Speech API 5.4

ISpRecoGrammar::SetWordSequenceData

ISpRecoGrammar::SetWordSequenceData sets a word sequence buffer in the SR engine.
The command and control grammar can refer to any subsequence of words in this buffer using the <TEXTBUFFER> tag, or  the SPRULETRANS_TEXTBUFFER special transition type in ISpGrammarBuilder::AddRuleTransition().

  
    HRESULT SetWordSequenceData(
   [annotation("__in_ecount_opt(cchText)")] const WCHAR   *pText,
   ULONG                                                   cchText,
   const  SPTEXTSELECTIONINFO                             *pInfo
);

Parameters

• pText
  [in] Buffer containing the text to search for possible word sequences. The buffer is double-NULL terminated. The whole buffer could be separated into different groups by '\0'. Any sub-sequence of words in the same group is recognizable, any sub-sequence of words across different groups is not recognizable. The word could be in simple format or complex format: /disp/lex/pron. The SR engines determine where to break words and when to normalize text for better performance. For example, if the buffer displays: "please play\0this new game\0\0", "please play" is recognizable, while "this new game" is not recognizable.
• cchText
  [in] The number of characters (WCHAR) in pText, including null terminators. Because pText should be a double-null-terminated string, the value of cchText should include any internal null terminators and the ending double-null terminators.
• pInfo
  [optional, in] Address of the SPTEXTSELECTIONINFO structure that contains the selection information. If NULL, the SR engine will use the entire contents of pText.

Return values

Value

S_OK

E_INVALIDARG

FAILED(hr)

Remarks

An application that has a text box could enable the user to speak commands into the text box to edit the text. One way to design this functionality would be to create a CFG which supports such commands as "cut the text *", "bold the text *", or "italicize the words *". The grammar would then use a TEXTBUFFER tag in place of the * which would enable the SR engine to recognize the text buffer information. At run time, the application would update the SR engine's view of the text buffer using ::SetWordSequenceData. So if a user had the text "hello world" in the text box, the SR engine could recognize "bold the text world". 

See also ISpRecoGrammar::SetTextSelection for information on how to update the text selection information independent of the word sequence data.

See also ISpSREngine::SetWordSequenceData for information on how SAPI passes the word sequence data to the SR engine.

The SR engine must support text buffer features. Check for the presence of the TextBuffer attribute for the SR engine. Microsoft SR ASR engines support these features although there is no requirement that other manufacturers engines need to. See Recognizers in Object Tokens and Registry Settings for more information.

Example

The following code snippet illustrates how an application could send a text buffer to the SR engine using ISpRecoGrammar::SetWordSequenceData.

  
// Declare local identifiers:
HRESULT                      hr = S_OK;
CComPtr<ISpRecoContext>      cpRecoContext;
CComPtr<ISpRecoGrammar>      cpRecoGrammar;
SPTEXTSELECTIONINFO          tsi;
DWORD                        cch = 0;
WCHAR                        *pwszCoMem = L"";
WCHAR                        *pwszCoMem2;

// Place the contents of text buffer into pwszCoMem
// and the length of the text into cch:
tsi.ulStartActiveOffset = 0;
tsi.cchActiveChars = cch;
tsi.ulStartSelection = 0;
tsi.cchSelection = cch;

pwszCoMem2 = (WCHAR *)CoTaskMemAlloc(sizeof(WCHAR) * (cch + 2));

if (SUCCEEDED(hr) && pwszCoMem2)
{
   // SetWordSequenceData requires double NULL terminator:
   memcpy(pwszCoMem2, pwszCoMem, sizeof(WCHAR) * cch);
   pwszCoMem2[cch] = L'\0';
   pwszCoMem2[cch+1] = L'\0';

   // Set the text buffer data.
   hr = cpRecoGrammar->SetWordSequenceData(pwszCoMem2, cch + 2, NULL);
}

if (SUCCEEDED(hr))
{
   // Set the text selection information.
   hr = cpRecoGrammar->SetTextSelection(&tsi;);
}

if (SUCCEEDED(hr))
{
   // The SR engine is now capable of recognizing
   // the contents of the text buffer.
}

// Release system resources:
CoTaskMemFree(pwszCoMem2);
CoTaskMemFree(pwszCoMem);