WinHttpReadData-Funktion (winhttp.h)
Die WinHttpReadData-Funktion liest Daten aus einem Handle, das von der WinHttpOpenRequest-Funktion geöffnet wird.
Siehe auch WinHttpReadDataEx.
Syntax
WINHTTPAPI BOOL WinHttpReadData(
[in] HINTERNET hRequest,
[out] LPVOID lpBuffer,
[in] DWORD dwNumberOfBytesToRead,
[out] LPDWORD lpdwNumberOfBytesRead
);
Parameter
[in] hRequest
Gültiges HINTERNET-Handle, das von einem vorherigen Aufruf von WinHttpOpenRequest zurückgegeben wurde. WinHttpReceiveResponse oder WinHttpQueryDataAvailable muss für dieses Handle aufgerufen und abgeschlossen sein, bevor WinHttpReadData aufgerufen wird. Das Aufrufen von WinHttpReadData unmittelbar nach Abschluss von WinHttpReceiveResponse vermeidet zwar den Aufwand einer Pufferkopie, erfordert jedoch, dass die Anwendung einen Puffer mit fester Länge zum Lesen verwendet.
[out] lpBuffer
Zeiger auf einen Puffer, der die gelesenen Daten empfängt. Stellen Sie sicher, dass dieser Puffer gültig bleibt, bis WinHttpReadData abgeschlossen ist.
[in] dwNumberOfBytesToRead
Unsigned long integer value that contains the number of bytes to read.
[out] lpdwNumberOfBytesRead
Zeiger auf eine variable Long-Integer ohne Vorzeichen, die die Anzahl der gelesenen Bytes empfängt. WinHttpReadData legt diesen Wert vor der Arbeit oder Fehlerüberprüfung auf 0 (null) fest. Wenn Sie WinHTTP asynchron verwenden, legen Sie diesen Parameter immer auf NULL fest, und rufen Sie die Informationen in der Rückruffunktion ab. Dies kann zu einem Speicherfehler führen.
Rückgabewert
Gibt TRUE zurück, wenn erfolgreich, andernfalls FALSE . Rufen Sie GetLastError auf, um erweiterte Fehlerinformationen zu erhalten. In der folgenden Tabelle werden die zurückgegebenen Fehlercodes aufgeführt.
| Fehlercode | BESCHREIBUNG |
|---|---|
|
Die Verbindung mit dem Server wurde zurückgesetzt oder beendet, oder es wurde ein inkompatibles SSL-Protokoll gefunden. Beispielsweise unterstützt WinHTTP 5.1 SSL2 nur, wenn der Client dies ausdrücklich aktiviert. |
|
Der angeforderte Vorgang kann nicht ausgeführt werden, da sich das angegebene Handle nicht im richtigen Zustand befindet. |
|
Der Typ des angegebenen Handles ist für diesen Vorgang falsch. |
|
Ein interner Fehler ist aufgetreten. |
|
Der Vorgang wurde abgebrochen, in der Regel, weil das Handle, für das die Anforderung ausgeführt wurde, vor Abschluss des Vorgangs geschlossen wurde. |
|
Wird zurückgegeben, wenn eine eingehende Antwort ein internes WinHTTP-Größenlimit überschreitet. |
|
Timeout für die Anforderung. |
|
Es war nicht genügend Arbeitsspeicher verfügbar, um den angeforderten Vorgang abzuschließen. (Windows-Fehlercode) |
Hinweise
Ab Windows Vista und Windows Server 2008 ermöglicht WinHttp Anwendungen das Ausführen einer Blockübertragungscodierung für daten, die an den Server gesendet werden. Wenn der Transfer-Encoding-Header in der WinHttp-Antwort vorhanden ist, entfernt WinHttpReadData die Blockinformationen, bevor die Daten an die Anwendung übergeben werden.
Auch wenn WinHTTP im asynchronen Modus verwendet wird (d. h. wenn WINHTTP_FLAG_ASYNC in WinHttpOpen festgelegt wurde), kann diese Funktion entweder synchron oder asynchron ausgeführt werden. Wenn diese Funktion FALSE zurückgibt, ist bei dieser Funktion ein Fehler aufgetreten, und Sie können GetLastError aufrufen, um erweiterte Fehlerinformationen zu erhalten. Wenn diese Funktion TRUE zurückgibt, verwenden Sie die WINHTTP_CALLBACK_STATUS_READ_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 fehlgeschlagen ist.
Wenn Sie WinHttpReadData synchron verwenden und der Rückgabewert TRUE ist und die Anzahl der gelesenen Bytes null ist, wurde die Übertragung abgeschlossen, und es gibt keine weiteren Bytes, die für das Handle gelesen werden müssen. Dies entspricht dem Erreichen des Dateiendes in einer lokalen Datei. Wenn Sie die Funktion asynchron verwenden, wird der WINHTTP_CALLBACK_STATUS_READ_COMPLETE Rückruf aufgerufen, wobei der dwStatusInformationLength-Parameter auf Null festgelegt ist, wenn das Ende einer Antwort gefunden wird.
WinHttpReadData versucht, den Puffer zu füllen, auf den lpBuffer verweist, bis keine weiteren Daten aus der Antwort verfügbar sind. Wenn nicht genügend Daten vom Server eingetroffen sind, wird der Puffer nicht gefüllt.
Für HINTERNET-Handles , die von der WinHttpOpenRequest-Funktion erstellt und von WinHttpSendRequest gesendet werden, muss ein Aufruf von WinHttpReceiveResponse für das Handle erfolgen, bevor WinHttpReadData verwendet werden kann.
Einzelne Bytezeichen, die mit WinHttpReadData abgerufen werden, werden nicht in Multibytezeichen konvertiert.
Wenn der Lesepuffer sehr klein ist, kann WinHttpReadData synchron abgeschlossen werden, und wenn der WINHTTP_CALLBACK_STATUS_READ_COMPLETE Abschluss dann einen weiteren Aufruf von WinHttpReadData auslöst, kann es zu einem Stapelüberlauf führen. Es empfiehlt sich, einen Lesepuffer zu verwenden, der größer als 8 KB ist.
Wenn nicht genügend Daten vom Server eingetroffen sind, füllt WinHttpReadData den Puffer, auf den lpBuffer verweist, nicht vollständig aus. Der Puffer muss groß genug sein, um die HTTP-Header beim ersten Lesevorgang zu speichern, und beim Lesen von HTML-codierten Verzeichniseinträgen muss er groß genug sein, um mindestens einen vollständigen Eintrag aufzunehmen.
Wenn eine status Rückruffunktion mithilfe von WinHttpSetStatusCallback installiert wurde, zeigen die Benachrichtigungen der folgenden Benachrichtigungen, die im dwNotificationFlags-Parameter von WinHttpSetStatusCallback festgelegt wurden, den Fortschritt bei der Überprüfung nach verfügbaren Daten an:
- WINHTTP_CALLBACK_STATUS_RECEIVING_RESPONSE
- WINHTTP_CALLBACK_STATUS_RESPONSE_RECEIVED
- WINHTTP_CALLBACK_STATUS_CONNECTION_CLOSED
- WINHTTP_CALLBACK_STATUS_READ_COMPLETE
Beispiele
Das folgende Beispiel zeigt, wie Sie mithilfe der Semantik für sichere Transaktionen eine Ressource von einem HTTPS-Server (Secure Hypertext Transfer Protocol) herunterladen. Der Beispielcode initialisiert die WinHTTP-Api (Application Programming Interface), wählt einen HTTPS-Zielserver aus, öffnet und sendet eine Anforderung für diese sichere Ressource.
WinHttpQueryDataAvailable wird mit dem Anforderungshandle verwendet, um zu bestimmen, wie viele Daten zum Herunterladen verfügbar sind. Anschließend wird WinHttpReadData verwendet, um diese Daten zu lesen. Dieser Vorgang wird wiederholt, bis das gesamte Dokument abgerufen und angezeigt wurde.
DWORD dwSize = 0;
DWORD dwDownloaded = 0;
LPSTR pszOutBuffer;
BOOL bResults = FALSE;
HINTERNET hSession = NULL,
hConnect = NULL,
hRequest = NULL;
// Use WinHttpOpen to obtain a session handle.
hSession = WinHttpOpen( L"WinHTTP Example/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.microsoft.com",
INTERNET_DEFAULT_HTTPS_PORT, 0);
// Create an HTTP request handle.
if (hConnect)
hRequest = WinHttpOpenRequest( hConnect, L"GET", NULL,
NULL, WINHTTP_NO_REFERER,
WINHTTP_DEFAULT_ACCEPT_TYPES,
WINHTTP_FLAG_SECURE);
// Send a request.
if (hRequest)
bResults = WinHttpSendRequest( hRequest,
WINHTTP_NO_ADDITIONAL_HEADERS,
0, WINHTTP_NO_REQUEST_DATA, 0,
0, 0);
// End the request.
if (bResults)
bResults = WinHttpReceiveResponse( hRequest, NULL);
// Keep checking for data until there is nothing left.
if (bResults)
{
do
{
// Check for available data.
dwSize = 0;
if (!WinHttpQueryDataAvailable( hRequest, &dwSize))
{
printf( "Error %u in WinHttpQueryDataAvailable.\n",
GetLastError());
break;
}
// No more available data.
if (!dwSize)
break;
// Allocate space for the buffer.
pszOutBuffer = new char[dwSize+1];
if (!pszOutBuffer)
{
printf("Out of memory\n");
break;
}
// Read the Data.
ZeroMemory(pszOutBuffer, dwSize+1);
if (!WinHttpReadData( hRequest, (LPVOID)pszOutBuffer,
dwSize, &dwDownloaded))
{
printf( "Error %u in WinHttpReadData.\n", GetLastError());
}
else
{
printf("%s", pszOutBuffer);
}
// Free the memory allocated to the buffer.
delete [] pszOutBuffer;
// This condition should never be reached since WinHttpQueryDataAvailable
// reported that there are bits to read.
if (!dwDownloaded)
break;
} while (dwSize > 0);
}
else
{
// Report any errors.
printf( "Error %d has occurred.\n", GetLastError() );
}
// Close any 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. |