RmShutdown function (restartmanager.h)
Initiates the shutdown of applications. This function can only be called from the installer that started the Restart Manager session using the RmStartSession function.
Syntax
DWORD RmShutdown(
[in] DWORD dwSessionHandle,
[in] ULONG lActionFlags,
[in, optional] RM_WRITE_STATUS_CALLBACK fnStatus
);
Parameters
[in] dwSessionHandle
A handle to an existing Restart Manager session.
[in] lActionFlags
One or more RM_SHUTDOWN_TYPE options that configure the shut down of components. The following values can be combined by an OR operator to specify that unresponsive applications and services are to be forced to shut down if, and only if, all applications have been registered for restart.
| Value | Meaning |
|---|---|
|
Force unresponsive applications and services to shut down after the timeout period. An application that does not respond to a shutdown request is forced to shut down within 30 seconds. A service that does not respond to a shutdown request is forced to shut down after 20 seconds. |
|
Shut down applications if and only if all the applications have been registered for restart using the RegisterApplicationRestart function. If any processes or services cannot be restarted, then no processes or services are shut down. |
[in, optional] fnStatus
A pointer to an RM_WRITE_STATUS_CALLBACK function that is used to communicate detailed status while this function is executing. If NULL, no status is provided.
Return value
This is the most recent error received. The function can return one of the system error codes that are defined in Winerror.h.
| Value | Meaning |
|---|---|
|
All shutdown, restart, and callback operations were successfully completed. |
|
No shutdown actions were performed. One or more processes or services require a restart of the system to be shut down. This error code is returned when the Restart Manager detects that a restart of the system is required before shutting down any application. |
|
Some applications could not be shut down. The AppStatus of the RM_PROCESS_INFO structures returned by the RmGetList function contain updated status information. |
|
This error value is returned by the RmShutdown function when the request to cancel an operation is successful. |
|
A Restart Manager function could not obtain a Registry write mutex in the allotted time. A system restart is recommended because further use of the Restart Manager is likely to fail. |
|
One or more arguments are not correct. This error value is returned by the Restart Manager function if a NULL pointer or 0 is passed in a parameter that requires a non-null and non-zero value. |
|
An operation was unable to read or write to the registry. |
|
A Restart Manager operation could not be completed because not enough memory is available. |
|
No Restart Manager session exists for the handle supplied. |
Remarks
The RmShutdown function calls RmGetList and updates the list of processes currently using registered resources before attempting to shut down any processes. The RmShutdown function then attempts to shut down the processes using registered resources in the most current list. The RmShutdown function updates the AppStatus member of the RM_PROCESS_INFO structures that are returned by the RmGetList function with detailed status information.
The Restart Manager respects the privileges that separate different user or terminal sessions. An installer that is running as a service with LocalSystem privileges cannot shut down or restart any applications in another user or terminal session. Installers should implement custom methods to shut down and restart applications that are running in other sessions. One method would be to start a new installer process in the other session to perform shutdown and restart operations.
Installers should always restart application and services using the RmRestart function even when the RmShutdown function returns an error indicating that not all applications and services could be shut down.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows Vista [desktop apps only] |
| Minimum supported server | Windows Server 2008 [desktop apps only] |
| Target Platform | Windows |
| Header | restartmanager.h |
| Library | Rstrtmgr.lib |
| DLL | Rstrtmgr.dll |