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.

Example

//example for CFile::OpenCFile f;CFileException e;char* pFileName = "test.dat";if( !f.Open( pFileName, CFile::modeCreate | CFile::modeWrite, &e ) ){#ifdef _DEBUGafxDump << "File could not be opened " << e.m_cause << "\n";#endif}//A second example for CFile::Open.//This console program uses CFile to copy binary files.#include <afx.h>#include <afxwin.h>#include <iostream>using namespace std;CWinApp theApp;int main(int argc, char *argv[]){  if (!AfxWinInit(GetModuleHandle(NULL), NULL, GetCommandLine(), 0))  {     cout << "panic: MFC couldn't initialize!" << endl;     return 1;  }  // constructing these file objects doesn't open them  CFile sourceFile;  CFile destFile;  // see that we have a reasonable number of arguments  if (argc != 3)  {     cout << "usage: " << argv[0];     cout << " <source> <dest>" << endl;     cout << endl;     return 1;  }  // we'll use a CFileException object to get error information  CFileException ex;  // open the source file for reading  if (!sourceFile.Open(argv[1],     CFile::modeRead | CFile::shareDenyWrite, &ex))  {     // complain if an error happened     // no need to delete the ex object     TCHAR szError[1024];     ex.GetErrorMessage(szError, 1024);     cout << "Couldn't open source file: ";     cout << szError;     return 1;  }  else  {     if (!destFile.Open(argv[2], CFile::modeWrite |           CFile::shareExclusive | CFile::modeCreate, &ex))     {        TCHAR szError[1024];        ex.GetErrorMessage(szError, 1024);        cout << "Couldn't open source file: ";        cout << szError;        sourceFile.Close();        return 1;     }     BYTE buffer[4096];     DWORD dwRead;     // Read in 4096-byte blocks,     // remember how many bytes were actually read,     // and try to write that many out. This loop ends     // when there are no more bytes to read.     do     {        dwRead = sourceFile.Read(buffer, 4096);        destFile.Write(buffer, dwRead);     }     while (dwRead > 0);     // Close both files     destFile.Close();     sourceFile.Close();  }  return 0;}