ISpGrammarBuilder::GetRule (Windows CE 5.0)
This method gets the initial state of a grammar rule. Either the rule name or identifier has to be provided (the other can either be NULL or zero). If both a grammar rule name and identifier are provided, they must match for the call to succeed. If the grammar rule does not already exist and fCreateIfNotExists is true, then the grammar rule is defined. Otherwise this call will return an error.
HRESULT GetRule(const WCHAR* pszRuleName,DWORD dwRuleId,DWORD dwAttributes,BOOL fCreateIfNotExist,SPSTATEHANDLE* phInitialState);
Parameters
- pszRuleName
[in] Pointer to a null-terminated string specifying the grammar rule name. If NULL, no search is made for the name. - dwRuleId
[in] Grammar rule identifier. If zero, no search is made for the rule identifier. - dwAttributes
[in] Grammar rule attributes of type SPCFGRULEATTRIBUTES for the new rule created. This parameter is ignored if the rule already exists. Values can be combined to allow for multiple attributes. - fCreateIfNotExist
[in] Value indicating if the method is to create the grammar rule if one does not already exist. Set this value to TRUE to create the grammar rule, and to FALSE otherwise. - phInitialState
[out] Pointer to the initial state of the rule. Can be NULL.
Return Values
The following table shows the possible return values.
| Value | Description |
|---|---|
| S_OK | Function completed successfully. |
| SPERR_RULE_NOT_FOUND | No rule matching the specified criteria can be found and a new rule is not created. |
| SPERR_RULE_NAME_ID_CONFLICT | One of the name and identifier matches an existing rule but the other does not match the same rule. |
| E_INVALIDARG | At least one parameter is invalid. Also returned when both pszRuleName and dwRuleId are NULL. |
| E_OUTOFMEMORY | Exceeded available memory. |
Example
The following code example illustrates the use of GetRule.
HRESULT hr = S_OK;
SPSTATEHANDLE hState;
//======================================================================
// Create a rule with name and identifier.
hr = pGrammarBuilder->GetRule(L"rule1", 1, SPRAF_Dynamic, TRUE, &hState);
//Check return value.
//======================================================================
// Create a rule with name only.
hr = pGrammarBuilder->GetRule(L"rule", 0, SPRAF_Dynamic, TRUE, &hState);
//Check return value.
//======================================================================
// Create a rule with identifier only.
hr = pGrammarBuilder->GetRule(NULL, 2, SPRAF_Dynamic, TRUE, &hState);
//Check return value.
//======================================================================
// Get an existing rule by identifier.
hr = pGrammarBuilder->GetRule(L"rule1", 1, SPRAF_Dynamic, FALSE, &hState);
//Check return value.
hr = pGrammarBuilder->GetRule(NULL, 1, SPRAF_Dynamic, FALSE, &hState);
//Check return value.
//======================================================================
// Get an existing rule by name.
hr = pGrammarBuilder->GetRule(L"rule1", 0, SPRAF_Dynamic, FALSE, &hState);
//Check return value.
//======================================================================
// Get rule references to other grammars.
// Compose the name of the rule as follows.
// Note the double back-slash before the rule name.
// OBJECT --> pszRuleName = L"SAPI5OBJECT:MyApp.ClassId\\\\RuleName"
// URL --> pszRuleName = L"URL:http://myserver.com\\\\RuleName"
hr = pBackend->GetRule(pszRuleName, 0 , SPRAF_Import, TRUE, phTarget)
//Check return value.
// phTarget contains a valid rule handle that can be used to reference the
rule.
Requirements
OS Versions: Windows CE .NET 4.1 and later.
Header: Sapi.h, Sapi.idl.
Link Library: Sapilib.lib.
See Also
ISpGrammarBuilder | SAPI Interfaces
Send Feedback on this topic to the authors