CFile-Klasse

Artikel
10/12/2023

Die Basisklasse für Microsoft Foundation Class-Dateiklassen.

Syntax

class CFile : public CObject

Member

Öffentliche Konstruktoren

Name	Beschreibung
CFile::CFile	Erstellt ein `CFile` Objekt aus einem Pfad- oder Dateihandle.

Öffentliche Methoden

Name	Beschreibung
CFile::Abort	Schließt eine Datei, die alle Warnungen und Fehler ignoriert.
CFile::Close	Schließt eine Datei und löscht das Objekt.
CFile::D uplicate	Erstellt ein dupliziertes Objekt basierend auf dieser Datei.
CFile::Flush	Löscht alle Daten, die noch geschrieben werden sollen.
CFile::GetFileName	Ruft den Dateinamen der ausgewählten Datei ab.
CFile::GetFilePath	Ruft den vollständigen Dateipfad der ausgewählten Datei ab.
CFile::GetFileTitle	Ruft den Titel der ausgewählten Datei ab.
CFile::GetLength	Ruft die Länge der Datei ab.
CFile::GetPosition	Ruft den aktuellen Dateizeiger ab.
CFile::GetStatus	Ruft den Status der geöffneten Datei oder in der statischen Version ab, ruft den Status der angegebenen Datei ab (statisch, virtuelle Funktion).
CFile::LockRange	Sperrt einen Bytebereich in einer Datei.
CFile::Open	Tresor eine Datei mit einer Fehlertestoption öffnet.
CFile::Read	Liest (ungebufferte) Daten aus einer Datei an der aktuellen Dateiposition.
CFile::Remove	Löscht die angegebene Datei (statische Funktion).
CFile::Rename	Benennt die angegebene Datei um (statische Funktion).
CFile::Seek	Positioniert den aktuellen Dateizeiger.
CFile::SeekToBegin	Positioniert den aktuellen Dateizeiger am Anfang der Datei.
CFile::SeekToEnd	Positioniert den aktuellen Dateizeiger am Ende der Datei.
CFile::SetFilePath	Legt den vollständigen Dateipfad der ausgewählten Datei fest.
CFile::SetLength	Ändert die Länge der Datei.
CFile::SetStatus	Legt den Status der angegebenen Datei fest (statisch, virtuelle Funktion).
CFile::UnlockRange	Entsperrt einen Bytebereich in einer Datei.
CFile::Write	Schreibt (nicht gepufferte) Daten in eine Datei an die aktuelle Dateiposition.

Öffentliche Operatoren

Name	Beschreibung
CFile::operator HANDLE	Ein Handle für ein `CFile` Objekt.

Öffentliche Datenmember

Name	Beschreibung
CFile::hFileNull	Bestimmt, ob das `CFile` Objekt über einen gültigen Handle verfügt.
CFile::m_hFile	Enthält in der Regel das Betriebssystemdateihandle.

Geschützte Datenmember

Name	Beschreibung
CFile::m_pTM	Zeiger auf das `CAtlTransactionManager`-Objekt.

Hinweise

Sie bietet direkt entbufferte, binäre Datenträgereingabe-/Ausgabedienste und unterstützt indirekt Textdateien und Speicherdateien über die abgeleiteten Klassen. CFile arbeitet in Verbindung mit der CArchive Klasse zur Unterstützung der Serialisierung von Microsoft Foundation Class-Objekten.

Die hierarchische Beziehung zwischen dieser Klasse und den abgeleiteten Klassen ermöglicht es Ihrem Programm, auf allen Dateiobjekten über die polymorphe CFile Schnittstelle zu arbeiten. Eine Speicherdatei verhält sich beispielsweise wie eine Datenträgerdatei.

Verwenden Sie CFile und die abgeleiteten Klassen für allgemeine Datenträger-E/A. Verwenden Sie ofstream oder andere Microsoft-Klassen iostream für formatierten Text, der an eine Datenträgerdatei gesendet wird.

Normalerweise wird eine Datenträgerdatei automatisch beim CFile Bau geöffnet und bei der Zerstörung geschlossen. Mit statischen Memberfunktionen können Sie den Status einer Datei abfragen, ohne die Datei zu öffnen.

Weitere Informationen zur Verwendung CFilefinden Sie in den Artikeln "Dateien in MFC " und "Dateibehandlung " in der Laufzeitbibliotheksreferenz.

Vererbungshierarchie

CObject

CFile

Anforderungen

Header: afx.h

CFile::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 CFile::Abort unterscheidet sich dies von CFile::Close zwei wichtigen Methoden. Erstens löst die Abort Funktion keine Ausnahme bei Fehlern aus, da Fehler ignoriert werden.Abort Zweitens wird nicht BESTÄTIGT, Abort wenn die Datei nicht geöffnet wurde oder zuvor geschlossen wurde.

Wenn Sie new das CFile Objekt für den Heap zugeordnet haben, müssen Sie es nach dem Schließen der Datei löschen. Abort festgelegt m_hFile auf CFile::hFileNull.

Beispiel

CStdioFile fileTest;
TCHAR* pszFileName = _T("Abort_File.dat");

// do stuff that may cause exceptions
CFileException ex;
if (!fileTest.Open(pszFileName, CFile::modeWrite, &ex))
{
   ex.ReportError();
   fileTest.Abort();   // close file safely and quietly
}

CFile::CFile

Erstellt und initialisiert ein CFile-Objekt.

CFile();
CFile(CAtlTransactionManager* pTM);
CFile(HANDLE hFile);

CFile(
LPCTSTR lpszFileName,
UINT nOpenFlags);

CFile(
LPCTSTR lpszFileName,
UINT nOpenFlags,
CAtlTransactionManager* pTM);

Parameter

hFile
Handle einer Datei zum Anhängen an das CFile-Objekt.

lpszFileName
Relativer oder vollständiger Pfad einer Datei zum Anhängen an das CFile-Objekt.

nOpenFlags
Bitweise Kombination (OR) der Dateizugriffsoptionen für die angegebene Datei. Mögliche Optionen finden Sie im Abschnitt "Hinweise".

Ptm
Zeiger auf CAtlTransactionManager-Objekt

Hinweise

In den folgenden fünf Tabellen sind die möglichen Optionen für den Parameter nOpenFlags aufgeführt.

Wählen Sie eine der folgenden Dateizugriffsmodus-Optionen. Der standardmäßige Dateizugriffsmodus ist CFile::modeRead, wobei es sich um einen schreibgeschützten Modus handelt.

Wert	Beschreibung
`CFile::modeRead`	Fordert nur Lesezugriff an.
`CFile::modeWrite`	Fordert nur Schreibzugriff an.
`CFile::modeReadWrite`	Fordert Lese- und Schreibzugriff an.

Wählen Sie eine der folgenden Zeichenmodus-Optionen.

Wert	Beschreibung
`CFile::typeBinary`	Legt den Binärmodus fest (nur in abgeleiteten Klassen verwendet).
`CFile::typeText`	Legt den Textmodus mit spezieller Verarbeitung für Wagenrücklauflinienvorschubpaare fest (nur in abgeleiteten Klassen verwendet).
`CFile::typeUnicode`	Legt den Unicode-Modus fest (nur in abgeleiteten Klassen verwendet). Text wird im Unicode-Format in die Datei geschrieben, wenn die Anwendung in einer Unicode-Konfiguration erstellt wurde. Es wird keine BOM in die Datei geschrieben.

Wählen Sie eine der folgenden Dateifreigabemodus-Optionen. Der standardmäßige Dateifreigabemodus ist CFile::shareExclusive, wobei es sich um einen exklusiven Modus handelt.

Wert	Beschreibung
`CFile::shareDenyNone`	Keine Freigabebeschränkungen.
`CFile::shareDenyRead`	Verweigert allen anderen Lesezugriff.
`CFile::shareDenyWrite`	Verweigert allen anderen Schreibzugriff.
`CFile::shareExclusive`	Verweigert allen anderen Lese- und Schreibzugriff.

Wählen Sie die erste oder beide Dateierstellungsmodus-Optionen. Der standardmäßige Dateierstellungsmodus ist CFile::modeNoTruncate, wobei es sich um "offen vorhanden" handelt.

Wert	Beschreibung
`CFile::modeCreate`	Erstellt eine neue Datei, wenn keine Datei vorhanden ist. Wenn die Datei bereits vorhanden ist, wird sie überschrieben und zunächst auf null Länge festgelegt.
`CFile::modeNoTruncate`	Erstellt eine neue Datei, wenn keine Datei vorhanden ist; andernfalls, wenn die Datei bereits vorhanden ist, wird sie an das `CFile` Objekt angefügt.

Wählen Sie die folgenden Datei-Cache-Optionen wie beschrieben. Standardmäßig verwendet das System ein allgemeines Zwischenspeicherungsschema, das nicht als Option verfügbar ist.

Wert	Beschreibung
`CFile::osNoBuffer`	Das System verwendet keinen Zwischencache für die Datei. Diese Option bricht die beiden folgenden Optionen ab.
`CFile::osRandomAccess`	Der Datei-Cache wird für wahlfreien Zugriff optimiert. Verwenden Sie diese Option und die Sequenzscanoption nicht.
`CFile::osSequentialScan`	Der Datei-Cache wird für sequenziellen Zugriff optimiert. Verwenden Sie diese Option und die Option für den zufälligen Zugriff nicht.
`CFile::osWriteThrough`	Schreibvorgänge werden ohne Verzögerung ausgeführt.

Wählen Sie die folgende Sicherheitsoption, um zu verhindern, dass der Dateihandle übergeben wird. Standardmäßig können alle neuen untergeordneten Prozesse den Dateihandle verwenden.

Wert	Beschreibung
`CFile::modeNoInherit`	Verhindert, dass untergeordnete Prozesse den Dateihandle verwenden.

Der Standardkonstruktor initialisiert Elemente, fügt jedoch keine Datei an das CFile Objekt an. Nachdem Sie diesen Konstruktor verwendet haben, verwenden Sie die CFile::Open-Methode , um eine Datei zu öffnen und an das CFile Objekt anzufügen.

Der Konstruktor mit einem Parameter initialisiert Member und hängt eine vorhandene Datei an das CFile-Objekt an.

Der Konstruktor mit zwei Parametern initialisiert Member und versucht, die angegebene Datei zu öffnen. Wenn der Konstruktor die angegebene Datei erfolgreich öffnet, wird die Datei an das CFile-Objekt angehängt; anderenfalls löst der Konstruktor einen Zeiger auf ein CInvalidArgException-Objekt aus. Weitere Informationen zum Behandeln von Ausnahmen finden Sie unter "Ausnahmen".

Wenn ein CFile Objekt eine angegebene Datei erfolgreich öffnet, wird diese Datei automatisch geschlossen, wenn das CFile Objekt zerstört wird. Andernfalls müssen Sie die Datei explizit schließen, nachdem sie nicht mehr an das CFile Objekt angefügt wurde.

Beispiel

Der folgende Code veranschaulicht die Verwendung einer CFile.

HANDLE hFile = CreateFile(_T("CFile_File.dat"),
   GENERIC_WRITE, FILE_SHARE_READ,
   NULL, CREATE_ALWAYS, FILE_ATTRIBUTE_NORMAL, NULL);

if (hFile == INVALID_HANDLE_VALUE)
{
   AfxMessageBox(_T("Couldn't create the file!"));
}
else
{
   // Attach a CFile object to the handle we have.
   CFile myFile(hFile);

   static const TCHAR sz[] = _T("I love CFile!");

   // write string
   myFile.Write(sz, sizeof(sz));

   // We need to call Close() explicitly. Note that there's no need to 
   // call CloseHandle() on the handle returned by the API because 
   // Close() automatically calls CloseHandle() for us.
   myFile.Close();

CFile::Close

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

virtual void Close();

Hinweise

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

Wenn Sie new das CFile Objekt für den Heap zugeordnet haben, müssen Sie es nach dem Schließen der Datei löschen. Close festgelegt m_hFile auf CFile::hFileNull.

Beispiel

Sehen Sie sich das Beispiel für CFile::CFile an.

CFile::D uplicate

Erstellt ein dupliziertes CFile Objekt für eine bestimmte Datei.

virtual CFile* Duplicate() const;

Rückgabewert

Ein Zeiger auf ein dupliziertes CFile Objekt.

Hinweise

Diese Funktion entspricht der C-Laufzeitfunktion _dup.

CFile::Flush

Erzwingt, dass daten erneut in den Dateipuffer geschrieben werden Standard.

virtual void Flush();

Hinweise

Die Verwendung von Flush Puffern garantiert nicht das Leeren von CArchive Puffern. Wenn Sie ein Archiv verwenden, rufen Sie zuerst CArchive::Flush auf.

Beispiel

Sehen Sie sich das Beispiel für CFile::SetFilePath an.

CFile::GetFileName

Rufen Sie diese Memberfunktion auf, um den Namen einer angegebenen Datei abzurufen.

virtual CString GetFileName() const;

Rückgabewert

Der Name der Datei.

Hinweise

Wenn Sie beispielsweise aufrufen GetFileName , um eine Nachricht an den Benutzer über die Datei c:\windows\write\myfile.wrizu generieren, myfile.wriwird der Dateiname zurückgegeben.

Rufen Sie GetFilePath auf, um den gesamten Pfad der Datei einschließlich des Namens zurückzugeben. Rufen Sie GetFileTitle auf, um den Titel der Datei ( myfile) zurückzugeben.

Beispiel

Dieses Codefragment öffnet das SYSTEM. INI-Datei in Ihrem WINDOWS-Verzeichnis. Wenn das Beispiel gefunden wird, wird der Name und der Pfad und der Titel ausgegeben, wie unter "Ausgabe" dargestellt:

try
{
   // try to open the file
   CFile sysFile(_T("C:\\WINDOWS\\SYSTEM.INI"), CFile::modeRead);

   // print out path name and title information
   _tprintf_s(_T("Path is : \"%s\"\n"),
      (LPCTSTR) sysFile.GetFilePath());
   _tprintf_s(_T("Name is : \"%s\"\n"),
      (LPCTSTR) sysFile.GetFileName());
   _tprintf_s(_T("Title is: \"%s\"\n"), 
      (LPCTSTR) sysFile.GetFileTitle());

   // close the file handle
   sysFile.Close();
}
catch (CFileException* pEx)
{
   // if an error occurs, just make a message box
   pEx->ReportError();
   pEx->Delete();
}

CFile::GetFilePath

Rufen Sie diese Memberfunktion auf, um den vollständigen Pfad einer angegebenen Datei abzurufen.

virtual CString GetFilePath() const;

Rückgabewert

Der vollständige Pfad der angegebenen Datei.

Hinweise

Wenn Sie beispielsweise aufrufen GetFilePath , um eine Nachricht an den Benutzer über die Datei c:\windows\write\myfile.wrizu generieren, c:\windows\write\myfile.wriwird der Dateipfad zurückgegeben.

Rufen Sie GetFileName auf, um nur den Namen der Datei (myfile.wri) zurückzugeben. Rufen Sie GetFileTitle auf, um den Titel der Datei (myfile) zurückzugeben.

Beispiel

Sehen Sie sich das Beispiel für GetFileName an.

CFile::GetFileTitle

Rufen Sie diese Memberfunktion auf, um den Dateititel (den Anzeigenamen) für die Datei abzurufen.

virtual CString GetFileTitle() const;

Rückgabewert

Der Titel der zugrunde liegenden Datei.

Hinweise

Diese Methode ruft GetFileTitle auf, um den Titel der Datei abzurufen. Bei erfolgreicher Ausführung gibt die Methode die Zeichenfolge zurück, die das System zum Anzeigen des Dateinamens für den Benutzer verwenden würde. Andernfalls ruft die Methode PathFindFileName auf, um den Dateinamen (einschließlich der Dateierweiterung) der zugrunde liegenden Datei abzurufen. Dies bedeutet, dass die Dateierweiterung nicht immer in der zurückgegebenen Dateititelzeichenfolge enthalten ist. Weitere Informationen finden Sie unter "GetFileTitle " und "PathFindFileName " im Windows SDK.

Rufen Sie GetFilePath auf, um den gesamten Pfad der Datei einschließlich des Namens zurückzugeben. Rufen Sie GetFileName auf, um nur den Namen der Datei zurückzugeben.

Beispiel

Sehen Sie sich das Beispiel für GetFileName an.

CFile::GetLength

Ruft die aktuelle logische Länge der Datei in Byte ab.

virtual ULONGLONG GetLength() const;

Rückgabewert

Die Länge der Datei.

Beispiel

CFile* pFile = NULL;
// Constructing a CFile object with this override may throw
// a CFile exception, and won't throw any other exceptions.
// Calling CString::Format() may throw a CMemoryException,
// so we have a catch block for such exceptions, too. Any
// other exception types this function throws will be
// routed to the calling function.
try
{
   pFile = new CFile(_T("C:\\WINDOWS\\SYSTEM.INI"),
      CFile::modeRead | CFile::shareDenyNone);
   ULONGLONG dwLength = pFile->GetLength();
   CString str;
   str.Format(_T("Your SYSTEM.INI file is %I64u bytes long."), dwLength);
   AfxMessageBox(str);
}
catch (CFileException* pEx)
{
   // Simply show an error message to the user.
   pEx->ReportError();
   pEx->Delete();
}
catch(CMemoryException* pEx)
{
   pEx->ReportError();
   pEx->Delete();
   // We can't recover from this memory exception, so we'll
   // just terminate the app without any cleanup. Normally,
   // an application should do everything it possibly can to
   // clean up properly and _not_ call AfxAbort().
   AfxAbort();
}

// If an exception occurs in the CFile constructor,
// the language will free the memory allocated by new
// and will not complete the assignment to pFile.
// Thus, our clean-up code needs to test for NULL.
if (pFile != NULL)
{
   pFile->Close();
   delete pFile;
}

CFile::GetPosition

Ruft den aktuellen Wert des Dateizeigers ab, der in späteren Aufrufen Seekverwendet werden kann.

virtual ULONGLONG GetPosition() const;

Rückgabewert

Der Dateizeiger.

Beispiel

CFile cfile;
cfile.Open(_T("Seek_File.dat"), CFile::modeCreate |
   CFile::modeReadWrite);
LONGLONG lOffset = 1000;
ULONGLONG lActual;
lActual = cfile.Seek(lOffset, CFile::begin);
ASSERT(cfile.GetPosition() == lActual);

CFile::GetStatus

Diese Methode ruft Statusinformationen im Zusammenhang mit einer bestimmten CFile Objektinstanz oder einem bestimmten Dateipfad ab.

BOOL GetStatus(CFileStatus& rStatus) const;

static BOOL PASCAL GetStatus(
    LPCTSTR lpszFileName,
    CFileStatus& rStatus,
    CAtlTransactionManager* pTM = NULL);

Parameter

rStatus
Ein Verweis auf eine vom Benutzer bereitgestellte CFileStatus Struktur, die die Statusinformationen empfängt. Die CFileStatus Struktur weist die folgenden Felder auf:

CTime m_ctime Das Datum und die Uhrzeit der Erstellung der Datei.
CTime m_mtime Datum und Uhrzeit der letzten Änderung der Datei.
CTime m_atime Datum und Uhrzeit des letzten Zugriffs auf die Datei zum Lesen.
ULONGLONG m_size Die logische Größe der Datei in Byte, wie vom BEFEHL DIR angegeben.
BYTE m_attribute Das Attributbyte der Datei.
char m_szFullName[_MAX_PATH] Der absolute Dateiname im Windows-Zeichensatz.

lpszFileName
Eine Zeichenfolge im Windows-Zeichensatz, bei der es sich um den Pfad zur gewünschten Datei handelt. Der Pfad kann relativ oder absolut sein oder einen Netzwerkpfadnamen enthalten.

Ptm
Zeiger auf CAtlTransactionManager-Objekt

Rückgabewert

TRUE, wenn die Statusinformationen für die angegebene Datei erfolgreich abgerufen werden; andernfalls FALSE.

Hinweise

Die nicht statische Version von GetStatus Ruft Statusinformationen der geöffneten Datei ab, die dem angegebenen CFile Objekt zugeordnet ist. Die statische Version des GetStatus Dateistatus wird aus einem bestimmten Dateipfad abgerufen, ohne die Datei tatsächlich zu öffnen. Diese Version ist nützlich, um das Vorhandensein und die Zugriffsrechte einer Datei zu testen.

Das m_attribute Element der CFileStatus Struktur bezieht sich auf den Datei-Attributsatz. Die CFile Klasse stellt den Attributenumerationstyp bereit, damit Dateiattribute symbolisch angegeben werden können:

enum Attribute {
    normal =    0x00,
    readOnly =  0x01,
    hidden =    0x02,
    system =    0x04,
    volume =    0x08,
    directory = 0x10,
    archive =   0x20
    };

Beispiel

CFile cfile;
cfile.Open(_T("SetLength_File.dat"), CFile::modeCreate |
   CFile::modeReadWrite);
ULONGLONG dwNewLength = 10000;
cfile.SetLength(dwNewLength);
CFileStatus status;
if(cfile.GetStatus(status))    // virtual member function
{
   TRACE(_T("File size = %u\n"), status.m_size);
}
TCHAR* pszFileName = _T("SetLength_File.dat");
if(CFile::GetStatus(pszFileName, status))   // static function
{
   TRACE(_T("Full file name = %s\n"), status.m_szFullName);
}

CFile::hFileNull

Bestimmt das Vorhandensein eines gültigen Dateihandles für das CFile Objekt.

static AFX_DATA const HANDLE hFileNull;

Hinweise

Diese Konstante wird verwendet, um zu ermitteln, ob das CFile Objekt über ein gültiges Dateihandle verfügt.

Im folgenden Beispiel wird dieser Vorgang veranschaulicht:

if (myFile.m_hFile != CFile::hFileNull)
   ;//perform operations on the file
else
   ;//indicate the presence of an invalid handle

CFile::LockRange

Sperrt einen Bytebereich in einer geöffneten Datei und löst eine Ausnahme aus, wenn die Datei bereits gesperrt ist.

virtual void LockRange(
    ULONGLONG dwPos,
    ULONGLONG dwCount);

Parameter

dwPos
Der Byteoffset des Anfangs des zu sperrenden Bytebereichs.

dwCount
Die Anzahl der Bytes im zu sperrenden Bereich.

Hinweise

Das Sperren von Bytes in einer Datei verhindert den Zugriff auf diese Bytes durch andere Prozesse. Sie können mehrere Bereiche einer Datei sperren, aber keine überlappenden Bereiche sind zulässig.

Wenn Sie den Bereich mit der UnlockRange Memberfunktion entsperren, muss der Bytebereich exakt dem Bereich entsprechen, der zuvor gesperrt wurde. Die LockRange Funktion führt keine angrenzenden Bereiche zusammen. Wenn zwei gesperrte Bereiche nebeneinander liegen, müssen Sie jede Region separat entsperren.

Hinweis

Diese Funktion ist für die CMemFileabgeleitete Klasse nicht verfügbar.

Beispiel

CFile cfile;
cfile.Open(_T("LockRange_File.dat"), CFile::modeCreate |
   CFile::modeReadWrite);
ULONGLONG dwPos = 10;
ULONGLONG dwCount = 100;
cfile.LockRange(dwPos, dwCount);

// do something with the file

cfile.UnlockRange(dwPos, dwCount);

CFile::m_hFile

Enthält das Betriebssystemdateihandle für eine geöffnete Datei.

HANDLE m_hFile;

Hinweise

m_hFile ist eine öffentliche Variable vom Typ UINT. Es enthält CFile::hFileNulleine betriebssystemunabhängige leere Dateianzeige, wenn das Handle nicht zugewiesen wurde.

Die Verwendung von wird m_hFile nicht empfohlen, da die Bedeutung des Elements von der abgeleiteten Klasse abhängt. m_hFile wird ein öffentliches Mitglied zur Vereinfachung der Unterstützung nichtpolymorpher Verwendung der Klasse gemacht.

CFile::m_pTM

Zeiger auf ein CAtlTransactionManager Objekt.

CAtlTransactionManager* m_pTM;

Hinweise

CFile::Open

Überladen. Open ist für die Verwendung mit dem Standardkonstruktor CFile vorgesehen.

virtual BOOL Open(
    LPCTSTR lpszFileName,
    UINT nOpenFlags,
    CFileException* pError = NULL);

virtual BOOL Open(
    LPCTSTR lpszFileName,
    UINT nOpenFlags,
    CAtlTransactionManager* pTM,
    CFileException* pError = NULL);

Parameter

lpszFileName
Eine Zeichenfolge, die den Pfad zur gewünschten Datei enthält. Der Pfad kann relativ, absolut oder ein Netzwerkname (UNC) sein.

nOpenFlags
Ein UINT, der den Freigabe- und Zugriffsmodus der Datei definiert. Es gibt die Aktion an, die beim Öffnen der Datei ausgeführt werden soll. Sie können Optionen kombinieren, indem Sie den Bitweise-OR ( ) -Operator verwenden | . Eine Zugriffsberechtigung und eine Freigabeoption sind erforderlich; die modeCreate Modi sind modeNoInherit optional. Eine Liste der Modusoptionen finden Sie im CFile-Konstruktor .

pError
Ein Zeiger auf ein vorhandenes Datei-Ausnahmeobjekt, das den Status eines fehlgeschlagenen Vorgangs empfängt.

Ptm
Zeiger auf CAtlTransactionManager-Objekt

Rückgabewert

Nonzero, wenn das Öffnen erfolgreich war; andernfalls 0. Der pError-Parameter ist nur dann sinnvoll, wenn 0 zurückgegeben wird.

Hinweise

Die beiden Open Funktionen sind "sichere" Methoden zum Öffnen einer Datei, bei denen ein Fehler eine normale, erwartete Bedingung ist.

Während der CFile Konstruktor eine Ausnahme in einer Fehlerbedingung auslöst, Open wird FALSE für Fehlerbedingungen zurückgegeben. Open kann jedoch weiterhin ein CFileException-Objekt initialisieren, um den Fehler zu beschreiben. Wenn Sie den pError-Parameter nicht angeben oder NULL für pError übergeben, Open wird FALSE zurückgegeben und kein Fehler ausgelöstCFileException. Wenn Sie einen Zeiger an einen vorhandenen CFileExceptionZeiger übergeben und Open auf einen Fehler stoßen, füllt sie die Funktion mit Informationen, die diesen Fehler beschreiben. Open löst in beiden Fällen keine Ausnahme aus.

Die folgende Tabelle beschreibt die möglichen Ergebnisse von Open.

`pError`	Fehler aufgetreten	Rückgabewert	CFileException-Inhalt
NULL	Nein	TRUE	–
ptr to `CFileException`	Nein	TRUE	unverändert
NULL	Ja	FALSE	–
ptr to `CFileException`	Ja	FALSE	initialisiert, um Fehler zu beschreiben

Beispiel

CFile f;
CFileException e;
TCHAR* pszFileName = _T("Open_File.dat");
if(!f.Open(pszFileName, CFile::modeCreate | CFile::modeWrite, &e))
{
   TRACE(_T("File could not be opened %d\n"), e.m_cause);
}

//A second example for CFile::Open.
//This function uses CFile to copy binary files.
bool BinaryFileCopy(LPCTSTR pszSource, LPCTSTR pszDest)
{
   // constructing these file objects doesn't open them
   CFile sourceFile;
   CFile destFile;

   // we'll use a CFileException object to get error information
   CFileException ex;

   // open the source file for reading
   if (!sourceFile.Open(pszSource,
      CFile::modeRead | CFile::shareDenyWrite, &ex))
   {
      // complain if an error happened
      // no need to delete the ex object

      TCHAR szError[1024];
      ex.GetErrorMessage(szError, 1024);
      _tprintf_s(_T("Couldn't open source file: %1024s"), szError);
      return false;
   }
   else
   {
      if (!destFile.Open(pszDest, CFile::modeWrite |
         CFile::shareExclusive | CFile::modeCreate, &ex))
      {
         TCHAR szError[1024];
         ex.GetErrorMessage(szError, 1024);
         _tprintf_s(_T("Couldn't open source file: %1024s"), szError);

         sourceFile.Close();
         return false;
      }

      BYTE buffer[4096];
      DWORD dwRead;

      // Read in 4096-byte blocks,
      // remember how many bytes were actually read,
      // and try to write that many out. This loop ends
      // when there are no more bytes to read.
      do
      {
         dwRead = sourceFile.Read(buffer, 4096);
         destFile.Write(buffer, dwRead);
      }
      while (dwRead > 0);

      // Close both files

      destFile.Close();
      sourceFile.Close();
   }

   return true;
}

CFile::operator HANDLE

Verwenden Sie diesen Operator, um ein Handle an ein CFile Objekt an Funktionen wie ReadFileEx und GetFileTime zu übergeben, die ein HANDLEObjekt erwarten.

operator HANDLE() const;

CFile::Read

Liest Daten aus der datei, die dem CFile Objekt zugeordnet ist, in einen Puffer.

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

Parameter

lpBuf
Zeigen Sie auf den vom Benutzer bereitgestellten Puffer, der die aus der Datei gelesenen Daten empfängt.

nCount
Die maximale Anzahl von Bytes, die aus der Datei gelesen werden sollen. Bei Textmodusdateien werden Wagenrücklauf-Zeilenvorschubpaare als einzelne Zeichen gezählt.

Rückgabewert

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

Beispiel

CFile cfile;
cfile.Open(_T("Write_File.dat"), CFile::modeCreate | 
   CFile::modeReadWrite);
char pbufWrite[100];
memset(pbufWrite, 'a', sizeof(pbufWrite));
cfile.Write(pbufWrite, 100);         
cfile.Flush();
cfile.SeekToBegin();
char pbufRead[100];
cfile.Read(pbufRead, sizeof(pbufRead));
ASSERT(0 == memcmp(pbufWrite, pbufRead, sizeof(pbufWrite)));

Ein weiteres Beispiel finden Sie unter "CFile::Open".

CFile::Remove

Diese statische Funktion löscht die durch den Pfad angegebene Datei.

static void PASCAL Remove(
    LPCTSTR lpszFileName,
    CAtlTransactionManager* pTM = NULL);

Parameter

lpszFileName
Eine Zeichenfolge, die den Pfad zur gewünschten Datei darstellt. Der Pfad kann relativ oder absolut sein und einen Netzwerknamen enthalten.

Ptm
Zeiger auf CAtlTransactionManager-Objekt

Hinweise

Remove entfernt kein Verzeichnis.

Die Remove Memberfunktion löst eine Ausnahme aus, wenn die verbundene Datei geöffnet ist oder die Datei nicht entfernt werden kann. Diese Funktion entspricht dem DEL-Befehl.

Beispiel

//example for CFile::Remove
TCHAR* pFileName = _T("Remove_File.dat");
try
{
   CFile::Remove(pFileName);
}
catch (CFileException* pEx)
{
   TRACE(_T("File %20s cannot be removed\n"), pFileName);
   pEx->Delete();
}

CFile::Rename

Diese statische Funktion benennt die angegebene Datei um.

static void PASCAL Rename(
    LPCTSTR lpszOldName,
    LPCTSTR lpszNewName,
    CAtlTransactionManager* pTM = NULL);

Parameter

lpszOldName
Der alte Pfad.

lpszNewName
Der neue Pfad.

Ptm
Zeiger auf CAtlTransactionManager-Objekt

Hinweise

Verzeichnisse können nicht umbenannt werden. Diese Funktion entspricht dem BEFEHL REN.

Beispiel

TCHAR* pOldName = _T("Oldname_File.dat");
TCHAR* pNewName = _T("Renamed_File.dat");

try
{
    CFile::Rename(pOldName, pNewName);
}
catch(CFileException* pEx )
{
    TRACE(_T("File %20s not found, cause = %d\n"), pOldName, 
       pEx->m_cause);
    pEx->Delete();
}

CFile::Seek

Positioniert den Dateizeiger in einer geöffneten Datei neu.

virtual ULONGLONG Seek(
LONGLONG lOff,
UINT nFrom);

Parameter

lOff
Die Anzahl der Bytes, mit der der Dateizeiger verschoben werden soll. Positive Werte verschieben den Dateizeiger an das Ende der Datei; Negative Werte verschieben den Dateizeiger an den Anfang der Datei.

nFrom
Position, von der gesucht werden soll. Mögliche Werte finden Sie im Abschnitt Anmerkungen.

Rückgabewert

Die Position des Dateizeigers, wenn die Methode erfolgreich war; andernfalls wird der Rückgabewert nicht definiert, und ein Zeiger auf eine CFileException Ausnahme wird ausgelöst.

Hinweise

In der folgenden Tabelle sind mögliche Werte für den Parameter "nFrom" aufgeführt.

Wert	Beschreibung
`CFile::begin`	Suchen Sie vom Anfang der Datei aus.
`CFile::current`	Suchen Sie vom aktuellen Speicherort des Dateizeigers.
`CFile::end`	Suchen Sie vom Ende der Datei.

Wenn eine Datei geöffnet wird, wird der Dateizeiger auf 0, dem Anfang der Datei, positioniert.

Sie können den Dateizeiger auf eine Position außerhalb des Endes einer Datei festlegen. Wenn Sie dies tun, wird die Größe der Datei erst vergrößert, wenn Sie in die Datei schreiben.

Der Ausnahmehandler für diese Methode muss das Ausnahmeobjekt löschen, nachdem die Ausnahme verarbeitet wurde.

Beispiel

CFile cfile;
cfile.Open(_T("Seek_File.dat"), CFile::modeCreate |
   CFile::modeReadWrite);
LONGLONG lOffset = 1000;
ULONGLONG lActual;
lActual = cfile.Seek(lOffset, CFile::begin);

CFile::SeekToBegin

Legt den Wert des Dateizeigers auf den Anfang der Datei fest.

void SeekToBegin();

Hinweise

SeekToBegin() entspricht Seek( 0L, CFile::begin ).

Beispiel

CFile f;
f.Open(_T("Seeker_File.dat"), CFile::modeCreate |
   CFile::modeReadWrite);
f.SeekToBegin();
ULONGLONG ullEnd = f.SeekToEnd();

CFile::SeekToEnd

Legt den Wert des Dateizeigers auf das logische Ende der Datei fest.

ULONGLONG SeekToEnd();

Rückgabewert

Die Länge der Datei in Byte.

Hinweise

SeekToEnd() entspricht CFile::Seek( 0L, CFile::end ).

Beispiel

CFile f;
f.Open(_T("Seeker_File.dat"), CFile::modeCreate |
   CFile::modeReadWrite);
f.SeekToBegin();
ULONGLONG ullEnd = f.SeekToEnd();

CFile::SetFilePath

Rufen Sie diese Funktion auf, um den Pfad der Datei anzugeben. Wenn beispielsweise der Pfad einer Datei nicht verfügbar ist, wenn ein CFile-Objekt erstellt wird, rufen Sie SetFilePath ihn auf, um sie bereitzustellen.

virtual void SetFilePath(LPCTSTR lpszNewName);

Parameter

lpszNewName
Zeigen Sie auf eine Zeichenfolge, die den neuen Pfad angibt.

Hinweise

Hinweis

SetFilePath öffnet die Datei nicht oder erstellt die Datei; es ordnet das CFile Objekt einfach einem Pfadnamen zu, der dann verwendet werden kann.

Beispiel

TCHAR* pstrName = _T("C:\\test\\SetPath_File.dat");

// open a file
HANDLE hFile = ::CreateFile(pstrName, GENERIC_WRITE, FILE_SHARE_READ,
   NULL, CREATE_ALWAYS, 0, NULL);

if (hFile != INVALID_HANDLE_VALUE)
{
   // attach a CFile object to it
   CFile myFile(hFile);

   // At this point, myFile doesn't know the path name for the file
   // it owns because Windows doesn't associate that information
   // with the handle. Any CFileExceptions thrown by this object
   // won't have complete information.

   // Calling SetFilePath() remedies that problem by letting CFile
   // know the name of the file that's associated with the object.

   myFile.SetFilePath(pstrName);

   // write something to the file and flush it immediately
   DWORD dwValue = 1234;
   myFile.Write(&dwValue, sizeof(dwValue));
   myFile.Flush();

   // destroying the CObject here will call ::CloseHandle() on the file
}

CFile::SetLength

Rufen Sie diese Funktion auf, um die Länge der Datei zu ändern.

virtual void SetLength(ULONGLONG dwNewLen);

Parameter

dwNewLen
Gewünschte Länge der Datei in Byte. Dieser Wert kann größer oder kleiner als die aktuelle Länge der Datei sein. Die Datei wird entsprechend erweitert oder abgeschnitten.

Hinweise

Hinweis

Mit CMemFiledieser Funktion könnte ein CMemoryException Objekt ausgelöst werden.

Beispiel

CFile cfile;
cfile.Open(_T("SetLength_File.dat"), CFile::modeCreate |
   CFile::modeReadWrite);
ULONGLONG dwNewLength = 10000;
cfile.SetLength(dwNewLength);

CFile::SetStatus

Legt den Status der Datei fest, die diesem Dateispeicherort zugeordnet ist.

static void PASCAL SetStatus(
    LPCTSTR lpszFileName,
    const CFileStatus& status,
    CAtlTransactionManager* pTM = NULL);

Parameter

lpszFileName
Eine Zeichenfolge, die den Pfad zur gewünschten Datei darstellt. Der Pfad kann relativ oder absolut sein und einen Netzwerknamen enthalten.

status
Der Puffer, der die neuen Statusinformationen enthält. Rufen Sie die GetStatus Memberfunktion auf, um die CFileStatus Struktur mit aktuellen Werten vorzufüllen, und nehmen Sie dann nach Bedarf Änderungen vor. Wenn ein Wert 0 ist, wird das entsprechende Statuselement nicht aktualisiert. Eine Beschreibung der CFileStatus Struktur finden Sie in der GetStatus-Memberfunktion.

Ptm
Zeiger auf CAtlTransactionManager-Objekt

Hinweise

Um die Uhrzeit festzulegen, ändern Sie das m_mtime Feld des Status.

Wenn Sie einen Aufruf ausführen SetStatus , um nur die Attribute der Datei zu ändern, und das m_mtime Element der Dateistatusstruktur ungleich Null ist, sind die Attribute möglicherweise auch betroffen (das Ändern des Zeitstempels kann Nebenwirkungen auf die Attribute haben). Wenn Sie nur die Attribute der Datei ändern möchten, legen Sie zuerst das m_mtime Element der Dateistatusstruktur auf Null fest und rufen Sie dann auf SetStatus.

Beispiel

TCHAR* pFileName = _T("ReadOnly_File.dat");
CFileStatus status;
CFile::GetStatus(pFileName, status);
status.m_attribute |= CFile::readOnly;
CFile::SetStatus(pFileName, status);

CFile::UnlockRange

Entsperrt einen Bytebereich in einer geöffneten Datei.

virtual void UnlockRange(
    ULONGLONG dwPos,
    ULONGLONG dwCount);

Parameter

dwPos
Der Byteoffset des Anfangs des Bytebereichs, der entsperrt werden soll.

dwCount
Die Anzahl der Bytes im Bereich, die entsperrt werden soll.

Hinweise

Ausführliche Informationen finden Sie in der Beschreibung der LockRange-Memberfunktion .

Hinweis

Diese Funktion ist für die CMemFileabgeleitete Klasse nicht verfügbar.

Beispiel

CFile cfile;
cfile.Open(_T("LockRange_File.dat"), CFile::modeCreate |
   CFile::modeReadWrite);
ULONGLONG dwPos = 10;
ULONGLONG dwCount = 100;
cfile.LockRange(dwPos, dwCount);

// do something with the file

cfile.UnlockRange(dwPos, dwCount);

CFile::Write

Schreibt Daten aus einem Puffer in die datei, die dem CFile Objekt zugeordnet ist.

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

Parameter

lpBuf
Ein Zeiger auf den vom Benutzer bereitgestellten Puffer, der die daten enthält, die in die Datei geschrieben werden sollen.

nCount
Die Anzahl der Bytes, die aus dem Puffer übertragen werden sollen. Bei Textmodusdateien werden Wagenrücklauf-Zeilenvorschubpaare als einzelne Zeichen gezählt.

Hinweise

Write löst eine Ausnahme als Reaktion auf mehrere Bedingungen aus, einschließlich der Datenträger-Vollbedingung.

Beispiel

CFile cfile;
cfile.Open(_T("Write_File.dat"), CFile::modeCreate | 
   CFile::modeReadWrite);
char pbufWrite[100];
memset(pbufWrite, 'a', sizeof(pbufWrite));
cfile.Write(pbufWrite, 100);         
cfile.Flush();

Sehen Sie sich auch die Beispiele für CFile::CFile und CFile::Open an.

Siehe auch

MFC-Beispiel DRAWCLI
CObject-Klasse
Hierarchiediagramm
CStdioFile-Klasse
CMemFile-Klasse