Funzione WinHttpQueryOption (winhttp.h)

Articolo
08/27/2023

La funzione WinHttpQueryOption esegue una query su un'opzione Internet nell'handle specificato.

Sintassi

WINHTTPAPI BOOL WinHttpQueryOption(
  [in]      HINTERNET hInternet,
  [in]      DWORD     dwOption,
  [out]     LPVOID    lpBuffer,
  [in, out] LPDWORD   lpdwBufferLength
);

Parametri

[in] hInternet

Handle DELL'interfaccia DELLA RETE SU cui eseguire query sulle informazioni. Si noti che può trattarsi di un handle di sessione o di un handle di richiesta, a seconda dell'opzione su cui viene eseguita una query; vedere l'argomento Flag di opzione per determinare quale handle è appropriato usare per eseguire query su una determinata opzione.

[in] dwOption

Valore intero long senza segno che contiene l'opzione Internet per la query. Può trattarsi di uno dei valori di Flag di opzione .

[out] lpBuffer

Puntatore a un buffer che riceve l'impostazione dell'opzione. Le stringhe restituite dalla funzione WinHttpQueryOption vengono allocate a livello globale, pertanto l'applicazione chiamante deve liberare globalmente la stringa al termine dell'uso. Se si imposta questo parametro su NULL , questa funzione restituisce FALSE. La chiamata a GetLastError restituisce quindi ERROR_INSUFFICIENT_BUFFER e lpdwBufferLength contiene il numero di byte necessari per contenere le informazioni richieste.

[in, out] lpdwBufferLength

Puntatore a una variabile long integer senza segno che contiene la lunghezza di lpBuffer, in byte. Quando la funzione viene restituita, la variabile riceve la lunghezza dei dati inseriti in lpBuffer. Se GetLastError restituisce ERROR_INSUFFICIENT_BUFFER, questo parametro riceve il numero di byte necessari per contenere le informazioni richieste.

Valore restituito

Restituisce TRUE se l'operazione riesce o FALSE in caso contrario. Per ottenere un messaggio di errore specifico, chiamare GetLastError. Tra i codici di errore restituiti sono riportati di seguito:

Codice di errore	Descrizione
ERROR_WINHTTP_INCORRECT_HANDLE_STATE	Impossibile eseguire l'operazione richiesta perché l'handle fornito non è nello stato corretto.
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE	Il tipo di handle fornito non è corretto per questa operazione.
ERROR_WINHTTP_INTERNAL_ERROR	Si è verificato un errore interno.
ERROR_WINHTTP_INVALID_OPTION	È stato specificato un valore di opzione non valido.
ERROR_NOT_ENOUGH_MEMORY	Memoria insufficiente per completare l'operazione richiesta. (Codice errore di Windows)

Commenti

Anche quando WinHTTP viene usato in modalità asincrona , ovvero quando WINHTTP_FLAG_ASYNC è stato impostato in WinHttpOpen, questa funzione funziona in modo sincrono. Il valore restituito indica l'esito positivo o negativo. Per informazioni dettagliate sull'errore, chiamare GetLastError.

GetLastError restituisce il ERROR_INVALID_PARAMETER se al parametro dwOption viene passato un flag di opzione non valido per il tipo di handle specificato.

Nota Per Windows XP e Windows 2000, vedere la sezione Requisiti di runtime della pagina iniziale di WinHttp.

Esempio

In questo esempio viene illustrato il recupero del valore di timeout della connessione:

    DWORD data;
    DWORD dwSize = sizeof(DWORD);

    // Use WinHttpOpen to obtain an HINTERNET handle.
    HINTERNET hSession = WinHttpOpen(L"A WinHTTP Example Program/1.0", 
                                    WINHTTP_ACCESS_TYPE_DEFAULT_PROXY,
                                    WINHTTP_NO_PROXY_NAME, 
                                    WINHTTP_NO_PROXY_BYPASS, 0);
    if (hSession)
    {


        // Use WinHttpQueryOption to retrieve internet options.
        if (WinHttpQueryOption( hSession, 
                                WINHTTP_OPTION_CONNECT_TIMEOUT, 
                                &data, &dwSize))
        {
            printf("Connection timeout: %u ms\n\n",data);
        }
        else
        {
            printf( "Error %u in WinHttpQueryOption.\n", GetLastError());
        }        
        
        // When finished, release the HINTERNET handle.
        WinHttpCloseHandle(hSession);
    }
    else
    {
        printf("Error %u in WinHttpOpen.\n", GetLastError());
    }

Requisiti


Client minimo supportato	Windows XP, Windows 2000 Professional con SP3 [solo app desktop]
Server minimo supportato	Windows Server 2003, Windows 2000 Server con SP3 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	winhttp.h
Libreria	Winhttp.lib
DLL	Winhttp.dll
Componente ridistribuibile	WinHTTP 5.0 e Internet Explorer 5.01 o versione successiva in Windows XP e Windows 2000.