Freigeben über

CHttpFile-Klasse

  • Artikel

Stellt die Funktionalität bereit, um Dateien auf einem HTTP-Server anfordern und zu lesen.

Syntax

class CHttpFile : public CInternetFile

Member

Geschützte Konstruktoren

Name Beschreibung
CHttpFile::CHttpFile Erstellt ein CHttpFile-Objekt.

Öffentliche Methoden

Name Beschreibung
CHttpFile::AddRequestHeaders Fügt der anforderung, die an einen HTTP-Server gesendet wird, Header hinzu.
CHttpFile::EndRequest Beendet eine an einen HTTP-Server gesendete Anforderung mit der SendRequestEx-Memberfunktion .
CHttpFile::GetFileURL Ruft die URL für die angegebene Datei ab.
CHttpFile::GetObject Ruft das Zielobjekt des Verbs in einer Anforderung an einen HTTP-Server ab.
CHttpFile::GetVerb Ruft das Verb ab, das in einer Anforderung an einen HTTP-Server verwendet wurde.
CHttpFile::QueryInfo Gibt die Antwort- oder Anforderungsheader vom HTTP-Server zurück.
CHttpFile::QueryInfoStatusCode Ruft den Statuscode ab, der einer HTTP-Anforderung zugeordnet ist, und platziert ihn im angegebenen dwStatusCode Parameter.
CHttpFile::SendRequest Sendet eine Anforderung an einen HTTP-Server.
CHttpFile::SendRequestEx Sendet eine Anforderung an einen HTTP-Server mit den Methoden Write oder WriteString von CInternetFile.

Hinweise

Wenn Ihre Internetsitzung Daten von einem HTTP-Server liest, müssen Sie eine Instanz von CHttpFile.

Weitere Informationen zur CHttpFile Funktionsweise mit den anderen MFC-Internetklassen finden Sie im Artikel "Internet Programming with WinInet".

Vererbungshierarchie

CObject

CFile

CStdioFile

CInternetFile

CHttpFile

Anforderungen

Kopfzeile: afxinet.h

CHttpFile::AddRequestHeaders

Rufen Sie diese Memberfunktion auf, um dem HTTP-Anforderungshandle einen oder mehrere HTTP-Anforderungsheader hinzuzufügen.

BOOL AddRequestHeaders(
    LPCTSTR pstrHeaders,
    DWORD dwFlags = HTTP_ADDREQ_FLAG_ADD_IF_NEW,
    int dwHeadersLen = -1);

BOOL AddRequestHeaders(
    CString& str,
    DWORD dwFlags = HTTP_ADDREQ_FLAG_ADD_IF_NEW);

Parameter

pstrHeaders
Ein Zeiger auf eine Zeichenfolge, die die Kopf- oder Kopfzeilen enthält, die an die Anforderung angefügt werden sollen. Jeder Header muss durch ein CR/LF-Paar beendet werden.

dwFlags
Ändert die Semantik der neuen Kopfzeilen. Dabei kann es sich um eine der folgenden Methoden handeln:

  • HTTP_ADDREQ_FLAG_COALESCE Führt Kopfzeilen mit demselben Namen zusammen, wobei das Kennzeichen verwendet wird, um die erste Kopfzeile, die der nachfolgenden Kopfzeile gefunden wurde, hinzuzufügen. Beispielsweise führt "Accept: text/*" gefolgt von "Accept: audio/*" zur Bildung der einzelnen Kopfzeile "Accept: text/*, audio/*". Es liegt an der aufrufenden Anwendung, ein zusammenhängendes Schema in Bezug auf die von Anforderungen empfangenen Daten sicherzustellen, die mit zusammengefügten oder getrennten Headern gesendet werden.

  • HTTP_ADDREQ_FLAG_REPLACE Führt eine Entfernung aus und fügt hinzu, um die aktuelle Kopfzeile zu ersetzen. Der Kopfzeilenname wird verwendet, um die aktuelle Kopfzeile zu entfernen, und der vollständige Wert wird verwendet, um den neuen Header hinzuzufügen. Wenn der Headerwert leer ist und die Kopfzeile gefunden wird, wird er entfernt. Wenn nicht leer, wird der Kopfzeilenwert ersetzt.

  • HTTP_ADDREQ_FLAG_ADD_IF_NEW Fügt die Kopfzeile nur hinzu, wenn sie noch nicht vorhanden ist. Wenn vorhanden, wird ein Fehler zurückgegeben.

  • HTTP_ADDREQ_FLAG_ADD Wird mit REPLACE verwendet. Fügt die Kopfzeile hinzu, wenn sie nicht vorhanden ist.

dwHeadersLen
Die Länge (in Zeichen) von pstrHeaders. Wenn dies -1L ist, wird pstrHeaders als null beendet und die Länge berechnet.

str
Ein Verweis auf ein CString-Objekt , das den Anforderungsheader oder header enthält, die hinzugefügt werden sollen.

Rückgabewert

Ungleich Null, wenn erfolgreich, andernfalls 0 (Null). Wenn der Aufruf fehlschlägt, kann die Win32-Funktion GetLastError aufgerufen werden, um die Ursache des Fehlers zu ermitteln.

Hinweise

AddRequestHeaders fügt zusätzliche, freiformatige Header an das HTTP-Anforderungshandle an. Es ist für die Verwendung durch anspruchsvolle Clients vorgesehen, die detaillierte Kontrolle über die genaue Anforderung benötigen, die an den HTTP-Server gesendet wird.

Hinweis

Die Anwendung kann mehrere Header in pstrHeaders oder str für einen AddRequestHeaders Anruf mithilfe von HTTP_ADDREQ_FLAG_ADD oder HTTP_ADDREQ_FLAG_ADD_IF_NEW übergeben. Wenn die Anwendung versucht, einen Header mithilfe von HTTP_ADDREQ_FLAG_REMOVE oder HTTP_ADDREQ_FLAG_REPLACE zu entfernen oder zu ersetzen, kann nur ein Header in lpszHeaders bereitgestellt werden.

CHttpFile::CHttpFile

Diese Memberfunktion wird aufgerufen, um ein CHttpFile Objekt zu erstellen.

CHttpFile(
    HINTERNET hFile,
    HINTERNET hSession,
    LPCTSTR pstrObject,
    LPCTSTR pstrServer,
    LPCTSTR pstrVerb,
    DWORD_PTR dwContext);

CHttpFile(
    HINTERNET hFile,
    LPCTSTR pstrVerb,
    LPCTSTR pstrObject,
    CHttpConnection* pConnection);

Parameter

hFile
Ein Handle für eine Internetdatei.

hSession
Ein Handle für eine Internetsitzung.

pstrObject
Ein Zeiger auf eine Zeichenfolge, die das CHttpFile Objekt enthält.

pstrServer
Ein Zeiger auf eine Zeichenfolge, die den Namen des Servers enthält.

pstrVerb
Ein Zeiger auf eine Zeichenfolge, die die Methode enthält, die beim Senden der Anforderung verwendet werden soll. Kann POST, HEAD oder GET sein.

dwContext
Der Kontextbezeichner für das CHttpFile Objekt. Weitere Informationen zu diesem Parameter finden Sie in den Hinweisen .

pConnection
Ein Zeiger auf ein CHttpConnection-Objekt .

Hinweise

Sie erstellen ein CHttpFile Objekt nie direkt. Rufen Sie stattdessen stattdessen CInternetSession::OpenURL oder CHttpConnection::OpenRequest auf.

Der Standardwert wird dwContext von MFC an das CHttpFile Objekt aus dem CInternetSession-Objekt gesendet, das das CHttpFile Objekt erstellt hat. Wenn Sie ein CHttpFile Objekt aufrufen CInternetSession::OpenURL oder CHttpConnection erstellen möchten, können Sie den Standardwert überschreiben, um den Kontextbezeichner auf einen Wert Ihrer Wahl festzulegen. Der Kontextbezeichner wird an CInternetSession::OnStatusCallback zurückgegeben, um den Status des Objekts bereitzustellen, mit dem es identifiziert wird. Weitere Informationen zum Kontextbezeichner finden Sie im Artikel "Internet First Steps: WinInet ".

CHttpFile::EndRequest

Rufen Sie diese Memberfunktion auf, um eine an einen HTTP-Server gesendete Anforderung mit der SendRequestEx-Memberfunktion zu beenden.

BOOL EndRequest(
    DWORD dwFlags = 0,
    LPINTERNET_BUFFERS lpBuffIn = NULL,
    DWORD_PTR dwContext = 1);

Parameter

dwFlags
Flags, die den Vorgang beschreiben. Eine Liste der entsprechenden Flags finden Sie unter HttpEndRequest im Windows SDK.

lpBuffIn
Zeiger auf eine initialisierte INTERNET_BUFFERS , die den für den Vorgang verwendeten Eingabepuffer beschreibt.

dwContext
Der Kontextbezeichner für den CHttpFile-Vorgang. Weitere Informationen zu diesem Parameter finden Sie in den Hinweisen.

Rückgabewert

Ungleich Null, wenn erfolgreich, andernfalls 0 (Null). Wenn der Aufruf fehlschlägt, ermitteln Sie die Ursache des Fehlers, indem Sie das ausgelöste CInternetException-Objekt untersuchen.

Hinweise

Der Standardwert für dwContext wird von MFC an das CHttpFile Objekt aus dem CInternetSession-Objekt gesendet, das das CHttpFile Objekt erstellt hat. Wenn Sie CInternetSession::OpenURL oder CHttpConnection aufrufen, um ein CHttpFile Objekt zu erstellen, können Sie den Standardwert überschreiben, um den Kontextbezeichner auf einen Wert Ihrer Wahl festzulegen. Der Kontextbezeichner wird an CInternetSession::OnStatusCallback zurückgegeben, um den Status des Objekts bereitzustellen, mit dem es identifiziert wird. Weitere Informationen zum Kontextbezeichner finden Sie im Artikel " Internet First Steps: WinInet ".

CHttpFile::GetFileURL

Rufen Sie diese Memberfunktion auf, um den Namen der HTTP-Datei als URL abzurufen.

virtual CString GetFileURL() const;

Rückgabewert

Ein CString-Objekt , das eine URL enthält, die auf die ressource verweist, die dieser Datei zugeordnet ist.

Hinweise

Verwenden Sie diese Memberfunktion nur nach einem erfolgreichen Aufruf von SendRequest oder für ein CHttpFile Objekt, das von OpenURL erfolgreich erstellt wurde.

CHttpFile::GetObject

Rufen Sie diese Memberfunktion auf, um den Namen des diesem CHttpFileZugeordneten Objekts abzurufen.

CString GetObject() const;

Rückgabewert

Ein CString-Objekt , das den Namen des Objekts enthält.

Hinweise

Verwenden Sie diese Memberfunktion nur nach einem erfolgreichen Aufruf von SendRequest oder für ein CHttpFile Objekt, das von OpenURL erfolgreich erstellt wurde.

CHttpFile::GetVerb

Rufen Sie diese Memberfunktion auf, um das DIESEM zugeordnete CHttpFileHTTP-Verb (oder methode) abzurufen.

CString GetVerb() const;

Rückgabewert

Ein CString-Objekt , das den Namen des HTTP-Verbs (oder der Methode) enthält.

Hinweise

Verwenden Sie diese Memberfunktion nur nach einem erfolgreichen Aufruf von SendRequest oder für ein CHttpFile Objekt, das von OpenURL erfolgreich erstellt wurde.

CHttpFile::QueryInfo

Rufen Sie diese Memberfunktion auf, um Antwort- oder Anforderungsheader aus einer HTTP-Anforderung zurückzugeben.

BOOL QueryInfo(
    DWORD dwInfoLevel,
    LPVOID lpvBuffer,
    LPDWORD lpdwBufferLength,
    LPDWORD lpdwIndex = NULL) const;

BOOL QueryInfo(
    DWORD dwInfoLevel,
    CString& str,
    LPDWORD dwIndex = NULL) const;

BOOL QueryInfo(
    DWORD dwInfoLevel,
    SYSTEMTIME* pSysTime,
    LPDWORD dwIndex = NULL) const;

Parameter

dwInfoLevel
Eine Kombination aus dem zu abfragenden Attribut und den folgenden Flags, die den angeforderten Informationstyp angeben:

  • HTTP_QUERY_CUSTOM Findet den Headernamen und gibt diesen Wert in lpvBuffer für die Ausgabe zurück. HTTP_QUERY_CUSTOM löst eine Assertion aus, wenn der Header nicht gefunden wird.

  • HTTP_QUERY_FLAG_REQUEST_HEADERS In der Regel fragt die Anwendung die Antwortheader ab, aber eine Anwendung kann auch Anforderungsheader mithilfe dieses Flags abfragen.

  • HTTP_QUERY_FLAG_SYSTEMTIME Für diese Header, deren Wert eine Datums-/Uhrzeitzeichenfolge ist, z. B. "Last-Modified-Time", gibt dieses Flag den Headerwert als standardmäßige Win32 SYSTEMTIME-Struktur zurück, die die Anwendung nicht zum Analysieren der Daten benötigt. Wenn Sie dieses Kennzeichen verwenden, können Sie die SYSTEMTIME Außerkraftsetzung der Funktion verwenden.

  • HTTP_QUERY_FLAG_NUMBER Bei Kopfzeilen, deren Wert eine Zahl ist, z. B. der Statuscode, gibt dieses Flag die Daten als 32-Bit-Zahl zurück.

Eine Liste der möglichen Werte finden Sie im Abschnitt "Hinweise ".

lpvBuffer
Ein Zeiger auf den Puffer, der die Informationen empfängt.

lpdwBufferLength
Bei der Eingabe verweist dies auf einen Wert, der die Länge des Datenpuffers in Anzahl von Zeichen oder Bytes enthält. Ausführlichere Informationen zu diesem Parameter finden Sie im Abschnitt "Hinweise ".

lpdwIndex
Ein Zeiger auf einen nullbasierten Headerindex. Kann den Wert NULL haben. Verwenden Sie dieses Kennzeichen, um mehrere Kopfzeilen mit demselben Namen aufzählen zu können. Bei eingabe gibt lpdwIndex den Index des angegebenen Headers an, der zurückgegeben werden soll. Bei der Ausgabe gibt lpdwIndex den Index des nächsten Headers an. Wenn der nächste Index nicht gefunden werden kann, wird ERROR_HTTP_HEADER_NOT_FOUND zurückgegeben.

str
Ein Verweis auf das CString-Objekt , das die zurückgegebenen Informationen empfängt.

dwIndex
Ein Indexwert. Siehe lpdwIndex.

pSysTime
Ein Zeiger auf eine Win32 SYSTEMTIME-Struktur .

Rückgabewert

Ungleich Null, wenn erfolgreich, andernfalls 0 (Null). Wenn der Aufruf fehlschlägt, kann die Win32-Funktion GetLastError aufgerufen werden, um die Ursache des Fehlers zu ermitteln.

Hinweise

Verwenden Sie diese Memberfunktion nur nach einem erfolgreichen Aufruf von SendRequest oder für ein CHttpFile Objekt, das von OpenURL erfolgreich erstellt wurde.

Sie können die folgenden Datentypen abrufen aus QueryInfo:

  • Zeichenfolgen (Standard)

  • SYSTEMTIME (für "Data:" Läuft ab:" usw. Kopfzeilen)

  • DWORD (für STATUS_CODE, CONTENT_LENGTH usw.)

Wenn eine Zeichenfolge in den Puffer geschrieben wird und die Memberfunktion erfolgreich ausgeführt wird, lpdwBufferLength enthält die Länge der Zeichenfolge in Zeichen minus 1 für das endende NULL-Zeichen.

Zu den möglichen dwInfoLevel-Werten gehören:

  • HTTP_QUERY_MIME_VERSION

  • HTTP_QUERY_CONTENT_TYPE

  • HTTP_QUERY_CONTENT_TRANSFER_ENCODING

  • HTTP_QUERY_CONTENT_ID

  • HTTP_QUERY_CONTENT_DESCRIPTION

  • HTTP_QUERY_CONTENT_LENGTH

  • HTTP_QUERY_ALLOWED_METHODS

  • HTTP_QUERY_PUBLIC_METHODS

  • HTTP_QUERY_DATE

  • HTTP_QUERY_EXPIRES

  • HTTP_QUERY_LAST_MODIFIED

  • HTTP_QUERY_MESSAGE_ID

  • HTTP_QUERY_URI

  • HTTP_QUERY_DERIVED_FROM

  • HTTP_QUERY_LANGUAGE

  • HTTP_QUERY_COST

  • HTTP_QUERY_WWW_LINK

  • HTTP_QUERY_PRAGMA

  • HTTP_QUERY_VERSION

  • HTTP_QUERY_STATUS_CODE

  • HTTP_QUERY_STATUS_TEXT

  • HTTP_QUERY_RAW_HEADERS

  • HTTP_QUERY_RAW_HEADERS_CRLF

CHttpFile::QueryInfoStatusCode

Rufen Sie diese Memberfunktion auf, um den Statuscode abzurufen, der einer HTTP-Anforderung zugeordnet ist, und platzieren Sie ihn im angegebenen dwStatusCode-Parameter .

BOOL QueryInfoStatusCode(DWORD& dwStatusCode) const;

Parameter

dwStatusCode
Ein Verweis auf einen Statuscode. Statuscodes geben den Erfolg oder Fehler des angeforderten Ereignisses an. Eine Auswahl von Statuscodebeschreibungen finden Sie in den Hinweisen .

Rückgabewert

Ungleich Null, wenn erfolgreich, andernfalls 0 (Null). Wenn der Aufruf fehlschlägt, kann die Win32-Funktion GetLastError aufgerufen werden, um die Ursache des Fehlers zu ermitteln.

Hinweise

Verwenden Sie diese Memberfunktion nur nach einem erfolgreichen Aufruf von SendRequest oder für ein CHttpFile Objekt, das von OpenURL erfolgreich erstellt wurde.

HTTP-Statuscodes werden in Gruppen unterteilt, die den Erfolg oder Fehler der Anforderung angeben. In den folgenden Tabellen werden die Statuscodegruppen und die am häufigsten verwendeten HTTP-Statuscodes beschrieben.

Group Bedeutung
200–299 Erfolgreich
300–399 Informationen
400-499 Anforderungsfehler
500-599 Serverfehler

Allgemeine HTTP-Statuscodes:

Statuscode Bedeutung
200 URL, Übertragung folgt
400 Nicht lesbare Anforderung
404 Die angeforderte URL wurde nicht gefunden.
405 Die angeforderte Methode wird vom Server nicht unterstützt.
500 Unbekannter Serverfehler
503 Serverkapazität erreicht

CHttpFile::SendRequest

Rufen Sie diese Memberfunktion auf, um eine Anforderung an einen HTTP-Server zu senden.

BOOL SendRequest(
    LPCTSTR pstrHeaders = NULL,
    DWORD dwHeadersLen = 0,
    LPVOID lpOptional = NULL,
    DWORD dwOptionalLen = 0);

BOOL SendRequest(
    CString& strHeaders,
    LPVOID lpOptional = NULL,
    DWORD dwOptionalLen = 0);

Parameter

pstrHeaders
Ein Zeiger auf eine Zeichenfolge, die den Namen der zu sendenden Kopfzeilen enthält.

dwHeadersLen
Die Länge der von pstrHeaders identifizierten Header.

lpOptional
Alle optionalen Daten, die unmittelbar nach den Anforderungsheadern gesendet werden sollen. Dies wird in der Regel für POST- und PUT-Vorgänge verwendet. Dies kann NULL sein, wenn keine optionalen Daten gesendet werden.

dwOptionalLen
Die Länge von lpOptional.

strHeaders
Eine Zeichenfolge, die den Namen der Header für die gesendete Anforderung enthält.

Rückgabewert

Ungleich Null, wenn erfolgreich, andernfalls 0 (Null). Wenn der Aufruf fehlschlägt, ermitteln Sie die Ursache des Fehlers, indem Sie das ausgelöste CInternetException-Objekt untersuchen.

CHttpFile::SendRequestEx

Rufen Sie diese Memberfunktion auf, um eine Anforderung an einen HTTP-Server zu senden.

BOOL SendRequestEx(
    DWORD dwTotalLen,
    DWORD dwFlags = HSR_INITIATE,
    DWORD_PTR dwContext = 1);

BOOL SendRequestEx(
    LPINTERNET_BUFFERS lpBuffIn,
    LPINTERNET_BUFFERS lpBuffOut,
    DWORD dwFlags = HSR_INITIATE,
    DWORD_PTR dwContext = 1);

Parameter

dwTotalLen
Die Anzahl der Bytes, die in der Anforderung gesendet werden sollen.

dwFlags
Flags, die den Vorgang beschreiben. Eine Liste der entsprechenden Flags finden Sie unter HttpSendRequestEx im Windows SDK.

dwContext
Der Kontextbezeichner für den CHttpFile-Vorgang. Weitere Informationen zu diesem Parameter finden Sie in den Hinweisen.

lpBuffIn
Zeiger auf eine initialisierte INTERNET_BUFFERS , die den für den Vorgang verwendeten Eingabepuffer beschreibt.

lpBuffOut
Zeiger auf eine initialisierte INTERNET_BUFFERS, die den für den Vorgang verwendeten Ausgabepuffer beschreibt.

Rückgabewert

Nonzero bei erfolgreicher Ausführung. Wenn der Aufruf fehlschlägt, ermitteln Sie die Ursache des Fehlers, indem Sie das ausgelöste CInternetException-Objekt untersuchen.

Hinweise

Mit dieser Funktion kann Ihre Anwendung Daten mithilfe der Methoden Write und WriteString von CInternetFilesenden. Sie müssen die Länge der zu sendenden Daten kennen, bevor Sie eine der beiden Außerkraftsetzungen dieser Funktion aufrufen. Mit der ersten Außerkraftsetzung können Sie die Länge der Daten angeben, die Sie senden möchten. Die zweite Außerkraftsetzung akzeptiert Zeiger auf INTERNET_BUFFERS Strukturen, die verwendet werden können, um den Puffer detailliert zu beschreiben.

Nachdem der Inhalt in die Datei geschrieben wurde, rufen Sie EndRequest auf, um den Vorgang zu beenden.

Der Standardwert für dwContext wird von MFC an das CHttpFile Objekt aus dem CInternetSession-Objekt gesendet, das das CHttpFile Objekt erstellt hat. Wenn Sie CInternetSession::OpenURL oder CHttpConnection aufrufen, um ein CHttpFile Objekt zu erstellen, können Sie den Standardwert überschreiben, um den Kontextbezeichner auf einen Wert Ihrer Wahl festzulegen. Der Kontextbezeichner wird an CInternetSession::OnStatusCallback zurückgegeben, um den Status des Objekts bereitzustellen, mit dem es identifiziert wird. Weitere Informationen zum Kontextbezeichner finden Sie im Artikel "Internet First Steps: WinInet ".

Beispiel

Dieses Codefragment sendet den Inhalt einer Zeichenfolge an eine DLL mit dem Namen MFCISAPI.DLL auf dem LOCALHOST-Server. Während in diesem Beispiel nur ein Aufruf verwendet WriteStringwird, ist die Verwendung mehrerer Aufrufe zum Senden von Daten in Blöcken akzeptabel.

CString strData = _T("Some very long data to be POSTed here!");
pServer = session.GetHttpConnection(_T("localhost"));
pFile = pServer->OpenRequest(CHttpConnection::HTTP_VERB_POST,
                             _T("/MFCISAPI/MFCISAPI.dll?"));
pFile->SendRequestEx(strData.GetLength());

pFile->WriteString(strData);
pFile->EndRequest();

Siehe auch

CInternetFile-Klasse
Hierarchiediagramm
CInternetFile-Klasse
CGopherFile-Klasse
CHttpConnection-Klasse