A grammar provides a speech-recognition engine with the words and rules that determine what the engine can recognize. Before an engine can use a grammar, you must create and load a grammar object by calling the ISRCentral::GrammarLoad member function. The function's arguments include an SDATA structure that specifies the address and size of the grammar's data, and the address of the ISRGramNotifySink interface that the engine uses to notify the application of recognition events. The GrammarLoad member function returns the address of the grammar object's IUnknown interface. The application can use IUnknown to retrieve the addresses of other interfaces provided by the grammar object, including ISRGramCommon and ISRGramCFG.
The following example shows how to load a grammar, create a grammar object, and obtain the addresses of the grammar object's ISRGramCommon and ISRGramCFG interfaces. The example includes a function called GrammarReadFile that creates a memory object, reads grammar data from a file into the object, and fills an SDATA structure with the address and size of the object.
// InitializeGrammar - Loads a context-free grammar and obtains the
// addresses of interfaces supported by the grammar object.
// Returns TRUE if successful, or FALSE otherwise
// pISRCentral - address of the ISRCentral interface
// pszFileName - name of the grammar file
//
// Global variables:
// g_pGramNotifySink - address of the application's
// ISRGramNotifySink interface
// g_pISRGramCommon - address of the ISRGramCommon interface
// g_pISRGramCFG - address of the ISRGramCFG interface
// g_pISRGramDictation - address of the ISRGramDictation
// interface
BOOL InitializeGrammar(PISRCENTRAL pISRCentral, LPSTR pszFileName)
{
SDATA dGramData;
HGLOBAL hgbl;
HRESULT hRes;
LPUNKNOWN lpUnk;
// Call an application-defined function that reads the contents of
// the specified grammar file into a global memory object.
if (!GrammarReadFile(pszFileName, &dGramData, &hgbl))
return FALSE;
// Load the grammar and create a grammar object.
hRes = pISRCentral->GrammarLoad(SRGRMFMT_CFG, dGramData,
(PVOID)g_pGramNotifySink, IID_ISRGramNotifySink, &lpUnk);
// Unlock and free the global memory object.
GlobalUnlock(hgbl);
GlobalFree(hgbl);
if (hRes != NOERROR) {
HandleError(hRes);
return FALSE;
}
// Get the address of the ISRGramCommon interface.
hRes = lpUnk->QueryInterface(IID_ISRGramCommon,
(void**) &g_pISRGramCommon);
if (hRes != NOERROR) {
HandleError(hRes);
lpUnk->Release();
return FALSE;
}
// Get the address of the ISRGramCFG interface.
hRes = lpUnk->QueryInterface(IID_ISRGramCFG,
(void**) &g_pISRGramCFG);
if (hRes != NOERROR) {
HandleError(hRes);
lpUnk->Release();
return FALSE;
}
// Get the address of the ISRGramDictation interface.
hRes = lpUnk->QueryInterface(IID_ISRGramDictation,
(void**) &g_pISRGramDict);
lpUnk-Release();
return TRUE;
}
// GrammarReadFile - Reads the contents of a grammar file into a global
// memory object.
// Returns TRUE if successful, or FALSE otherwise.
// pszFileName - name of the grammar file
// pData - address of a structure that receives the size and address
// of the grammar data
// phgbl - address of a variable that receives the handle of the memory
/ object
BOOL GrammarReadFile(LPSTR pszFileName, PSDATA pData, HGLOBAL *phgbl)
{
HANDLE hf;
DWORD dwBytesRead;
// Open the grammar file.
hf = CreateFile(pszFileName, GENERIC_READ, 0, NULL, OPEN_EXISTING,
FILE_ATTRIBUTE_NORMAL, NULL);
if (hf == NULL)
return FALSE;
// Retrieve the file size and allocate a global memory object
// to contain the file's contents.
pData-dwSize = GetFileSize(hf, NULL);
*phgbl = GlobalAlloc(GMEM_ZEROINIT, pData-dwSize);
pData-pData = GlobalLock(*phgbl);
if (!pData-pData) {
CloseHandle(hf);
return FALSE;
}
// Read the contents of the file into memory, filling the SDATA
// structure in the process.
ReadFile(hf, pData->pData, pData->dwSize, &dwBytesRead, NULL);
CloseHandle(hf);
return TRUE;
}