Funzione GetApplicationRestartSettings (winbase.h)

Articolo
08/27/2023

Recupera le informazioni di riavvio registrate per il processo specificato.

Sintassi

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

Parametri

[in] hProcess

Handle per il processo. Questo handle deve avere il diritto di accesso PROCESS_VM_READ.

[out, optional] pwzCommandline

Puntatore a un buffer che riceve la riga di comando di riavvio specificata dall'applicazione quando ha chiamato la funzione RegisterApplicationRestart . La dimensione massima della riga di comando, in caratteri, è RESTART_MAX_CMD_LINE. Può essere NULL se pcchSize è zero.

[in, out] pcchSize

In input, specifica le dimensioni del buffer pwzCommandLine , in caratteri.

Se il buffer non è sufficientemente grande da ricevere la riga di comando, la funzione ha esito negativo con HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER) e imposta questo parametro sulla dimensione del buffer richiesta, in caratteri.

Nell'output specifica le dimensioni del buffer utilizzato.

Per determinare le dimensioni del buffer necessarie, impostare pwzCommandLine su NULL e questo parametro su zero. La dimensione include una per il carattere di terminazione Null. Si noti che la funzione restituisce S_OK, non HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER) in questo caso.

[out, optional] pdwFlags

Puntatore a una variabile che riceve i flag specificati dall'applicazione quando ha chiamato la funzione RegisterApplicationRestart .

Valore restituito

Questa funzione restituisce S_OK in caso di esito positivo o uno dei codici di errore seguenti.

Codice restituito	Descrizione
E_INVALIDARG	Uno o più parametri non sono validi.
HRESULT_FROM_WIN32(ERROR_NOT_FOUND)	L'applicazione non è stata registrata per il riavvio.
HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER)	Il buffer pwzCommandLine è troppo piccolo. La funzione restituisce le dimensioni del buffer necessarie in pcchSize. Usare le dimensioni necessarie per riallocare il buffer.

Commenti

Queste informazioni sono disponibili solo per il processo corrente; non è possibile chiamare questa funzione dopo il riavvio del programma per ottenere la riga di comando di riavvio. Per ottenere la riga di comando dopo un riavvio, accedere al parametro argv della funzione main .

Esempio

Nell'esempio seguente viene illustrato come ottenere le impostazioni di riavvio specificate quando è stata chiamata la funzione 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);
}

Requisiti


Client minimo supportato	Windows Vista [solo app desktop]
Server minimo supportato	Windows Server 2008 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	winbase.h (include Windows.h)
Libreria	Kernel32.lib
DLL	Kernel32.dll

Vedere anche

RegisterApplicationRestart

Condividi tramite