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
Name | Description |
---|---|
CFileException::CFileException | Constructs a CFileException object. |
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. |
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);
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.
Do not use this constructor directly, but rather call the global function [AfxThrowFileException]--brokenlink--(../Topic/not%20found.md#afxthrowfileexception).
Hinweis
The variable lOsError
applies only to CFile
and CStdioFile
objects. The CMemFile
class does not handle this error code.
Converts a given run-time library error value to a CFileException
enumerated error value.
static int PASCAL ErrnoToException(int nErrno);
nErrno
An integer error code as defined in the run-time include file ERRNO.H.
Enumerated value that corresponds to a given run-time library error value.
See CFileException::m_cause for a list of the possible enumerated values.
ASSERT(CFileException::ErrnoToException(EACCES) ==
CFileException::accessDenied);
Retrieves text that describes an exception.
virtual BOOL GetErrorMessage(
LPTSTR lpszError,
UINT nMaxError,
PUINT pnHelpContext = NULL) const;
[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.
TRUE
if the method was successful; otherwise FALSE
.
If the specified buffer is too small, the error message is truncated.
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;
This data member is a public variable of type int
. The enumerators and their meanings are as follows:
CFileException::none
0: No error occurred.CFileException::genericException
1: An unspecified error occurred.CFileException::fileNotFound
2: The file could not be located.CFileException::badPath
3: All or part of the path is invalid.CFileException::tooManyOpenFiles
4: The permitted number of open files was exceeded.CFileException::accessDenied
5: The file could not be accessed.CFileException::invalidFile
6: There was an attempt to use an invalid file handle.CFileException::removeCurrentDir
7: The current working directory cannot be removed.CFileException::directoryFull
8: There are no more directory entries.CFileException::badSeek
9: There was an error trying to set the file pointer.CFileException::hardIO
10: There was a hardware error.CFileException::sharingViolation
11: SHARE.EXE was not loaded, or a shared region was locked.CFileException::lockViolation
12: There was an attempt to lock a region that was already locked.CFileException::diskFull
14: The disk is full.CFileException::endOfFile
15: The end of file was reached.Hinweis
These
CFileException
cause enumerators are distinct from theCArchiveException
cause enumerators.Hinweis
CArchiveException::generic
is deprecated. UsegenericException
instead. Ifgeneric
is used in an application and built with /clr, the resulting syntax errors are not easy to decipher.
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;
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);
lOsError
An operating-system-specific error code.
Enumerated value that corresponds to a given operating-system error value.
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);
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.
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);
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.
CFileException::ThrowOsError(ERROR_ACCESS_DENIED); // "access denied"