WinHttpOpenRequest, fonction (winhttp.h)

Article
08/27/2023

La fonction WinHttpOpenRequest crée un handle de requête HTTP.

Syntaxe

WINHTTPAPI HINTERNET WinHttpOpenRequest(
  [in] HINTERNET hConnect,
  [in] LPCWSTR   pwszVerb,
  [in] LPCWSTR   pwszObjectName,
  [in] LPCWSTR   pwszVersion,
  [in] LPCWSTR   pwszReferrer,
  [in] LPCWSTR   *ppwszAcceptTypes,
  [in] DWORD     dwFlags
);

Paramètres

[in] hConnect

Handle de connexion HINTERNET à une session HTTP retournée par WinHttpConnect.

[in] pwszVerb

Pointeur vers une chaîne qui contient le verbe HTTP à utiliser dans la requête. Si ce paramètre a la valeur NULL, la fonction utilise GET comme verbe HTTP. Note Cette chaîne doit être en majuscules. De nombreux serveurs traitent les verbes HTTP comme respectant la casse, et les requêtes de commentaires (RFC) de l’Internet Engineering Task Force (IETF) écrivent ces verbes à l’aide de caractères majuscules uniquement.

[in] pwszObjectName

Pointeur vers une chaîne qui contient le nom de la ressource cible du verbe HTTP spécifié. Il s’agit généralement d’un nom de fichier, d’un module exécutable ou d’un spécificateur de recherche.

[in] pwszVersion

Pointeur vers une chaîne qui contient la version HTTP. Si ce paramètre a la valeur NULL, la fonction utilise HTTP/1.1.

[in] pwszReferrer

Pointeur vers une chaîne qui spécifie l’URL du document à partir duquel l’URL de la requête pwszObjectName a été obtenue. Si ce paramètre est défini sur WINHTTP_NO_REFERER, aucun document de référence n’est spécifié.

[in] ppwszAcceptTypes

Pointeur vers un tableau terminé par une valeur Null de pointeurs de chaîne qui spécifie les types de médias acceptés par le client. Si ce paramètre est défini sur WINHTTP_DEFAULT_ACCEPT_TYPES, aucun type n’est accepté par le client. En règle générale, les serveurs gèrent un manque de types acceptés comme indication que le client accepte uniquement les documents de type « text/* » ; c’est-à-dire uniquement des documents texte , pas d’images ou d’autres fichiers binaires. Pour obtenir la liste des types de médias valides, consultez Types de médias définis par l’IANA à l’adresse http://www.iana.org/assignments/media-types/.

[in] dwFlags

Valeur entière longue non signée qui contient les valeurs d’indicateur Internet. Il peut s’agir de l’une ou plusieurs des valeurs suivantes :

Valeur	Signification
WINHTTP_FLAG_BYPASS_PROXY_CACHE	Cet indicateur offre le même comportement que WINHTTP_FLAG_REFRESH.
WINHTTP_FLAG_ESCAPE_DISABLE	Les caractères non sécurisés dans l’URL passée pour pwszObjectName ne sont pas convertis en séquences d’échappement.
WINHTTP_FLAG_ESCAPE_DISABLE_QUERY	Les caractères non sécurisés dans le composant de requête de l’URL passée pour pwszObjectName ne sont pas convertis en séquences d’échappement.
WINHTTP_FLAG_ESCAPE_PERCENT	La chaîne transmise pour pwszObjectName est convertie d’un LPCWSTR en LPSTR. Tous les caractères non sécurisés sont convertis en séquence d’échappement, y compris le symbole de pourcentage. Par défaut, tous les caractères non sécurisés, à l’exception du symbole de pourcentage, sont convertis en séquence d’échappement.
WINHTTP_FLAG_NULL_CODEPAGE	La chaîne transmise pour pwszObjectName est supposée être constituée de caractères ANSI valides représentés par WCHAR. Aucune case activée n’est effectuée pour les caractères non sécurisés. Windows 7 : Cette option est obsolète.
WINHTTP_FLAG_REFRESH	Indique que la demande doit être transférée au serveur d’origine au lieu d’envoyer une version mise en cache d’une ressource à partir d’un serveur proxy. Lorsque cet indicateur est utilisé, un en-tête « Pragma : no-cache » est ajouté au handle de requête. Lors de la création d’un en-tête de requête HTTP/1.1, un « Cache-Control : no-cache » est également ajouté.
WINHTTP_FLAG_SECURE	Utilise la sémantique de transaction sécurisée. Cela se traduit par l’utilisation du protocole SSL (Secure Sockets Layer)/TLS (Transport Layer Security).

Valeur retournée

Retourne un handle de requête HTTP valide en cas de réussite, ou NULL si ce n’est pas le cas. Pour obtenir des informations d’erreur étendues, appelez GetLastError. Parmi les codes d’erreur retournés figurent les suivants.

Code 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	L’URL a spécifié un schéma autre que « http : » ou « https : ».
ERROR_NOT_ENOUGH_MEMORY	La mémoire disponible était insuffisante pour terminer l’opération demandée. (Code d’erreur Windows)

Remarques

La valeur de retour indique la réussite ou l’échec. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

La fonction WinHttpOpenRequest crée un nouveau handle de requête HTTP et stocke les paramètres spécifiés dans ce handle. Un handle de requête HTTP contient une demande à envoyer à un serveur HTTP et contient tous les en-têtes RFC822/MIME/HTTP à envoyer dans le cadre de la requête.

Si pwszVerb est défini sur « HEAD », l’en-tête Content-Length est ignoré.

Si une fonction de rappel status a été installée avec WinHttpSetStatusCallback, une notification WINHTTP_CALLBACK_STATUS_HANDLE_CREATED indique que WinHttpOpenRequest a créé un handle de demande.

Une fois l’application appelante terminée à l’aide du handle HINTERNET retourné par WinHttpOpenRequest, elle doit être fermée à l’aide de la fonction WinHttpCloseHandle .

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

Exemples

Cet exemple montre comment obtenir un handle HINTERNET , ouvrir une session HTTP, créer un en-tête de requête et envoyer cet en-tête au serveur.


    BOOL  bResults = FALSE;
    HINTERNET hSession = NULL,
              hConnect = NULL,
              hRequest = NULL;

    // Use WinHttpOpen to obtain a session handle.
    hSession = WinHttpOpen(  L"A WinHTTP Example Program/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.wingtiptoys.com",
                                   INTERNET_DEFAULT_HTTP_PORT, 0);

    // Create an HTTP Request handle.
    if (hConnect)
        hRequest = WinHttpOpenRequest( hConnect, L"PUT", 
                                       L"/writetst.txt", 
                                       NULL, WINHTTP_NO_REFERER, 
                                       WINHTTP_DEFAULT_ACCEPT_TYPES,
                                       0);

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

    // PLACE ADDITIONAL CODE HERE.

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