CFileException Class
The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.
The latest version of this topic can be found at CFileException Class.
Represents a file-related exception condition.
class CFileException : public CException
Public Constructors
| Name | Description |
|---|---|
| CFileException::CFileException | Constructs a CFileException object. |
Public Methods
| Name | Description |
|---|---|
| CFileException::ErrnoToException | Returns cause code corresponding to a run-time error number. |
| CFileException::GetErrorMessage | Retrieves the message describing an exception. |
| CFileException::OsErrorToException | Returns a cause code corresponding to an operating system error code. |
| CFileException::ThrowErrno | Throws a file exception based on a runtime error number. |
| CFileException::ThrowOsError | Throws a file exception based on an operating system error number. |
Public Data Members
| Name | Description |
|---|---|
| CFileException::m_cause | Contains portable code corresponding to the exception cause. |
| CFileException::m_lOsError | Contains the related operating-system error number. |
| CFileException::m_strFileName | Contains the name of the file for this exception. |
The CFileException class includes public data members that hold the portable cause code and the operating-system-specific error number. The class also provides static member functions for throwing file exceptions and for returning cause codes for both operating-system errors and C run-time errors.
CFileException objects are constructed and thrown in CFile member functions and in member functions of derived classes. You can access these objects within the scope of a CATCH expression. For portability, use only the cause code to get the reason for an exception. For more information about exceptions, see the article Exception Handling (MFC).
CFileException
Header: afx.h
Constructs a CFileException object that stores the cause code and the operating-system code in the object.
CFileException(
int cause = CFileException::none,
LONG lOsError = -1,
LPCTSTR lpszArchiveName = NULL);
Parameters
cause
An enumerated type variable that indicates the reason for the exception. See CFileException::m_cause for a list of the possible values.
lOsError
An operating-system-specific reason for the exception, if available. The lOsError parameter provides more information than cause does.
lpszArchiveName
Points to a string containing the name of the CFile object causing the exception.
Remarks
Do not use this constructor directly, but rather call the global function [AfxThrowFileException]--brokenlink--(../Topic/not%20found.md#afxthrowfileexception).
The variable |
Converts a given run-time library error value to a CFileException enumerated error value.
static int PASCAL ErrnoToException(int nErrno);
Parameters
nErrno
An integer error code as defined in the run-time include file ERRNO.H.
Return Value
Enumerated value that corresponds to a given run-time library error value.
Remarks
See CFileException::m_cause for a list of the possible enumerated values.
Example
ASSERT(CFileException::ErrnoToException(EACCES) ==
CFileException::accessDenied);
Retrieves text that describes an exception.
virtual BOOL GetErrorMessage(
LPTSTR lpszError,
UINT nMaxError,
PUINT pnHelpContext = NULL) const;
Parameters
[in, out] lpszError
Pointer to a buffer that receives an error message.
[in] nMaxError
The maximum number of characters the specified buffer can hold. This includes the terminating null character.
[in, out] pnHelpContext
Pointer to an unsigned integer that receives the help context ID. If NULL, no ID is returned.
Return Value
TRUE if the method was successful; otherwise FALSE.
Remarks
If the specified buffer is too small, the error message is truncated.
Example
The following example uses CFileException::GetErrorMessage.
CFile fileInput; CFileException ex; // try to open a file for reading. // The file will certainly not // exist because there are too many explicit // directories in the name. // if the call to Open() fails, ex will be // initialized with exception // information. the call to ex.GetErrorMessage() // will retrieve an appropriate message describing // the error, and we'll add our own text // to make sure the user is perfectly sure what // went wrong. if (!fileInput.Open(_T("\\Too\\Many\\Bad\\Dirs.DAT"), CFile::modeRead, &ex)) { TCHAR szCause[255]; CString strFormatted; ex.GetErrorMessage(szCause, 255); // (in real life, it's probably more // appropriate to read this from // a string resource so it would be easy to // localize) strFormatted = _T("The data file could not be opened because of this error: "); strFormatted += szCause; AfxMessageBox(strFormatted); } else { // the file was opened, so do whatever work // with fileInput // we were planning... fileInput.Close(); }
Contains values defined by a CFileException enumerated type.
int m_cause;
Remarks
This data member is a public variable of type int. The enumerators and their meanings are as follows:
CFileException::none0: No error occurred.CFileException::genericException1: An unspecified error occurred.CFileException::fileNotFound2: The file could not be located.CFileException::badPath3: All or part of the path is invalid.CFileException::tooManyOpenFiles4: The permitted number of open files was exceeded.CFileException::accessDenied5: The file could not be accessed.CFileException::invalidFile6: There was an attempt to use an invalid file handle.CFileException::removeCurrentDir7: The current working directory cannot be removed.CFileException::directoryFull8: There are no more directory entries.CFileException::badSeek9: There was an error trying to set the file pointer.CFileException::hardIO10: There was a hardware error.CFileException::sharingViolation11: SHARE.EXE was not loaded, or a shared region was locked.CFileException::lockViolation12: There was an attempt to lock a region that was already locked.CFileException::diskFull14: The disk is full.CFileException::endOfFile15: The end of file was reached.
Note These
CFileExceptioncause enumerators are distinct from theCArchiveExceptioncause enumerators.
Note CArchiveException::genericis deprecated. UsegenericExceptioninstead. Ifgenericis used in an application and built with /clr, the resulting syntax errors are not easy to decipher.
Example
try
{
CFile f(_T("M_Cause_File.dat"), CFile::modeWrite);
}
catch(CFileException* e)
{
if( e->m_cause == CFileException::fileNotFound)
TRACE(_T("ERROR: File not found\n"));
e->Delete();
}
Contains the operating-system error code for this exception.
LONG m_lOsError;
Remarks
See your operating-system technical manual for a listing of error codes. This data member is a public variable of type LONG.
Contains the name of the file for this exception condition.
CString m_strFileName;
Returns an enumerator that corresponds to a given lOsError value. If the error code is unknown, then the function returns CFileException::generic.
static int PASCAL OsErrorToException(LONG lOsError);
Parameters
lOsError
An operating-system-specific error code.
Return Value
Enumerated value that corresponds to a given operating-system error value.
Example
ASSERT(CFileException::OsErrorToException(ERROR_ACCESS_DENIED) ==
CFileException::accessDenied);
Constructs a CFileException object corresponding to a given nErrno value, then throws the exception.
static void PASCAL ThrowErrno(int nErrno, LPCTSTR lpszFileName = NULL);
Parameters
nErrno
An integer error code as defined in the run-time include file ERRNO.H.
lpszFileName
A pointer to the string containing the name of the file that caused the exception, if available.
Example
CFileException::ThrowErrno(EACCES); // "access denied"
Throws a CFileException corresponding to a given lOsError value. If the error code is unknown, then the function throws an exception coded as CFileException::generic.
static void PASCAL ThrowOsError(LONG lOsError, LPCTSTR lpszFileName = NULL);
Parameters
lOsError
An operating-system-specific error code.
lpszFileName
A pointer to the string containing the name of the file that caused the exception, if available.
Example
CFileException::ThrowOsError(ERROR_ACCESS_DENIED); // "access denied"