`CFileException` 類別

發行項
10/12/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 執行時間錯誤的原因碼。

CFileException 物件會在成員函式和衍生類別的成員函式中建構和擲回 CFile 。您可以在運算式的範圍內 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]接收說明內容識別碼之不帶正負號的整數的指標。如果 NULL 為，則不會傳回任何識別碼。

傳回值

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`

CFileException建構對應至指定 nErrno 值的物件，然後擲回例外狀況。

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

參數

範例