Share via


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.