CFile::Open

virtual BOOL Open( LPCTSTR lpszFileName, UINT nOpenFlags, CFileException* pError = NULL );

Return Value

Nonzero if the open was successful; otherwise 0. The pError parameter is meaningful only if 0 is returned.

Parameters

lpszFileName

A string that is the path to the desired file. The path can be relative, absolute, or a network name (UNC).

nOpenFlags

A UINT that defines the file’s sharing and access mode. It specifies the action to take when opening the file. You can combine options by using the bitwise-OR ( | ) operator. One access permission and one share option are required; the modeCreate and modeNoInherit modes are optional. See the CFile constructor for a list of mode options.

pError

A pointer to an existing file-exception object that will receive the status of a failed operation.

Remarks

Open is designed for use with the default CFile constructor. The two functions form a “safe” method for opening a file where a failure is a normal, expected condition.

While the CFile constructor will throw an exception in an error condition, Open will return FALSE for error conditions. Open can still initialize a CFileException object to describe the error, however. If you don’t supply the pError parameter, or if you pass NULL for pError, Open will return FALSE and not throw a CFileException. If you pass a pointer to an existing CFileException, and Open encounters an error, the function will fill it with information describing that error. In neither case will Open throw an exception.

The following table describes the possible results of Open.

pError Error encountered? Return value CFileException content
NULL No TRUE n/a
ptr to CFileException No TRUE unchanged
NULL Yes FALSE n/a
ptr to CFileException Yes FALSE initialized to describe error

Example

//example for CFile::Open
CFile f;
CFileException e;
char* pFileName = "test.dat";
if( !f.Open( pFileName, CFile::modeCreate | CFile::modeWrite, &e ) )
   {
#ifdef _DEBUG
   afxDump << "File could not be opened " << e.m_cause << "\n";
#endif
   }

CFile OverviewClass MembersHierarchy Chart

See Also   CFile::CFile, CFile::Close