WinHttpSendRequest-Funktion (winhttp.h)

Die WinHttpSendRequest-Funktion sendet die angegebene Anforderung an den HTTP-Server.

Syntax

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

Parameter

[in] hRequest

Ein von WinHttpOpenRequest zurückgegebenes HINTERNET-Handle.

[in, optional] lpszHeaders

Ein Zeiger auf eine Zeichenfolge, die die zusätzlichen Header enthält, die an die Anforderung angefügt werden sollen. Dieser Parameter kann WINHTTP_NO_ADDITIONAL_HEADERS werden, wenn keine zusätzlichen Header angefügt werden können.

[in] dwHeadersLength

Ein ganzzahliger Wert ohne Vorzeichen, der die Länge der zusätzlichen Kopfzeilen in Zeichen enthält. Wenn dieser Parameter -1L ist und pwszHeaders nicht NULL ist, geht diese Funktion davon aus, dass pwszHeadersnull-beendet ist und die Länge berechnet wird.

[in, optional] lpOptional

Ein Zeiger auf einen Puffer, der alle optionalen Daten enthält, die unmittelbar nach den Anforderungsheadern gesendet werden sollen. Dieser Parameter wird im Allgemeinen für POST- und PUT-Vorgänge verwendet. Die optionalen Daten können die Ressource oder daten sein, die an den Server gesendet werden. Dieser Parameter kann WINHTTP_NO_REQUEST_DATA werden, wenn keine optionalen Daten zum Senden vorhanden sind.

Wenn der dwOptionalLength-Parameter 0 ist, wird dieser Parameter ignoriert und auf NULL festgelegt.

Dieser Puffer muss verfügbar bleiben, bis das Anforderungshandle geschlossen oder der Aufruf von WinHttpReceiveResponse abgeschlossen ist.

[in] dwOptionalLength

Ein ganzzahliger Wert ohne Vorzeichen, der die Länge der optionalen Daten in Bytes enthält. Dieser Parameter kann null sein, wenn keine optionalen Daten zum Senden vorhanden sind.

Dieser Parameter muss eine gültige Länge enthalten, wenn der lpOptional-Parameter nicht NULL ist. Andernfalls wird lpOptional ignoriert und auf NULL festgelegt.

[in] dwTotalLength

Ein ganzzahliger Wert ohne Vorzeichen, der die Länge der gesendeten Gesamtdaten in Bytes enthält. Dieser Parameter gibt den Content-Length-Header der Anforderung an. Wenn der Wert dieses Parameters größer als die von dwOptionalLength angegebene Länge ist, kann WinHttpWriteData zum Senden zusätzlicher Daten verwendet werden.

dwTotalLength darf zwischen Aufrufen von WinHttpSendRequest für dieselbe Anforderung nicht geändert werden. Wenn dwTotalLength geändert werden muss, sollte der Aufrufer eine neue Anforderung erstellen.

[in] dwContext

Ein Zeiger auf eine Variable mit Zeigergröße, die einen anwendungsdefinierten Wert enthält, der mit dem Anforderungshandle an alle Rückruffunktionen übergeben wird.

Rückgabewert

Gibt TRUE zurück, wenn der Vorgang erfolgreich war, oder andernfalls FALSE . Rufen Sie GetLastError auf, um erweiterte Fehlerinformationen zu erhalten. Fehlercodes sind in der folgenden Tabelle aufgeführt.

Fehlercode BESCHREIBUNG
ERROR_WINHTTP_CANNOT_CONNECT
Wird zurückgegeben, wenn die Verbindung mit dem Server fehlgeschlagen ist.
ERROR_WINHTTP_CLIENT_AUTH_CERT_NEEDED
Für den sicheren HTTP-Server ist ein Clientzertifikat erforderlich. Die Anwendung ruft die Liste der Zertifikataussteller ab, indem WinHttpQueryOption mit der Option WINHTTP_OPTION_CLIENT_CERT_ISSUER_LIST aufgerufen wird.

Wenn der Server das Clientzertifikat anfordert, es aber nicht benötigt, kann die Anwendung Alternativ WinHttpSetOption mit der Option WINHTTP_OPTION_CLIENT_CERT_CONTEXT aufrufen. In diesem Fall gibt die Anwendung das WINHTTP_NO_CLIENT_CERT_CONTEXT Makro im lpBuffer-Parameter von WinHttpSetOption an. Weitere Informationen finden Sie in der Option WINHTTP_OPTION_CLIENT_CERT_CONTEXT . Windows Server 2003 mit SP1, Windows XP mit SP2 und Windows 2000: Dieser Fehler wird nicht unterstützt.

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_INVALID_URL
Die URL ist ungültig.
ERROR_WINHTTP_LOGIN_FAILURE
Fehler beim Anmeldeversuch. Wenn dieser Fehler auftritt, sollte das Anforderungshandle mit WinHttpCloseHandle geschlossen werden. Ein neues Anforderungshandle muss erstellt werden, bevor sie die Funktion wiederholen, die ursprünglich diesen Fehler verursacht hat.
ERROR_WINHTTP_NAME_NOT_RESOLVED
Der Servername kann nicht aufgelöst werden.
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_RESPONSE_DRAIN_OVERFLOW
Wird zurückgegeben, wenn eine eingehende Antwort ein internes WinHTTP-Größenlimit überschreitet.
ERROR_WINHTTP_SECURE_FAILURE
Mindestens ein Fehler wurde in dem SSL-Zertifikat (Secure Sockets Layer) gefunden, das vom Server gesendet wurde. Um zu ermitteln, welcher Fehlertyp aufgetreten ist, überprüfen Sie über eine WINHTTP_CALLBACK_STATUS_SECURE_FAILURE Benachrichtigung in einer status Rückruffunktion. Weitere Informationen finden Sie unter WINHTTP_STATUS_CALLBACK.
ERROR_WINHTTP_SHUTDOWN
Die WinHTTP-Funktionsunterstützung wird heruntergefahren oder entladen.
ERROR_WINHTTP_TIMEOUT
Das Zeitlimit der Anforderung wurde überschritten.
ERROR_WINHTTP_UNRECOGNIZED_SCHEME
Die URL hat ein anderes Schema als "http:" oder "https:" angegeben.
ERROR_NOT_ENOUGH_MEMORY
Für den angeforderten Vorgang war nicht genügend Arbeitsspeicher verfügbar. (Windows-Fehlercode)

Windows Server 2003, Windows XP und Windows 2000: Der TCP-Reservierungsbereich, der mit der Option WINHTTP_OPTION_PORT_RESERVATION festgelegt ist, ist nicht groß genug, um diese Anforderung zu senden.

ERROR_INVALID_PARAMETER
Die im dwTotalLength-Parameter angegebene Inhaltslänge stimmt nicht mit der im Content-Length-Header angegebenen Länge überein.

Der lpOptional-Parameter muss NULL und der dwOptionalLength-Parameter null sein, wenn der Transfer-Encoding-Header vorhanden ist.

Der Content-Length-Header kann nicht vorhanden sein, wenn der Transfer-Encoding-Header vorhanden ist.

ERROR_WINHTTP_RESEND_REQUEST
Die Anwendung muss WinHttpSendRequest aufgrund einer Umleitungs- oder Authentifizierungsanforderung erneut aufrufen.

Windows Server 2003 mit SP1, Windows XP mit SP2 und Windows 2000: Dieser Fehler wird nicht unterstützt.

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. In beiden Fällen wird die Anwendung zurückgerufen, wenn die Anforderung erfolgreich gesendet wird, und die Vervollständigung status auf WINHTTP_CALLBACK_STATUS_SENDREQUEST_COMPLETE festgelegt. Die WINHTTP_CALLBACK_STATUS_REQUEST_ERROR Vervollständigung gibt an, dass der Vorgang asynchron abgeschlossen wurde, aber ein Fehler aufgetreten ist. Beim Empfang des WINHTTP_CALLBACK_STATUS_SENDREQUEST_COMPLETE status Rückrufs kann die Anwendung beginnen, eine Antwort vom Server mit WinHttpReceiveResponse zu empfangen. Bis dahin können keine anderen asynchronen Funktionen aufgerufen werden, andernfalls wird ERROR_WINHTTP_INCORRECT_HANDLE_STATE zurückgegeben.

Eine Anwendung darf den Puffer, auf den lpOptional verweist, nicht löschen oder ändern, bis das Anforderungshandle geschlossen oder der Aufruf von WinHttpReceiveResponse abgeschlossen ist, da beim Empfang der Antwort eine Authentifizierungsanforderung oder Umleitung auftreten kann, die die optionalen Daten erforderte. Wenn der Vorgang mit WinHttpCloseHandle abgebrochen werden muss, muss die Anwendung den Puffer gültig halten, bis sie den Rückruf WINHTTP_CALLBACK_STATUS_REQUEST_ERROR mit einem ERROR_WINHTTP_OPERATION_CANCELLED Fehlercode empfängt.

Wenn WinHTTP synchron verwendet wird, d. h. wenn WINHTP_FLAG_ASYNC nicht in WinHttpOpen festgelegt wurde, wird eine Anwendung nicht mit einer Vervollständigung status aufgerufen, auch wenn eine Rückruffunktion registriert ist. In diesem Modus kann die Anwendung WinHttpReceiveResponse aufrufen, wenn WinHttpSendRequest zurückgibt.

Die WinHttpSendRequest-Funktion sendet die angegebene Anforderung an den HTTP-Server und ermöglicht es dem Client, zusätzliche Header anzugeben, die zusammen mit der Anforderung gesendet werden sollen.

Mit dieser Funktion kann der Client auch optionale Daten angeben, die unmittelbar nach den Anforderungsheadern an den HTTP-Server gesendet werden sollen. Dieses Feature wird im Allgemeinen für Schreibvorgänge wie PUT und POST verwendet.

Eine Anwendung kann dasselbe HTTP-Anforderungshandle in mehreren Aufrufen von WinHttpSendRequest verwenden, um dieselbe Anforderung erneut zu senden. Die Anwendung muss jedoch alle vom vorherigen Aufruf zurückgegebenen Daten lesen, bevor diese Funktion erneut aufgerufen wird.

Der Name und der Wert der Mit dieser Funktion hinzugefügten Anforderungsheader werden überprüft. Header müssen wohlgeformt sein. Weitere Informationen zu gültigen HTTP-Headern finden Sie unter RFC 2616. Wenn ein ungültiger Header verwendet wird, schlägt diese Funktion fehl, und GetLastError gibt ERROR_INVALID_PARAMETER zurück. Der ungültige Header wird nicht hinzugefügt.

Windows 2000: Beim Senden von Anforderungen von mehreren Threads kann es zu einer erheblichen Abnahme der Netzwerk- und CPU-Leistung kommen.

Windows XP und Windows 2000: Siehe Laufzeitanforderungen.

WinHttpSetStatusCallback

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 der Anforderung an:
  • WINHTTP_CALLBACK_STATUS_DETECTING_PROXY (nicht implementiert)
  • WINHTTP_CALLBACK_STATUS_SENDREQUEST_COMPLETE (nur im asynchronen Modus)
  • WINHTTP_CALLBACK_STATUS_REDIRECT
  • WINHTTP_CALLBACK_STATUS_SECURE_FAILURE
  • WINHTTP_CALLBACK_STATUS_INTERMEDIATE_RESPONSE
Hinweis Unter Windows 7 und Windows Server 2008 R2 sind alle folgenden Benachrichtigungen veraltet.
 
  • 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
Wenn der Server die Verbindung schließt, werden auch die folgenden Benachrichtigungen gesendet, sofern sie im dwNotificationFlags-Parameter von WinHttpSetStatusCallback festgelegt wurden:
  • WINHTTP_CALLBACK_STATUS_CLOSING_CONNECTION
  • WINHTTP_CALLBACK_STATUS_CONNECTION_CLOSED

Unterstützung für mehr als 4 GB Upload

Ab Windows Vista und Windows Server 2008 unterstützt WinHttp das Hochladen von Dateien bis zur Größe eines LARGE_INTEGER (2^64 Bytes) mithilfe des Headers Content-Length. Nutzlastlängen, die im Aufruf von WinHttpSendRequest angegeben werden, sind auf die Größe eines DWORD -Werts (2^32 Bytes) beschränkt. Um Daten in eine URL hochzuladen, die größer als ein DWORD ist, muss die Anwendung die Länge im Content-Length-Header der Anforderung angeben. In diesem Fall ruft die WinHttp-Clientanwendung WinHttpSendRequest auf, wobei der dwTotalLength-Parameter auf WINHTTP_IGNORE_REQUEST_TOTAL_LENGTH festgelegt ist.

Wenn der Content-Length-Header eine Länge kleiner als 2^32 angibt, muss die Anwendung auch die Inhaltslänge im Aufruf von WinHttpSendRequest angeben. Wenn der dwTotalLength-Parameter nicht mit der im Content-Length-Header angegebenen Länge übereinstimmt, schlägt der Aufruf fehl und gibt ERROR_INVALID_PARAMETER zurück.

Der Content-Length-Header kann im Aufruf von WinHttpAddRequestHeaders hinzugefügt oder im lpszHeader-Parameter von WinHttpSendRequest angegeben werden, wie im folgenden Codebeispiel gezeigt.

BOOL fRet = WinHttpSendRequest(
			hReq,
			L"Content-Length: 68719476735\r\n",
			-1L,
			WINHTTP_NO_REQUEST_DATA,
			0,
			WINHTTP_IGNORE_REQUEST_TOTAL_LENGTH,
			pMyContent);

Transfercodierungsheader

Ab Windows Vista und Windows Server 2008 ermöglicht WinHttp Anwendungen das Ausführen einer Codierung für die Codierung von daten, die an den Server gesendet werden. Wenn der Transfer-Encoding-Header in der WinHttp-Anforderung vorhanden ist, wird der dwTotalLength-Parameter im Aufruf von WinHttpSendRequest auf WINHTTP_IGNORE_REQUEST_TOTAL_LENGTH festgelegt, und die Anwendung sendet den Entitätstext in einem oder mehreren Aufrufen von WinHttpWriteData. Der lpOptional-Parameter von WinHttpSendRequest muss NULL und der dwOptionLength-Parameter 0 sein, andernfalls wird ein ERROR_WINHTTP_INVALID_PARAMETER-Fehler zurückgegeben. Um die blockierte Datenübertragung zu beenden, generiert die Anwendung einen Block der Länge null und sendet ihn beim letzten Aufruf von WinHttpWriteData.

Beispiele

Das folgende Codebeispiel zeigt, wie Sie ein HINTERNET-Handle abrufen, eine HTTP-Sitzung öffnen, einen Anforderungsheader erstellen und diesen Header an den Server senden.

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

Anforderungen

Anforderung Wert
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.

Weitere Informationen

Informationen zu Microsoft Windows HTTP-Diensten (WinHTTP)

WINHTTP_STATUS_CALLBACK

WinHTTP-Versionen

WinHttpCloseHandle

WinHttpConnect

WinHttpOpen

WinHttpOpenRequest

WinHttpReceiveResponse