SREC Initialization Functions - Microsoft Windows Pen API Programmer's Reference

Microsoft Windows Pen API Programmer's Reference

Custom Search

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.

Last news from Greatis Software

    Nostalgia .Net     .Net is powerful, but not all-powerful, so sometimes we need to use Win32 API for our .Net applications. It's simple enough with Platform Invoke if you have Win32 skill, but we do not always have time to dig the ancient documentation, declare the special types that are compatible with Win32, find the values of the Win32's constants and so on. Nostalgia .Net offers several simple-to-use classes, and components that will allow you to forget about the headache of Win32 and just use the power of Win32 in your application the same way as you use the native. Net classes. More »

Recommended software for developers

    Ultimate Pack     Component pack for Delphi and C++ Builder that contains runtime form designer, runtime object inspector, print suite and much more for the very special price. More »

    Form Designer .Net     Unique runtime form design solution that allows to edit any form in .Net WinForms application at runtime with full source codes for only 300 euro! More »

    Print Suite .Net     Print Suite .Net is a set of components for easy printing texts, images and grids from your WinForms applications. Full C# source codes are available More »

    Gradient Controls .Net     Gradient Controls .Net offers controls with gradient background feature. Labels, panels and so on... Full C# source codes are available More »

    Greatis iGrid     iGrid plots drawing grid right over your desktop, so you can use it everywhere, with any drawing application without any special plugins for different graphic editors. More »

All the contacts and projects

Dmitry Vasiliev (just.dmitry)

More Online Helps

Win32 Programmer's Reference
Win32 Multimedia Programmer's Reference
OLE Programmer's Reference
Microsoft Windows Pen API Programmer's Reference
Microsoft Windows Sockets 2 Reference
Microsoft Windows Telephony API (TAPI) Programmer's Reference
Unix Manual Pages

greatis just4fun network