CFile::CFile

Constructs and initializes a CFile object.

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

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.

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 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; otherwise, if the file already exists, it is attached to the CFile object and is truncated to 0 length.
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 CFileException 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

All three constructors are demonstrated in the following code.

// CFile default constructor example.
CFile myFile1; 
CFileException exception;
if(myFile1.Open(_T("ExistingFile.txt"),
    CFile::modeReadWrite, &exception))
{
    // TODO: Perform file reads/writes here. 

    // Close file by choice.
    myFile1.Close();
}
else
{
    // Display exception.
    exception.ReportError();
    // Ensure file is closed. 
    if(myFile1.m_hFile != INVALID_HANDLE_VALUE)
        myFile1.Close();
}

// CFile handle constructor example.
HANDLE myFileHandle = CreateFile(_T("NewFile.txt"),
    GENERIC_WRITE, 0, NULL, CREATE_ALWAYS,
    FILE_ATTRIBUTE_NORMAL, NULL);
if(myFileHandle == INVALID_HANDLE_VALUE)
{
    AfxMessageBox(_T("Cannot Create file"));
}
else
{
    CFile myFile2(myFileHandle);
    try
    {
        myFile2.Write("Sample data", 11);
        // Must close file.
        myFile2.Close();
    }
    catch(CFileException* e)
    {
        e->ReportError();
        e->Delete();
        // Ensure file is closed. 
        if(myFile2.m_hFile != INVALID_HANDLE_VALUE)
            myFile2.Close();
    }
}

// CFile open constructor example. 
try
{
    CFile myFile3(_T("NewFile.txt"), CFile::modeRead);

    // TODO: Perform file reads here. 

    // File closed automatically.
}
catch(CFileException* e)
{
    e->ReportError();
    e->Delete();
}

Requirements

Header: afx.h

See Also

Reference

CFile Class

Hierarchy Chart

Other Resources

CFile Members

Change History

Date	History	Reason
October 2008	Updated whole topic.	Customer feedback.