CFile::CFile

The default constructor does not open a file but rather sets m_hFile to CFile::hFileNull.

CFile( );
CFile(
   HANDLE hFile 
);
CFile(
   LPCTSTR lpszFileName,
   UINT nOpenFlags 
);

Parameters

  • hFile
    The HFILE returned from a previous call to CreateFile, as described in the Windows SDK.

  • lpszFileName
    A string that is the path to the desired file. The path can be relative or absolute.

  • nOpenFlags
    Sharing and access mode. Specifies the action to take when opening the file. You can combine options listed below by using the bitwise-OR (|) operator. One access permission and one share option are required; the modeCreate and modeNoInherit modes are optional. The values are as follows:

    • CFile::modeCreate   Directs the constructor to create a new file. If the file exists already, it is truncated to 0 length.

    • CFile::modeNoTruncate   Combine this value with modeCreate. If the file being created already exists, it is not truncated to 0 length. Furthermore, if the file being created already exists, the underlying file pointer will point to the beginning of the file. This flag guarantees the file to open, either as a newly created file or as an existing file. This might be useful, for example, when opening a settings file that may or may not exist already. This option applies to CStdioFile as well.

    • CFile::modeRead   Opens the file for reading only.

    • CFile::modeReadWrite   Opens the file for reading and writing.

    • CFile::modeWrite   Opens the file for writing only.

    • CFile::modeNoInherit   Prevents the file from being inherited by child processes.

    • CFile::shareDenyNone   Opens the file without denying other processes read or write access to the file. Create fails if the file has been opened in compatibility mode by any other process.

    • CFile::shareDenyRead   Opens the file and denies other processes read access to the file. Create fails if the file has been opened in compatibility mode or for read access by any other process.

    • CFile::shareDenyWrite   Opens the file and denies other processes write access to the file. Create fails if the file has been opened in compatibility mode or for write access by any other process.

    • CFile::shareExclusive   Opens the file with exclusive mode, denying other processes both read and write access to the file. Construction fails if the file has been opened in any other mode for read or write access, even by the current process.

    • CFile::shareCompat   This flag is not available in 32-bit and 64-bit MFC. This flag maps to CFile::shareExclusive when used in CFile::Open.

    • CFile::typeText   Sets text mode with special processing for carriage return–linefeed pairs (used in derived classes only).

    • CFile::typeBinary   Sets binary mode (used in derived classes only).

    • **CFile::osNoBuffer   **The system opens a file with no system caching. For more information see FILE_FLAG_NO_BUFFERING in CreateFile in the Windows SDK.

    • **CFile::osWriteThrough   **The system writes through any intermediate cache and goes directly to disk. For more information see FILE_FLAG_WRITE_THROUGH in CreateFile in the Windows SDK.

    • **CFile::osRandomAccess   **A file is accessed randomly. The system can use this as a hint to optimize file caching.

    • **CFile::osSequentialScan   **A file is accessed sequentially from beginning to end. The system can use this as a hint to optimize file caching. For more information see FILE_FLAG_SEQUENTIAL_SCAN in CreateFile in the Windows SDK.

Remarks

Because this constructor does not throw an exception, it does not make sense to use TRY/CATCH logic. Use the Open member function, then test directly for exception conditions. For a discussion of exception-processing strategy, see the article Exceptions.

The constructor with one argument creates a CFile object that corresponds to an existing operating-system file identified by hFile. No check is made on the access mode or file type. When the CFile object is destroyed, the operating-system file will not be closed. You must close the file yourself.

The constructor with two arguments creates a CFile object and opens the corresponding operating-system file with the given path. This constructor combines the functions of the first constructor and the Open member function. It throws an exception if there is an error while opening the file. Generally, this means that the error is unrecoverable and that the user should be alerted.

Example

For an example using the default constructor, see CFile::Open. For an example using the constructor which throws exceptions, see CATCH.

The HANDLE constructor can be used as in the following code, which creates a file named C:\MyFile.DAT and writes the ANSI characters "Hockey is best!":

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 can call Close() explicitly, but the destructor would have
   // also closed the file for us. Note that there's no need to
   // call the CloseHandle() on the handle returned by the API because
   // MFC will close it for us.
   myFile.Close();

Requirements

Header: afx.h

See Also

Concepts

CFile Class

CFile Members

Hierarchy Chart