Klasa CFile

Artykuł
06/16/2023

Klasa bazowa klas plików klasy Microsoft Foundation.

Składnia

class CFile : public CObject

Członkowie

Konstruktory publiczne

Nazwa/nazwisko	opis
CFile::CFile	`CFile` Tworzy obiekt ze ścieżki lub uchwytu pliku.

Metody publiczne

Nazwa/nazwisko	opis
CFile::Abort	Zamyka plik ignorując wszystkie ostrzeżenia i błędy.
CFile::Close	Zamyka plik i usuwa obiekt.
CFile::D uplicate	Tworzy zduplikowany obiekt na podstawie tego pliku.
CFile::Flush	Opróżnia wszystkie dane jeszcze do zapisania.
CFile::GetFileName	Pobiera nazwę pliku wybranego pliku.
CFile::GetFilePath	Pobiera pełną ścieżkę pliku wybranego pliku.
CFile::GetFileTitle	Pobiera tytuł wybranego pliku.
CFile::GetLength	Pobiera długość pliku.
CFile::GetPosition	Pobiera bieżący wskaźnik pliku.
CFile::GetStatus	Pobiera stan otwartego pliku lub w wersji statycznej pobiera stan określonego pliku (funkcja statyczna, wirtualna).
CFile::LockRange	Blokuje zakres bajtów w pliku.
CFile::Open	Sejf otwiera plik z opcją testowania błędów.
CFile::Read	Odczytuje (niebuforowane) dane z pliku w bieżącym położeniu pliku.
CFile::Remove	Usuwa określony plik (funkcja statyczna).
CFile::Rename	Zmienia nazwę określonego pliku (funkcji statycznej).
CFile::Seek	Umieszcza bieżący wskaźnik pliku.
CFile::SeekToBegin	Umieszcza bieżący wskaźnik pliku na początku pliku.
CFile::SeekToEnd	Umieszcza bieżący wskaźnik pliku na końcu pliku.
CFile::SetFilePath	Ustawia pełną ścieżkę pliku wybranego pliku.
CFile::SetLength	Zmienia długość pliku.
CFile::SetStatus	Ustawia stan określonego pliku (statyczna, funkcja wirtualna).
CFile::UnlockRange	Odblokowuje zakres bajtów w pliku.
CFile::Write	Zapisuje (niebuforowane) dane w pliku na bieżącej pozycji pliku.

Operatory publiczne

Nazwa/nazwisko	opis
CFile::operator HANDLE	Uchwyt do `CFile` obiektu.

Publiczne elementy członkowskie danych

Nazwa/nazwisko	opis
CFile::hFileNull	Określa, czy `CFile` obiekt ma prawidłową dojście.
CFile::m_hFile	Zwykle zawiera dojście do plików systemu operacyjnego.

Chronione składowe danych

Nazwa/nazwisko	opis
CFile::m_pTM	Wskaźnik do `CAtlTransactionManager` obiektu.

Uwagi

Zapewnia on bezpośrednio niebuforowane, binarne usługi wejściowe/wyjściowe dysku, a pośrednio obsługuje pliki tekstowe i pliki pamięci za pośrednictwem klas pochodnych. CFile działa w połączeniu z klasą CArchive w celu obsługi serializacji obiektów klasy programu Microsoft Foundation.

Hierarchiczna relacja między tą klasą a jej klasami pochodnymi umożliwia programowi działanie na wszystkich obiektach plików za pośrednictwem interfejsu polimorficznego CFile . Na przykład plik pamięci zachowuje się jak plik dysku.

Użyj CFile i jego klasy pochodne dla operacji we/wy dysku ogólnego przeznaczenia. Użyj ofstream lub innych klas firmy Microsoft iostream do sformatowanego tekstu wysyłanego do pliku dysku.

Zwykle plik dysku jest otwierany automatycznie w CFile trakcie budowy i zamykany w przypadku zniszczenia. Statyczne funkcje składowe umożliwiają przesłuchanie stanu pliku bez otwierania pliku.

Aby uzyskać więcej informacji na temat korzystania z programu CFile, zobacz artykuły Pliki w MFC i Obsługa plików w dokumentacji biblioteki czasu wykonywania.

Hierarchia dziedziczenia

Cobject

CFile

Wymagania

Nagłówek: afx.h

CFile::Abort

Zamyka plik skojarzony z tym obiektem i sprawia, że plik jest niedostępny do odczytu lub zapisu.

virtual void Abort();

Uwagi

Jeśli plik nie został zamknięty przed zniszczeniem obiektu, destruktor zamknie go za Ciebie.

W przypadku obsługi wyjątków CFile::Abort różni się od CFile::Close dwóch ważnych sposobów. Abort Najpierw funkcja nie zgłosi wyjątku dotyczącego błędów, ponieważ błędy są ignorowane przez Abortelement . Po drugie, nie będzie asercją, Abort jeśli plik nie został otwarty lub został wcześniej zamknięty.

Jeśli został użyty new do przydzielenia CFile obiektu na stercie, należy go usunąć po zamknięciu pliku. Abort ustawia wartość m_hFileCFile::hFileNull.

Przykład

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

Tworzy i inicjuje CFile obiekt.

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

CFile(
LPCTSTR lpszFileName,
UINT nOpenFlags);

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

Parametry

hFile
Obsługa pliku w celu dołączenia do CFile obiektu.

lpszFileName
Względna lub pełna ścieżka pliku do dołączenia do CFile obiektu.

nOpenFlags
Kombinacja bitowa (OR) opcji dostępu do pliku dla określonego pliku. Zobacz sekcję Uwagi, aby uzyskać możliwe opcje.

Ptm
Wskaźnik do obiektu CAtlTransactionManager

Uwagi

W poniższych pięciu tabelach wymieniono możliwe opcje parametru nOpenFlags .

Wybierz tylko jedną z następujących opcji trybu dostępu do plików. Domyślnym trybem dostępu do plików jest CFile::modeRead, który jest tylko do odczytu.

Wartość	Opis
`CFile::modeRead`	Żąda dostępu tylko do odczytu.
`CFile::modeWrite`	Żąda dostępu tylko do zapisu.
`CFile::modeReadWrite`	Żąda dostępu do odczytu i zapisu.

Wybierz jedną z następujących opcji trybu znaków.

Wartość	Opis
`CFile::typeBinary`	Ustawia tryb binarny (używany tylko w klasach pochodnych).
`CFile::typeText`	Ustawia tryb tekstowy ze specjalnym przetwarzaniem dla par zestawienia powrotu karetki (używane tylko w klasach pochodnych).
`CFile::typeUnicode`	Ustawia tryb Unicode (używany tylko w klasach pochodnych). Tekst jest zapisywany w pliku w formacie Unicode, gdy aplikacja jest wbudowana w konfigurację Unicode. Żaden element BOM nie jest zapisywany w pliku.

Wybierz tylko jedną z następujących opcji trybu udziału plików. Domyślny tryb udziału plików to CFile::shareExclusive, który jest wyłączny.

Wartość	Opis
`CFile::shareDenyNone`	Brak ograniczeń udostępniania.
`CFile::shareDenyRead`	Odmawia dostępu do odczytu wszystkim innym osobom.
`CFile::shareDenyWrite`	Odmowa dostępu do zapisu we wszystkich innych.
`CFile::shareExclusive`	Odmawia dostępu do odczytu i zapisu we wszystkich innych.

Wybierz pierwszą lub obie z następujących opcji trybu tworzenia plików. Domyślnym trybem tworzenia jest CFile::modeNoTruncate, który jest otwarty w istniejącej.

Wartość	Opis
`CFile::modeCreate`	Tworzy nowy plik, jeśli plik nie istnieje. Jeśli plik już istnieje, zostanie zastąpiony i początkowo ustawiony na zero długości.
`CFile::modeNoTruncate`	Tworzy nowy plik, jeśli nie istnieje plik; w przeciwnym razie, jeśli plik już istnieje, jest on dołączony do `CFile` obiektu.

Wybierz następujące opcje buforowania plików zgodnie z opisem. Domyślnie system używa schematu buforowania ogólnego przeznaczenia, który nie jest dostępny jako opcja.

Wartość	Opis
`CFile::osNoBuffer`	System nie używa pośredniej pamięci podręcznej dla pliku. Ta opcja anuluje następujące 2 opcje.
`CFile::osRandomAccess`	Pamięć podręczna plików jest zoptymalizowana pod kątem dostępu losowego. Nie używaj tej opcji i opcji skanowania sekwencyjnego.
`CFile::osSequentialScan`	Pamięć podręczna plików jest zoptymalizowana pod kątem dostępu sekwencyjnego. Nie używaj tej opcji i opcji dostępu losowego.
`CFile::osWriteThrough`	Operacje zapisu są wykonywane bez opóźnień.

Wybierz następującą opcję zabezpieczeń, aby uniemożliwić dziedziczenie dojścia plików. Domyślnie wszystkie nowe procesy podrzędne mogą używać dojścia do plików.

Wartość	Opis
`CFile::modeNoInherit`	Zapobiega używaniu uchwytu plików przez wszystkie procesy podrzędne.

Domyślny konstruktor inicjuje elementy członkowskie, ale nie dołącza pliku do CFile obiektu. Po użyciu tego konstruktora użyj metody CFile::Open , aby otworzyć plik i dołączyć go do CFile obiektu.

Konstruktor z jednym parametrem inicjuje elementy członkowskie i dołącza istniejący plik do CFile obiektu.

Konstruktor z dwoma parametrami inicjuje elementy członkowskie i próbuje otworzyć określony plik. Jeśli ten konstruktor pomyślnie otworzy określony plik, plik jest dołączony do CFile obiektu. W przeciwnym razie ten konstruktor zgłasza wskaźnik do CInvalidArgException obiektu. Aby uzyskać więcej informacji na temat obsługi wyjątków, zobacz Wyjątki.

CFile Jeśli obiekt pomyślnie otworzy określony plik, zamknie ten plik automatycznie, gdy CFile obiekt zostanie zniszczony. W przeciwnym razie należy jawnie zamknąć plik po tym, jak nie jest już dołączony do CFile obiektu.

Przykład

Poniższy kod pokazuje, jak używać .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

Zamyka plik skojarzony z tym obiektem i sprawia, że plik jest niedostępny do odczytu lub zapisu.

virtual void Close();

Uwagi

Jeśli plik nie został zamknięty przed zniszczeniem obiektu, destruktor zamknie go za Ciebie.

Jeśli został użyty new do przydzielenia CFile obiektu na stercie, należy go usunąć po zamknięciu pliku. Close ustawia wartość m_hFileCFile::hFileNull.

Przykład

Zobacz przykład dla pliku CFile::CFile.

CFile::D uplicate

Tworzy zduplikowany CFile obiekt dla danego pliku.

virtual CFile* Duplicate() const;

Wartość zwracana

Wskaźnik do zduplikowanego CFile obiektu.

Uwagi

Ta funkcja jest równoważna funkcji _dupczasu wykonywania języka C .

CFile::Flush

Wymusza zapisanie wszystkich danych w buforze plików.

virtual void Flush();

Uwagi

Użycie Flush funkcji nie gwarantuje opróżniania buforów CArchive . Jeśli używasz archiwum, najpierw wywołaj metodę CArchive::Flush .

Przykład

Zobacz przykład CFile::SetFilePath.

CFile::GetFileName

Wywołaj tę funkcję składową, aby pobrać nazwę określonego pliku.

virtual CString GetFileName() const;

Wartość zwracana

Nazwa pliku.

Uwagi

Na przykład po wywołaniu GetFileName wywołania w celu wygenerowania komunikatu dla użytkownika o pliku c:\windows\write\myfile.wri, zwracana jest nazwa pliku myfile.wri, .

Aby zwrócić całą ścieżkę pliku, w tym nazwę, wywołaj metodę GetFilePath. Aby zwrócić tytuł pliku ( myfile), wywołaj metodę GetFileTitle.

Przykład

Ten fragment kodu otwiera system. Plik INI w katalogu systemu WINDOWS. Jeśli zostanie znaleziony, w przykładzie zostanie wyświetlona nazwa i ścieżka i tytuł, jak pokazano w obszarze Dane wyjściowe:

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

Wywołaj tę funkcję składową, aby pobrać pełną ścieżkę określonego pliku.

virtual CString GetFilePath() const;

Wartość zwracana

Pełna ścieżka określonego pliku.

Uwagi

Na przykład po wywołaniu GetFilePath wywołania w celu wygenerowania komunikatu do użytkownika o pliku , zwracana jest ścieżka c:\windows\write\myfile.wripliku c:\windows\write\myfile.wri.

Aby zwrócić tylko nazwę pliku (myfile.wri), wywołaj metodę GetFileName. Aby zwrócić tytuł pliku (myfile), wywołaj metodę GetFileTitle.

Przykład

Zobacz przykład GetFileName.

CFile::GetFileTitle

Wywołaj tę funkcję składową, aby pobrać tytuł pliku (nazwę wyświetlaną) pliku.

virtual CString GetFileTitle() const;

Wartość zwracana

Tytuł pliku bazowego.

Uwagi

Ta metoda wywołuje metodę GetFileTitle , aby pobrać tytuł pliku. Jeśli operacja powiedzie się, metoda zwróci ciąg, którego system użyje do wyświetlenia nazwy pliku użytkownikowi. W przeciwnym razie metoda wywołuje metodę PathFindFileName , aby pobrać nazwę pliku (w tym rozszerzenie pliku) pliku bazowego. Oznacza to, że rozszerzenie pliku nie zawsze jest uwzględniane w zwracanym ciągu tytułu pliku. Aby uzyskać więcej informacji, zobacz GetFileTitle i PathFindFileName w zestawie Windows SDK.

Aby zwrócić całą ścieżkę pliku, w tym nazwę, wywołaj metodę GetFilePath. Aby zwrócić tylko nazwę pliku, wywołaj metodę GetFileName.

Przykład

Zobacz przykład GetFileName.

CFile::GetLength

Uzyskuje bieżącą długość logiczną pliku w bajtach.

virtual ULONGLONG GetLength() const;

Wartość zwracana

Długość pliku.

Przykład

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

Uzyskuje bieżącą wartość wskaźnika pliku, która może być używana w kolejnych wywołaniach metody .Seek

virtual ULONGLONG GetPosition() const;

Wartość zwracana

Wskaźnik pliku.

Przykład

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

Ta metoda pobiera informacje o stanie związane z danym CFile wystąpieniem obiektu lub daną ścieżką pliku.

BOOL GetStatus(CFileStatus& rStatus) const;

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

Parametry

rStatus
Odwołanie do struktury dostarczonej przez CFileStatus użytkownika, która będzie otrzymywać informacje o stanie. Struktura CFileStatus ma następujące pola:

CTime m_ctime Data i godzina utworzenia pliku.
CTime m_mtime Data i godzina ostatniej modyfikacji pliku.
CTime m_atime Data i godzina ostatniego dostępu do pliku do odczytu.
ULONGLONG m_size Logiczny rozmiar pliku w bajtach zgłoszony przez polecenie DIR.
BYTE m_attribute Bajt atrybutu pliku.
char m_szFullName[_MAX_PATH] Bezwzględna nazwa pliku w zestawie znaków systemu Windows.

lpszFileName
Ciąg w zestawie znaków systemu Windows, który jest ścieżką do żądanego pliku. Ścieżka może być względna lub bezwzględna lub może zawierać nazwę ścieżki sieciowej.

Ptm
Wskaźnik do obiektu CAtlTransactionManager

Wartość zwracana

WARTOŚĆ TRUE, jeśli informacje o stanie określonego pliku zostały pomyślnie uzyskane; w przeciwnym razie, FAŁSZ.

Uwagi

Wersja GetStatus niestatyczna pobiera informacje o stanie otwartego pliku skojarzonego z danym CFile obiektem. Statyczna wersja GetStatus pliku uzyskuje stan pliku z danej ścieżki pliku bez faktycznego otwierania pliku. Ta wersja jest przydatna do testowania istnienia i praw dostępu do pliku.

Element m_attribute członkowski CFileStatus struktury odwołuje się do zestawu atrybutów pliku. Klasa CFile udostępnia typ wyliczenia atrybutów, dzięki czemu atrybuty pliku można określić symbolicznie:

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

Przykład

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

Określa obecność prawidłowego uchwytu CFile pliku dla obiektu.

static AFX_DATA const HANDLE hFileNull;

Uwagi

Ta stała służy do określania CFile , czy obiekt ma prawidłowy uchwyt pliku.

W poniższym przykładzie pokazano tę operację:

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

CFile::LockRange

Blokuje zakres bajtów w otwartym pliku, zgłaszając wyjątek, jeśli plik jest już zablokowany.

virtual void LockRange(
    ULONGLONG dwPos,
    ULONGLONG dwCount);

Parametry

dwPos
Przesunięcie bajtu początku zakresu bajtów w celu zablokowania.

dwCount
Liczba bajtów w zakresie do zablokowania.

Uwagi

Blokowanie bajtów w pliku uniemożliwia dostęp do tych bajtów przez inne procesy. Możesz zablokować więcej niż jeden region pliku, ale nie są dozwolone żadne nakładające się regiony.

Po odblokowaniu regionu przy użyciu funkcji składowej UnlockRange zakres bajtów musi odpowiadać dokładnie regionowi, który został wcześniej zablokowany. Funkcja LockRange nie scala sąsiednich regionów. Jeśli sąsiadują dwa zablokowane regiony, musisz oddzielnie odblokować każdy region.

Uwaga

Ta funkcja nie jest dostępna dla klasy pochodnej CMemFile.

Przykład

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

Zawiera dojście do plików systemu operacyjnego dla otwartego pliku.

HANDLE m_hFile;

Uwagi

m_hFile jest publiczną zmienną typu UINT. Zawiera CFile::hFileNullon , niezależny od systemu operacyjnego pusty wskaźnik pliku, jeśli dojście nie zostało przypisane.

Użycie elementu m_hFile nie jest zalecane, ponieważ znaczenie elementu członkowskiego zależy od klasy pochodnej. m_hFile jest częścią publiczną dla wygody w obsłudze niepolymorficznego użycia klasy.

CFile::m_pTM

Wskaźnik do CAtlTransactionManager obiektu.

CAtlTransactionManager* m_pTM;

Uwagi

CFile::Open

Przeciążone. Open jest przeznaczony do użycia z konstruktorem domyślnym CFile .

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

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

Parametry

lpszFileName
Ciąg zawierający ścieżkę do żądanego pliku. Ścieżka może być względna, bezwzględna lub nazwa sieci (UNC).

nOpenFlags
Funkcja UINT, która definiuje tryb udostępniania i dostępu do pliku. Określa akcję do wykonania podczas otwierania pliku. Opcje można połączyć za pomocą operatora bitowego OR ( ). | Wymagane jest jedno uprawnienie dostępu i jedna opcja udziału; modeCreate tryby i modeNoInherit są opcjonalne. Zobacz konstruktor CFile, aby uzyskać listę opcji trybu.

Perror
Wskaźnik do istniejącego obiektu wyjątku pliku, który otrzyma stan operacji, która zakończy się niepowodzeniem.

Ptm
Wskaźnik do obiektu CAtlTransactionManager

Wartość zwracana

Nonzero, jeśli otwarcie zakończyło się pomyślnie; w przeciwnym razie 0. Parametr pError ma znaczenie tylko wtedy, gdy zostanie zwrócona wartość 0.

Uwagi

Dwie Open funkcje są "bezpiecznymi" metodami otwierania pliku, gdzie awaria jest normalnym, oczekiwanym warunkiem.

CFile Podczas gdy konstruktor zgłasza wyjątek w warunku błędu, Open zwraca wartość FALSE dla warunków błędu. Open Nadal można zainicjować obiekt CFileException w celu opisania błędu. Jeśli nie podasz parametru pError lub jeśli przekażesz wartość NULL dla błędu pError, Open zwraca wartość FALSE i nie zgłasza wartości CFileException. Jeśli wskaźnik zostanie przekazany do istniejącego CFileExceptionelementu i Open napotka błąd, funkcja wypełni ją informacjami opisującym ten błąd. Open nie zgłasza wyjątku w obu przypadkach.

W poniższej tabeli opisano możliwe wyniki .Open

`pError`	Napotkano błąd	Wartość zwracana	Zawartość CFileException
NULL	Nie.	PRAWDA	nie dotyczy
ptr do `CFileException`	Nie.	PRAWDA	Niezmienione
NULL	Tak	FAŁSZ	nie dotyczy
ptr do `CFileException`	Tak	FAŁSZ	zainicjowane w celu opisania błędu

Przykład

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

Użyj tego operatora, aby przekazać uchwyt do obiektu do CFile funkcji, takich jak ReadFileEx i GetFileTime, które oczekują .HANDLE

operator HANDLE() const;

CFile::Read

Odczytuje dane do buforu z pliku skojarzonego z obiektem CFile .

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

Parametry

lpBuf
Wskaźnik do buforu dostarczonego przez użytkownika, który ma odbierać dane odczytane z pliku.

Ncount
Maksymalna liczba bajtów do odczytu z pliku. W przypadku plików w trybie tekstowym pary zestawienia powrotu karetki są liczone jako pojedyncze znaki.

Wartość zwracana

Liczba bajtów przesłanych do buforu. W przypadku wszystkich CFile klas wartość zwracana może być mniejsza niż nCount , jeśli osiągnięto koniec pliku.

Przykład

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)));

Aby zapoznać się z innym przykładem, zobacz CFile::Open.

CFile::Remove

Ta funkcja statyczna usuwa plik określony przez ścieżkę.

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

Parametry

lpszFileName
Ciąg, który jest ścieżką do żądanego pliku. Ścieżka może być względna lub bezwzględna i może zawierać nazwę sieci.

Ptm
Wskaźnik do obiektu CAtlTransactionManager

Uwagi

Remove nie spowoduje usunięcia katalogu.

Funkcja Remove składowa zgłasza wyjątek, jeśli połączony plik jest otwarty lub nie można usunąć pliku. Ta funkcja jest odpowiednikiem polecenia DEL.

Przykład

//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

Ta funkcja statyczna zmienia nazwę określonego pliku.

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

Parametry

lpszOldName
Stara ścieżka.

lpszNewName
Nowa ścieżka.

Ptm
Wskaźnik do obiektu CAtlTransactionManager

Uwagi

Nie można zmienić nazwy katalogów. Ta funkcja jest odpowiednikiem polecenia REN.

Przykład

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

Zmienia położenie wskaźnika pliku w otwartym pliku.

virtual ULONGLONG Seek(
LONGLONG lOff,
UINT nFrom);

Parametry

lOff
Liczba bajtów do przeniesienia wskaźnika pliku. Wartości dodatnie przenoszą wskaźnik pliku na końcu pliku; wartości ujemne przenoszą wskaźnik pliku do początku pliku.

nFrom
Pozycja do poszukiwania od. Zobacz sekcję Uwagi, aby uzyskać możliwe wartości.

Wartość zwracana

Położenie wskaźnika pliku, jeśli metoda zakończyła się pomyślnie; w przeciwnym razie zwracana wartość jest niezdefiniowana, a wskaźnik do wyjątku CFileException jest zgłaszany.

Uwagi

W poniższej tabeli wymieniono możliwe wartości parametru nFrom .

Wartość	Opis
`CFile::begin`	Szukaj od początku pliku.
`CFile::current`	Poszukaj z bieżącej lokalizacji wskaźnika pliku.
`CFile::end`	Poszukaj na końcu pliku.

Po otwarciu pliku wskaźnik pliku jest umieszczony na 0, początek pliku.

Wskaźnik pliku można ustawić na pozycję poza końcem pliku. Jeśli tak, rozmiar pliku nie zwiększa się, dopóki nie zostanie zapisana w pliku.

Program obsługi wyjątków dla tej metody musi usunąć obiekt wyjątku po przetworzeniu wyjątku.

Przykład

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

Ustawia wartość wskaźnika pliku na początek pliku.

void SeekToBegin();

Uwagi

SeekToBegin() jest równoważne z Seek( 0L, CFile::begin ).

Przykład

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

CFile::SeekToEnd

Ustawia wartość wskaźnika pliku na logiczny koniec pliku.

ULONGLONG SeekToEnd();

Wartość zwracana

Długość pliku w bajtach.

Uwagi

SeekToEnd() jest równoważne z CFile::Seek( 0L, CFile::end ).

Przykład

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

CFile::SetFilePath

Wywołaj tę funkcję, aby określić ścieżkę pliku. Jeśli na przykład ścieżka pliku nie jest dostępna w przypadku konstruowania obiektu CFile , wywołaj metodę SetFilePath , aby ją podać.

virtual void SetFilePath(LPCTSTR lpszNewName);

Parametry

lpszNewName
Wskaźnik do ciągu określającego nową ścieżkę.

Uwagi

Uwaga

SetFilePath nie otwiera pliku ani nie tworzy pliku; po prostu kojarzy CFile obiekt z nazwą ścieżki, której następnie można użyć.

Przykład

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

Wywołaj tę funkcję, aby zmienić długość pliku.

virtual void SetLength(ULONGLONG dwNewLen);

Parametry

dwNewLen
Żądana długość pliku w bajtach. Ta wartość może być większa lub mniejsza niż bieżąca długość pliku. Plik zostanie rozszerzony lub obcięty zgodnie z potrzebami.

Uwagi

Uwaga

W przypadku CMemFilefunkcji ta funkcja może zgłosić CMemoryException obiekt.

Przykład

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

CFile::SetStatus

Ustawia stan pliku skojarzonego z tą lokalizacją pliku.

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

Parametry

lpszFileName
Ciąg, który jest ścieżką do żądanego pliku. Ścieżka może być względna lub bezwzględna i może zawierać nazwę sieci.

status
Bufor zawierający nowe informacje o stanie. Wywołaj funkcję składową GetStatus , aby wstępnie wypełnić CFileStatus strukturę bieżącymi wartościami, a następnie wprowadzić zmiany zgodnie z potrzebami. Jeśli wartość to 0, odpowiedni element stanu nie zostanie zaktualizowany. Aby uzyskać opis CFileStatus struktury, zobacz funkcję składową GetStatus.

Ptm
Wskaźnik do obiektu CAtlTransactionManager

Uwagi

Aby ustawić czas, zmodyfikuj m_mtime pole stanu.

W przypadku wywołania SetStatus metody w celu zmiany tylko atrybutów pliku, a m_mtime element członkowski struktury stanu pliku nie jestzerowy, atrybuty mogą również mieć wpływ (zmiana sygnatury czasowej może mieć wpływ na atrybuty). Jeśli chcesz zmienić tylko atrybuty pliku, najpierw ustaw m_mtime element członkowski struktury stanu pliku na zero, a następnie wywołaj metodę SetStatus.

Przykład

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

CFile::UnlockRange

Odblokuje zakres bajtów w otwartym pliku.

virtual void UnlockRange(
    ULONGLONG dwPos,
    ULONGLONG dwCount);

Parametry

dwPos
Przesunięcie bajtu początku zakresu bajtów do odblokowania.

dwCount
Liczba bajtów w zakresie do odblokowania.

Uwagi

Aby uzyskać szczegółowe informacje, zobacz opis funkcji składowej LockRange .

Uwaga

Ta funkcja nie jest dostępna dla klasy -pochodnej CMemFile.

Przykład

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

Zapisuje dane z buforu do pliku skojarzonego z obiektem CFile .

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

Parametry

lpBuf
Wskaźnik do buforu dostarczonego przez użytkownika, który zawiera dane do zapisania w pliku.

Ncount
Liczba bajtów, które mają zostać przeniesione z buforu. W przypadku plików w trybie tekstowym pary zestawienia powrotu karetki są liczone jako pojedyncze znaki.

Uwagi

Write zgłasza wyjątek w odpowiedzi na kilka warunków, w tym warunek pełny dysku.

Przykład

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();

Zobacz również przykłady plików CFile::CFile i CFile::Open.

Zobacz też

Przykład MFC DRAWCLI
Klasa CObject
Wykres hierarchii
Klasa CStdioFile
Klasa CMemFile