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  

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).

CObject

CException

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).

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 the CArchiveException cause enumerators.

  Hinweis

  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.

         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"         

CException Class
Hierarchy Chart
Exception Processing