Fungsi GetApplicationRestartSettings (winbase.h)

Artikel
08/27/2023

Mengambil informasi hidupkan ulang yang terdaftar untuk proses yang ditentukan.

Sintaks

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

Parameter

[in] hProcess

Handel untuk proses. Handel ini harus memiliki hak akses PROCESS_VM_READ.

[out, optional] pwzCommandline

Penunjuk ke buffer yang menerima baris perintah hidupkan ulang yang ditentukan oleh aplikasi saat disebut fungsi RegisterApplicationRestart . Ukuran maksimum baris perintah, dalam karakter, adalah RESTART_MAX_CMD_LINE. Dapat berupa NULL jika pcchSize adalah nol.

[in, out] pcchSize

Pada input, menentukan ukuran buffer pwzCommandLine , dalam karakter.

Jika buffer tidak cukup besar untuk menerima baris perintah, fungsi gagal dengan HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER) dan mengatur parameter ini ke ukuran buffer yang diperlukan, dalam karakter.

Pada output, menentukan ukuran buffer yang digunakan.

Untuk menentukan ukuran buffer yang diperlukan, atur pwzCommandLine ke NULL dan parameter ini ke nol. Ukurannya mencakup satu untuk karakter null-terminator. Perhatikan bahwa fungsi mengembalikan S_OK, bukan HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER) dalam hal ini.

[out, optional] pdwFlags

Penunjuk ke variabel yang menerima bendera yang ditentukan oleh aplikasi saat disebut fungsi RegisterApplicationRestart .

Nilai kembali

Fungsi ini mengembalikan S_OK pada keberhasilan atau salah satu kode kesalahan berikut.

Menampilkan kode	Deskripsi
E_INVALIDARG	Satu atau beberapa parameter tidak valid.
HRESULT_FROM_WIN32(ERROR_NOT_FOUND)	Aplikasi tidak mendaftar untuk memulai ulang.
HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER)	Buffer pwzCommandLine terlalu kecil. Fungsi mengembalikan ukuran buffer yang diperlukan dalam pcchSize. Gunakan ukuran yang diperlukan untuk mengalokasikan ulang buffer.

Keterangan

Informasi ini hanya tersedia untuk proses saat ini; Anda tidak dapat memanggil fungsi ini setelah program dimulai ulang untuk mendapatkan baris perintah hidupkan ulang. Untuk mendapatkan baris perintah setelah restart, akses parameter argv dari fungsi utama Anda.

Contoh

Contoh berikut menunjukkan cara mendapatkan pengaturan hidupkan ulang yang ditentukan saat Anda memanggil fungsi 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);
}

Persyaratan


Klien minimum yang didukung	Windows Vista [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2008 [hanya aplikasi desktop]
Target Platform	Windows
Header	winbase.h (termasuk Windows.h)
Pustaka	Kernel32.lib
DLL	Kernel32.dll

Lihat juga

RegisterApplicationRestart

Bagikan melalui