description | title | ms.date | f1_keywords | helpviewer_keywords | ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Learn more about: CFileException Class |
CFileException Class |
06/09/2020 |
|
|
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.
Don't use this constructor directly, but rather call the global function AfxThrowFileException
.
Note
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.
[!code-cppNVC_MFCFiles#26]
Retrieves text that describes an exception.
virtual BOOL GetErrorMessage(
LPTSTR lpszError,
UINT nMaxError,
PUINT pnHelpContext = NULL) const;
lpszError
[in, out] Pointer to a buffer that receives an error message.
nMaxError
[in] The maximum number of characters the specified buffer can hold. This includes the terminating NULL
character.
pnHelpContext
[in, out] 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
.
[!code-cppNVC_MFCExceptions#22]
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:
Error | Value and meaning |
---|---|
CFileException::none |
0: No error occurred. |
CFileException::genericException |
1: An unspecified error occurred. |
CFileException::fileNotFound |
2: The file couldn't 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 couldn't be accessed. |
CFileException::invalidFile |
6: There was an attempt to use an invalid file handle. |
CFileException::removeCurrentDir |
7: The current working directory can't 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 wasn't loaded, or a shared region was locked. |
CFileException::lockViolation |
12: There was an attempt to lock a region that was already locked. |
CFileException::diskFull |
13: The disk is full. |
CFileException::endOfFile |
14: The end of file was reached. |
Note
These CFileException
cause enumerators are distinct from the CArchiveException
cause enumerators.
Note
CArchiveException::generic
is deprecated. Use genericException
instead. If generic
is used in an application and built with /clr
, the resulting syntax errors are not easy to decipher.
[!code-cppNVC_MFCFiles#30]
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.
[!code-cppNVC_MFCFiles#27]
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.
[!code-cppNVC_MFCFiles#28]
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.
[!code-cppNVC_MFCFiles#29]