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 |
|---|---|
|
Wird zurückgegeben, wenn die Verbindung mit dem Server fehlgeschlagen ist. |
|
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. |
|
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. |
|
Der angeforderte Vorgang kann nicht ausgeführt werden, da sich der angegebene Handle nicht im richtigen Zustand befindet. |
|
Der Typ des angegebenen Handles ist für diesen Vorgang falsch. |
|
Ein interner Fehler ist aufgetreten. |
|
Die URL ist ungültig. |
|
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. |
|
Der Servername kann nicht aufgelöst werden. |
|
Der Vorgang wurde abgebrochen, in der Regel, weil der Handle, an dem die Anforderung ausgeführt wurde, vor Abschluss des Vorgangs geschlossen wurde. |
|
Wird zurückgegeben, wenn eine eingehende Antwort ein internes WinHTTP-Größenlimit überschreitet. |
|
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. |
|
Die WinHTTP-Funktionsunterstützung wird heruntergefahren oder entladen. |
|
Das Zeitlimit der Anforderung wurde überschritten. |
|
Die URL hat ein anderes Schema als "http:" oder "https:" angegeben. |
|
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. |
|
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. |
|
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
- 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
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