#include <toolhelp.h> |
BOOL NotifyRegister(htask, lpfnCallback, wFlags) | |||||
HTASK htask; | /* handle of task, */ | ||||
LPFNNOTIFYCALLBACK lpfnCallback; | /* address of callback function | */ | |||
WORD wFlags; | /* notification flags, */ |
The NotifyRegister function installs a notification callback function for the given task.
htask
Identifies the task associated with the callback function. If this parameter is NULL, it identifies the current task.
lpfnCallback
Points to the notification callback function that is installed for the task. The kernel calls this function whenever it sends a notification to the task.
The callback-function address is normally the return value of a call to MakeProcInstance. This causes the callback function to be entered with the AX register set to the selector of the application's data segment. Usually, an exported function prolog contains the following code:
mov ds,ax
wFlags
Specifies the optional notifications that the application will receive, in addition to the default notifications. This parameter can be NF_NORMAL or any combination of the following values:
Value | Meaning |
NF_NORMAL | The application will receive the default notifications but none of the notifications of task switching, system debugging errors, or debug strings. |
NF_TASKSWITCH | The application will receive task-switching notifications. To avoid poor performance, an application should not receive these notifications unless absolutely necessary. |
NF_RIP | The application will receive notifications of system debugging errors. |
The return value is nonzero if the function was successful. Otherwise, it is zero.
The syntax of the function pointed to by lpfnCallback is as follows:
BOOL NotifyRegisterCallback(wID, dwData)
WORD wID;
DWORD dwData;
wID
Indicates the type of notification and the value of the dwData parameter. The wID parameter may be one of the following values in Windows versions 3.0 and later:
Value | Meaning |
NFY_DELMODULE | The low-order word of dwData is the handle of the module to be freed. |
NFY_EXITTASK | The low-order byte of dwData contains the program exit code. |
NFY_FREESEG | The low-order word of dwData is the selector of the segment to be freed. |
NFY_INCHAR | The dwData parameter is not used. The notification callback function should return either the ASCII value for the keystroke or NULL. |
NFY_LOADSEG | The dwData parameter points to an NFYLOADSEG structure. |
NFY_OUTSTR | The dwData parameter points to the string to be displayed. |
NFY_RIP | The dwData parameter points to an NFYRIP structure. |
NFY_STARTDLL | The dwData parameter points to an NFYSTARTDLL structure. |
NFY_STARTTASK | The dwData parameter is the CS:IP of the starting address of the task. |
NFY_UNKNOWN | The kernel returned an unknown notification. |
In Windows version 3.1, wID may be one of the following values:
Value | Meaning |
NFY_LOGERROR | The dwData parameter points to an NFYLOGERROR structure. |
NFY_LOGPARAMERROR | The dwData parameter points to an NFYLOGPARAMERROR structure. |
NFY_TASKIN | The dwData parameter is undefined. The callback function should call the GetCurrentTask function. |
NFY_TASKOUT | The dwData parameter is undefined. The callback function should call GetCurrentTask. |
dwData
Specifies data, or specifies a pointer to data, or is undefined, depending on the value of wID.
The return value of the callback function is nonzero if the callback function handled the notification. Otherwise, it is zero and the notification is passed to other callback functions.
A notification callback function must be able to ignore any unknown notification value. Typically, the notification callback function cannot use any Windows function, with the exception of the Tool Helper functions and PostMessage.
NotifyRegisterCallback is a placeholder for the application-defined function name. The actual name must be exported by including it in an EXPORTS statement in the application's module-definition file.
InterruptRegister, InterruptUnRegister, MakeProcInstance, NotifyUnRegister, TerminateApp