RmShutdown function (restartmanager.h)

Article
10/13/2021

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
RmForceShutdown 0x1	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.
RmShutdownOnlyRegistered 0x10	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
ERROR_SUCCESS 0	All shutdown, restart, and callback operations were successfully completed.
ERROR_FAIL_NOACTION_REBOOT 350	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.
ERROR_FAIL_SHUTDOWN 351	Some applications could not be shut down. The AppStatus of the RM_PROCESS_INFO structures returned by the RmGetList function contain updated status information.
ERROR_CANCELLED 1223	This error value is returned by the RmShutdown function when the request to cancel an operation is successful.
ERROR_SEM_TIMEOUT 121	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.
ERROR_BAD_ARGUMENTS 160	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.
ERROR_WRITE_FAULT 29	An operation was unable to read or write to the registry.
ERROR_OUTOFMEMORY 14	A Restart Manager operation could not be completed because not enough memory is available.
ERROR_INVALID_HANDLE 6	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