Função GetApplicationRestartSettings (winbase.h)

Recupera as informações de reinicialização registradas para o processo especificado.

Sintaxe

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

Parâmetros

[in] hProcess

Um identificador para o processo. Esse identificador deve ter o direito de acesso PROCESS_VM_READ.

[out, optional] pwzCommandline

Um ponteiro para um buffer que recebe a linha de comando de reinicialização especificada pelo aplicativo quando ele chamou a função RegisterApplicationRestart . O tamanho máximo da linha de comando, em caracteres, é RESTART_MAX_CMD_LINE. Pode ser NULL se pcchSize for zero.

[in, out] pcchSize

Na entrada, especifica o tamanho do buffer pwzCommandLine , em caracteres.

Se o buffer não for grande o suficiente para receber a linha de comando, a função falhará com HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER) e definirá esse parâmetro como o tamanho do buffer necessário, em caracteres.

Na saída, especifica o tamanho do buffer que foi usado.

Para determinar o tamanho do buffer necessário, defina pwzCommandLine como NULL e esse parâmetro como zero. O tamanho inclui um para o caractere de terminador nulo. Observe que a função retorna S_OK, não HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER) nesse caso.

[out, optional] pdwFlags

Um ponteiro para uma variável que recebe os sinalizadores especificados pelo aplicativo quando ele chamou a função RegisterApplicationRestart .

Valor retornado

Essa função retorna S_OK em caso de êxito ou um dos códigos de erro a seguir.

Código de retorno	Descrição
E_INVALIDARG	Um ou mais dos parâmetros não são válidos.
HRESULT_FROM_WIN32(ERROR_NOT_FOUND)	O aplicativo não se registrou para reinicialização.
HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER)	O buffer pwzCommandLine é muito pequeno. A função retorna o tamanho do buffer necessário em pcchSize. Use o tamanho necessário para realocar o buffer.

Comentários

Essas informações estão disponíveis apenas para o processo atual; você não pode chamar essa função depois que o programa é reiniciado para obter a linha de comando de reinicialização. Para obter a linha de comando após uma reinicialização, acesse o parâmetro argv da função main.

Exemplos

O exemplo a seguir mostra como obter as configurações de reinicialização especificadas quando você chamou a função 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);
}

Requisitos

Cliente mínimo com suporte	Windows Vista [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2008 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	winbase.h (incluir Windows.h)
Biblioteca	Kernel32.lib
DLL	Kernel32.dll

Confira também

RegisterApplicationRestart