windows_programming_notes.nbk: Home | Index | Next Page: WM_QUERYNEWPALETTE | Previous Page: WM_QUERYDRAGICON

 WM_QUERYENDSESSION

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_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.
• lParam
If this parameter is zero, the system is shutting down or restarting (it is not possible to determine which event is occurring).

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.

Requirements

• Client
  • Requires Windows Vista, Windows XP, Windows 2000 Professional, Windows NT Workstation, Windows Me, Windows 98, or Windows 95.
• Server
  • Requires Windows Server 2008, Windows Server 2003, Windows 2000 Server, or Windows NT Server.
• Header
  • Declared in WinUser.h; include Windows.h.

windows_programming_notes.nbk: Home | Index | Next Page: WM_QUERYNEWPALETTE | Previous Page: WM_QUERYDRAGICON

Notebook exported on Monday, 7 July 2008, 18:56:50 PM Eastern Daylight Time