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.
- Software for developers
-
Delphi Components
.Net Components
Software for Android Developers
- More information resources
-
MegaDetailed.Net
Unix Manual Pages
Delphi Examples
- Databases for Amazon shops developers
-
Amazon Categories Database
Browse Nodes Database
