GetApplicationRestartSettings 函式 (winbase.h)

擷取為指定進程註冊的重新開機資訊。

語法

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。 如果pcchSize為零，可以是Null。

[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中所需的緩衝區大小。 使用必要的大小來重新配置緩衝區。

備註

這項資訊僅適用于目前的進程;重新開機程式之後，您無法呼叫此函式，以取得重新開機命令列。 若要在重新開機之後取得命令列，請存取main函式的argv參數。

範例

下列範例示範如何在您呼叫 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
標頭	winbase.h (包含 Windows.h)
程式庫	Kernel32.lib
DLL	Kernel32.dll

另請參閱

RegisterApplicationRestart