CInternetFile-Klasse

  • Artikel

Ermöglicht den Zugriff auf Dateien auf Remotesystemen, die Internetprotokolle verwenden.

Syntax

class CInternetFile : public CStdioFile

Member

Geschützte Konstruktoren

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

Öffentliche Methoden

Name Beschreibung
CInternetFile::Abort Schließt die Datei, wobei alle Warnungen und Fehler ignoriert werden.
CInternetFile::Close Schließt ein CInternetFile und gibt seine Ressourcen frei.
CInternetFile::Flush Löscht den Inhalt des Schreibpuffers und stellt sicher, dass die Daten im Arbeitsspeicher auf den Zielcomputer geschrieben werden.
CInternetFile::GetLength Gibt die Größe der Datei zurück.
CInternetFile::Read Liest die Anzahl der angegebenen Bytes.
CInternetFile::ReadString Liest einen Zeichenstrom.
CInternetFile::Seek Positioniert den Zeiger in einer geöffneten Datei neu.
CInternetFile::SetReadBufferSize Legt die Größe des Puffers fest, in dem Daten gelesen werden.
CInternetFile::SetWriteBufferSize Legt die Größe des Puffers fest, in den Daten geschrieben werden.
CInternetFile::Write Schreibt die Anzahl der angegebenen Bytes.
CInternetFile::WriteString Schreibt eine mit Null beendete Zeichenfolge in eine Datei.

Öffentliche Operatoren

Name Beschreibung
CInternetFile::operator HINTERNET Ein Umwandlungsoperator für einen Internethandle.

Geschützte Datenmember

Name Beschreibung
CInternetFile::m_hFile Ein Handle für eine Datei.

Hinweise

Stellt eine Basisklasse für die Dateiklassen CHttpFile und CGopherFile bereit. Sie erstellen nie direkt ein CInternetFile Objekt. Erstellen Sie stattdessen ein Objekt einer der abgeleiteten Klassen, indem Sie CGopherConnection::OpenFile oder CHttpConnection::OpenRequest aufrufen. Sie können auch ein CInternetFile Objekt erstellen, indem Sie CFtpConnection::OpenFile aufrufen.

Die CInternetFile Memberfunktionen Open, LockRange, UnlockRange, und Duplicate sind nicht implementiert für CInternetFile. Wenn Sie diese Funktionen für ein CInternetFile Objekt aufrufen, erhalten Sie eine CNotSupportedException.

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

Vererbungshierarchie

CObject

CFile

CStdioFile

CInternetFile

Anforderungen

Kopfzeile: afxinet.h

CInternetFile::Abort

Schließt die diesem Objekt zugeordnete Datei und macht die Datei zum Lesen oder Schreiben nicht verfügbar.

virtual void Abort();

Hinweise

Wenn Sie die Datei noch nicht geschlossen haben, bevor Sie das Objekt zerstören, schließt der Destruktor sie für Sie.

Bei der Behandlung von Ausnahmen Abort unterscheidet sich von Close auf zwei wichtige Weise. Erstens löst die Abort Funktion keine Ausnahme bei Fehlern aus, da fehler ignoriert werden. Zweitens wird nicht bestätigt, Abort ob die Datei noch nicht geöffnet oder zuvor geschlossen wurde.

CInternetFile::CInternetFile

Diese Memberfunktion wird aufgerufen, wenn ein CInternetFile-Objekt erstellt wird.

CInternetFile(
    HINTERNET hFile,
    LPCTSTR pstrFileName,
    CInternetConnection* pConnection,
    BOOL bReadMode);

CInternetFile(
    HINTERNET hFile,
    HINTERNET hSession,
    LPCTSTR pstrFileName,
    LPCTSTR pstrServer,
    DWORD_PTR dwContext,
    BOOL bReadMode);

Parameter

hFile
Ein Handle für eine Internetdatei.

pstrFileName
Ein Zeiger auf eine Zeichenfolge, die den Dateinamen enthält.

pConnection
Ein Zeiger auf ein CInternetConnection-Objekt .

bReadMode
Gibt an, ob die Datei schreibgeschützt ist.

hSession
Ein Handle für eine Internetsitzung.

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

dwContext
Der Kontextbezeichner für das CInternetFile Objekt. Weitere Informationen zum Kontextbezeichner finden Sie unter WinInet Basics .

Hinweise

Sie erstellen nie direkt ein CInternetFile Objekt. Erstellen Sie stattdessen ein Objekt einer der abgeleiteten Klassen, indem Sie CGopherConnection::OpenFile oder CHttpConnection::OpenRequest aufrufen. Sie können auch ein CInternetFile Objekt erstellen, indem Sie CFtpConnection::OpenFile aufrufen.

CInternetFile::Close

Schließt eine CInternetFile Ressource und gibt alle ressourcen frei.

virtual void Close();

Hinweise

Wenn die Datei zum Schreiben geöffnet wurde, gibt es einen impliziten Aufruf von Flush , um sicherzustellen, dass alle gepufferten Daten auf den Host geschrieben werden. Sie sollten aufrufen Close , wenn Sie mit der Verwendung einer Datei fertig sind.

CInternetFile::Flush

Rufen Sie diese Memberfunktion auf, um den Inhalt des Schreibpuffers zu leeren.

virtual void Flush();

Hinweise

Wird Flush verwendet, um sicherzustellen, dass alle Daten im Arbeitsspeicher tatsächlich auf den Zielcomputer geschrieben wurden und ihre Transaktion mit dem Hostcomputer abgeschlossen wurde. Flush ist nur für Objekte wirksam, CInternetFile die zum Schreiben geöffnet wurden.

CInternetFile::GetLength

Gibt die Größe der Datei zurück.

virtual ULONGLONG GetLength() const;

CInternetFile::m_hFile

Ein Handle für die Datei, die diesem Objekt zugeordnet ist.

HINTERNET m_hFile;

CInternetFile::operator HINTERNET

Verwenden Sie diesen Operator, um das Windows-Handle für die aktuelle Internetsitzung abzurufen.

operator HINTERNET() const;

CInternetFile::Read

Rufen Sie diese Memberfunktion auf, um in den angegebenen Speicher zu lesen, beginnend bei lpvBuf, der angegebenen Anzahl von Bytes, nCount.

virtual UINT Read(
    void* lpBuf,
    UINT nCount);

Parameter

lpBuf
Ein Zeiger auf eine Speicheradresse, auf der Dateidaten gelesen werden.

nCount
Die Anzahl der zu schreibenden Bytes.

Rückgabewert

Die Anzahl der in den Puffer übertrageben Bytes. Der Rückgabewert kann kleiner als nCount sein, wenn das Ende der Datei erreicht wurde.

Hinweise

Die Funktion gibt die Anzahl der tatsächlich gelesenen Bytes zurück – eine Zahl, die kleiner als nCount sein kann, wenn die Datei endet. Wenn beim Lesen der Datei ein Fehler auftritt, löst die Funktion ein CInternetException-Objekt aus, das den Fehler beschreibt. Beachten Sie, dass der Lesevorgang nach dem Ende der Datei nicht als Fehler angesehen und keine Ausnahme ausgelöst wird.

Um sicherzustellen, dass alle Daten abgerufen werden, muss eine Anwendung die CInternetFile::Read Methode weiterhin aufrufen, bis die Methode Null zurückgibt.

CInternetFile::ReadString

Rufen Sie diese Memberfunktion auf, um einen Zeichenstrom zu lesen, bis ein Neuzeilenzeichen gefunden wird.

virtual BOOL ReadString(CString& rString);

virtual LPTSTR ReadString(
    LPTSTR pstr,
    UINT nMax);

Parameter

pstr
Ein Zeiger auf eine Zeichenfolge, die die gelesene Zeile empfängt.

nMax
Die maximale Anzahl von Zeichen, die gelesen werden sollen.

rString
Ein Verweis auf das CString-Objekt , das die Lesezeile empfängt.

Rückgabewert

Ein Zeiger auf den Puffer, der einfache Daten enthält, die aus dem CInternetFile-Objekt abgerufen wurden. Unabhängig vom Datentyp des an diese Methode übergebenen Puffers führt er keine Manipulationen für die Daten durch (z. B. Konvertierung in Unicode), sodass Sie die zurückgegebenen Daten der erwarteten Struktur zuordnen müssen, als ob der void * Typ zurückgegeben wurde.

NULL, wenn das Ende der Datei erreicht wurde, ohne Daten zu lesen; oder, wenn boolean, FALSE, wenn das Ende der Datei erreicht wurde, ohne Daten zu lesen.

Hinweise

Die Funktion platziert die resultierende Zeile in den Speicher, auf den der Pstr-Parameter verweist. Sie stoppt das Lesen von Zeichen, wenn sie die maximale Anzahl von Zeichen erreicht, die durch nMax angegeben werden. Der Puffer empfängt immer ein endendes NULL-Zeichen.

Wenn Sie ohne ersten Aufruf von SetReadBufferSize aufrufenReadString, erhalten Sie einen Puffer von 4096 Byte.

CInternetFile::Seek

Rufen Sie diese Memberfunktion auf, um den Zeiger in einer zuvor geöffneten Datei neu zu positionieren.

virtual ULONGLONG Seek(
    LONGLONG lOffset,
    UINT nFrom);

Parameter

lOffset
Versetzt in Bytes, um den Lese-/Schreibzeiger in der Datei zu verschieben.

nFrom
Relativer Bezug für den Offset. Dies muss einer der folgenden Werte sein:

  • CFile::begin Verschieben Sie den Dateizeiger "lOff Bytes" vom Anfang der Datei nach vorne.

  • CFile::current Verschieben Sie den Dateizeiger lOff bytes von der aktuellen Position in der Datei.

  • CFile::end Verschieben Sie den Dateizeiger lOff Bytes vom Ende der Datei. lOff muss negativ sein, um in die vorhandene Datei zu suchen. Positive Werte suchen über das Ende der Datei.

Rückgabewert

Der neue Byte-Offset vom Anfang der Datei, wenn die angeforderte Position legal ist; andernfalls wird der Wert nicht definiert, und ein CInternetException-Objekt wird ausgelöst.

Hinweise

Die Seek Funktion ermöglicht den zufälligen Zugriff auf den Inhalt einer Datei, indem der Zeiger eine bestimmte Menge, absolut oder relativ, verschoben wird. Während der Suche werden keine Daten gelesen.

Derzeit wird ein Aufruf dieser Memberfunktion nur für Daten unterstützt, die Objekten zugeordnet sind CHttpFile . Es wird für FTP- oder Gopher-Anforderungen nicht unterstützt. Wenn Sie einen dieser nicht unterstützten Dienste aufrufen Seek , werden Sie an den Win32-Fehlercode ERROR_INTERNET_INVALID_OPERATION übergeben.

Wenn eine Datei geöffnet wird, befindet sich der Dateizeiger bei Offset 0, dem Anfang der Datei.

Hinweis

Die Verwendung Seek kann dazu führen, dass ein impliziter Aufruf von Flush aufgerufen wird.

Beispiel

Sehen Sie sich das Beispiel für die Implementierung der Basisklasse an ( CFile::Seek).

CInternetFile::SetReadBufferSize

Rufen Sie diese Memberfunktion auf, um die Größe des temporären Lesepuffers festzulegen, der von einem CInternetFileabgeleiteten Objekt verwendet wird.

BOOL SetReadBufferSize(UINT nReadSize);

Parameter

nReadSize
Die gewünschte Puffergröße in Bytes.

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

Die zugrunde liegenden WinInet-APIs führen keine Pufferung durch. Wählen Sie daher eine Puffergröße aus, mit der Ihre Anwendung Daten effizient lesen kann, unabhängig von der zu lesenden Datenmenge. Wenn jeder Aufruf von Read normalerweise einen großen Teil von Daten umfasst (z. B. vier oder mehr Kilobyte), sollten Sie keinen Puffer benötigen. Wenn Sie jedoch aufrufenRead, um kleine Datenblöcke abzurufen, oder wenn Sie ReadString verwenden, um einzelne Zeilen gleichzeitig zu lesen, verbessert ein Lesepuffer die Anwendungsleistung.

Standardmäßig stellt ein CInternetFile Objekt keine Pufferung zum Lesen bereit. Wenn Sie diese Memberfunktion aufrufen, müssen Sie sicherstellen, dass die Datei für den Lesezugriff geöffnet wurde.

Sie können die Puffergröße jederzeit erhöhen, aber das Verkleinern des Puffers hat keine Auswirkung. Wenn Sie ReadString ohne ersten Aufruf aufrufenSetReadBufferSize, erhalten Sie einen Puffer von 4096 Bytes.

CInternetFile::SetWriteBufferSize

Rufen Sie diese Memberfunktion auf, um die Größe des temporären Schreibpuffers festzulegen, der von einem CInternetFileabgeleiteten Objekt verwendet wird.

BOOL SetWriteBufferSize(UINT nWriteSize);

Parameter

nWriteSize
Die Größe des Puffers in Byte.

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

Die zugrunde liegenden WinInet-APIs führen keine Pufferung durch. Wählen Sie daher eine Puffergröße aus, mit der Ihre Anwendung Daten unabhängig von der zu schreibenden Datenmenge effizient schreiben kann. Wenn jeder Aufruf von Write normalerweise eine große Menge an Daten umfasst (z. B. vier oder mehr Kilobyte gleichzeitig), sollten Sie keinen Puffer benötigen. Wenn Sie jedoch "Write" aufrufen, um kleine Datenblöcke zu schreiben, verbessert ein Schreibpuffer die Leistung Ihrer Anwendung.

Standardmäßig stellt ein CInternetFile Objekt keine Pufferung zum Schreiben bereit. Wenn Sie diese Memberfunktion aufrufen, müssen Sie sicherstellen, dass die Datei für den Schreibzugriff geöffnet wurde. Sie können die Größe des Schreibpuffers jederzeit ändern, führt jedoch zu einem impliziten Aufruf von Flush.

CInternetFile::Write

Rufen Sie diese Memberfunktion auf, um in den angegebenen Speicher zu schreiben, lpvBuf, die angegebene Anzahl von Bytes, nCount.

virtual void Write(
    const void* lpBuf,
    UINT nCount);

Parameter

lpBuf
Ein Zeiger auf das erste zu schreibende Byte.

nCount
Gibt die Anzahl der zu schreibenden Bytes an.

Hinweise

Tritt beim Schreiben der Daten ein Fehler auf, löst die Funktion ein CInternetException-Objekt aus, das den Fehler beschreibt.

CInternetFile::WriteString

Diese Funktion schreibt eine mit Null beendete Zeichenfolge in die zugeordnete Datei.

virtual void WriteString(LPCTSTR pstr);

Parameter

pstr
Ein Zeiger auf eine Zeichenfolge, die den zu schreibenden Inhalt enthält.

Hinweise

Tritt beim Schreiben der Daten ein Fehler auf, löst die Funktion ein CInternetException-Objekt aus, das den Fehler beschreibt.

Siehe auch

CStdioFile-Klasse
Hierarchiediagramm
CInternetConnection-Klasse