WinHttpConnect, fonction (winhttp.h)

Article
03/13/2024

La fonction WinHttpConnect spécifie le serveur cible initial d’une requête HTTP et retourne un handle de connexion HINTERNET à une session HTTP pour cette cible initiale.

Syntaxe

WINHTTPAPI HINTERNET WinHttpConnect(
  [in] HINTERNET     hSession,
  [in] LPCWSTR       pswzServerName,
  [in] INTERNET_PORT nServerPort,
  [in] DWORD         dwReserved
);

Paramètres

[in] hSession

Handle de session WINHTTP HINTERNET valide retourné par un appel précédent à WinHttpOpen.

[in] pswzServerName

Pointeur vers une chaîne terminée par null qui contient le nom d’hôte d’un serveur HTTP. La chaîne peut également contenir l’adresse IP du site en ASCII, par exemple, 10.0.1.45. Notez que WinHttp n’accepte pas les noms d’hôtes internationaux sans les convertir d’abord en Punycode. Pour plus d’informations, consultez Gestion des noms de domaine internationalisés (IDN).

[in] nServerPort

Entier non signé qui spécifie le port TCP/IP sur le serveur auquel une connexion est établie. Ce paramètre peut être n’importe quel numéro de port TCP/IP valide ou l’une des valeurs suivantes.

Valeur	Signification
INTERNET_DEFAULT_HTTP_PORT	Utilise le port par défaut pour les serveurs HTTP (port 80).
INTERNET_DEFAULT_HTTPS_PORT	Utilise le port par défaut pour les serveurs HTTPS (port 443). La sélection de ce port n’établit pas automatiquement une connexion sécurisée. Vous devez toujours spécifier l’utilisation de la sémantique de transaction sécurisée à l’aide de l’indicateur WINHTTP_FLAG_SECURE avec WinHttpOpenRequest.
INTERNET_DEFAULT_PORT	Utilise le port 80 pour HTTP et le port 443 pour le protocole HTTPS (Secure Hypertext Transfer Protocol).

[in] dwReserved

Ce paramètre est réservé et doit être 0.

Valeur retournée

Retourne un handle de connexion valide à la session HTTP si la connexion réussit, 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.

Codes d’erreur	Description
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_URL	L’URL n’est pas valide.
ERROR_WINHTTP_OPERATION_CANCELLED	L’opération a été annulée, généralement parce que le handle sur lequel la requête fonctionnait a été fermé avant la fin de l’opération.
ERROR_WINHTTP_UNRECOGNIZED_SCHEME	Le schéma d’URL n’a pas pu être reconnu ou n’est pas pris en charge.
ERROR_WINHTTP_SHUTDOWN	La prise en charge de la fonction WinHTTP est en cours d’arrêt ou de déchargement.
ERROR_NOT_ENOUGH_MEMORY	La mémoire disponible était insuffisante pour terminer l’opération demandée. (Code d’erreur Windows)

Remarques

Même lorsque WinHTTP est utilisé en mode asynchrone (autrement dit, quand 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.

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

WinHttpConnect spécifie le serveur HTTP cible, mais une réponse peut provenir d’un autre serveur si la requête a été redirigée. Vous pouvez déterminer l’URL du serveur qui envoie la réponse en appelant WinHttpQueryOption avec l’indicateur WINHTTP_OPTION_URL.

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

Exemples

L’exemple suivant montre comment utiliser la sémantique de transaction sécurisée pour télécharger une ressource à partir d’un serveur HTTPS. L’exemple de code initialise l’interface de programmation d’applications (API) microsoft Windows HTTP Services (WinHTTP), sélectionne un serveur HTTPS cible, puis ouvre et envoie une demande pour cette ressource sécurisée.
WinHttpQueryDataAvailable est utilisé avec le handle de requête pour déterminer la quantité de données disponibles en téléchargement, puis WinHttpReadData est utilisé pour lire ces données. Ce processus se répète jusqu’à ce que l’intégralité du document ait été récupérée et affichée.


    DWORD dwSize = 0;
    DWORD dwDownloaded = 0;
    LPSTR pszOutBuffer;
    BOOL  bResults = FALSE;
    HINTERNET  hSession = NULL, 
               hConnect = NULL,
               hRequest = NULL;

    // Use WinHttpOpen to obtain a session handle.
    hSession = WinHttpOpen( L"WinHTTP Example/1.0",  
                            WINHTTP_ACCESS_TYPE_DEFAULT_PROXY,
                            WINHTTP_NO_PROXY_NAME, 
                            WINHTTP_NO_PROXY_BYPASS, 0);

    // Specify an HTTP server.
    if (hSession)
        hConnect = WinHttpConnect( hSession, L"www.microsoft.com",
                                   INTERNET_DEFAULT_HTTPS_PORT, 0);

    // Create an HTTP request handle.
    if (hConnect)
        hRequest = WinHttpOpenRequest( hConnect, L"GET", NULL,
                                       NULL, WINHTTP_NO_REFERER, 
                                       WINHTTP_DEFAULT_ACCEPT_TYPES, 
                                       WINHTTP_FLAG_SECURE);

    // Send a request.
    if (hRequest)
        bResults = WinHttpSendRequest( hRequest,
                                       WINHTTP_NO_ADDITIONAL_HEADERS,
                                       0, WINHTTP_NO_REQUEST_DATA, 0, 
                                       0, 0);

 
    // End the request.
    if (bResults)
        bResults = WinHttpReceiveResponse( hRequest, NULL);

    // Keep checking for data until there is nothing left.
    if (bResults)
        do 
        {
            // Check for available data.
            dwSize = 0;
            if (!WinHttpQueryDataAvailable( hRequest, &dwSize))
                printf("Error %u in WinHttpQueryDataAvailable.\n", GetLastError());

            // Allocate space for the buffer.
            pszOutBuffer = new char[dwSize+1];
            if (!pszOutBuffer)
            {
                printf("Out of memory\n");
                dwSize=0;
            }
            else
            {
                // Read the Data.
                ZeroMemory(pszOutBuffer, dwSize+1);

                if (!WinHttpReadData( hRequest, (LPVOID)pszOutBuffer, 
                                      dwSize, &dwDownloaded))
                    printf( "Error %u in WinHttpReadData.\n", GetLastError());
                else
                    printf( "%s\n", pszOutBuffer);
            
                // Free the memory allocated to the buffer.
                delete [] pszOutBuffer;
            }

        } while (dwSize > 0);


    // Report any errors.
    if (!bResults)
        printf("Error %d has occurred.\n", GetLastError());

    // Close any open handles.
    if (hRequest) WinHttpCloseHandle(hRequest);
    if (hConnect) WinHttpCloseHandle(hConnect);
    if (hSession) WinHttpCloseHandle(hSession);

Configuration requise

Condition requise	Valeur
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.