Skip to content

cfileexception-class.md

Latest commit

 

History

History
277 lines (178 loc) · 9.81 KB

cfileexception-class.md

File metadata and controls

277 lines (178 loc) · 9.81 KB
description Learn more about: CFileException Class
title CFileException Class
ms.date 06/09/2020
f1_keywords
CFileException
AFX/CFileException
AFX/CFileException::CFileException
AFX/CFileException::ErrnoToException
AFX/CFileException::GetErrorMessage
AFX/CFileException::OsErrorToException
AFX/CFileException::ThrowErrno
AFX/CFileException::ThrowOsError
AFX/CFileException::m_cause
AFX/CFileException::m_lOsError
AFX/CFileException::m_strFileName
helpviewer_keywords
CFileException [MFC], CFileException
CFileException [MFC], ErrnoToException
CFileException [MFC], GetErrorMessage
CFileException [MFC], OsErrorToException
CFileException [MFC], ThrowErrno
CFileException [MFC], ThrowOsError
CFileException [MFC], m_cause
CFileException [MFC], m_lOsError
CFileException [MFC], m_strFileName

CFileException Class

Represents a file-related exception condition.

Syntax

class CFileException : public CException

Members

Public Constructors

Name Description
CFileException::CFileException Constructs a CFileException object.

Public Methods

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.

Public Data Members

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.

Remarks

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

Inheritance Hierarchy

CObject

CException

CFileException

Requirements

Header: afx.h

CFileException::CFileException

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

Parameters

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.

Remarks

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.

CFileException::ErrnoToException

Converts a given run-time library error value to a CFileException enumerated error value.

static int PASCAL ErrnoToException(int nErrno);

Parameters

nErrno
An integer error code as defined in the run-time include file ERRNO.H.

Return Value

Enumerated value that corresponds to a given run-time library error value.

Remarks

See CFileException::m_cause for a list of the possible enumerated values.

Example

[!code-cppNVC_MFCFiles#26]

CFileException::GetErrorMessage

Retrieves text that describes an exception.

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

Parameters

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.

Return Value

TRUE if the method was successful; otherwise FALSE.

Remarks

If the specified buffer is too small, the error message is truncated.

Example

The following example uses CFileException::GetErrorMessage.

[!code-cppNVC_MFCExceptions#22]

CFileException::m_cause

Contains values defined by a CFileException enumerated type.

int m_cause;

Remarks

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.

Example

[!code-cppNVC_MFCFiles#30]

CFileException::m_lOsError

Contains the operating-system error code for this exception.

LONG m_lOsError;

Remarks

See your operating-system technical manual for a listing of error codes. This data member is a public variable of type LONG.

CFileException::m_strFileName

Contains the name of the file for this exception condition.

CString m_strFileName;

CFileException::OsErrorToException

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

Parameters

lOsError
An operating-system-specific error code.

Return Value

Enumerated value that corresponds to a given operating-system error value.

Example

[!code-cppNVC_MFCFiles#27]

CFileException::ThrowErrno

Constructs a CFileException object corresponding to a given nErrno value, then throws the exception.

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

Parameters

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.

Example

[!code-cppNVC_MFCFiles#28]

CFileException::ThrowOsError

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

Parameters

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.

Example

[!code-cppNVC_MFCFiles#29]

See also

CException Class
Hierarchy Chart
Exception Processing