Функция GetApplicationRestartSettings (winbase.h)

Статья
08/27/2023

Извлекает сведения о перезапуске, зарегистрированные для указанного процесса.

Синтаксис

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

Параметры

[in] hProcess

Дескриптор процесса. Этот дескриптор должен иметь право доступа к PROCESS_VM_READ.

[out, optional] pwzCommandline

Указатель на буфер, который получает командную строку перезапуска, указанную приложением при вызове функции RegisterApplicationRestart . Максимальный размер командной строки в символах — RESTART_MAX_CMD_LINE. Может иметь значение NULL, если pcchSize равно нулю.

[in, out] pcchSize

На входных данных указывает размер буфера pwzCommandLine в символах.

Если буфер недостаточно велик для получения командной строки, функция завершается ошибкой HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER) и задает для этого параметра требуемый размер буфера в символах.

В выходных данных указывает размер использованного буфера.

Чтобы определить требуемый размер буфера, задайте для параметра pwzCommandLineзначение NULL , а для этого параметра — нулевое значение. Размер включает один для символа конца null. Обратите внимание, что функция возвращает S_OK, а не HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER) в данном случае.

[out, optional] pdwFlags

Указатель на переменную, которая получает флаги, заданные приложением при вызове функции RegisterApplicationRestart .

Возвращаемое значение

Эта функция возвращает S_OK при успешном выполнении или одном из следующих кодов ошибок.

Код возврата	Описание
E_INVALIDARG	Один или несколько параметров являются недопустимыми.
HRESULT_FROM_WIN32(ERROR_NOT_FOUND)	Приложение не зарегистрировано для перезапуска.
HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER)	Буфер pwzCommandLine слишком мал. Функция возвращает требуемый размер буфера в pcchSize. Используйте необходимый размер для перераспределения буфера.

Эти сведения доступны только для текущего процесса; Эту функцию нельзя вызвать после перезапуска программы, чтобы получить командную строку перезапуска. Чтобы получить командную строку после перезапуска, обратитесь к параметру argv функции main.

Примеры

В следующем примере показано, как получить параметры перезапуска, указанные при вызове функции 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);
}

Требования


Минимальная версия клиента	Windows Vista [только классические приложения]
Минимальная версия сервера	Windows Server 2008 [только классические приложения]
Целевая платформа	Windows
Header	winbase.h (включая Windows.h)
Библиотека	Kernel32.lib
DLL	Kernel32.dll

См. также

RegisterApplicationRestart

Поделиться через