WinHttpQueryOption-Funktion (winhttp.h)

Artikel
08/27/2023

Die WinHttpQueryOption-Funktion fragt eine Internetoption für das angegebene Handle ab.

Syntax

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

Parameter

[in] hInternet

Ein HINTERNET-Handle , für das Informationen abgefragt werden sollen. Beachten Sie, dass dies entweder ein Sitzungshandle oder ein Anforderungshandle sein kann, je nachdem, welche Option abgefragt wird. Im Thema Option Flags finden Sie informationen dazu, welches Handle beim Abfragen einer bestimmten Option verwendet werden kann.

[in] dwOption

Ein ganzzahliger Wert ohne Vorzeichen, der die Abfrageoption Internet enthält. Dies kann einer der Option Flags-Werte sein.

[out] lpBuffer

Ein Zeiger auf einen Puffer, der die Optionseinstellung empfängt. Zeichenfolgen, die von der WinHttpQueryOption-Funktion zurückgegeben werden, werden global zugeordnet, sodass die aufrufende Anwendung die Zeichenfolge global freigeben muss, wenn sie die Verwendung abgeschlossen hat. Wenn Dieser Parameter auf NULL festgelegt wird, gibt diese Funktion FALSE zurück. Beim Aufrufen von GetLastError wird dann ERROR_INSUFFICIENT_BUFFER zurückgegeben, und lpdwBufferLength enthält die Anzahl der Bytes, die zum Aufnehmen der angeforderten Informationen erforderlich sind.

[in, out] lpdwBufferLength

Ein Zeiger auf eine ganzzahlige Variable ohne Vorzeichen, die die Länge von lpBuffer in Bytes enthält. Wenn die Funktion zurückgibt, empfängt die Variable die Länge der In lpBuffer platzierten Daten. Wenn GetLastError ERROR_INSUFFICIENT_BUFFER zurückgibt, empfängt dieser Parameter die Anzahl von Bytes, die zum Aufnehmen der angeforderten Informationen erforderlich sind.

Rückgabewert

Gibt TRUE zurück, wenn der Vorgang erfolgreich war, oder andernfalls FALSE . Rufen Sie GetLastError auf, um eine bestimmte Fehlermeldung zu erhalten. Zu den zurückgegebenen Fehlercodes gehören die folgenden:

Fehlercode	BESCHREIBUNG
ERROR_WINHTTP_INCORRECT_HANDLE_STATE	Der angeforderte Vorgang kann nicht ausgeführt werden, da sich der angegebene Handle nicht im richtigen Zustand befindet.
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE	Der Typ des angegebenen Handles ist für diesen Vorgang falsch.
ERROR_WINHTTP_INTERNAL_ERROR	Ein interner Fehler ist aufgetreten.
ERROR_WINHTTP_INVALID_OPTION	Ein ungültiger Optionswert wurde angegeben.
ERROR_NOT_ENOUGH_MEMORY	Für den angeforderten Vorgang war nicht genügend Arbeitsspeicher verfügbar. (Windows-Fehlercode)

Hinweise

Auch wenn WinHTTP im asynchronen Modus verwendet wird (d. h. wenn WINHTTP_FLAG_ASYNC in WinHttpOpen festgelegt wurde), arbeitet diese Funktion synchron. Der Rückgabewert weist auf Erfolg oder Fehler hin. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

GetLastError gibt den ERROR_INVALID_PARAMETER zurück, wenn ein Optionsflag, das für den angegebenen Handle-Typ ungültig ist, an den dwOption-Parameter übergeben wird.

Hinweis Informationen zu Windows XP und Windows 2000 finden Sie im Abschnitt Laufzeitanforderungen der WinHttp-Startseite .

Beispiele

In diesem Beispiel wird das Abrufen des Verbindungstimeoutwerts veranschaulicht:

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

Anforderungen


Unterstützte Mindestversion (Client)	Windows XP, Windows 2000 Professional mit SP3 [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003, Windows 2000 Server mit SP3 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	winhttp.h
Bibliothek	Winhttp.lib
DLL	Winhttp.dll
Verteilbare Komponente	WinHTTP 5.0 und Internet Explorer 5.01 oder höher unter Windows XP und Windows 2000.