Condividi tramite

Restart Manager Development

  • Articolo

Restart Manager Development

Introduction

Restart Manager in Windows Vista® enables all but the most critical applications and services to be stopped and restarted at any time during application installation and updates. System shut down and restart is required to release files that are being used by a running application or service.

Developers should use Restart Manager when they need to reconfigure the system, to start or stop services, to query for locked data or executable files, or for files that might otherwise affect system stability. Restart Manager guarantees that after a service is stopped, its constituent DLLs and resources are unloaded.

The restart manager provides a well-defined mechanism for determining if a resource (file) is currently locked. If the resource is locked, the resource manager determines which applications are locking it. If necessary, applications can be programmed to use the Restart Manager to stop and restart non-critical services or applications currently locking files.

Depending on the type of application being managed, users can be prompted to save and close information, applications can be restarted transparently, or users can be prompted to schedule a system restart if a restart is unavoidable. For more information, see the "Critical System Services" section in the Windows Software Development Kit (SDK).

Installer Support

Windows Vista automatically takes advantage of the new installer technology. Developers who use Windows Vista–enabled tools, such as Macrovision InstallShield to construct the Microsoft® Windows® Installer transparently make use of the Restart Manager. The ClickOnce installer, a Web-based deployment technology, should not require a system restart as part of installation.

Restart Manager Session Overview

A Restart Manager session is a set of coordinated Restart Manager functions that implement a set of system or application modifications, updates, or reconfigurations. These functions are known as an Update Set.

All Restart Manager sessions are created and controlled by one component or process known as Conductor, which supports the Restart Manager session's user interface (if any) and sequences all the operations in the Update Set. Both Windows Update and Windows Installer use restart management transparently, and either can be used as the Conductor. For example, with Windows Installer (which uses Restart management transparently), the user interface is controlled by Windows Installer, and therefore it is the Conductor.

It may be reasonable to separate the user interface process from the actual process of system modification. Also, for complicated Restart Manager sessions, it may be useful to delegate various tasks to additional components or processes. Such a constituent component of a Restart Manager is referred to as a Subordinate. These components and processes can run from the Conductor process in-proc or out-of-proc.

Because Restart Manager session operations can be time consuming, it is recommended that any operation that takes more than a few seconds use the Win32® (the unmanaged programming model for the Windows operating system) Windows Vista cancellation API in conjunction with a "stop button" (or equivalent) to give users more control.

Execution Model

The execution model of Restart Manager is as follows:

  • A Conductor starts the Restart Manager session by calling RmStartSession function.

  • If Subordinate processes are needed, they must be contacted (if present) or started (if not present) by the Conductor. Subordinate processes join the Restart Manager session using RmJoinSession function.

  • The Conductor and any Subordinates register objects to be part of the Update Set using RmRegisterResources function. The objects registered can be: Files with full path names, Services, or Processes.

  • The Conductor then queries for Update Set dependencies, using RmGetList, and gets back an array of RM_PROCESS_INFO structures, one for each registered application.

    If the Restart Manager determines that it cannot release the registered resources by shutting down an object, the function sets a flag indicating that a computer restart is needed to complete the system modification.

    The Conductor can interrogate the returned array of RM_PROCESS_INFO structures, determine why a restart is required, and decide how to handle the situation. It can choose to restart applications or services itself, or schedule a restart by using standard Windows reboot scheduling functionality.

  • The Conductor stops those processes and applications locking resources by using RmShutdown.

  • System modification can be executed either at once, or be scheduled to be performed during a restart.

  • The Conductor restarts all the applications it can, using RmRestart.

  • Conductors and Subordinates call RmEndSession to leave a Restart Manager session.

A Conductor provides control and a user interface, as well as handling the two Subordinate processes that do the actual installing.

Affected Processes Handling

It is critical to properly handle those processes affected by a planned system resource modification. The basic steps are:

  1. Obtain information about the affected applications.

  2. Prepare for application shutdown.

  3. Issue a Shut Down command.

  4. Restart the applications.

Creating an Affected Application List

A Conductor uses RmGetList to obtain information about applications affected by changes in registered resources. Therefore, it is critical that all applications that will use Restart Manager register all affected resources through calls to RmRegisterResources. To compile a list of all affected applications, RmGetList uses the following algorithm:

  • Processes detected as holding files registered as resources are added to the list of affected applications. This detection identifies only files actively in use, and does not apply to driver files, such as win32k.sys.

  • Applications explicitly registered by calls to RmRegisterResources are added to the list of affected applications.

  • All the services supporting the process already detected are added to the list of affected applications.

  • All services explicitly registered by calls to RmRegisterResources are added to the list of affected applications.

  • All services dependent on services already enumerated are added to the list of affected applications.

It is very important to properly register all files, applications, and servers that might be affected by an operation.

Restart Manager returns the process identification number (PID), time of process creation, friendly name, version, and vendor of each application identified as affected. In addition to being identified, each application is classified according to the RM_APP_TYPE enumeration.

The following lists the RM_APP_TYPE enumeration.

RmUnknownApp

Application type cannot be classified.

RmMainWindow

A Windows application displaying a top-level window.

RmOtherWindow

A Windows application that does not display a top-level window.

RmService

The application is a Windows Service.

RmExplorer

The application is the Explorer.

RmCritical

Application is a critical system process. A system reboot will be required to restart the application.

If any application in the list of affected applications is critical, the RmGetList function sets a flag indicating that a reboot will be required.

Preparing for Application Shutdown

With the list of affected applications, a Conductor can prepare for applications shutdown. By examining the bRestartable member of an application's RM_PROCESS_INFO, the Conductor can determine if an application is restartable.

Users should be prompted to get their permission to shutdown applications using the new MsiRmFilesinUse dialog (Link to the MSI SDK) this is incorrect. RM does this internally, not the conductor.

Issuing a Shutdown Command

A call by a Conductor to RmShutdown is designed to gracefully terminate every running application registered with a Restart Manager session or detected to be holding registered resources in use.

When issuing a shutdown command, a Conductor needs to specify the shutdown type, defined by the RM_SHUTDOWN_TYPE enumeration:

RmForceShutdown

The restart manager will attempt to forcibly shut down all processes and services as determined by RmGetList.

RmShudownOnlyRegistered

The restart manager will attempt to shut down all currently running processes and services as determined by RmGetList, if—and only if—all running processes on the list have registered themselves as restartable.

If any running process or service on the list of registered applications has not registered as restartable, no processes will be stopped.

RmShutdown will return an error if either of the following conditions exists:

  • One or more registered applications are a critical service and can only be shut down by restarting.

  • The shutdown type is RmShudownOnlyRegistered, and one or more of the registered applications running is not registered for restart.

Note

If one or more of the registered applications currently running cannot be shut down by RmShudownOnlyRegistered, none of the registered applications currently running will be stopped.

Closing All Graphical User Interface Applications

Graphical User Interface (GUI) applications are defined as those supported by a WindowProc message pump (except for Windows Explorer). To close all GUI applications, the Restart Manager:

  • Query registered GUI applications to verify that they support graceful shutdown by sending a WM_QUERYENDSESSION message with an LPARAM value of ENDSESSION_CLOSEAPP and wparam with value of True.

  • If a registered GUI application's WindowProc returns TRUE,the Restart Manager:

    • Sends the application a WM_ENDSESSION message with an LPARAM value of ENDSESSION_CLOSEAPP.

    • Sends the application a WM_CLOSE signal. This message is sent to applications that do not follow the shutdown protocol.

  • If any of the registered GUI application's WindowProc returns FALSE, then:

    • If RM_SHUTDOWN_TYPE is not set to RmForceShutdown, the shutdown is canceled.

    • If RM_SHUTDOWN_TYPE is set to RmForceShutdown, Restart Manager attempts to gracefully shutdown the application by sending a WM_ENDSESSION and a WM_CLOSE message as mentioned above. If a graceful shutdown fails, Restart Manager will forcefully terminate the process.

If RM_SHUTDOWN_TYPE is set to RmShudownOnlyRegistered, then the application will be shut down if and only if it has been registered for restart using the RegisterApplicationRestart function.

Note

Each Windows message has a time-out of 5 seconds. If no response is received and if RM_SHUTDOWN_TYPE is not set to RmForceShutdown, the shutdown aborts.

All Windows Vista compatible applications and all Logo candidates must listen and properly handle WM_QUERYENDSESSION, WM_ENDSESSION, and WM_CLOSE events.

Closing console applications

Console applications registered with Restart Manager and currently running are closed by sending signals to the application's console control handler.

A CTRL_C_EVENT event is sent to the application. If a given console application does not shut down within 10 seconds, and:

  • If RM_SHUTDOWN_TYPE is not set to RmForceShutdown, the shutdown is canceled.

  • If RM_SHUTDOWN_TYPE is set to RmForceShutdown, the Restart Manager calls the EndTask function to terminate the application.

Closing services

Services registered with Restart Manager and currently running, and any dependent services, are shut down through Service Control Manager. If a given service or one of its dependent services does not shut down within 10 seconds, and:

  • If RM_SHUTDOWN_TYPE is not set to RmForceShutdown, the shutdown is canceled.

  • If RM_SHUTDOWN_TYPE is set to RmForceShutdown, the Restart Manager uses the Service Control Manager to forcefully terminate the service.

Closing Explorer

If necessary, the Restart Manager closes any instance of Windows Explorer that is registered with it. The Restart Manager sends a WM_QUERYENDSESSION message with an LPARAM value of ENDSESSION_CLOSEAPP. If the Explorer instance does not shut down gracefully within 10 seconds, and:

  • If RM_SHUTDOWN_TYPE is not set to RmForceShutdown, the shutdown is canceled.

  • If RM_SHUTDOWN_TYPE is set to RmForceShutdown, the Restart Manager forcefully terminates the instance.

Restarting Applications

Restart Manager stores a list of all services and applications that it shut down. This information can be retrieved by calling RmGetList.

Writing Restart Manager Compatible Applications

The keys to writing an application compatible with the restart manager are simple, leveraging off Windows Feedback and the handling of WindowProc messages.

In Depth: Critical System Services

Only a limited number of system services cannot be stopped and restarted by a Restart Manager session. Any file or resource owned by one of these services will require a reboot to complete modification, using known technologies such as the reboot properties and method in Windows Installer, the Window Update Agent, and Windows Management Instrumentation SDK.

The Windows Vista critical system services are:

  • Client/Server Runtime Server Subsystem (csrss.exe)

  • Local Security Authority Service (lsass.exe)

  • Windows logon process (Winlogon.exe)

  • Logon User Interface (logonui.exe)

  • SVChost.exe with RPCSS

  • SVChost.exe with Dcom

  • Svchost.exe with PnP

  • Session Manager Subsystem (smss.exe)

  • Windows Service Controller (services.exe)

  • Windows Startup/Shutdown Service (wininit.exe, new in Windows Vista)

Whether a process is part of a critical system service or not can be determined by examining the ApplicationType member of the process's RM_PROCESS_INFO structure returned by RmGetList.

Synchronization and Sequencing of API Calls

Each Restart Manager session has a mutex created by the Restart Manager to maintain synchronization of Conductors and Subordinates, and in particular, their Registry accesses. There is a single, global mutex for the creation and deletion of Restart Manager sessions.

To support synchronization:

  • All Restart Manager function calls return an error if the caller has neither created nor joined a session.

  • Most functions will block if a different function is executing and return an error if the operation cannot begin within five seconds. This prevents having one component register resources while another call queries for affected applications before the registration is complete. The exceptions are:

    • The status callback function RM_WRITE_STATUS_CAllBACK.

    • RMGetList can be called anytime except while a registration is still completing.

    • Most functions can be called multiple times during a session. However, the call ordering of the functions is important. Depending on the state of the Restart Manager, an otherwise repeatable call may be prevented from being made. This situation can be deduced from the function's return values. The exceptions are functions used to start, end, or join a Restart Manager session: RmStartSession, RmJoinSesssion, and RmEndSession.

Resources

Windows Vista provides Win32 access to Restart Manager through a set of set of C++ objects and methods wrapped in C–callable APIs. Applications developed in the .NET Framework 3.0 programming model can access this functionality through interoperability support in the Windows SDK. For more information, see the Interoperability & Migration in the Windows SDK.

The following table lists supporting resources for the ClickOnce technology for .NET Framework 3.0 and Windows Vista.

Libraries

Description

Rstrtmgr.dll

Restart Manager DLL.

kernel32.dll

Library containing application restart functionality.

Headers

Description

Rstrtmgr.h

Header file for Restart Manager.

windows.h

Header file for application restart functionality.

Restart Manager API

Description

RmCancelCurrentTask

Conductors use this function to terminate a Restart Manager session's current task — if that task is cancelable.

RmEndSession

Conductors use this function to close and clean up a Restart Manager session.

RmGetList

Conductors use this function to get the list of all applications that need to be restarted.

RmJoinSession

Subordinate components use this function to join an existing session created by a Conductor.

RmRegisterResources

Component managing resources use this function in an Update Set to register those resources to the Restart Manager.

RmRestart

Conductors use this function to restart applications that were previously shut down.

RmShutdown

Conductors use this function to shut down all affected applications registered in a Restart Manager session.

RmStartSession

Conductors and components controlling install UI use this function to create a Restart Manager.

RM_WRITE_STATUS_CALLBACK

Signature of the callback function used to write data to the Windows Event Log.

Restart Manager data types

Description

RM_APP_TYPE

Indicates the type of application Restart Manager is working with.

RM_SHUTDOWN_TYPE

Defines the type of shutdown operation to be used.

RM_APP_STATUS

Indicates the status of a process Restart Manager is working with.

RM_UNIQUE_PROCESS

Provides a unique process identifier.

RM_PROCESS_INFO

A structure that contains all information about a process that Restart Manager is working with.

Supporting API

Description

RegisterApplicationRestart

Client applications use this function to register how they need to be restarted by the Restart Manager.

GetApplicationRestart

Restart Manager uses this function to determine how to applications.

See Also

Concepts

Installation and Update Management