WinHttpWriteData-Funktion (winhttp.h)

Artikel
08/27/2023

Die WinHttpWriteData-Funktion schreibt Anforderungsdaten auf einen HTTP-Server.

Syntax

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

Parameter

[in] hRequest

Gültiges HINTERNET-Handle, das von WinHttpOpenRequest zurückgegeben wird. Warten Sie, bis WinHttpSendRequest abgeschlossen ist, bevor Sie diese Funktion aufrufen.

[in] lpBuffer

Zeiger auf einen Puffer, der die Daten enthält, die an den Server gesendet werden sollen. Stellen Sie sicher, dass dieser Puffer bis nach Abschluss von WinHttpWriteData gültig bleibt.

[in] dwNumberOfBytesToWrite

Ganzzahlwert ohne Vorzeichen, der die Anzahl der Bytes enthält, die in die Datei geschrieben werden sollen.

[out] lpdwNumberOfBytesWritten

Zeiger auf eine ganzzahlige Variable ohne Vorzeichen, die die Anzahl der in den Puffer geschriebenen Bytes empfängt. Die WinHttpWriteData-Funktion legt diesen Wert vor der Arbeit oder Fehlerüberprüfung auf Null fest. Wenn Sie WinHTTP asynchron verwenden, muss dieser Parameter auf NULL festgelegt werden und die Informationen in der Rückruffunktion abrufen. Dies kann zu einem Speicherfehler führen.

Rückgabewert

Gibt TRUE zurück, wenn der Vorgang erfolgreich war, oder andernfalls FALSE . Rufen Sie GetLastError auf, um erweiterte Fehlerinformationen zu erhalten. Zu den zurückgegebenen Fehlercodes gehören:

Fehlercode	BESCHREIBUNG
ERROR_WINHTTP_CONNECTION_ERROR	Die Verbindung mit dem Server wurde zurückgesetzt oder beendet, oder es wurde ein inkompatibles SSL-Protokoll gefunden. Beispielsweise unterstützt WinHTTP, Version 5.1, SSL2 nur dann, wenn der Client dies ausdrücklich aktiviert.
ERROR_WINHTTP_INCORRECT_HANDLE_STATE	Der angeforderte Vorgang kann nicht ausgeführt werden, da sich der angegebene Handle nicht im richtigen Zustand befindet.
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE	Der Typ des angegebenen Handles ist für diesen Vorgang falsch.
ERROR_WINHTTP_INTERNAL_ERROR	Ein interner Fehler ist aufgetreten.
ERROR_WINHTTP_OPERATION_CANCELLED	Der Vorgang wurde abgebrochen, in der Regel, weil der Handle, an dem die Anforderung ausgeführt wurde, vor Abschluss des Vorgangs geschlossen wurde.
ERROR_WINHTTP_TIMEOUT	Timeout für die Anforderung.
ERROR_NOT_ENOUGH_MEMORY	Für den angeforderten Vorgang war nicht genügend Arbeitsspeicher verfügbar. (Windows-Fehlercode)

Hinweise

Selbst wenn WinHTTP im asynchronen Modus verwendet wird (d. h. wenn WINHTTP_FLAG_ASYNC in WinHttpOpen festgelegt wurde), kann diese Funktion synchron oder asynchron ausgeführt werden. Wenn diese Funktion FALSE zurückgibt, können Sie GetLastError aufrufen, um erweiterte Fehlerinformationen abzurufen. Wenn diese Funktion TRUE zurückgibt, verwenden Sie die WINHTTP_CALLBACK_STATUS_WRITE_COMPLETE Vervollständigung, um zu bestimmen, ob diese Funktion erfolgreich war, und den Wert der Parameter. Die WINHTTP_CALLBACK_STATUS_REQUEST_ERROR Vervollständigung gibt an, dass der Vorgang asynchron abgeschlossen wurde, aber ein Fehler aufgetreten ist.

Warnung Legen Sie bei asynchroner Verwendung von WinHTTP immer den Parameter lpdwNumberOfBytesWritten auf NULL fest, und rufen Sie die in der Rückruffunktion geschriebenen Bytes ab. andernfalls kann ein Speicherfehler auftreten.

Wenn die Anwendung Daten sendet, kann sie WinHttpReceiveResponse aufrufen, um die Datenübertragung zu beenden. Wenn WinHttpCloseHandle aufgerufen wird, wird die Datenübertragung abgebrochen.

Wenn eine status Rückruffunktion mit WinHttpSetStatusCallback installiert wurde, zeigen die folgenden Benachrichtigungen, die im dwNotificationFlags-Parameter von WinHttpSetStatusCallback festgelegt wurden, den Fortschritt beim Senden von Daten an den Server an:

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

Zwei Probleme können beim Versuch auftreten, POST-Daten (oder PUT) an Proxys oder Servern zu verwenden, die die NTLM- oder Negotiate-Authentifizierung in Frage stellen. Erstens können diese Proxys oder Server 401/407-Herausforderungen senden und die Verbindung schließen, bevor alle Daten POST'ed werden können. In diesem Fall schlägt winHttpWriteData nicht nur fehl, sondern auch WinHTTP kann die Authentifizierungsherausforderungen nicht bewältigen. NTLM und Negotiate erfordern, dass alle Authentifizierungs-Handshakes über dieselbe Socketverbindung ausgetauscht werden, sodass die Authentifizierung fehlschlägt, wenn die Verbindung vorzeitig unterbrochen wird.

Zweitens erfordern NTLM und Negotiate möglicherweise mehrere Handshakes, um die Authentifizierung abzuschließen, was erfordert, dass die Daten für jede Authentifizierungsbeine erneut POST'ediert werden. Dies kann bei großen Datenuploads sehr ineffizient sein.

Um diese beiden Probleme zu umgehen, besteht eine Lösung darin, eine idempotente Aufwärmanforderung wie HEAD zuerst an die authentifizierende V-Dir zu senden, die mit dieser Anforderung verbundenen Authentifizierungsheraufforderungen und erst dann POST-Daten zu behandeln. Solange derselbe Socket für die Verarbeitung des POST-Vorgangs erneut verwendet wird, sollten keine weiteren Authentifizierungsproblemen auftreten und alle Daten gleichzeitig hochgeladen werden. Da ein authentifizierter Socket nur für nachfolgende Anforderungen innerhalb derselben Sitzung wiederverwendet werden kann, sollte der POST im selben Socket ausgeführt werden, solange der Socket nicht mit gleichzeitigen Anforderungen im Pool zusammengefasst ist, die um ihn konkurrieren.

Hinweis Informationen zu Windows XP und Windows 2000 finden Sie im Abschnitt Laufzeitanforderungen der WinHTTP-Startseite .

Beispiele

Dieses Beispiel zeigt Code, der Daten auf einen HTTP-Server schreibt. Der im Beispiel angegebene Servername www.wingtiptoys.com ist fiktiv und muss durch den Namen eines Servers ersetzt werden, für den Sie Schreibzugriff haben.

    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);

Anforderungen


Unterstützte Mindestversion (Client)	Windows XP, Windows 2000 Professional mit SP3 [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003, Windows 2000 Server mit SP3 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	winhttp.h
Bibliothek	Winhttp.lib
DLL	Winhttp.dll
Verteilbare Komponente	WinHTTP 5.0 und Internet Explorer 5.01 oder höher unter Windows XP und Windows 2000.