WinHttpOpen, fonction (winhttp.h)

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.

[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 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.

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 .

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

Voir aussi

À propos de Microsoft Windows HTTP Services (WinHTTP)

WinHTTP Versions

WinHttpCloseHandle