ISpGrammarBuilder

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

• Windows Embedded CE 6.0 R3

8/28/2008

This interface exposes the back end of the SAPI context-free grammar (CFG) compiler. These methods can be used to programmatically construct grammars (for example, implement a grammar compiler).

When To Implement

Applications should use this interface to change dynamically loaded grammars (see ISpRecoGrammar) and to change previously compiled binary grammars (see ISpGramCompBackend).

Methods

The following table shows the methods for the ISpGrammarBuilder interface.

Method	Description
AddResource	Adds a resource (name and string value) to the grammar rule specified in hRuleState.
AddRuleTransition	Adds a rule (reference) transition from one grammar rule to another.
AddWordTransition	Adds a word or a sequence of words to the grammar.
ClearRule	Removes all grammar rule information except for the rule's initial state handle.
Commit	Performs consistency checks of the grammar structure, creates the serialized format and either saves it to the stream provided by SetSaveObjects, or reloads it into the SR engine.
CreateNewState	Creates a new state in the same grammar rule as hState.
GetRule	Gets a grammar rule's initial state information (and defines the rule if requested).
ResetGrammar	Clears all grammar rules (undefines them) and resets the grammar language.

Example

The following code example illustrates an implementation of the ISpGrammarBuilder interface.

// HRESULT checking code omitted.
SPSTATEHANDLE hStateTravel;
hr = pGrammarBuilder->GetRule(L"Travel",
  0, 
  SPRAF_TopLevel | SPRAF_Active,
  TRUE,
  &hStateTravel);

// Approach 1: List all possible phrases.
hr = pGrammarBuilder->AddWordTransition(hStateTravel, NULL, 
  L"fly to Seattle",
  L" ", SPWT_LEXICAL, 1, NULL);
hr = pGrammarBuilder->AddWordTransition(hStateTravel, NULL, 
  L"fly to New York",
  L" ", SPWT_LEXICAL, 1, NULL);
hr = pGrammarBuilder->AddWordTransition(hStateTravel, NULL, 
  L"fly to Washington DC",
  L" ", SPWT_LEXICAL, 1, NULL);
hr = pGrammarBuilder->AddWordTransition(hStateTravel, NULL,
  L"drive to Washington DC",
  L" ", SPWT_LEXICAL, 1, NULL);
hr = pGrammarBuilder->AddWordTransition(hStateTravel, NULL,
  L"drive to New York",
  L" ", SPWT_LEXICAL, 1, NULL);
// This is the most intuitive approach, and it does not
// sacrifice efficiency because the grammar builder will 
// merge shared subphrases when possible.

// Approach 2: Construct the directed-graph using intermediate states.
SPSTATEHANDLE hStateTravel1;
hr = pGrammarBuilder->CreateNewState(hStateTravel, &hStateTravel1);
hr = pGrammarBuilder->AddWordTransition(hStateTravel, hStateTravel1,
  L"fly to",
  L" ", SPWT_LEXICAL, 1, NULL);
hr = pGrammarBuilder->AddWordTransition(hStateTravel, hStateTravel1,
  L"drive to",
  L" ", SPWT_LEXICAL, 1, NULL);
hr = pGrammarBuilder->AddWordTransition(hStateTravel, hStateTravel1,
  L"take train to",
  L" ", SPWT_LEXICAL, 1, NULL);
hr = pGrammarBuilder->AddWordTransition(hStateTravel1, NULL,
  L"Seattle",
  L" ", SPWT_LEXICAL, 1, NULL);
hr = pGrammarBuilder->AddWordTransition(hStateTravel1, NULL, 
  L"New York",
  L" ", SPWT_LEXICAL, 1, NULL);
hr = pGrammarBuilder->AddWordTransition(hStateTravel1, NULL,
  L"Washington DC",
  L" ", SPWT_LEXICAL, 1, NULL);
// This approach gives you more control of the grammar layout, and can be
// easier to implement when you have some combinations.

// Approach 3: Using subrules.
SPSTATEHANDLE hStateMethod;
SPSTATEHANDLE hStateDest;
hr = pGrammarBuilder->GetRule(L"Method", 0, 0, TRUE, &hStateMethod);
hr = pGrammarBuilder->GetRule(L"Dest", 0, SPRAF_Dynamic, TRUE, &hStateDest);
// Dynamic rules can be modified after commit and reload.

SPSTATEHANDLE hStateTravel2;
hr = pGrammarBuilder->CreateNewState(hStateTravel, &hStateTravel2);
hr = pGrammarBuilder->AddRuleTransition(hStateTravel, hStateTravel2,
  hStateMethod, 1, NULL);
hr = pGrammarBuilder->AddRuleTransition(hStateTravel2, NULL,
  hStateDest, 1, NULL);
hr = pGrammarBuilder->AddWordTransition(hStateMethod, NULL,
  L"fly to",
  L" ", SPWT_LEXICAL, 1, NULL);
hr = pGrammarBuilder->AddWordTransition(hStateMethod, NULL,
  L"drive to",
  L" ", SPWT_LEXICAL, 1, NULL);
hr = pGrammarBuilder->AddWordTransition(hStateMethod, NULL,
  L"take train to",
  L" ", SPWT_LEXICAL, 1, NULL);
hr = pGrammarBuilder->AddWordTransition(hStateDest, NULL,
  L"Seattle",
  L" ", SPWT_LEXICAL, 1, NULL);
hr = pGrammarBuilder->AddWordTransition(hStateDest, NULL, 
  L"New York",
  L" ", SPWT_LEXICAL, 1, NULL);
hr = pGrammarBuilder->AddWordTransition(hStateDest, NULL,
  L"Washington DC",
  L" ", SPWT_LEXICAL, 1, NULL);
// This approach lets you structure the grammars and is useful
// when building large grammars.

// Must commit before using the grammar.
hr = pGrammarBuilder->Commit(0);

See Also

Reference

SAPI Interfaces