Fonction WinHttpSendRequest (winhttp.h)
La fonction WinHttpSendRequest envoie la requête spécifiée au serveur HTTP.
Syntaxe
WINHTTPAPI BOOL WinHttpSendRequest(
[in] HINTERNET hRequest,
[in, optional] LPCWSTR lpszHeaders,
[in] DWORD dwHeadersLength,
[in, optional] LPVOID lpOptional,
[in] DWORD dwOptionalLength,
[in] DWORD dwTotalLength,
[in] DWORD_PTR dwContext
);
Paramètres
[in] hRequest
Handle HINTERNET retourné par WinHttpOpenRequest.
[in, optional] lpszHeaders
Pointeur vers une chaîne qui contient les en-têtes supplémentaires à ajouter à la demande. Ce paramètre peut être WINHTTP_NO_ADDITIONAL_HEADERS s’il n’y a pas d’en-têtes supplémentaires à ajouter.
[in] dwHeadersLength
Valeur entière longue non signée qui contient la longueur, en caractères, des en-têtes supplémentaires. Si ce paramètre a la valeur -1L et que pwszHeaders n’a pas la valeur NULL, cette fonction suppose que pwszHeaders est terminé par null et que la longueur est calculée.
[in, optional] lpOptional
Pointeur vers une mémoire tampon qui contient les données facultatives à envoyer immédiatement après les en-têtes de requête. Ce paramètre est généralement utilisé pour les opérations POST et PUT. Les données facultatives peuvent être la ressource ou les données publiées sur le serveur. Ce paramètre peut être WINHTTP_NO_REQUEST_DATA s’il n’existe aucune donnée facultative à envoyer.
Si le paramètre dwOptionalLength est 0, ce paramètre est ignoré et défini sur NULL.
Cette mémoire tampon doit rester disponible jusqu’à ce que le handle de requête soit fermé ou que l’appel à WinHttpReceiveResponse soit terminé.
[in] dwOptionalLength
Valeur entière longue non signée qui contient la longueur, en octets, des données facultatives. Ce paramètre peut être égal à zéro s’il n’y a pas de données facultatives à envoyer.
Ce paramètre doit contenir une longueur valide lorsque le paramètre lpOptional n’est pas NULL. Sinon, lpOptional est ignoré et défini sur NULL.
[in] dwTotalLength
Valeur entière longue non signée qui contient la longueur, en octets, du total des données envoyées. Ce paramètre spécifie l’en-tête Content-Length de la demande. Si la valeur de ce paramètre est supérieure à la longueur spécifiée par dwOptionalLength, winHttpWriteData peut être utilisé pour envoyer des données supplémentaires.
dwTotalLength ne doit pas changer entre les appels à WinHttpSendRequest pour la même demande. Si dwTotalLength doit être modifié, l’appelant doit créer une nouvelle demande.
[in] dwContext
Pointeur vers une variable de la taille du pointeur qui contient une valeur définie par l’application qui est passée, avec le handle de requête, à toutes les fonctions de rappel.
Valeur retournée
Retourne LA valeur TRUE si elle réussit ou FALSE dans le cas contraire. Pour obtenir des informations d’erreur étendues, appelez GetLastError. Les codes d’erreur sont répertoriés dans le tableau suivant.
| Code d'erreur | Description |
|---|---|
|
Retourné si la connexion au serveur a échoué. |
|
Le serveur HTTP sécurisé nécessite un certificat client. L’application récupère la liste des émetteurs de certificats en appelant WinHttpQueryOption avec l’option WINHTTP_OPTION_CLIENT_CERT_ISSUER_LIST .
Si le serveur demande le certificat client, mais n’en a pas besoin, l’application peut également appeler WinHttpSetOption avec l’option WINHTTP_OPTION_CLIENT_CERT_CONTEXT . Dans ce cas, l’application spécifie la macro WINHTTP_NO_CLIENT_CERT_CONTEXT dans le paramètre lpBuffer de WinHttpSetOption. Pour plus d’informations, consultez l’option WINHTTP_OPTION_CLIENT_CERT_CONTEXT . Windows Server 2003 avec SP1, Windows XP avec SP2 et Windows 2000 : Cette erreur n’est pas prise en charge. |
|
La connexion au serveur a été réinitialisée ou terminée, ou un protocole SSL incompatible a été rencontré. Par exemple, WinHTTP version 5.1 ne prend pas en charge SSL2, sauf si le client l’active spécifiquement. |
|
L’opération demandée ne peut pas être effectuée, car le handle fourni n’est pas dans l’état correct. |
|
Le type de handle fourni est incorrect pour cette opération. |
|
Une erreur interne s'est produite. |
|
L’URL n’est pas valide. |
|
La tentative de connexion a échoué. Lorsque cette erreur se produit, le handle de demande doit être fermé avec WinHttpCloseHandle. Un nouveau handle de requête doit être créé avant de réessayer la fonction à l’origine de cette erreur. |
|
Impossible de résoudre le nom du serveur. |
|
L’opération a été annulée, généralement parce que le handle sur lequel la demande fonctionnait a été fermé avant la fin de l’opération. |
|
Retourné lorsqu’une réponse entrante dépasse une limite de taille WinHTTP interne. |
|
Une ou plusieurs erreurs ont été détectées dans le certificat SSL (Secure Sockets Layer) envoyé par le serveur. Pour déterminer le type d’erreur rencontré, vérifiez via une notification WINHTTP_CALLBACK_STATUS_SECURE_FAILURE dans une fonction de rappel status. Pour plus d’informations, consultez WINHTTP_STATUS_CALLBACK. |
|
La prise en charge de la fonction WinHTTP est arrêtée ou déchargée. |
|
La demande a expiré. |
|
L’URL a spécifié un schéma autre que « http : » ou « https : ». |
|
La mémoire disponible n’était pas suffisante pour effectuer l’opération demandée. (Code d’erreur Windows) Windows Server 2003, Windows XP et Windows 2000 : La plage de réservation TCP définie avec l’option WINHTTP_OPTION_PORT_RESERVATION n’est pas assez grande pour envoyer cette demande. |
|
La longueur de contenu spécifiée dans le paramètre dwTotalLength ne correspond pas à la longueur spécifiée dans l’en-tête Content-Length.
Le paramètre lpOptional doit avoir la valeur NULL et le paramètre dwOptionalLength doit être égal à zéro lorsque l’en-tête Transfer-Encoding est présent. L’en-tête Content-Length ne peut pas être présent lorsque l’en-tête Transfer-Encoding est présent. |
|
L’application doit à nouveau appeler WinHttpSendRequest en raison d’une redirection ou d’un défi d’authentification.
Windows Server 2003 avec SP1, Windows XP avec SP2 et Windows 2000 : Cette erreur n’est pas prise en charge. |
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 peut fonctionner de manière synchrone ou asynchrone. Dans les deux cas, si la demande est envoyée correctement, l’application est rappelée avec le status d’achèvement défini sur WINHTTP_CALLBACK_STATUS_SENDREQUEST_COMPLETE. L’WINHTTP_CALLBACK_STATUS_REQUEST_ERROR’achèvement indique que l’opération s’est terminée de manière asynchrone, mais a échoué. À la réception du rappel WINHTTP_CALLBACK_STATUS_SENDREQUEST_COMPLETE status, l’application peut commencer à recevoir une réponse du serveur avec WinHttpReceiveResponse. Avant cela, aucune autre fonction asynchrone ne peut être appelée, sinon, ERROR_WINHTTP_INCORRECT_HANDLE_STATE est retourné.
Une application ne doit pas supprimer ou modifier la mémoire tampon pointée vers lpOptional tant que le handle de demande n’est pas fermé ou que l’appel à WinHttpReceiveResponse n’est pas terminé, car un défi d’authentification ou une redirection nécessitant les données facultatives peut être rencontré lors de la réception de la réponse. Si l’opération doit être abandonnée avec WinHttpCloseHandle, l’application doit conserver la mémoire tampon valide jusqu’à ce qu’elle reçoive le rappel WINHTTP_CALLBACK_STATUS_REQUEST_ERROR avec un code d’erreur ERROR_WINHTTP_OPERATION_CANCELLED .
Si WinHTTP est utilisé de manière synchrone, c’est-à-dire quand WINHTP_FLAG_ASYNC n’a pas été défini dans WinHttpOpen, une application n’est pas appelée avec un status d’achèvement même si une fonction de rappel est inscrite. Dans ce mode, l’application peut appeler WinHttpReceiveResponse lorsque WinHttpSendRequest retourne.
La fonction WinHttpSendRequest envoie la requête spécifiée au serveur HTTP et permet au client de spécifier des en-têtes supplémentaires à envoyer avec la requête.
Cette fonction permet également au client de spécifier des données facultatives à envoyer au serveur HTTP immédiatement après les en-têtes de requête. Cette fonctionnalité est généralement utilisée pour les opérations d’écriture telles que PUT et POST.
Une application peut utiliser le même handle de requête HTTP dans plusieurs appels à WinHttpSendRequest pour renvoyer la même requête, mais l’application doit lire toutes les données retournées par l’appel précédent avant d’appeler à nouveau cette fonction.
Le nom et la valeur des en-têtes de requête ajoutés avec cette fonction sont validés. Les en-têtes doivent être bien formés. Pour plus d’informations sur les en-têtes HTTP valides, consultez RFC 2616. Si un en-tête non valide est utilisé, cette fonction échoue et GetLastError retourne ERROR_INVALID_PARAMETER. L’en-tête non valide n’est pas ajouté.
Windows 2000 : Lors de l’envoi de requêtes à partir de plusieurs threads, il peut y avoir une diminution significative des performances du réseau et du processeur.
Windows XP et Windows 2000 : Consultez Conditions requises au moment de l’exécution.
WinHttpSetStatusCallback
Si une fonction de rappel status a été installée avec WinHttpSetStatusCallback, celles des notifications suivantes qui ont été définies dans le paramètre dwNotificationFlags de WinHttpSetStatusCallback indiquent la progression de l’envoi de la demande :- WINHTTP_CALLBACK_STATUS_DETECTING_PROXY (non implémenté)
- WINHTTP_CALLBACK_STATUS_SENDREQUEST_COMPLETE (uniquement en mode asynchrone)
- WINHTTP_CALLBACK_STATUS_REDIRECT
- WINHTTP_CALLBACK_STATUS_SECURE_FAILURE
- WINHTTP_CALLBACK_STATUS_INTERMEDIATE_RESPONSE
- WINHTTP_CALLBACK_STATUS_RESOLVING_NAME
- WINHTTP_CALLBACK_STATUS_NAME_RESOLVED
- WINHTTP_CALLBACK_STATUS_CONNECTING_TO_SERVER
- WINHTTP_CALLBACK_STATUS_CONNECTED_TO_SERVER
- WINHTTP_CALLBACK_STATUS_SENDING_REQUEST
- WINHTTP_CALLBACK_STATUS_REQUEST_SENT
- WINHTTP_CALLBACK_STATUS_RECEIVING_RESPONSE
- WINHTTP_CALLBACK_STATUS_RESPONSE_RECEIVED
- WINHTTP_CALLBACK_STATUS_CLOSING_CONNECTION
- WINHTTP_CALLBACK_STATUS_CONNECTION_CLOSED
Prise en charge du chargement supérieur à 4 Go
À compter de Windows Vista et Windows Server 2008, WinHttp prend en charge le chargement de fichiers jusqu’à la taille d’un LARGE_INTEGER (2^64 octets) à l’aide de l’en-tête Content-Length. Les longueurs de charge utile spécifiées dans l’appel à WinHttpSendRequest sont limitées à la taille d’un DWORD (2^32 octets). Pour charger des données vers une URL supérieure à DWORD, l’application doit fournir la longueur dans l’en-tête Content-Length de la requête. Dans ce cas, l’application cliente WinHttp appelle WinHttpSendRequest avec le paramètre dwTotalLength défini sur WINHTTP_IGNORE_REQUEST_TOTAL_LENGTH.Si l’en-tête Content-Length spécifie une longueur inférieure à 2^32, l’application doit également spécifier la longueur du contenu dans l’appel à WinHttpSendRequest. Si le paramètre dwTotalLength ne correspond pas à la longueur spécifiée dans l’en-tête Content-Length, l’appel échoue et retourne ERROR_INVALID_PARAMETER.
L’en-tête Content-Length peut être ajouté dans l’appel à WinHttpAddRequestHeaders, ou il peut être spécifié dans le paramètre lpszHeader de WinHttpSendRequest , comme indiqué dans l’exemple de code suivant.
BOOL fRet = WinHttpSendRequest(
hReq,
L"Content-Length: 68719476735\r\n",
-1L,
WINHTTP_NO_REQUEST_DATA,
0,
WINHTTP_IGNORE_REQUEST_TOTAL_LENGTH,
pMyContent);
En-tête d’encodage de transfert
À compter de Windows Vista et Windows Server 2008, WinHttp permet aux applications d’effectuer un encodage de transfert en bloc sur les données envoyées au serveur. Lorsque l’en-tête Transfer-Encoding est présent sur la requête WinHttp, le paramètre dwTotalLength dans l’appel à WinHttpSendRequest est défini sur WINHTTP_IGNORE_REQUEST_TOTAL_LENGTH et l’application envoie le corps de l’entité dans un ou plusieurs appels à WinHttpWriteData. Le paramètre lpOptional de WinHttpSendRequest doit être NULL et le paramètre dwOptionLength doit être égal à zéro, sinon une erreur de ERROR_WINHTTP_INVALID_PARAMETER est retournée. Pour arrêter le transfert de données en bloc, l’application génère un bloc de longueur nulle et l’envoie dans le dernier appel à WinHttpWriteData.Exemples
L’exemple de code suivant 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 errors.
if (!bResults)
printf("Error %d has occurred.\n",GetLastError());
// Close 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. |
Voir aussi
À propos des services HTTP Microsoft Windows (WinHTTP)
WINHTTP_STATUS_CALLBACK