Share via


CFile::CFile

Constructs and initializes a CFile object.

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

Parameters

  • hFile
    Handle of a file to attach to the CFile object.

  • lpszFileName
    Relative or full path of a file to attach to the CFile object.

  • nOpenFlags
    Bitwise combination (OR) of file access options for the specified file. See the Remarks section for possible options.

  • pTM
    Pointer to CAtlTransactionManager object

Remarks

The following five tables list the possible options for the nOpenFlags parameter.

Choose only one of the following file access mode options. The default file access mode is CFile::modeRead, which is read only.

Value

Description

CFile::modeRead

Requests read access only.

CFile::modeWrite

Requests write access only.

CFile::modeReadWrite

Requests read and write access.

Choose one of the following character mode options.

Value

Description

CFile::typeBinary

Sets binary mode (used in derived classes only).

CFile::typeText

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

CFile::typeUnicode

Sets Unicode mode (used in derived classes only). Text is written to the file in Unicode format when the application is built in a Unicode configuration. No BOM is written to the file.

Choose only one of the following file share mode options. The default file share mode is CFile::shareExclusive, which is exclusive.

Value

Description

CFile::shareDenyNone

No sharing restrictions.

CFile::shareDenyRead

Denies read access to all others.

CFile::shareDenyWrite

Denies write access to all others.

CFile::shareExclusive

Denies read and write access to all others.

Choose the first, or both, of the following file creation mode options. The default creation mode is CFile::modeNoTruncate, which is open existing.

Value

Description

CFile::modeCreate

Creates a new file if no file exists.; If the file already exists, CFileException is raised.

CFile::modeNoTruncate

Creates a new file if no file exists; otherwise, if the file already exists, it is attached to the CFile object.

Choose the following file caching options as described. By default, the system uses a general purpose caching scheme that is not available as an option.

Value

Description

CFile::osNoBuffer

The system does not use an intermediate cache for the file. This option cancels the following 2 options.

CFile::osRandomAccess

The file cache is optimized for random access. Do not use this option and the sequential scan option.

CFile::osSequentialScan

The file cache is optimized for sequential access. Do not use this option and the random access option.

CFile::osWriteThrough

Write operations are performed without delay.

Choose the following security option to prevent the file handle from being inherited. By default, any new child processes can use the file handle.

Value

Description

CFile::modeNoInherit

Prevents any child processes from using the file handle.

The default constructor initializes members but does not attach a file to the CFile object. After using this constructor, use the CFile::Open method to open a file and attach it to the CFile object.

The constructor with one parameter initializes members and attaches an existing file to the CFile object.

The constructor with two parameters initializes members and tries to open the specified file. If this constructor successfully opens the specified file, the file is attached to the CFile object; otherwise, this constructor throws a pointer to a CInvalidArgException object. For more information about how to handle exceptions, see Exceptions.

If a CFile object successfully opens a specified file, it will close this file automatically when the CFile object is destroyed; otherwise, you must explicitly close the file after it is no longer attached to the CFile object.

Example

The following code shows how to use a 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 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

Reference

CFile Class

Hierarchy Chart