ISpGrammarBuilder::GetRule

Other versions of this page are also available for the following:

• Windows Embedded CE 6.0 R3

8/28/2008

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.

Syntax

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 Value

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:https://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

Header	sapi.h, sapi.idl
Library	sapilib.lib
Windows Embedded CE	Windows CE .NET 4.1 and later

See Also

Reference

ISpGrammarBuilder
SAPI Interfaces