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 が 0 の場合は NULL を指定できます。

[in, out] pcchSize

入力時に、 pwzCommandLine バッファーのサイズを文字数で指定します。

バッファーがコマンド ラインを受け取るのに十分な大きさでない場合、関数は HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER) で失敗し、このパラメーターを必要なバッファー サイズ (文字数) に設定します。

出力時に、使用されたバッファーのサイズを指定します。

必要なバッファー サイズを決定するには、 pwzCommandLine を NULL に設定し、このパラメーターを 0 に設定します。 サイズには 、null 終端文字用の 1 つが含まれます。 この場合、関数は HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER) ではなく、S_OKを返します。

[out, optional] pdwFlags

アプリケーションが RegisterApplicationRestart 関数を呼び出したときに指定されたフラグを受け取る変数へのポインター。

戻り値

この関数は、成功した S_OK 、または次のいずれかのエラー コードを返します。

リターン コード 説明
E_INVALIDARG
 1 つ以上のパラメーターが無効です。
HRESULT_FROM_WIN32(ERROR_NOT_FOUND)
 アプリケーションが再起動のために登録されませんでした。
HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER)
 pwzCommandLine バッファーが小さすぎます。 この関数は、必要なバッファー サイズを pcchSize で返します。 バッファーを再割り当てするには、必要なサイズを使用します。

解説

この情報は、現在のプロセスでのみ使用できます。プログラムの再起動後にこの関数を呼び出して、再起動コマンド ラインを取得することはできません。 再起動後にコマンド ラインを取得するには、メイン関数の 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 を含む)
Library Kernel32.lib
[DLL] Kernel32.dll

関連項目

RegisterApplicationRestart