ISpSREngine::RuleNotify (SAPI 5.3)

Microsoft Speech API 5.3

ISpSREngine::RuleNotify

ISpSREngine::RuleNotify notifies the SR engine when CFG rules are added, changed, or removed.

  
    HRESULT RuleNotify(SPCFGNOTIFY          Action,
  ULONG                cRules,
  const SPRULEENTRY   *pRules
);

Parameters

• Action
  The SPCFGNOTIFY enumeration value specifying the action that is occurring.
• cRules
  The number of rules contained in pRules.
• pRules
  Array of SPRULEENTRY structures containing information on each rule.

Return values

Remarks

The engine recognizes each CFG grammar as containing one or more rules. Rules can be top-level, indicating that they can be activated for recognition. Each rule has an initial state and additional states, connected by transitions. Each transition can be one of several types: a word transition indicating a word to be recognized, a rule transition indicating a reference to a sub-rule, an epsilon (null) transition, and some special transitions for such features as embedding dictation within a CFG.

References to sub-rules can be recursive; i.e., rules can reference themselves, either directly or indirectly. Left recursion is not supported and SAPI will reject such grammars upon loading. Inside a grammar, transitions can have semantic properties, although the engine does not normally need to identify these.

SAPI takes full control of loading of a grammar when an application asks it to. The loading can be from a file, a URL, a resource, or from memory, and can involve loading either binary or XML forms of the grammar, and resolving imports. SAPI then notifies the SR engine about the contents of the grammar through various DDI methods.

There are five actions that are performed on rules:

- New rules can be added (SPCFGN_ADD) or existing rules removed (SPCFGN_REMOVE).
- Rules can be activated (SPCFGN_ACTIVATE) or deactivated (SPCFGN_DEATIVATE) for recognition.
- Rule can be invalidated (SPCFGN_INVALIDATE), which means the rule has been edited by the application and thus the engine needs to reread the contents of the rule.

Each rule is represented by an SPRULEENTRY structure. This contains an hRule, which gives a unique handle identifying the rule. The pvClientRuleContext is a pointer that the engine can set using ISpSREngineSite::SetRuleClientContext. Then, subsequent calls to the ISpSREngineSite::GetRuleInfo method will return the same structure but with the pvClientRuleContext field filled in. The pvClientGrammarContext is the pointer that the engine set in the ISpSREngine::OnCreateGrammar method. This indicates which grammar the rule belongs to. The Attributes field, of type SPCFGRULEATTRIBUTES, contains some flags giving extra information about the rule:

SPRAF_TopLevel if the rule is top level and thus can be activated for recognition.

SPRAF_Active if the rule is currently activated.

SPRAF_Interpreter if the rule is associated with an Interpreter object for semantic processing.

SPRAF_AutoPause if the rule is autopause.

The hInitialState gives the initial state of the rule.

In order for the SR engine to find out the full contents of the rule (either immediately, or later during recognition), it can use the ISpSREngineSite::GetStateInfo method. This gives information about all the subsequent transitions and states following on from any given state (starting with the initial state of the rule).