Reads (unbuffered) data from a file at the current file position.

Transcription

1 CFile CFile is the base class for Microsoft Foundation file classes. It directly provides unbuffered, binary disk input/output services, and it indirectly supports text files and memory files through its derived classes. CFile works in conjunction with the CArchive class to support serialization of Microsoft Foundation Class objects. The hierarchical relationship between this class and its derived classes allows your program to operate on all file objects through the polymorphic CFile interface. A memory file, for example, behaves like a disk file. Use CFile and its derived classes for general-purpose disk I/O. Use ofstream or other Microsoft iostream classes for formatted text sent to a disk file. Normally, a disk file is opened automatically on CFile construction and closed on destruction. Static member functions permit you to interrogate a file s status without opening the file. For more information on using CFile, see the article Files in MFC in Visual C++ Programmer's Guide and File Handling in the Run-Time Library Reference. #include <afx.h> CFile Class Members Data Members m_hfile Usually contains the operating-system file handle. Construction CFile Abort Duplicate Open Close Constructs a CFile object from a path or file handle. Closes a file ignoring all warnings and errors. Constructs a duplicate object based on this file. Safely opens a file with an error-testing option. Closes a file and deletes the object. Input/Output Read ReadHuge Reads (unbuffered) data from a file at the current file position. Can read more than 64K of (unbuffered) data from a file at the current file position. Obsolete in 32-bit programming. See Read. 1

2 Write WriteHuge Flush Writes (unbuffered) data in a file to the current file position. Can write more than 64K of (unbuffered) data in a file to the current file position. Obsolete in 32-bit programming. See Write. Flushes any data yet to be written. Position Seek SeekToBegin SeekToEnd GetLength SetLength Positions the current file pointer. Positions the current file pointer at the beginning of the file. Positions the current file pointer at the end of the file. Retrieves the length of the file. Changes the length of the file. Locking LockRange Locks a range of bytes in a file. UnlockRange Unlocks a range of bytes in a file. Status GetPosition GetStatus GetFileName GetFileTitle GetFilePath SetFilePath Retrieves the current file pointer. Retrieves the status of this open file. Retrieves the filename of the selected file. Retrieves the title of the selected file. Retrieves the full file path of the selected file. Sets the full file path of the selected file. Static Rename Remove GetStatus SetStatus Renames the specified file (static function). Deletes the specified file (static function). Retrieves the status of the specified file (static, virtual function). Sets the status of the specified file (static, virtual function). 2

3 CFile::m_hFile Contains the operating-system file handle for an open file. m_hfile is a public variable of type UINT. It contains CFile::hFileNull (an operating-system-independent empty file indicator) if the handle has not been assigned. Use of m_hfile is not recommended because the member s meaning depends on the derived class. m_hfile is made a public member for convenience in supporting nonpolymorphic use of the class. CFile::CFile CFile( ); CFile( int hfile ); CFile( LPCTSTR lpszfilename, UINT nopenflags ); Parameters hfile The handle of a file that is already open. lpszfilename A string that is the path to the desired file. The path can be relative or absolute. nopenflags Sharing and access mode. Specifies the action to take when opening the file. You can combine options listed below by using the bitwise-or ( ) operator. One access permission and one share option are required; the modecreate and modenoinherit modes are optional. The values are as follows: CFile::modeCreate Directs the constructor to create a new file. If the file exists already, it is truncated to 0 length. CFile::modeNoTruncate Combine this value with modecreate. If the file being created already exists, it is not truncated to 0 length. Thus the file is guaranteed to open, either as a newly created file or as an existing file. This might be useful, for example, when opening a settings file that may or may not exist already. This option applies to CStdioFile as well. CFile::modeRead Opens the file for reading only. CFile::modeReadWrite Opens the file for reading and writing. 3

4 CFile::modeWrite Opens the file for writing only. CFile::modeNoInherit Prevents the file from being inherited by child processes. CFile::shareDenyNone Opens the file without denying other processes read or write access to the file. Create fails if the file has been opened in compatibility mode by any other process. CFile::shareDenyRead Opens the file and denies other processes read access to the file. Create fails if the file has been opened in compatibility mode or for read access by any other process. CFile::shareDenyWrite Opens the file and denies other processes write access to the file. Create fails if the file has been opened in compatibility mode or for write access by any other process. CFile::shareExclusive Opens the file with exclusive mode, denying other processes both read and write access to the file. Construction fails if the file has been opened in any other mode for read or write access, even by the current process. CFile::shareCompat This flag is not available in 32 bit MFC. This flag maps to CFile::shareExclusive when used in CFile::Open. CFile::typeText Sets text mode with special processing for carriage return linefeed pairs (used in derived classes only). CFile::typeBinary Sets binary mode (used in derived classes only). The default constructor does not open a file but rather sets m_hfile to CFile::hFileNull. Because this constructor does not throw an exception, it does not make sense to use TRY/CATCH logic. Use the Open member function, then test directly for exception conditions. For a discussion of exception-processing strategy, see the article Exceptions in Visual C++ Programmer's Guide. The constructor with one argument creates a CFile object that corresponds to an existing operating-system file identified by hfile. No check is made on the access mode or file type. When the CFile object is destroyed, the operating-system file will not be closed. You must close the file yourself. The constructor with two arguments creates a CFile object and opens the corresponding operating-system file with the given path. This constructor combines the functions of the first constructor and the Open member function. It throws an exception if there is an error while opening the file. Generally, this means that the error is unrecoverable and that the user should be alerted. //example for CFile::CFile char* pfilename = "test.dat"; TRY { CFile f( pfilename, CFile::modeCreate CFile::modeWrite ); 4

5 } CATCH( CFileException, e ) { #ifdef _DEBUG afxdump << "File could not be opened " << e->m_cause << "\n"; #endif } END_CATCH 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. 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. 5

6 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 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::Close virtual void Close( ); Closes the file associated with this object and makes the file unavailable for reading or writing. If you have not closed the file before destroying the object, the destructor closes it for you. If you used new to allocate the CFile object on the heap, then you must delete it after closing the file. Close sets m_hfile to CFile::hFileNull. CFile::Read virtual UINT Read( void* lpbuf, UINT ncount ); Return Value The number of bytes transferred to the buffer. Note that for all CFile classes, the return value may be less than ncount if the end of file was reached. 6

7 Parameters lpbuf Pointer to the user-supplied buffer that is to receive the data read from the file. ncount The maximum number of bytes to be read from the file. For text-mode files, carriage return linefeed pairs are counted as single characters. Reads data into a buffer from the file associated with the CFile object. //example for CFile::Read extern CFile cfile; char pbuf[100]; UINT nbytesread = cfile.read( pbuf, 100 ); CFile::Write virtual void Write( const void* lpbuf, UINT ncount ); Parameters lpbuf A pointer to the user-supplied buffer that contains the data to be written to the file. ncount The number of bytes to be transferred from the buffer. For text-mode files, carriage return linefeed pairs are counted as single characters. Writes data from a buffer to the file associated with the CFile object. Write throws an exception in response to several conditions, including the disk-full condition. //example for CFile::Write extern CFile cfile; 7

8 char pbuf[100]; cfile.write( pbuf, 100 ); CFile::Seek virtual LONG Seek( LONG loff, UINT nfrom ); Return Value If the requested position is legal, Seek returns the new byte offset from the beginning of the file. Otherwise, the return value is undefined and a CFileException object is thrown. Parameters loff Number of bytes to move the pointer. nfrom Pointer movement mode. Must be one of the following values: CFile::begin Move the file pointer loff bytes forward from the beginning of the file. CFile::current Move the file pointer loff bytes from the current position in the file. CFile::end Move the file pointer loff bytes from the end of the file. Note that loff must be negative to seek into the existing file; positive values will seek past the end of the file. Repositions the pointer in a previously opened file. The Seek function permits random access to a file s contents by moving the pointer a specified amount, absolutely or relatively. No data is actually read during the seek. When a file is opened, the file pointer is positioned at offset 0, the beginning of the file. //example for CFile::Seek extern CFile cfile; LONG loffset = 1000, lactual; lactual = cfile.seek( loffset, CFile::begin ); CFile::GetFileName virtual CString GetFileName( ) const; 8

9 Return Value The name of the file. Call this member function to retrieve the name of a specified file. For example, when you call GetFileName to generate a message to the user about the file c:\windows\write\myfile.wri, the filename, myfile.wri, is returned. To return the entire path of the file, including the name, call GetFilePath. To return the title of the file (myfile), call GetFileTitle. CFile::GetFilePath virtual CString GetFilePath( ) const; Return Value The full path of the specified file. Call this member function to retrieve the full path of a specified file. For example, when you call GetFilePath to generate a message to the user about the file c:\windows\write\myfile.wri, the file path, c:\windows\write\myfile.wri, is returned. To return just the name of the file (myfile.wri), call GetFileName. To return the title of the file (myfile), call GetFileTitle. 9