Service Function 0004h Hook Notification Chain

les di, CBInfo ;es:di points to SWCALLBACKINFO structure

mov ax, 0004h ;Hook Notification Chain

call [Service] ;service-function handler

jc error_handler ;carry set on error

Hook Notification Chain (Service Function 0004h) directs the task switcher to add the specified SWCALLBACKINFO structure to its notification chain. Client programs that must be notified of session changes call this function during initialization.

Parameter

CBInfo

Points to the client program's SWCALLBACKINFO structure. The client program does not need to fill in the scbiNext field of this structure. The SWCALLBACKINFO structure has the following form:

SWCALLBACKINFO STRUC

scbiNext dd ? ;address of next structure in chain

scbiEntryPoint dd ? ;address of notification-function handler

scbiReserved dd ? ;reserved

scbiAPI dd ? ;address of list of SWAPIINFO structures

SWCALLBACKINFO ENDS

For a full description of the SWCALLBACKINFO and SWAPIINFO structures, see Section 7.11, “Structures.”

Return Value

If Hook Notification Chain is successful, the carry flag is clear and the AX register contains 0000h. If the task switcher does not support this function, the carry flag is set.

Comments

Client programs can check for a task switcher by using Detect Switcher (Interrupt 2Fh Function 4B02h). If a task switcher is present, the client programs add themselves to its notification chain by calling Hook Notification Chain. A client program must fill the SWCALLBACKINFO structure before calling the task switcher.

Some task switchers call Build Notification Chain (Interrupt 2Fh Function 4B01h) to create a notification chain before each session switch. These task switchers can simply return from Hook Notification Chain with no other action.

Most task switchers, however, generate the notification chain only during initialization, and client programs that start later must add themselves to it. For example, a task switcher may keep a separate notification chain for each session and supply each new session it creates with a copy of its original notification chain. A client program that runs within that new session must add its notification-function handler address to the local chain by calling Hook Notification Chain.

Before terminating, a client program must unhook itself from the task switcher's notification chain by calling Unhook Notification Chain (Function 0005h).

A task switcher processing Hook Notification Chain can enable interrupts and call any MS-DOS system function. Although the task switcher modifies the AX register, it must preserve all other registers.