SetInputScopes (Compact 2013)

Article
04/19/2017

3/28/2014

Set multiple InputScope values and additional data such as a Phrase List or Speech Recognition Grammar Specification (SRGS) on a specified input field.

Syntax

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

Parameters

hwnd
[in] The input field to set the InputScope on.

pInputScopes
[in] Pointer to an array of InputScopes. May be NULL. All of the scopes contained in the array are set as the InputScopes of the hwnd with equal weighting. IS_DEFAULT indicates the input field may accept any input.

cInputScopes
[in] A count of the number of input scopes in pInputScopes. The maximum value is 49.

ppszPhraseList
[in] Pointer to an array of pointers to NULL-terminated phrases accepted by the input field. Can be NULL. The maximum length of each phrase, including the NULL terminator, is 256.

cPhrases
[in] Number of phrases in ppszPhraseList. The maximum number of phrases is 1024.

pszRegExp
[in] Reserved. Must be set to 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 W3 Speech Recognition Grammar Specification (SRGS) standard. Can be NULL. The maximum size of the SRGS grammar string is 256K.

Return Value

Returns S_OK if the input scope is set or cleared successfully.

Returns S_FALSE to indicate that the SRGS data is not validated.

Returns E_OUTOFMEMORY if it cannot allocate enough memory to store the data set.

Returns E_INVLIDARG if non-zero counts are given for NULL buffer.

Returns ERROR_INVALID_WINDOW_HANDLE if hwnd is NULL or hwnd is not a valid handle in the thread.

Returns ERROR_NOT_SUPPORTED if pszRegExp is set to non-NULL value.

Returns ERROR_INVALID_DATA if the value specified in pInputScopes is invalid.

Returns ERROR_PARAMETER_QUOTA_EXCEEDED if one or more of the parameters exceed the stated size limitation.

Remarks

This function replaces any InputScope values that may have been set on the hwnd previously.

Extended InputScope values and reserved InputScope values are not allowed for this function.

Code Example

The following code illustrates how to limit the scope of the recognizer's vocabulary to a list of words or phrases by using a phrase list. This causes the recognizer to coerce to the input scope.

LPCWSTR phraseList[] = {L"blue", L"yellow", L"green", L"light blue"};
UINT cPhraseCount = 4;
SetInputScopes(hwnd, NULL, 0, phraseList, cPhraseCount, NULL, NULL);

The following code illustrates how to suggest (not force) a phrase list as an input scope, by specifying IS_DEFAULT.

LPCWSTR phraseList[] = {L"blue", L"yellow", L"green", L"light blue"};
UINT cPhraseCount = 4;
SetInputScopes(hwnd, {IS_DEFAULT}, 1, phraseList, cPhraseCount, NULL, NULL);

The following code shows how to force an input to multiple input scopes.

InputScope is[] ={IS_URL , IS_FILE_FILENAME , IS_EMAIL_USERNAME};
UINT cCount = 3;
SetInputScopes(hwnd, is, cCount, NULL, 0, NULL, NULL);

The following code shows how to force an input to a single input scope.

InputScope scope[] = {IS_TELEPHONE_FULLTELEPHONENUMBER};
SetInputScopes(hwnd, scope, 1, NULL, 0, NULL, NULL);

The following code shows how to clear an input scope.

InputScope scope[] = {IS_DEFAULT};
SetInputScopes(hwnd, scope, 1, NULL, 0, NULL, NULL);

Requirements

Header

inputscope.h

Share via