Microsoft Speech Platform

ISpGrammarBuilder::GetRule

ISpGrammarBuilder::GetRule retrieves grammar rule's initial state.

<pre IsFakePre="true" xmlns="http://www.w3.org/1999/xhtml"> HRESULT GetRule( LPCWSTR *pszRuleName, DWORD dwRuleId, DWORD dwAttributes, BOOL fCreateIfNotExist, SPSTATEHANDLE *phInitialState ); </pre>

Parameters

pszRuleName
[in] Address of the null-terminated string containing 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 ID.
dwAttributes
[in] Grammar rule attributes for the new rule created. Ignored if the rule already exists. Must be of type SPCFGRULEATTRIBUTES. Values may be combined to allow for multiple attributes.
fCreateIfNotExist
[in] Boolean indicating that the grammar rule is to be created if one does not currently exist. TRUE allows the creation; FALSE does not.
phInitialState
[out] The initial state of the rule. May be NULL.

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 ID 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	Not enough memory to complete operation.

Remarks

Either the rule name or ID must be provided (the other unused parameter can either be NULL or zero). If both a grammar rule name and identifier are provided, they both must match in order for this call to succeed. If the grammar rule does not already exist and fCreateIfNotExists is true, the grammar rule is defined. Otherwise this call will return an error.

Be sure that you use the correct letter casing when specifying the rule name. Rule names are case-sensitive in the Speech Platform. For example, if the name of the rule to target is "Test", and you set the value of pszRuleName to "test", the call will generate an error or incorrectly target a rule named "test".

Example

The following code snippet illustrates the use of GetRule.

// Declare local identifiers:
HRESULT                       hr = S_OK;
CComPtr<ISpGrammarBuilder>    cpGrammarBuilder;
CComPtr<ISpGrammarBuilder>    cpBackend;
SPSTATEHANDLE                 hState;
SPSTATEHANDLE                 phTarget;
WCHAR                         *pszRuleName = L"SPEECHPLATFORMOBJECT:MyApp.ClassId\\RuleName";
// Create a rule with name and ID.
hr = cpGrammarBuilder->GetRule(L"rule1", 1, SPRAF_Dynamic, TRUE, &hState;);
if (SUCCEEDED (hr))
{
// Create a rule with name only.
hr = cpGrammarBuilder->GetRule(L"rule", 0, SPRAF_Dynamic, TRUE, &hState;);
}
if (SUCCEEDED (hr))
{
// Create a rule with ID only.
hr = cpGrammarBuilder->GetRule(NULL, 2, SPRAF_Dynamic, TRUE, &hState;);
}
if (SUCCEEDED (hr))
{
// Get an existing rule by ID.
hr = cpGrammarBuilder->GetRule(L"rule1", 1, SPRAF_Dynamic, FALSE, &hState;);
}
if (SUCCEEDED (hr))
{
hr = cpGrammarBuilder->GetRule(NULL, 1, SPRAF_Dynamic, FALSE, &hState;);
}
if (SUCCEEDED (hr))
{
// Get an existing rule by name.
hr = cpGrammarBuilder->GetRule(L"rule1", 0, SPRAF_Dynamic, FALSE, &hState;);
}
if (SUCCEEDED (hr))
{
// Get rule references to other grammars and
// compose the name of the rule as follows.
// Please note the double back-slash before the rule name.
// OBJECT --> pszRuleName = L"SPEECHPLATFORMOBJECT:MyApp.ClassId\\RuleName"
// URL --> pszRuleName = L"URL:http://myserver.com\\RuleName"
hr = cpBackend->GetRule(pszRuleName, 0 , SPRAF_Import, TRUE, &phTarget;);
}
if (SUCCEEDED (hr))
{
// phTarget contains a valid rule handle that can by
// used to reference the rule; now do some more stuff.
}

Share via