Notification Function 0001h Query Suspend

mov bx, SessionID ;current session identifier

les di, Service ;es:di is address of service-function handler

mov ax, 0001h ;Query Suspend

call [Notification] ;client program's notification-function handler

mov [Result], ax ;0 = session switch okay, 1 = do not switch

Query Suspend (Notification Function 0001h) notifies client programs that the task switcher is preparing to perform a session switch. A task switcher calls this function when a session switch has been requested. The client program can prevent the session switch, or it can perform any operation needed to allow the switch before returning.

Parameters

SessionID

Identifies the session to be suspended.

Service

Points to the service-function handler for the task switcher. A client program can use this address to call the task switcher's service functions, such as Test Memory Region (Service Function 0001h).

Return Value

The AX register contains 0000h if a session switch can be performed safely or 0001h if it cannot.

All other values are reserved.

Comments

A client program in global memory can tell from the current session identifier which session will be suspended when the switch occurs. It also can use this identifier to maintain information about the session when the session is suspended, and to restore the information when the session is resumed. The session identifier is an arbitrary value provided by the task switcher; values are not necessarily sequential and may be reused after a session is destroyed.

A client program can call Test Memory Region (Service Function 0001h) to determine whether specific code or data in memory will be affected by the session switch, and whether the switch should be allowed. For example, a network redirector can run through a chain of outstanding request descriptors and, using Test Memory Region, determine whether any of the buffers or callback addresses are located in local memory. If any are in local memory, the redirector can prevent the session switch or invoke special code to handle the case.

Before preventing a session switch because of the state of an asynchronous API, a client program should call Query API Support (Service Function 0006h) to make sure the API is not being handled by another client program.

If any client program returns a nonzero value from a call to Query Suspend, all client programs may receive a call to Session Active (Notification Function 0004h), including the client program that returned nonzero. Client programs can ignore a call to Session Active without a preceding call to Query Suspend or Suspend Session (Notification Function 0002h).

The task switcher enables interrupts before calling the client program. The client program can call any MS-DOS system function. Although the client program modifies the AX register, it must preserve all other registers.