Fonction WinHttpWriteData (winhttp.h)

Article
08/27/2023

La fonction WinHttpWriteData écrit des données de requête sur un serveur HTTP.

Syntaxe

WINHTTPAPI BOOL WinHttpWriteData(
  [in]  HINTERNET hRequest,
  [in]  LPCVOID   lpBuffer,
  [in]  DWORD     dwNumberOfBytesToWrite,
  [out] LPDWORD   lpdwNumberOfBytesWritten
);

Paramètres

[in] hRequest

Handle HINTERNET valide retourné par WinHttpOpenRequest. Attendez que WinHttpSendRequest soit terminé avant d’appeler cette fonction.

[in] lpBuffer

Pointeur vers une mémoire tampon qui contient les données à envoyer au serveur. Assurez-vous que cette mémoire tampon reste valide jusqu’à la fin de WinHttpWriteData .

[in] dwNumberOfBytesToWrite

Valeur entière longue non signée qui contient le nombre d’octets à écrire dans le fichier.

[out] lpdwNumberOfBytesWritten

Pointeur vers une variable entière longue non signée qui reçoit le nombre d’octets écrits dans la mémoire tampon. La fonction WinHttpWriteData définit cette valeur sur zéro avant d’effectuer un travail ou une vérification des erreurs. Lors de l’utilisation asynchrone de WinHTTP, ce paramètre doit être défini sur NULL et récupérer les informations dans la fonction de rappel. Le fait de ne pas le faire peut provoquer une erreur de mémoire.

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. Parmi les codes d’erreur retournés, citons :

Code d'erreur	Description
ERROR_WINHTTP_CONNECTION_ERROR	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.
ERROR_WINHTTP_INCORRECT_HANDLE_STATE	L’opération demandée ne peut pas être effectuée, car le handle fourni n’est pas dans l’état correct.
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_OPERATION_CANCELLED	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.
ERROR_WINHTTP_TIMEOUT	Le délai d'attente de la requête a expiré.
ERROR_NOT_ENOUGH_MEMORY	La mémoire disponible n’était pas suffisante pour effectuer l’opération demandée. (Code d’erreur Windows)

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. Si cette fonction retourne FALSE, vous pouvez appeler GetLastError pour obtenir des informations d’erreur étendues. Si cette fonction retourne TRUE, utilisez la WINHTTP_CALLBACK_STATUS_WRITE_COMPLETE complétion pour déterminer si cette fonction a réussi et la valeur des paramètres. La WINHTTP_CALLBACK_STATUS_REQUEST_ERROR’achèvement indique que l’opération s’est terminée de manière asynchrone, mais a échoué.

Avertissement Lorsque vous utilisez WinHTTP de manière asynchrone, définissez toujours le paramètre lpdwNumberOfBytesWritten surNULL et récupérez les octets écrits dans la fonction de rappel ; sinon, une erreur de mémoire peut se produire.

Lorsque l’application envoie des données, elle peut appeler WinHttpReceiveResponse pour mettre fin au transfert de données. Si WinHttpCloseHandle est appelé, le transfert de données est abandonné.

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 données au serveur :

WINHTTP_CALLBACK_STATUS_RECEIVING_RESPONSE
WINHTTP_CALLBACK_STATUS_RESPONSE_RECEIVED
WINHTTP_CALLBACK_STATUS_DATA_WRITTEN
WINHTTP_CALLBACK_STATUS_SENDING_REQUEST
WINHTTP_CALLBACK_STATUS_REQUEST_SENT
WINHTTP_CALLBACK_STATUS_WRITE_COMPLETE

Deux problèmes peuvent se produire lors de la tentative d’authentification POST (ou PUT) de données sur des proxys ou des serveurs qui utilisent l’authentification NTLM ou Negotiate. Tout d’abord, ces serveurs ou proxys peuvent envoyer des défis 401/407 et fermer la connexion avant que toutes les données puissent être post’ed, auquel cas non seulement WinHttpWriteData échoue, mais winHTTP ne peut pas gérer les défis d’authentification. NTLM et Negotiate exigent que toutes les négociation d’authentification soient échangées sur la même connexion de socket, de sorte que l’authentification échoue si la connexion est interrompue prématurément.

Deuxièmement, NTLM et Negotiate peuvent nécessiter plusieurs liaisons pour terminer l’authentification, ce qui nécessite que les données soient re-POST’ed pour chaque étape d’authentification. Cela peut être très inefficace pour les chargements de données volumineux.

Pour contourner ces deux problèmes, une solution consiste à envoyer une demande de préchauffement idempotente telle que HEAD à l’authentification d’abord au V-dir, à gérer les défis d’authentification associés à cette demande, puis uniquement ensuite aux données POST. Tant que le même socket est réutilisé pour gérer la post’ing, aucun autre problème d’authentification ne doit être rencontré et toutes les données peuvent être chargées en même temps. Étant donné qu’un socket authentifié ne peut être réutilisé que pour les requêtes suivantes au sein de la même session, le post doit sortir dans le même socket tant que le socket n’est pas mis en pool avec des requêtes simultanées concurrentes.

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

Exemples

Cet exemple montre le code qui écrit des données sur un serveur HTTP. Le nom de serveur fourni dans l’exemple, www.wingtiptoys.com, est fictif et doit être remplacé par le nom d’un serveur pour lequel vous disposez d’un accès en écriture.

    PCSTR pszData = "WinHttpWriteData Example";
    DWORD dwBytesWritten = 0;
    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, 
                                       (DWORD)strlen(pszData), 0);

    // Write data to the server.
    if (bResults)
        bResults = WinHttpWriteData( hRequest, pszData, 
                                     (DWORD)strlen(pszData), 
                                     &dwBytesWritten);

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

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


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.