NotifyRegister

3.1

  #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.

Parameters

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.

Return Value

The return value is nonzero if the function was successful. Otherwise, it is zero.

Callback Function

The syntax of the function pointed to by lpfnCallback is as follows:

BOOL NotifyRegisterCallback(wID, dwData)
WORD wID;
DWORD dwData;

Parameters

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.

Return Value

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.

Comments

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.

See Also

InterruptRegister, InterruptUnRegister, MakeProcInstance, NotifyUnRegister, TerminateApp