GetApplicationRestartSettings, fonction (winbase.h)

Article
08/27/2023

Récupère les informations de redémarrage inscrites pour le processus spécifié.

Syntaxe

HRESULT GetApplicationRestartSettings(
  [in]            HANDLE hProcess,
  [out, optional] PWSTR  pwzCommandline,
  [in, out]       PDWORD pcchSize,
  [out, optional] PDWORD pdwFlags
);

Paramètres

[in] hProcess

Handle du processus. Ce handle doit avoir le droit d’accès PROCESS_VM_READ.

[out, optional] pwzCommandline

Pointeur vers une mémoire tampon qui reçoit la ligne de commande de redémarrage spécifiée par l’application lorsqu’elle a appelé la fonction RegisterApplicationRestart . La taille maximale de la ligne de commande, en caractères, est RESTART_MAX_CMD_LINE. Peut être NULL si pcchSize est égal à zéro.

[in, out] pcchSize

Lors de l’entrée, spécifie la taille de la mémoire tampon pwzCommandLine , en caractères.

Si la mémoire tampon n’est pas assez grande pour recevoir la ligne de commande, la fonction échoue avec HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER) et définit ce paramètre sur la taille de mémoire tampon requise, en caractères.

Lors de la sortie, spécifie la taille de la mémoire tampon utilisée.

Pour déterminer la taille de mémoire tampon requise, définissez pwzCommandLine sur NULL et ce paramètre sur zéro. La taille en inclut une pour le caractère de fin null. Notez que la fonction retourne S_OK, et non HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER) dans ce cas.

[out, optional] pdwFlags

Pointeur vers une variable qui reçoit les indicateurs spécifiés par l’application quand elle a appelé la fonction RegisterApplicationRestart .

Valeur retournée

Cette fonction retourne S_OK en cas de réussite ou l’un des codes d’erreur suivants.

Code de retour	Description
E_INVALIDARG	Un ou plusieurs paramètres ne sont pas valides.
HRESULT_FROM_WIN32(ERROR_NOT_FOUND)	L’application ne s’est pas inscrite au redémarrage.
HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER)	La mémoire tampon pwzCommandLine est trop petite. La fonction retourne la taille de mémoire tampon requise dans pcchSize. Utilisez la taille requise pour réallouer la mémoire tampon.

Remarques

Ces informations sont disponibles uniquement pour le processus actuel ; vous ne pouvez pas appeler cette fonction après le redémarrage de votre programme pour obtenir la ligne de commande de redémarrage. Pour obtenir la ligne de commande après un redémarrage, accédez au paramètre argv de votre fonction main.

Exemples

L’exemple suivant montre comment obtenir les paramètres de redémarrage spécifiés lorsque vous avez appelé la fonction RegisterApplicationRestart .

#include <windows.h>
#include <stdio.h>


void wmain(int argc, WCHAR* argv[])
{
    HRESULT hr = S_OK;
    WCHAR wsCommandLine[RESTART_MAX_CMD_LINE + 1];
    DWORD cchCmdLine = sizeof(wsCommandLine) / sizeof(WCHAR);
    DWORD dwFlags = 0;
    LPWSTR pwsCmdLine = NULL;
    UNREFERENCED_PARAMETER(argv);
    UNREFERENCED_PARAMETER(argc);

    wprintf(L"Registering for restart...\n");
    hr = RegisterApplicationRestart(L"/restart -f .\\filename.ext", 0);
    if (FAILED(hr))
    {
        wprintf(L"RegisterApplicationRestart failed, 0x%x\n", hr);
        goto cleanup;
    }

    wprintf(L"Get restart command line using static buffer...\n");
    hr = GetApplicationRestartSettings(GetCurrentProcess(), wsCommandLine, &cchCmdLine, &dwFlags);
    if (FAILED(hr))
    {
        wprintf(L"GetApplicationRestartSettings failed, 0x%x\n", hr);
        goto cleanup;
    }

    wprintf(L"Command line: %s\n", wsCommandLine);

    wprintf(L"\nGet settings using dynamic buffer...\n");

    cchCmdLine = 0;

    // Returns S_OK instead of ERROR_INSUFFICIENT_BUFFER when pBuffer is NULL and size is 0.
    hr = GetApplicationRestartSettings(GetCurrentProcess(), (PWSTR)pwsCmdLine, &cchCmdLine, &dwFlags);
    if (SUCCEEDED(hr))
    {
        pwsCmdLine = (LPWSTR)malloc(cchCmdLine * sizeof(WCHAR));

        if (pwsCmdLine)
        {
            hr = GetApplicationRestartSettings(GetCurrentProcess(), (PWSTR)pwsCmdLine, &cchCmdLine, &dwFlags);
            if (FAILED(hr))
            {
                wprintf(L"GetApplicationRestartSettings failed with 0x%x\n", hr);
                goto cleanup;
            }

            wprintf(L"Command line: %s\n", pwsCmdLine);
        }
        else
        {
            wprintf(L"Allocating the command-line buffer failed.\n");
        }
    }
    else
    {
        if (hr != HRESULT_FROM_WIN32(ERROR_NOT_FOUND)) // Not a restart.
        {
            wprintf(L"GetApplicationRestartSettings failed with 0x%x\n", hr);
            goto cleanup;
        }
    }

cleanup:

    if (pwsCmdLine)
        free(pwsCmdLine);
}

Configuration requise


Client minimal pris en charge	Windows Vista [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2008 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	winbase.h (inclure Windows.h)
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll

Voir aussi

RegisterApplicationRestart

Partager via