`CFileException` 类

项目
10/14/2023

表示与文件相关的异常条件。

语法

class CFileException : public CException

成员

公共构造函数

名称	描述
`CFileException::CFileException`	构造 `CFileException` 对象。

公共方法

名称	描述
`CFileException::ErrnoToException`	返回与运行时错误号对应的代码。
`CFileException::GetErrorMessage`	检索描述异常的消息。
`CFileException::OsErrorToException`	返回与操作系统错误代码对应的原因代码。
`CFileException::ThrowErrno`	根据运行时错误号引发文件异常。
`CFileException::ThrowOsError`	根据操作系统错误号引发文件异常。

公共数据成员

“属性”	描述
`CFileException::m_cause`	包含对应于异常原因的可移植代码。
`CFileException::m_lOsError`	包含相关的操作系统错误号。
`CFileException::m_strFileName`	包含此异常的文件的名称。

备注

该 CFileException 包含保存可移植原因代码和特定于操作系统的错误号的公共数据成员。该类还提供静态成员函数，用于引发文件异常，以及返回操作系统错误和 C 运行时错误的原因代码。

在 CFile 成员函数和派生类的成员函数中构造和引发 CFileException 对象。可以在 CATCH 表达式的范围内访问这些对象。对于可移植性，请仅使用原因代码来获取异常的原因。有关异常的详细信息，请参阅处理异常 (MFC)一文。

继承层次结构

CObject

CException

CFileException

要求

标头afx.h：

`CFileException::CFileException`

构造将原因代码和操作系统代码存储在对象中的 CFileException 对象。

CFileException(
    int cause = CFileException::none,
    LONG lOsError = -1,
    LPCTSTR lpszArchiveName = NULL);

参数

cause
指示异常原因的枚举类型变量。请参阅 CFileException::m_cause，查看可能值的列表。

lOsError
特定于操作系统的异常原因（如果有）。 lOsError 参数提供的信息比 cause 多。

lpszArchiveName
指向字符串，该字符串包含导致异常的 CFile 对象的名称。

备注

请勿直接使用此构造函数，而是调用全局函数 AfxThrowFileException。

注意

该变量 lOsError 仅适用于 CFile 对象和 CStdioFile 对象。 CMemFile 类不处理此错误代码。

`CFileException::ErrnoToException`

将给定的运行时库错误值转换为 CFileException 枚举错误值。

static int PASCAL ErrnoToException(int nErrno);

参数

nErrno
运行时包含文件 ERRNO.H 中定义的整数错误代码。

返回值

与给定运行时库错误值对应的枚举值。

备注

请参阅 CFileException::m_cause，查看可能的枚举值的列表。

示例

ASSERT(CFileException::ErrnoToException(EACCES) == 
   CFileException::accessDenied);

`CFileException::GetErrorMessage`

检索描述异常的文本。

virtual BOOL GetErrorMessage(
    LPTSTR lpszError,
    UINT nMaxError,
    PUINT pnHelpContext = NULL) const;

参数

lpszError
[in, out] 指向接收错误消息的缓冲区的指针。

nMaxError
[in] 指定缓冲区可容纳的最大字符数。包括终止 NULL 字符。

pnHelpContext
[in, out] 指向接收帮助上下文 ID 的无符号整数的指针。如果为 NULL，则不返回 ID。

返回值

如果该方法成功，则返回 TRUE；否则返回 FALSE。

备注

如果指定的缓冲区太小，错误消息会被截断。

示例

下面的示例使用 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();
}

`CFileException::m_cause`

包含由 CFileException 枚举类型定义的值。

int m_cause;

备注

此数据成员是类型 int 的公共变量。枚举器及其含义如下所示：

错误	值和含义
`CFileException::none`	0：未发生任何错误。
`CFileException::genericException`	1：发生了未指定的错误。
`CFileException::fileNotFound`	2:：无法找到该文件。
`CFileException::badPath`	3：全部或部分路径无效。
`CFileException::tooManyOpenFiles`	4：超出了允许打开的文件数。
`CFileException::accessDenied`	5：无法访问该文件。
`CFileException::invalidFile`	6：尝试使用了无效的文件句柄。
`CFileException::removeCurrentDir`	7：无法移除当前工作目录。
`CFileException::directoryFull`	8：没有更多的目录项。
`CFileException::badSeek`	9：在尝试设置文件指针时出错。
`CFileException::hardIO`	10：出现了硬件错误。
`CFileException::sharingViolation`	11：未加载 `SHARE.EXE`，或已锁定共享区域。
`CFileException::lockViolation`	12：尝试锁定已经锁定的区域。
`CFileException::diskFull`	13：磁盘已满。
`CFileException::endOfFile`	14：已到达文件末尾。

注意

引发这些 CFileException 的枚举器不同于引发 CArchiveException 的枚举器。

注意

CArchiveException::generic 已弃用。请改用 genericException。如果在应用程序中使用 generic 并使用 /clr 进行生成，则生成的语法错误难以解密。

示例

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();
}

`CFileException::m_lOsError`

包含此异常的操作系统错误代码。

LONG m_lOsError;

备注

请参阅操作系统技术手册，查看错误代码列表。此数据成员是类型 LONG 的公共变量。

`CFileException::m_strFileName`

包含此异常条件的文件的名称。

CString m_strFileName;

`CFileException::OsErrorToException`

返回对应于给定 lOsError 值的枚举器。如果错误代码未知，则函数返回 CFileException::generic。

static int PASCAL OsErrorToException(LONG lOsError);

参数

lOsError
特定于操作系统的错误代码。

返回值

与给定操作系统错误值对应的枚举值。

示例

ASSERT(CFileException::OsErrorToException(ERROR_ACCESS_DENIED) == 
   CFileException::accessDenied);

`CFileException::ThrowErrno`

构造对应于给定 nErrno 值的 CFileException 对象，然后引发异常。

static void PASCAL ThrowErrno(int nErrno, LPCTSTR lpszFileName = NULL);

参数

nErrno
运行时包含文件 ERRNO.H 中定义的整数错误代码。

lpszFileName
指向包含导致异常的文件的名称（如果有）的字符串的指针。

示例

CFileException::ThrowErrno(EACCES);  // "access denied"

`CFileException::ThrowOsError`

引发与给定 CFileException 值对应的 lOsError。如果错误代码未知，则函数将引发编码为 CFileException::generic 的异常。

static void PASCAL ThrowOsError(LONG lOsError, LPCTSTR lpszFileName = NULL);

参数

lOsError
特定于操作系统的错误代码。

lpszFileName
指向包含导致异常的文件的名称（如果有）的字符串的指针。

示例

CFileException::ThrowOsError(ERROR_ACCESS_DENIED);  // "access denied"

另请参阅

CException 类
 层次结构图
 异常处理

CFileException 类

语法

成员

公共构造函数

公共方法

公共数据成员

备注

继承层次结构

要求

CFileException::CFileException

参数

备注

CFileException::ErrnoToException

参数

返回值

备注

示例

CFileException::GetErrorMessage

参数

返回值

备注

示例

CFileException::m_cause

备注

示例

CFileException::m_lOsError

备注

CFileException::m_strFileName

CFileException::OsErrorToException

参数

返回值

示例

CFileException::ThrowErrno

参数

示例

CFileException::ThrowOsError

参数

示例