Usando o Gerenciador de Reinicialização com um Instalador Secundário
O procedimento a seguir descreve o uso do Gerenciador de Reinicialização com instaladores primários e secundários.
Ao usar instaladores primários e secundários, o instalador primário controla a interface do usuário.
Para usar o Gerenciador de Reinicialização com instaladores primários e secundários
O instalador primário chama a função RmStartSession para iniciar a sessão do Gerenciador de Reinicialização e obter um identificador de sessão e uma chave.
O instalador primário inicia ou entra em contato com o instalador secundário e fornece a chave de sessão obtida na etapa anterior.
O instalador secundário chama a função RmJoinSession com a chave de sessão para ingressar na sessão do Gerenciador de Reinicialização. Um instalador secundário pode ingressar em uma sessão iniciada pelo instalador primário somente quando ambos os instaladores forem executados no mesmo contexto de usuário.
Os instaladores primários e secundários chamam a função RmRegisterResources para registrar recursos. O Gerenciador de Reinicialização só pode usar recursos registrados para determinar quais aplicativos e serviços devem ser desligados e reiniciados. Todos os recursos que podem ser afetados pela instalação devem ser registrados na sessão. Os recursos podem ser identificados por nome de arquivo, nome curto do serviço ou uma estrutura de RM_UNIQUE_PROCESS .
O instalador primário chama a função RmGetList para obter uma matriz de estruturas de RM_PROCESS_INFO que lista todos os aplicativos e serviços que devem ser desligados e reiniciados.
Se o valor do parâmetro lpdwRebootReason retornado pela função RmGetList não for zero, o Gerenciador de Reinicialização não poderá liberar um recurso registrado pelo desligamento de um aplicativo ou serviço. Nesse caso, um desligamento e uma reinicialização do sistema são necessários para continuar a instalação. O instalador primário deve solicitar ao usuário uma ação, interromper programas ou serviços ou agendar um desligamento e reinicialização do sistema.
Se o valor do parâmetro lpdwRebootReason retornado pela função RmGetList for zero, o instalador deverá chamar a função RmShutdown . Isso desliga os serviços e aplicativos que estão usando recursos registrados. Em seguida, os instaladores primários e secundários devem executar modificações do sistema necessárias para concluir a instalação. Por fim, o instalador primário deve chamar a função RmRestart para que o Gerenciador de Reinicialização possa reiniciar os aplicativos que ele desligou e que foram registrados para uma reinicialização.
O instalador primário e secundário chama a função RmEndSession para fechar a sessão do Gerenciador de Reinicialização.
O snippet de código a seguir mostra um exemplo de um instalador primário iniciando e usando uma sessão do Gerenciador de Reinicialização. O exemplo requer o Windows 7 ou o Windows Server 2008 R2. No Windows Vista ou no Windows Server 2008, o aplicativo Calculadora é desligado, mas não é reiniciado. Este exemplo mostra como um instalador primário pode usar o Gerenciador de Reinicialização para desligar e reiniciar um processo. O exemplo pressupõe que a Calculadora já esteja em execução antes de iniciar a sessão do Gerenciador de Reinicialização.
#include <windows.h>
#include <restartmanager.h>
#pragma comment(lib, "rstrtmgr.lib")
int _cdecl wmain()
{
DWORD dwErrCode = ERROR_SUCCESS;
DWORD dwSessionHandle = 0xFFFFFFFF; // Invalid handle value
//
// CCH_RM_SESSION_KEY: Character count of the
// Text-Encoded session key,defined in RestartManager.h
//
WCHAR sessKey[CCH_RM_SESSION_KEY+1];
// Number of calc files to be registered.
DWORD dwFiles = 2;
//
// NOTE:We register two calc executable files.
// The second one is for the redirection of 32 bit calc on
// 64 bit machines. Even if you are using a 32 bit machine,
// you don't need to comment out the second line.
//
LPCWSTR rgsFiles[] =
{L"C:\\Windows\\System32\\calc.exe",
L"C:\\Windows\\SysWow64\\calc.exe"};
UINT nRetry = 0;
UINT nAffectedApps = 0;
UINT nProcInfoNeeded = 0;
RM_REBOOT_REASON dwRebootReasons = RmRebootReasonNone;
RM_PROCESS_INFO *rgAffectedApps = NULL;
//
// Start a Restart Manager Session
//
dwErrCode = RmStartSession(&dwSessionHandle, 0, sessKey);
if (ERROR_SUCCESS != dwErrCode)
{
goto RM_CLEANUP;
}
//
// Register items with Restart Manager
//
// NOTE: we only register two calc executable files
// in this sample. You can register files, processes
// (in the form of process ID), and services (in the
// form of service short names) with Restart Manager.
//
dwErrCode = RmRegisterResources(dwSessionHandle,
dwFiles,
rgsFiles, // Files
0,
NULL, // Processes
0,
NULL); // Services
if (ERROR_SUCCESS != dwErrCode)
{
goto RM_CLEANUP;
}
//
// Obtain the list of affected applications/services.
//
// NOTE: Restart Manager returns the results into the
// buffer allocated by the caller. The first call to
// RmGetList() will return the size of the buffer
// (i.e. nProcInfoNeeded) the caller needs to allocate.
// The caller then needs to allocate the buffer
// (i.e. rgAffectedApps) and make another RmGetList()
// call to ask Restart Manager to write the results
// into the buffer. However, since Restart Manager
// refreshes the list every time RmGetList()is called,
// it is possible that the size returned by the first
// RmGetList()call is not sufficient to hold the results
// discovered by the second RmGetList() call. Therefore,
// it is recommended that the caller follows the
// following practice to handle this race condition:
//
// Use a loop to call RmGetList() in case the buffer
// allocated according to the size returned in previous
// call is not enough.
//
// In this example, we use a do-while loop trying to make
// 3 RmGetList() calls (including the first attempt to get
// buffer size) and if we still cannot succeed, we give up.
//
do
{
dwErrCode = RmGetList(dwSessionHandle,
&nProcInfoNeeded,
&nAffectedApps,
rgAffectedApps,
(LPDWORD) &dwRebootReasons);
if (ERROR_SUCCESS == dwErrCode)
{
//
// RmGetList() succeeded
//
break;
}
if (ERROR_MORE_DATA != dwErrCode)
{
//
// RmGetList() failed, with errors
// other than ERROR_MORE_DATA
//
goto RM_CLEANUP;
}
//
// RmGetList() is asking for more data
//
nAffectedApps = nProcInfoNeeded;
if (NULL != rgAffectedApps)
{
delete []rgAffectedApps;
rgAffectedApps = NULL;
}
rgAffectedApps = new RM_PROCESS_INFO[nAffectedApps];
} while ((ERROR_MORE_DATA == dwErrCode) && (nRetry ++ < 3));
if (ERROR_SUCCESS != dwErrCode)
{
goto RM_CLEANUP;
}
if (RmRebootReasonNone != dwRebootReasons)
{
//
// Restart Manager cannot mitigate a reboot.
// We goes to the clean up. The caller may want
// to add additional code to handle this scenario.
//
goto RM_CLEANUP;
}
//
// Now rgAffectedApps contains the affected applications
// and services. The number of applications and services
// returned is nAffectedApps. The result of RmGetList can
// be interpreted by the user to determine subsequent
// action (e.g. ask user's permission to shutdown).
//
// CALLER CODE GOES HERE...
//
// Shut down all running instances of affected
// applications and services.
//
dwErrCode = RmShutdown(dwSessionHandle, 0, NULL);
if (ERROR_SUCCESS != dwErrCode)
{
goto RM_CLEANUP;
}
//
// An installer can now replace or update
// the calc executable file.
//
// CALLER CODE GOES HERE...
//
// Restart applications and services, after the
// files have been replaced or updated.
//
dwErrCode = RmRestart(dwSessionHandle, 0, NULL);
if (ERROR_SUCCESS != dwErrCode)
{
goto RM_CLEANUP;
}
RM_CLEANUP:
if (NULL != rgAffectedApps)
{
delete [] rgAffectedApps;
rgAffectedApps = NULL;
}
if (0xFFFFFFFF != dwSessionHandle)
{
//
// Clean up the Restart Manager session.
//
RmEndSession(dwSessionHandle);
dwSessionHandle = 0xFFFFFFFF;
}
return 0;
}
O snippet de código a seguir mostra um exemplo de junção de um instalador secundário à sessão existente do Restart Manager. O exemplo requer o Windows Vista ou o Windows Server 2008. O instalador secundário obtém a chave de sessão do instalador primário e usa isso para ingressar na sessão.
#include <windows.h>
#include <restartmanager.h>
#pragma comment(lib, "rstrtmgr.lib")
int _cdecl wmain()
{
DWORD dwErrCode = ERROR_SUCCESS;
DWORD dwSessionHandle = 0xFFFFFFFF; // Invalid handle value
//
// CCH_RM_SESSION_KEY: Character count of the
// Text-Encoded session key, defined in RestartManager.h
//
WCHAR sessKey[CCH_RM_SESSION_KEY+1];
// Number of files to be registered.
DWORD dwFiles = 1;
//
// We register oleaut32.dll with Restart Manager.
//
LPCWSTR rgsFiles[] =
{L"C:\\Windows\\System32\\oleaut32.dll"};
//
// Secondary installer needs to obtain the session key from
// the primary installer and uses it to join the session.
//
// CALLER CODE GOES HERE ...
//
// We assume the session key obtained is stored in sessKey
dwErrCode = RmJoinSession(&dwSessionHandle, sessKey);
if (ERROR_SUCCESS != dwErrCode)
{
goto RM_CLEANUP;
}
//
// Register items with Restart Manager
//
// NOTE: In Vista, the subordinate is only allowed to
// register resources and cannot perform any other
// getlist, shutdown, restart or filter operations.
//
dwErrCode = RmRegisterResources(dwSessionHandle,
dwFiles,
rgsFiles, // Files
0,
NULL, // Processes
0,
NULL); // Services
if (ERROR_SUCCESS != dwErrCode)
{
goto RM_CLEANUP;
}
RM_CLEANUP:
if (0xFFFFFFFF != dwSessionHandle)
{
//
// The subordinate leaves the conductor's session
// by calling RmEndSession(). The session itself
// won't be destroyed until the primary installer
// calls RmEndSession()
//
RmEndSession(dwSessionHandle);
dwSessionHandle = 0xFFFFFFFF;
}
return 0;
}