SetInputScopes function

Sets a combination of one input scope, multiple input scopes, one phrase list, a regular expression, and/or Speech Recognition Grammar Specification (SRGS) rules for the specified window.


HRESULT SetInputScopes(
  _In_       HWND       hwnd,
  _In_ const InputScope *pInputScopes,
  _In_       UINT       cInputScopes,
  _In_       WCHAR      **ppszPhraseList,
  _In_       UINT       cPhrases,
  _In_       WCHAR      *pszRegExp,
  _In_       WCHAR      *pszSRGS


hwnd [in]

The window to set the scope on.

*pInputScopes [in]

Pointer to an array of input scopes. Can be NULL. If not NULL, all of the input scopes in the array are set as the input scope of the window with equal weighting. Use IS_DEFAULT to accept all other input scopes as well.

cInputScopes [in]

The number of input scopes in the array pointed to by *pInputScopes. This value must be zero if the array is NULL.

**ppszPhraseList [in]

Pointer to an array of pointers to NULL-terminated phrases. Can be NULL.

cPhrases [in]

Number of pointers pointed to by **ppszPhraseList, which represents the number of phrases.

*pszRegExp [in]

Pointer to a NULL-terminated string containing the regular expression to be recognized. Can be NULL.

*pszSRGS [in]

Pointer to a NULL-terminated XML string that provides speech-specific hints and rules to aid in speech recognition. The XML format conforms to the Speech Recognition Grammar Specification (SRGS) standard, outlined at Can be NULL. $

Return value

S_OKThe method was successful.



Calling this method replaces whatever scope is associated with the window.

This API works only when the window (hwnd parameter) and the calling thread are in the same thread. If you call this API for a different thread's window, it fails with E_INVALIDARG.

If you call this method on a window (hwnd parameter) that has not been associated with a Document Manager, then no text service notifications are sent to interested clients (such as the touch keyboard) that may want to respond to the scope change.


Minimum supported client

Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]