Fonction WinHttpQueryOption (winhttp.h)

Article
08/27/2023

La fonction WinHttpQueryOption interroge une option Internet sur le handle spécifié.

Syntaxe

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

Paramètres

[in] hInternet

Un handle HINTERNET sur lequel interroger des informations. Notez qu’il peut s’agir d’un handle de session ou d’un handle de requête, en fonction de l’option interrogée ; Consultez la rubrique Indicateurs d’option pour déterminer le handle approprié à utiliser pour interroger une option particulière.

[in] dwOption

Valeur entière longue non signée qui contient l’option Internet à interroger. Il peut s’agir de l’une des valeurs d’indicateurs d’option .

[out] lpBuffer

Pointeur vers une mémoire tampon qui reçoit le paramètre d’option. Les chaînes retournées par la fonction WinHttpQueryOption étant globalement allouées, l’application appelante doit libérer globalement la chaîne lorsqu’elle a fini de l’utiliser. Si vous définissez ce paramètre sur NULL , cette fonction retourne FALSE. L’appel de GetLastError retourne ensuite ERROR_INSUFFICIENT_BUFFER et lpdwBufferLength contient le nombre d’octets requis pour contenir les informations demandées.

[in, out] lpdwBufferLength

Pointeur vers une variable entière longue non signée qui contient la longueur de lpBuffer, en octets. Lorsque la fonction retourne, la variable reçoit la longueur des données placées dans lpBuffer. Si GetLastError retourne ERROR_INSUFFICIENT_BUFFER, ce paramètre reçoit le nombre d’octets requis pour contenir les informations demandées.

Valeur retournée

Retourne LA valeur TRUE si elle réussit ou FALSE dans le cas contraire. Pour obtenir un message d’erreur spécifique, appelez GetLastError. Parmi les codes d’erreur retournés figurent les suivants :

Code d'erreur	Description
ERROR_WINHTTP_INCORRECT_HANDLE_STATE	L’opération demandée ne peut pas être effectuée, car le handle fourni n’est pas dans l’état correct.
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE	Le type de handle fourni est incorrect pour cette opération.
ERROR_WINHTTP_INTERNAL_ERROR	Une erreur interne s'est produite.
ERROR_WINHTTP_INVALID_OPTION	Une valeur d’option non valide a été spécifiée.
ERROR_NOT_ENOUGH_MEMORY	La mémoire disponible n’était pas suffisante pour effectuer l’opération demandée. (Code d’erreur Windows)

Remarques

Même lorsque WinHTTP est utilisé en mode asynchrone (c’est-à-dire, lorsque WINHTTP_FLAG_ASYNC a été défini dans WinHttpOpen), cette fonction fonctionne de manière synchrone. La valeur de retour indique la réussite ou l’échec. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

GetLastError retourne le ERROR_INVALID_PARAMETER si un indicateur d’option non valide pour le type de handle spécifié est passé au paramètre dwOption .

Note Pour Windows XP et Windows 2000, consultez la section Conditions d’exécution de la page de démarrage WinHttp.

Exemples

Cet exemple montre comment récupérer la valeur de délai d’expiration de la connexion :

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

Configuration requise


Client minimal pris en charge	Windows XP, Windows 2000 Professionnel avec SP3 [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2003, Windows 2000 Server avec SP3 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	winhttp.h
Bibliothèque	Winhttp.lib
DLL	Winhttp.dll
Composant redistribuable	WinHTTP 5.0 et Internet Explorer 5.01 ou version ultérieure sur Windows XP et Windows 2000.