SREC Initialization Functions - Microsoft Windows Pen API Programmer's Reference (penapi.hlp)

Microsoft Windows Pen API
Programmer's Reference

SREC Initialization Functions

As a Windows dynamic-link library, SREC exports LibMain and WEP. As a recognizer, it also exports the required initialization function ConfigRecognizer. All recognizers compatible with version 2.0 of the Pen API must provide these functions.

LibMain and WEP
The first two functions in the SREC recognizer are the standard Windows functions required in any dynamic-link library, LibMain and WEP. LibMain, the main DLL function, is analogous to WinMain. It performs any needed initialization and unlocks the data segment of the library. WEP is the standard DLL termination function, which receives control when Windows unloads the DLL. For a description of WEP, see the references listed at the beginning of this chapter.

ConfigRecognizer
The ConfigRecognizer function handles the recognizer's initialization tasks and configures it for special options. When it loads a recognizer, InstallRecognizer internally calls the recognizer's ConfigRecognizer function with the subcommand WCR_INITRECOGNIZER. In response to this call, the recognizer should perform any required initialization tasks.

As its name suggests, ConfigRecognizer handles more than initialization work. It also provides the means for setting recognizer options and to query for capabilities. With version 2.0 of the Pen API, which can load multiple recognizers, applications do not call ConfigRecognizer, because the function provides no way to identify the intended library. Instead, applications call the ConfigHREC function, which takes

the same arguments as ConfigRecognizer, with the addition of the HREC handle returned from InstallRecognizer. Internally, the system identifies the intended recognizer from the handle and passes the arguments to ConfigRecognizer in the appropriate recognizer. Thus, ConfigHREC and ConfigRecognizer refer to the same function. ConfigRecognizer is unique in that it is the only function exported by a recognizer that applications do not call directly.

As the following code fragment shows, SREC returns only its identification string and version number from ConfigRecognizer. Note also that SREC does not allow itself to be set as the system recognizer. Since SREC does not support standard editing gestures or recognize characters, it cannot serve as a system default recognizer.

int WINAPI ConfigRecognizer( UINT uSubFunc,

WPARAM wParam, LPARAM lParam )

{

int iRet = TRUE;

switch ( uSubFunc )

{

case WCR_INITRECOGNIZER: // No initialization or

case WCR_CLOSERECOGNIZER: // clean up duties to

break; // perform

case WCR_RECOGNAME:

lstrncpy( (LPSTR)lParam, szID, wParam );

break;

case WCR_DEFAULT: // Can't be system default

case WCR_QUERY: // Does not support config dialog

case WCR_QUERYLANGUAGE: // Does not support any language

iRet = FALSE;

break;

case WCR_PWVERSION:

case WCR_VERSION:

iRet = 0x0002; // Recognizer version 2.0

break;

default:

iRet = FALSE; // Anything else is unsupported

break;

}

return iRet;

}

For a complete list of WCR_ subfunctions, refer to the reference section for ConfigRecognizer in Chapter 10.

When the last client application unloads a recognizer, the UninstallRecognizer function calls the recognizer's ConfigRecognizer function with the command WCR_CLOSERECOGNIZER. This informs the recognizer that it is being unloaded. The previous code takes no action for WCR_CLOSERECOGNIZER because in SREC, memory allocations come from the local heap. As with any Windows-based program, a DLL's heap resides in its data segment. When Windows unloads a DLL, it automatically returns the entire data segment to the memory pool.

However, unloading SREC does not destroy its internal HPENDATA object. HPENDATA blocks occupy global heap space. If the client application terminates or unloads SREC without first destroying all HRC objects created by SREC, the corresponding HPENDATA blocks are left orphaned in memory. A recognizer more intelligent than SREC should maintain a count of active HPENDATA allocations and free any that remain before terminating.

A recognizer's WEP routine also receives control when Windows unloads the recognizer. Developers should note a subtle difference between handling cleanup chores in ConfigRecognizer and in WEP. When the former executes in response to the WCR_CLOSERECOGNIZER subfunction, the client is still active. However, the WEP routine cannot safely make the same assumption when it executes. ConfigRecognizer can therefore conceivably post a message to the client or perform some other action that relies on an active recipient.

The disadvantage of ConfigRecognizer is that the recognizer cannot be certain the function will execute because the client might not call UninstallRecognizer. Since the WEP function is guaranteed to execute when Windows unloads the recognizer, essential cleanup duties, such as unhooking interrupts, should be handled in WEP.

More Online Helps

Win32 Programmer's Reference (win32.hlp)
Win32 Multimedia Programmer's Reference (mmedia.hlp)
OLE Programmer's Reference (ole.hlp)
Microsoft Windows Sockets 2 Reference (sock2.hlp)
Microsoft Windows Telephony API (TAPI) Programmer's Reference (tapi.hlp)
Unix Manual Pages

greatis just4fun network