WM_QUERYENDSESSION message

The WM_QUERYENDSESSION message is sent when the user chooses to end the session or when an application calls one of the system shutdown functions. If any application returns zero, the session is not ended. The system stops sending WM_QUERYENDSESSION messages as soon as one application returns zero.

After processing this message, the system sends the WM_ENDSESSION message with the wParam parameter set to the results of the WM_QUERYENDSESSION message.

A window receives this message through its WindowProc function.

LRESULT CALLBACK WindowProc( 
  HWND hwnd,      // handle to window 
  UINT uMsg,      // message identifier 
  WPARAM wParam,  // not used 
  LPARAM lParam   // logoff option
);

Parameters

hwnd

A handle to the window.

uMsg

The WM_QUERYENDSESSION identifier.

wParam

This parameter is reserved for future use.

lParam

This parameter can be one or more of the following values. If this parameter is 0, the system is shutting down or restarting (it is not possible to determine which event is occurring).

Value Meaning
ENDSESSION_CLOSEAPP
0x00000001
The application is using a file that must be replaced, the system is being serviced, or system resources are exhausted. For more information, see Guidelines for Applications.
ENDSESSION_CRITICAL
0x40000000
The application is forced to shut down.
ENDSESSION_LOGOFF
0x80000000
The user is logging off. For more information, see Logging Off.

 

Note that this parameter is a bit mask. To test for this value, use a bit-wise operation; do not test for equality.

Return value

Applications should respect the user's intentions and return TRUE. By default, the DefWindowProc function returns TRUE for this message.

If shutting down would corrupt the system or media that is being burned, the application can return FALSE. However, it is good practice to respect the user's actions.

Remarks

When an application returns TRUE for this message, it receives the WM_ENDSESSION message, regardless of how the other applications respond to the WM_QUERYENDSESSION message. Each application should return TRUE or FALSE immediately upon receiving this message, and defer any cleanup operations until it receives the WM_ENDSESSION message.

Applications can display a user interface prompting the user for information at shutdown, however it is not recommended. After five seconds, the system displays information about the applications that are preventing shutdown and allows the user to terminate them. For example, Windows XP displays a dialog box, while Windows Vista displays a full screen with additional information about the applications blocking shutdown. If your application must block or postpone system shutdown, use the ShutdownBlockReasonCreate function. For more information, see Shutdown Changes for Windows Vista.

Console applications can use the SetConsoleCtrlHandler function to receive shutdown notification.

Service applications can use the RegisterServiceCtrlHandlerEx function to receive shutdown notifications in a handler routine.

Examples

For an example, see Logging Off.

Requirements

Requirement Value
Minimum supported client
Windows XP [desktop apps | UWP apps]
Minimum supported server
Windows Server 2003 [desktop apps | UWP apps]
Header
WinUser.h (include Windows.h)

See also

Logging Off

Shutting Down

DefWindowProc

ExitWindows

SetProcessShutdownParameters

WM_ENDSESSION