ISpCFGInterpreter::InitGrammar (SAPI 5.3)

ISpCFGInterpreter::InitGrammar

ISpCFGInterpreter_InitGrammar initializes a grammar that is loaded from an object or DLL.

When to call

InitGrammar is typically called by SAPI only when a grammar includes a rule reference (e.g., ProgId). The following grammar includes XML:

<RULEREF NAME="MyRule" OBJECT="MyObject"/>

SAPI will internally call ::CoCreateInstance on the COM object registered under the programmatic identifier (ProgId), "MyObject", and query for the ISpCFGInterpreter interface. SAPI will call ISpCFGInterpreter::InitGrammar and pass in the string identifier "MyRule" so that the COM object's implementation can return a pointer to the compiled grammar binary (typically stored in a resource).

When to implement

Application writers and engine vendors can use the ISpCFGInterpreter interface to create COM objects that contain compiled grammars. For example, the Microsoft Speech Recognition engine (that ships in the Microsoft Speech SDK) implements inverse text normalization (INT) as a compiled SAPI context-free grammar (CFG), which is retrievable using the ISpCFGInterpreter::InitGrammar method call.

HRESULT InitGrammar(
   LPCWSTR       *pszGrammarName,
   const void   **pvGrammarData
);

Parameters

pszGrammarName

[in] Address of a null-terminated string of the grammar to be loaded.

pvGrammarData

[in] Address of a pointer to the serialized binary grammar.

Return values

Example

The following code snippet illustrates how an application writer or engine vendor might implement the InitGrammar method.

STDMETHODIMP CMyCFGInterpreter::InitGrammar(const WCHAR * pszGrammarName, const void ** pvGrammarData)
{
    if (pszGrammarName == NULL);
    {
        return E_INVALIDARG;
    }

    if (pvGrammarData == NULL);
    {
        return E_INVALIDARG;
    }

    HRESULT hr = S_OK;

    // find the resource data of type COMPILED_CFG, which has the caller's specified name
    HRSRC hResInfo = ::FindResource(_Module.GetModuleInstance(), pszGrammarName, _T("COMPILED_CFG"));

    if (hResInfo)
    {
        // Load the resource into a global handle
        HGLOBAL hData = ::LoadResource(_Module.GetModuleInstance(), hResInfo);
		
        if (hData)
        {
            // return/store a pointer to the compiled grammar
            *pvGrammarData = ::LockResource(hData);

            if (*pvGrammarData == NULL)
            {
                hr = HRESULT_FROM_WIN32(::GetLastError());
            }
        }
        else
        {
            hr = HRESULT_FROM_WIN32(::GetLastError());
        }
    }
    else
    {
        hr = HRESULT_FROM_WIN32(::GetLastError());
    }

    return hr;
}