Share via

WinHttpOpen, fonction (winhttp.h)

  • Article

La fonction WinHttpOpen initialise, pour une application, l’utilisation des fonctions WinHTTP et retourne un handle de session WinHTTP.

Syntaxe

WINHTTPAPI HINTERNET WinHttpOpen(
  [in, optional] LPCWSTR pszAgentW,
  [in]           DWORD   dwAccessType,
  [in]           LPCWSTR pszProxyW,
  [in]           LPCWSTR pszProxyBypassW,
  [in]           DWORD   dwFlags
);

Paramètres

[in, optional] pszAgentW

Pointeur vers une variable de chaîne qui contient le nom de l’application ou de l’entité appelant les fonctions WinHTTP. Ce nom est utilisé comme agent utilisateur dans le protocole HTTP.

[in] dwAccessType

Type d’accès requis. Il peut s’agir de l’une des valeurs suivantes.

Valeur Signification
WINHTTP_ACCESS_TYPE_NO_PROXY
 Résout tous les noms d’hôtes directement sans proxy.
WINHTTP_ACCESS_TYPE_DEFAULT_PROXY
Important L’utilisation de cette option est déconseillée sur Windows 8.1 et les versions ultérieures. Utilisez WINHTTP_ACCESS_TYPE_AUTOMATIC_PROXY à la place.
 
Récupère le proxy statique ou la configuration directe à partir du Registre. WINHTTP_ACCESS_TYPE_DEFAULT_PROXY n’hérite pas des paramètres de proxy du navigateur.

La configuration du proxy WinHTTP est définie par l’un de ces mécanismes.
WINHTTP_ACCESS_TYPE_NAMED_PROXY
 Transmet les demandes au proxy, sauf si une liste de contournement de proxy est fournie et que le nom à résoudre contourne le proxy. Dans ce cas, cette fonction utilise les valeurs transmises pour pwszProxyName et pwszProxyBypass.
WINHTTP_ACCESS_TYPE_AUTOMATIC_PROXY
 Utilise les paramètres système et proxy par utilisateur (y compris la configuration du proxy Internet Explorer) pour déterminer les proxys/proxys à utiliser. Tente automatiquement de gérer le basculement entre plusieurs proxys, différentes configurations de proxy par interface et l’authentification. Pris en charge dans Windows 8.1 et versions ultérieures.

[in] pszProxyW

Pointeur vers une variable de chaîne qui contient le nom du serveur proxy à utiliser lorsque l’accès proxy est spécifié en définissant dwAccessTypesur WINHTTP_ACCESS_TYPE_NAMED_PROXY. Les fonctions WinHTTP reconnaissent uniquement les proxys de type CERN pour HTTP. Si dwAccessType n’est pas défini sur WINHTTP_ACCESS_TYPE_NAMED_PROXY, ce paramètre doit être défini sur WINHTTP_NO_PROXY_NAME.

[in] pszProxyBypassW

Pointeur vers une variable de chaîne qui contient une liste de points-virgules facultative délimitée de noms d’hôtes ou d’adresses IP, ou les deux, qui ne doit pas être acheminée via le proxy lorsque dwAccessType est défini sur WINHTTP_ACCESS_TYPE_NAMED_PROXY. La liste peut contenir des caractères génériques. N’utilisez pas de chaîne vide, car la fonction WinHttpOpen l’utilise comme liste de contournement de proxy. Si ce paramètre spécifie la macro «< locale> » dans la liste comme seule entrée, cette fonction contourne tout nom d’hôte qui ne contient pas de point. Si dwAccessType n’est pas défini sur WINHTTP_ACCESS_TYPE_NAMED_PROXY, ce paramètre doit être défini sur WINHTTP_NO_PROXY_BYPASS.

[in] dwFlags

Valeur entière longue non signée qui contient les indicateurs qui indiquent différentes options affectant le comportement de cette fonction. Ce paramètre peut avoir la valeur suivante.

Valeur Signification
WINHTTP_FLAG_ASYNC
 Utilisez les fonctions WinHTTP de manière asynchrone. Par défaut, toutes les fonctions WinHTTP qui utilisent le handle HINTERNET retourné sont exécutées de manière synchrone. Lorsque cet indicateur est défini, l’appelant doit spécifier une fonction de rappel via WinHttpSetStatusCallback.
WINHTTP_FLAG_SECURE_DEFAULTS
 Lorsque cet indicateur est défini, WinHttp nécessite l’utilisation de TLS 1.2 ou version ultérieure. Si l’appelant tente d’activer les versions TLS antérieures en définissant WINHTTP_OPTION_SECURE_PROTOCOLS, il échoue avec ERROR_ACCESS_DENIED. En outre, le secours TLS sera désactivé. Notez que la définition de cet indicateur définit également l’indicateur WINHTTP_FLAG_ASYNC.

Valeur retournée

Retourne un handle de session valide en cas de réussite, ou NULL dans le cas contraire. Pour récupérer des informations d’erreur étendues, appelez GetLastError. Parmi les codes d’erreur retournés figurent les suivants.

Code d'erreur Description
ERROR_WINHTTP_INTERNAL_ERROR
 Une erreur interne s'est produite.
ERROR_NOT_ENOUGH_MEMORY
 La mémoire disponible n’était pas suffisante pour effectuer l’opération demandée. (Code d’erreur Windows)

Remarques

Nous vous recommandons vivement d’utiliser WinHTTP en mode asynchrone (c’est-à-dire, lorsque WINHTTP_FLAG_ASYNC a été défini dans WinHttpOpen, afin que l’utilisation du HINTERNET retourné devienne asynchrone). La valeur de retour indique la réussite ou l’échec. Pour récupérer des informations d’erreur étendues, appelez GetLastError.

La fonction WinHttpOpen est la première des fonctions WinHTTP appelées par une application. Il initialise les structures de données WinHTTP internes et prépare les appels futurs de l’application. Lorsque l’application a terminé d’utiliser les fonctions WinHTTP, elle doit appeler WinHttpCloseHandle pour libérer le handle de session et toutes les ressources associées.

L’application peut effectuer n’importe quel nombre d’appels à WinHttpOpen, bien qu’un seul appel soit normalement suffisant. Chaque appel à WinHttpOpen ouvre un nouveau contexte de session. Étant donné que les données utilisateur ne sont pas partagées entre plusieurs contextes de session, une application qui effectue des demandes pour le compte de plusieurs utilisateurs doit créer une session distincte pour chaque utilisateur, afin de ne pas partager les cookies et l’état d’authentification spécifiques de l’utilisateur. L’application doit définir des comportements distincts pour chaque instance WinHttpOpen, par exemple des serveurs proxy différents configurés pour chacun d’eux.

Une fois que l’application appelante a terminé d’utiliser le handle HINTERNET retourné par WinHttpOpen, elle doit être fermée à l’aide de la fonction WinHttpCloseHandle .

Note Pour Windows XP et Windows 2000, consultez Exigences au moment de l’exécution.
 

Exemples

L’exemple de code suivant montre comment récupérer la valeur de délai d’expiration de connexion par défaut.


    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.

Voir aussi

À propos de Microsoft Windows HTTP Services (WinHTTP)

WinHTTP Versions

WinHttpCloseHandle