When you need your VB app to force a Windows computer to shut down, restart, or log off, you can use the ExitWindowsEx API. Let's look at what each action entails. Then, we'll consider an example that shows how you can use the API to accomplish these tasks.
A look at the API
The API can perform these actions:
- · System shutdown brings a system to a condition in which it is safe to turn off the computer. The system files are flushed to the disk, and a message box is displayed stating that it's safe to turn off the computer.
- · System restart does what system shutdown does, except that after the system is shut down, it's automatically restarted instead of showing a message box.
- · Log off logs the user off the system after all of the processes associated with the security context of the process that called the ExitWindowsEx function are stopped. It then displays a logon dialog box.
The ExitWindowsEx function works with Windows 9x/Me, NT/2000, and XP. It accepts two arguments: the type of the operation to be performed and a parameter that only Windows XP uses. Table A lists the values for these arguments.
|Possible parameter values|
Under Windows XP, the dwReserved parameter specifies the reason for the shutdown. Under earlier Windows versions, the parameter is ignored.
Using the EWX_FORCE flag may cause data loss because Windows will not send the messages WM_QUERYENDSESSION and WM_ENDSESSION to applications currently running on the computer. You should use this flag only when the loss of data won't be an issue.
The VB declaration of ExitWindowsEx looks like this:
Declare Function ExitWindowsEx& Lib "user32" (ByVal uFlags As Long, ByVal _
dwReserved As Long)
ExitWindowsEx returns a nonzero value if it's successful and a zero value if an error occurs. The function also sends WM_QUERYENDSESSION and WM_ENDSESSION messages to all applications currently running in order to establish whether they can be terminated.
When a call is made to either shut down or restart the system, all of the running applications have a certain amount of time to close. If, after that time has passed, some applications are still open, the system will display a dialog box asking a user to end the application forcibly, to restart the shutdown process, or to cancel it altogether. However, using the EWX_FORCE flag will force all applications to close without displaying the dialog box. In general, it's better not to use the EWX_FORCE flag, because you want to allow your users to save the work they may be performing before the shutdown takes place.
Note: To run ExitWindowsEx under Windows NT/2000 or Windows XP, the calling process must have the SE_SHUTDOWN_NAME privilege. Therefore, you may need to call the AdjustTokenPrivileges function to enable SE_SHUTDOWN_NAME. See this Microsoft article for more information.
When the ExitWindowsEx function runs, the results return immediately and the shutdown proceeds in the background. When you use the function in your application, be sure to terminate your own application to help the shutdown proceed smoothly.
To see how to put ExitWindowsEx to work, let's create a simple VB project that will shut down the computer:
- 1. Fire up VB and start a new project.
- 2. Add a module and place the following code in it:
Public Const EWX_LOGOFF = 0
Public Const EWX_SHUTDOWN = 1
Public Const EWX_REBOOT = 2
Public Const EWX_FORCE = 4
Public Declare Function ExitWindowsEx Lib "user32" _
(ByVal uFlags As Long, ByVal dwReserved As Long) As Long
- 3. Add a label to your form and set a Caption property to Please Select One of the Following Actions.
- 4. Add three option buttons to your form, optShutDown, optRestart, optLogoff, and set their caption properties to be Shut Down, Restart, and Logoff, respectively.
- 5. Add a command button to your form and call it cmdExecute.
Your screen should now resemble the one in Figure A.
|Form for computer shutdown|
- 6. Now, add the code in Listing A to the cmdExecute_Click() event.
- 7. Press [Ctrl][F5] to run the project, and you should see a screen that resembles the one in Figure B.
|Dialog box from our sample program|
- 8. Select one of the options and then click Execute.
- 9. When you're asked to confirm the selected action, click OK. Figure C shows the prompt you will see if you select Shut Down and click Execute.
|Result of selecting Shut Down and clicking Execute|
In this sample, we demonstrated how to use the ExitWindowsEx API to log off, shut down, or restart the system. Next time, we will look at some other API functions that you will find useful in your application development.
What APIs do you use?
What API do you find yourself using on a regular basis? Which ones can no programmer do without? Send us an e-mail with your experiences and suggestions or post a comment below.