GetApplicationRestartSettings-Funktion (winbase.h)

Artikel
08/27/2023

Ruft die Für den angegebenen Prozess registrierten Neustartinformationen ab.

Syntax

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

Parameter

[in] hProcess

Ein Handle für den Prozess. Dieses Handle muss über das zugriffsrecht PROCESS_VM_READ verfügen.

[out, optional] pwzCommandline

Ein Zeiger auf einen Puffer, der die Neustartbefehlszeile empfängt, die von der Anwendung beim Aufrufen der RegisterApplicationRestart-Funktion angegeben wurde. Die maximale Größe der Befehlszeile in Zeichen ist RESTART_MAX_CMD_LINE. Kann NULL sein, wenn pcchSize null ist.

[in, out] pcchSize

Gibt bei der Eingabe die Größe des pwzCommandLine-Puffers in Zeichen an.

Wenn der Puffer nicht groß genug ist, um die Befehlszeile zu empfangen, schlägt die Funktion mit HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER) fehl und legt diesen Parameter auf die erforderliche Puffergröße in Zeichen fest.

Gibt bei der Ausgabe die Größe des verwendeten Puffers an.

Um die erforderliche Puffergröße zu bestimmen, legen Sie pwzCommandLine auf NULL und diesen Parameter auf Null fest. Die Größe enthält eins für das NULL-Abschlusszeichen. Beachten Sie, dass die Funktion in diesem Fall S_OK und nicht HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER) zurückgibt.

[out, optional] pdwFlags

Ein Zeiger auf eine Variable, die die flags empfängt, die von der Anwendung beim Aufrufen der RegisterApplicationRestart-Funktion angegeben wurden.

Rückgabewert

Diese Funktion gibt S_OK bei Erfolg oder einen der folgenden Fehlercodes zurück.

Rückgabecode	Beschreibung
E_INVALIDARG	Mindestens ein Parameter ist ungültig.
HRESULT_FROM_WIN32(ERROR_NOT_FOUND)	Die Anwendung wurde nicht für den Neustart registriert.
HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER)	Der pwzCommandLine-Puffer ist zu klein. Die Funktion gibt die erforderliche Puffergröße in pcchSize zurück. Verwenden Sie die erforderliche Größe, um den Puffer neu zuzuspeichern.

Hinweise

Diese Informationen sind nur für den aktuellen Prozess verfügbar; Sie können diese Funktion nicht aufrufen, nachdem Das Programm neu gestartet wurde, um die Neustartbefehlszeile abzurufen. Um die Befehlszeile nach einem Neustart abzurufen, greifen Sie auf den argv-Parameter Ihrer Standard-Funktion zu.

Beispiele

Das folgende Beispiel zeigt, wie Sie die Neustarteinstellungen abrufen, die beim Aufrufen der RegisterApplicationRestart-Funktion angegeben wurden.

#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);
}

Anforderungen


Unterstützte Mindestversion (Client)	Windows Vista [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	winbase.h (Windows.h einschließen)
Bibliothek	Kernel32.lib
DLL	Kernel32.dll

Siehe auch

RegisterApplicationRestart

Freigeben über