Share via

Grammar Constructor (Stream, String, Uri)

  • Article

Constructs a new instance of Grammar from an instance System.IO.Stream connecting to an object containing a grammar specification; a base URI for relative references, may also be specified.

Namespace: Microsoft.Speech.Recognition
Assembly: Microsoft.Speech (in microsoft.speech.dll)

Syntax

'Declaration

Parameters

  • stream
    A System.IO.Stream connecting to an I/O object -- including files, Visual Studio Resources, and DLLs -- containingagrammar specification.

  • ruleName
    Name of a grammar rule used as the entry point or root of the Grammar object to be created.

    This parameter may be null.

  • baseUri
    System.Uri object defining base path that any relative rule references, for example to other grammars, within the grammar are resolved against.

    This parameter may be null.

Exceptions

Exception type Condition
ArgumentException

Generated for invalid stream,ruleName, or baseUri values.

Generated if the stream is connected to a grammar that does not contain the rule ruleName, or has a relative rule reference not resolvable even using the baseUri.

Remarks

The stream argument:

  • Can never be null and must be readable.

  • In general, the object a stream is connected to must be a W3C Speech Recognition Grammar Specification (SRGS) or Context Free Grammar (CFG).

    However:

    • If the input stream is connected to a VisualStudioResource, the Resource can only contain grammars in binary CFG format

    • If the input stream is connected to a DLL, that DLL must contain instances of Grammar.

No parameters are supplied to this constructor, therefore the loaded rule should either have no initialization handler defined, or the initialization handler should require no arguments.

The ruleName argument:

  • May be null or System.String.Empty.

  • If ruleName is not null and the rule specified is not found in the grammar being loaded, an exception is generated.

  • If ruleName is null, the grammar contained in the file specified by must specify a root rule. If there is not root rule in the grammar being loaded an exception is generated.

    (For more information on root rules, see the discussion of the Root property on the Microsoft.Speech.Recognition.SrgsGrammar.SrgsDocument class.)

The baseUri argument:

  • The value of baseUri should be an absolute URI, and can be a path or a file.

  • If the value of baseUri is a path, be sure and append a trailing slash.

  • The URI provided by baseUri is not validated when the Grammar object is constructed.

    Instead, if the URI is invalid or any relative references inaccessible, on grammar load, a recognition engine (instances of SpeechRecognizer or SpeechRecognitionEngine) generates and exception.

    Recognition engine handle references within a Grammar being loaded by:

    • Resolving all references with absolute URIs.

    • Attempting resolution within the XML of Grammar being loaded.

    • Using any paths indicated in the instance of srgsDocument used to create the Grammar to resolve the reference. If the srgsDocument has been created from a file, this typically includes the directory where that file was located.

    • Trying to resolve the reference with the value ofbaseUri if it is non-null.

Example

The following try/catch block attempts to create a new Grammar from an instance of System.IO.Stream (grammarString), which is connected to an object containing a grammar specification.

The object connected by the System.IO.Stream must:

  • Contain a root rule named "MapLookup"

  • Have all references to other rules and grammars accessible in the file http://mapLookup.com/MapUtils.xml"

  • Have no initialization handler, or a handler that takes not arguments..

The XML of a grammar meeting these conditions is available following the source to the try/catch block

try {
  Grammar grammar = new Grammar(grammarStream,
            @"MapLookup",
            new Uri("http://mapLookup.com/"));
  grammar.Enabled = true;
 } catch (System.ArgumentException exp) {
  MessageBox.Show(String.Format("Invalid constructor arguments:\n{0}\n", exp.Message));
 } catch (Exception exp) {
  // Catch all other exceptions
  MessageBox.Show(String.Format("Failed to load {0}.\nError Message:\n{1}",
            filename, exp.Message));
 }

A sample MapLookup.xml:

<grammar xml:lang="en-us" version="1.0"
xmlns="http://www.w3.org/2001/06/grammar" tag-format="properties-ms/1.0"
xmlns:sapi="http://schemas.microsoft.com/Speech/2002/06/SRGSExtensions"
sapi:debug="True" root="MapLookup">
  <rule id="MapLookup" scope="public" sapi:onParse="OnParseMapLookup" sapi:onInit="OnInit" >
    bis
  </rule>
   <sapi:script sapi:rule="MapLookup">
     <![CDATA[ 
       public object OnParseMapLookup(SemanticValue result, RecognizedWordUnit[] words) {
    Console.WriteLine("OnParse MapLookup: " + _value);
    return _value;
}


public SrgsRule[] OnInit(string state_region, string city, string country) {
    Console.WriteLine(String.Format("Initializer using three arguments: {0},{1},{2}\n",
                                     state_region, city, country));
    _state_region = state_region;
    _city = city;
    _country = country;
    return null;
}

public SrgsRule[] OnInit( string city, string state_region)
{
   Console.WriteLine (String.Format("Initializer using two arguments: {0},{1}\n",
                                    city,state_region));
    _state_region = state_region;
    _city=city;
    _country="United States";
    return null;
}

public SrgsRule[] OnInit(string country) {
    Console.WriteLine(String.Format("Initializer using one argument: {0}\n",
    country));
    _state_region = null;
    _city = null;
    _country = country;
    return null;
}

public SrgsRule[] OnInit() {
    Console.WriteLine(String.Format("Initializer using no arguments\n"));
    _state_region = null;
    _city = null;
    _country = "United States";
    return null;
}

private string _state_region;
private string _city;
private string _state_region1;
private string _city1;
private string _value;
private string _country;
]]>
   </sapi:script>

</grammar>

Platforms

Development Platforms

Windows XP Professional with Service Pack 2 (SP2), Windows Server 2003, Windows Vista Ultimate Edition, Windows Vista Business Edition, Windows Vista Enterprise Edition

Target Platforms

See Also

Reference

Grammar Class
Grammar Members
Microsoft.Speech.Recognition Namespace
SystemIO.Stream
Microsoft.Speech.Recognition.SrgsGrammar
SpeechRecognizer
SpeechRecognitionEngine
Grammar Constructor

Other Resources

Speech Recognition Grammar Specification