CFile Class

Overview
Quick Reference
Constructors
Methods

Overview

Note

The CFile class handles basic file operations

The structure used for this class is CFile

Quick Reference

Quick Ref

void CFile::CFile()

virtual void CFile::~CFile()

virtual void CFile::Abort()

virtual void CFile::Close()

virtual void CFile::Flush()

virtual unsigned int CFile::GetBufferPtr(unsigned int nCommand, unsigned int __formal)

virtual CString CFile::GetFileName()

virtual CString CFile::GetFilePath()

virtual CString CFile::GetFileTitle()

virtual unsigned long CFile::GetLength()

virtual unsigned long CFile::GetPosition()

int CFile::GetStatus(CFileStatus& rStatus)

virtual int CFile::Open(const char* lpszFileName, unsigned int nOpenFlags, CFileException* pException)

virtual unsigned int CFile::Read(void* lpBuf, unsigned int nCount)

virtual void __stdcall CFile::Remove(const char* lpszFileName) = 0

virtual long CFile::Seek(long lOff, unsigned int nFrom)

virtual void CFile::SetFilePath(const char* lpszNewName)

virtual void CFile::SetLength(unsigned long dwNewLen)

virtual unsigned int CFile::Write(const void* lpBuf, unsigned int nCount)

Constructors

Name	Description
CFile::CFile	Constructs a `CFile` object
CFile::~CFile	Destroys a `CFile` object

CFile::CFile

Constructs a CFile object

void CFile::CFile();

Remarks

Constructs a CFile object

CFile::~CFile

Destroys the CFile object

virtual void CFile::~CFile();

Remarks

Destroys the CFile object

Methods

Name	Description
CFile::Abort	Closes a file ignoring all warnings and errors
CFile::Close	Closes a file and deletes the object
CFile::Flush	Flushes any data yet to be written
CFile::GetBufferPtr
CFile::GetFileName	Retrieves the filename of the selected file
CFile::GetFilePath	Retrieves the full file path of the selected file
CFile::GetFileTitle	Retrieves the title of the selected file
CFile::GetLength	Retrieves the length of the file
CFile::GetPosition	Retrieves the current file pointer
CFile::GetStatus	Retrieves the status of the open file
CFile::Open	Safely opens a file with an error-testing option
CFile::Read	Reads (unbuffered) data from a file at the current file position
CFile::Remove	Deletes the specified file
CFile::Seek	Positions the current file pointer
CFile::SetFilePath	Sets the full file path of the selected file
CFile::SetLength	Changes the length of the file
CFile::Write	Writes (unbuffered) data in a file to the current file position

CFile::Abort

Closes a file ignoring all warnings and errors

virtual void CFile::Abort();

Remarks

If you haven't closed the file before destroying the object, the destructor closes it for you.

When handling exceptions, CFile::Abort differs from CFile::Close in that it won't throw an exception on failures, because failures are ignored by Abort.

CFile::Close

Closes a file and deletes the object

virtual void CFile::Close();

Remarks

If you haven't closed the file before destroying the object, the destructor closes it for you.

CFile::Flush

Flushes any data yet to be written

virtual void CFile::Flush();

Remarks

CFile::GetBufferPtr

virtual unsigned int CFile::GetBufferPtr(
   unsigned int nCommand,
   unsigned int __formal);

Parameters

unsigned int nCommand -
unsigned int __formal -

Return Value

Returns unsigned int

Remarks

CFile::GetFileName

Retrieves the filename of the selected file

virtual CString CFile::GetFileName();

Return Value

Returns a CString

Remarks

To return the entire path of the file, including the name, call CFile::GetFilePath. To return the title of the file (myfile), call CFile::GetFileTitle.

CFile::GetFilePath

Retrieves the full file path of the selected file

virtual CString CFile::GetFilePath();

Return Value

Returns a CString

Remarks

To return just the name of the file (myfile.wri), call CFile::GetFileName. To return the title of the file (myfile), call CFile::GetFileTitle.

CFile::GetFileTitle

Retrieves the title of the selected file

virtual CString CFile::GetFileTitle();

Return Value

Returns a CString

Remarks

To return the entire path of the file, including the name, call CFile::GetFilePath. To return just the name of the file, call CFile::GetFileName.

CFile::GetLength

Obtains the current logical length of the file in bytes.

virtual unsigned long CFile::GetLength();

Return Value

Returns unsigned long

Remarks

CFile::GetPosition

Obtains the current value of the file pointer, which can be used in later calls to CFile::Seek

virtual unsigned long CFile::GetPosition();

Return Value

Returns unsigned long

Remarks

CFile::GetStatus

This method retrieves status information related to a given CFile object instance or a given file path.

int CFile::GetStatus(CFileStatus& rStatus);

Parameters

CFileStatus& rStatus - A reference to a user-supplied CFileStatus structure that will receive the status information

Return Value

Returns an int value representing one or more of the following values:

0x00 normal
0x01 readOnly
0x02 hidden
0x04 system
0x08 volume
0x10 directory
0x20 archive

Remarks

The CFileStatus structure has the following fields:

CTime m_ctime - The date and time the file was created.
CTime m_mtime - The date and time the file was last modified.
CTime m_atime - The date and time the file was last accessed for reading.
ULONGLONG m_size - The logical size of the file in bytes, as reported by the DIR command.
BYTE m_attribute - The attribute byte of the file.
char m_szFullName[_MAX_PATH] - The absolute filename in the Windows character set.

CFile::Open

Safely opens a file with an error-testing option

virtual int CFile::Open(
   const char* lpszFileName,
   unsigned int nOpenFlags,
   CFileException* pException);

Parameters

const char* lpszFileName - A string that contains the path to the desired file. The path can be relative, absolute, or a network name (UNC)
unsigned int nOpenFlags - A UINT that defines the file's sharing and access mode. It specifies the action to take when opening the file.
CFileException* pException - A pointer to an existing file-exception object that will receive the status of a failed operation.

Return Value

Nonzero if the open was successful; otherwise 0.

Remarks

"safe" method for opening a file, where a failure is a normal, expected condition.

CFile::Read

Reads data into a buffer from the file associated with the CFile object.

virtual unsigned int CFile::Read(
   void* lpBuf,
   unsigned int nCount);

Parameters

void* lpBuf - Pointer to the user-supplied buffer that is to receive the data read from the file.
unsigned int nCount - The maximum number of bytes to be read from the file. For text-mode files, carriage return-line feed pairs are counted as single characters.

Return Value

The number of bytes transferred to the buffer.

Remarks

For all CFile classes, the return value may be less than nCount if the end of file was reached.

CFile::Remove

Deletes the specified file

virtual void __stdcall CFile::Remove(const char* lpszFileName);

Parameters

const char* lpszFileName - A string that is the path to the desired file. The path can be relative or absolute, and can contain a network name.

Remarks

CFile::Remove won't remove a directory.

CFile::Seek

Positions the current file pointer

virtual long CFile::Seek(
   long lOff,
   unsigned int nFrom);

Parameters

long lOff - Number of bytes to move the file pointer. Positive values move the file pointer towards the end of the file; negative values move the file pointer towards the start of the file.
unsigned int nFrom - Position to seek from. See the Remarks section for possible values.

Return Value

The position of the file pointer if the method was successful; otherwise, the return value is undefined and a pointer to a CFileException exception is thrown.

Remarks

The following table lists possible values for the nFrom parameter.

CFile::begin - Seek from the start of the file.
CFile::current - Seek from the current location of the file pointer.
CFile::end - Seek from the end of the file.

When a file is opened, the file pointer is positioned at 0, the start of the file.

You can set the file pointer to a position beyond the end of a file. If you do, the size of the file doesn't increase until you write to the file.

The exception handler for this method must delete the exception object after the exception is processed.

CFile::SetFilePath

Sets the full file path of the selected file

virtual void CFile::SetFilePath(const char* lpszNewName);

Parameters

const char* lpszNewName - Pointer to a string specifying the new path.

Remarks

CFile::SetFilePath does not open the file or create the file; it simply associates the CFile object with a path name, which can then be used.

CFile::SetLength

Changes the length of the file

virtual void CFile::SetLength(unsigned long dwNewLen);

Parameters

unsigned long dwNewLen - Desired length of the file in bytes. This value can be larger or smaller than the current length of the file. The file will be extended or truncated as appropriate.

CFile::Write

Writes (unbuffered) data in a file to the current file position

virtual unsigned int CFile::Write(
   const void* lpBuf,
   unsigned int nCount);

Parameters

const void* lpBuf - A pointer to the user-supplied buffer that contains the data to be written to the file.
unsigned int nCount - The number of bytes to be transferred from the buffer. For text-mode files, carriage return-line feed pairs are counted as single characters.

Return Value

Returns unsigned int of bytes written

Remarks

CFile::Write throws an exception in response to several conditions, including the disk-full condition.