Utilisation du Gestionnaire de redémarrage avec un programme d’installation secondaire
La procédure suivante décrit l’utilisation du Gestionnaire de redémarrage avec les programmes d’installation principaux et secondaires.
Lorsque vous utilisez des programmes d’installation principaux et secondaires, le programme d’installation principal contrôle l’interface utilisateur.
Pour utiliser Restart Manager avec les programmes d’installation principaux et secondaires
Le programme d’installation principal appelle la fonction RmStartSession pour démarrer la session Restart Manager et obtenir un handle et une clé de session.
Le programme d’installation principal démarre ou contacte le programme d’installation secondaire et lui fournit la clé de session obtenue à l’étape précédente.
Le programme d’installation secondaire appelle la fonction RmJoinSession avec la clé de session pour rejoindre la session Restart Manager. Un programme d’installation secondaire peut rejoindre une session démarrée par le programme d’installation principal uniquement lorsque les deux programmes d’installation s’exécutent dans le même contexte utilisateur.
Les programmes d’installation principal et secondaire appellent la fonction RmRegisterResources pour inscrire des ressources. Le Gestionnaire de redémarrage ne peut utiliser que des ressources inscrites pour déterminer les applications et services qui doivent être arrêtés et redémarrés. Toutes les ressources qui peuvent être affectées par l’installation doivent être inscrites auprès de la session. Les ressources peuvent être identifiées par nom de fichier, nom court du service ou structure RM_UNIQUE_PROCESS .
Le programme d’installation principal appelle la fonction RmGetList pour obtenir un tableau de structures RM_PROCESS_INFO qui répertorie toutes les applications et services qui doivent être arrêtés et redémarrés.
Si la valeur du paramètre lpdwRebootReason retourné par la fonction RmGetList n’est pas nulle, le Gestionnaire de redémarrage ne peut pas libérer une ressource inscrite par l’arrêt d’une application ou d’un service. Dans ce cas, un arrêt et un redémarrage du système sont nécessaires pour poursuivre l’installation. Le programme d’installation principal doit inviter l’utilisateur à effectuer une action, arrêter des programmes ou des services, ou planifier un arrêt et un redémarrage du système.
Si la valeur du paramètre lpdwRebootReason retourné par la fonction RmGetList est égale à zéro, le programme d’installation doit appeler la fonction RmShutdown . Cela arrête les services et les applications qui utilisent des ressources inscrites. Les programmes d’installation principal et secondaire doivent ensuite effectuer les modifications système requises pour terminer l’installation. Enfin, le programme d’installation principal doit appeler la fonction RmRestart afin que le Gestionnaire de redémarrage puisse redémarrer les applications qu’il a arrêtées et qui ont été inscrites pour un redémarrage.
Le programme d’installation principal et secondaire appelle la fonction RmEndSession pour fermer la session Restart Manager.
L’extrait de code suivant montre un exemple de programme d’installation principal qui démarre et utilise une session Restart Manager. L’exemple nécessite Windows 7 ou Windows Server 2008 R2. Sur Windows Vista ou Windows Server 2008, l’application Calculatrice s’arrête, mais ne redémarre pas. Cet exemple montre comment un programme d’installation principal peut utiliser Restart Manager pour arrêter et redémarrer un processus. L’exemple suppose que la calculatrice est déjà en cours d’exécution avant de démarrer la session du Gestionnaire de redémarrage.
#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;
}
L’extrait de code suivant montre un exemple de jointure d’un programme d’installation secondaire à la session Restart Manager existante. L’exemple nécessite Windows Vista ou Windows Server 2008. Le programme d’installation secondaire obtient la clé de session du programme d’installation principal et l’utilise pour rejoindre la session.
#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;
}