CFile64 - File System Wrapper

Download source files - 15 Kb

Introduction

Welcome to CFile64 v1.0, A freeware MFC class to provide access to the 64 bit file system API provided by the Win32 SDK.

A lot of developers may not realize that parts of the Win32 SDK already has some "64-bit"-isms. An example in kind is the API provided to access the file system. Currently the MFC CFile class hides this to provide a lowest common denominator approach to interacting with the API. If you do have occasion to use the 64 bit extensions then you will have no doubt cursed Microsoft when you start to use the raw SDK calls. This class is an attempt to provide a more OO interface to it.

Features

History

CFile64 class members

Contacting the Author

Features

• Provides access to the native 64 bit file system API available on NTFS volumes. Note: This does not prevent the class being used on FAT or FAT32 volumes, just that files cannot be extended beyond 4 GB in size.
• Provides access to all the parameters in the SDK CreateFile API. This can prove helpful when you want total control over the way a file is opened or created.
• Interface has been kept as close to CFile as possible.
• Uses the built in 64 bit integer type __in64 available in Visual C++ 4.0 or later. This makes use and understanding of the 64 bit API much easier when compared with using the raw Win32 SDK calls.
• Comprehensive documentation is included. The style should be familiar to anyone who uses MS Developer Studio documentation.

History

V1.0 (11 February 1998)

• Intial Public Release.

CFile64 Class Members

Data Members
operator HANDLE()	Returns the operating-system file handle this instance represents.
Construction
CFile64	Constructs a CFile64 object optionally from file handle.
Attach	Attaches to and already open file handle.
Abort	Closes a file ignoring all warnings and errors.
Duplicate	Constructs a duplicate object based on this file.
Open	Safely opens a file with an error-testing option.
Close	Closes a file and deletes the object.
Detach	CDetaches the CFile64 file the attached file handle.
Input/Output
Read	Reads (unbuffered) data from a file at the current file position.
Write	Writes (unbuffered) data in a file to the current file position.
Flush	Flushes any data yet to be written.
Position
Seek	Positions the current file pointer.
SeekToBegin	Positions the current file pointer at the beginning of the file.
SeekToEnd	Positions the current file pointer at the end of the file.
GetLength	Retrieves the length of the file.
SetLength	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	Retrieves the current file pointer.
GetFileName	Retrieves the filename of the selected file.
IsOpen	Returns TRUE if the file is currently open.
IsClosed	Returns TRUE if the file is currently closed.
SetFileName	Sets the filename of the selected file.

See Also CFile64 Overview, Class Members

CFile64::Abort

void Abort();

Remarks:
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.

When handling exceptions, CFile64::Abort() differs from CFile64::Close() in two important ways. First, the Abort() function will not throw an exception on failures because failures are ignored by Abort(). Second, Abort() will not ASSERT if the file has not been opened or was closed previously.

If you used new to allocate the CFile64 object on the heap, then you must delete it after closing the file. Abort() sets m_hFile to INVALID_HANDLE_VALUE.

Example:

//example for CFile64::Abort
CFile64 fileTest;
char* pFileName = "test.dat";
TRY
{
    // do stuff that may throw exceptions
    fileTest.Open( pFileName, CFile64::modeWrite );
}
CATCH_ALL( e )
{
    fileTest.Abort();    // close file safely and quietly
    THROW_LAST();
}
END_CATCH_ALL

See Also:
CFile64 Overview, Class Members, CFile64::Close(), CFile64::Open().

CFile64::Attach

void Attach(HANDLE hFile, BOOL bAutoClose);
throw(CFileException);

Return Value:
TRUE if the applet was successfully displayed otherwise FALSE.

Parameters:

• hFile -- The handle of a file that is already open.
• bAutoClose -- Should Close() be called by the destructor or Detach.

Remarks:
Creates a CFile64 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 CFile64 object is destroyed, the operating-system file will be closed if you set bAutoClose to TRUE.

See Also:
CFile64 Overview, Class Members, CFile64::Detach().

CFile64::CFile64

CFile64();

CFile64(HANDLE hFile, BOOL bAutoClose = TRUE);
throw(CFileException);

Return Value:
TRUE if the applet was successfully displayed otherwise FALSE.

Parameters:

• hFile -- The handle of a file that is already open.
• bAutoClose -- Should Close() be called by the destructor.

Remarks:
The default constructor does not open a file but rather sets m_hFile to INVALID_HANDLE_VALUE. 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 Programming with MFC.

The constructor with two arguments creates a CFile64 by calling the Attach() method.

See Also:
CFile64 Overview, Class Members, CFile64::Open().

CFile64::Close

void Close();
throw(CFileException);

Remarks:
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 CFile64 object on the heap, then you must delete it after closing the file. Close() sets m_hFile to INVALID_HANDLE_VALUE.

See Also:
CFile64 Overview, Class Members, CFile64::Open().

CFile64::Detach

void Detach();
throw(CFileException);

Remarks:
Call this function to detach m_hFile from the CFile64 object and set m_hFile to INVALID_HANDLE_VALUE. The file will be closed if told to do so using Attach().

See Also:
CFile64 Overview, Class Members, CFile64::Attach().

CFile64::Duplicate

CFile64* Duplicate() const;
throw(CFileException);

Return Value:
A pointer to a duplicate CFile64 object.

Remarks:
Constructs a duplicate CFile64 object for a given file.

See Also:
CFile64 Overview, Class Members.

CFile64::Flush

void Flush();
throw(CFileException);

Remarks:
Forces any data remaining in the file buffer to be written to the file.

See Also:
CFile64 Overview, Class Members.

CFile64::GetFileName

CString GetFileName( ) const;

Return Value:
The name of the file.

Remarks:
Call this member function to retrieve the filename 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, c:\windows\write\myfile.wri, is returned.

See Also:
CFile64 Overview, Class Members, CFile64::SetFileName().

CFile64::GetLength

UINT64 GetLength() const;
throw(CFileException);

Return Value:
The length of the file.

Remarks:
Obtains the current logical length of the file in bytes, not the amount.

See Also:
CFile64 Overview, Class Members, CFile64::SetLength().

CFile64::GetPosition

UINT64 GetPosition() const;
throw(CFileException);

Return Value:
The file pointer as a 64-bit unsigned integer.

Remarks:
Obtains the current value of the file pointer, which can be used in subsequent calls to Seek().

Example:

//example for CFile64::GetPosition
extern CFile64 CFile64;
UINT64 lPosition = CFile64.GetPosition();

See Also:
CFile64 Overview, Class Members.

CFile64::IsClosed

BOOL IsClosed() const;

Return Value:
TRUE if the file is currently closed otherwise FALSE.

See Also:
CFile64 Overview, Class Members.

CFile64::IsOpen

BOOL IsOpen() const;

Return Value:
TRUE if the file is currently open otherwise FALSE.

See Also:
CFile64 Overview, Class Members.

CFile64::LockRange

void LockRange(const UINT64& lPos, const UINT64& lCount);
throw(CFileException);

Return Value:
TRUE if the applet was successfully displayed otherwise FALSE.

Parameters:

• lPos -- The byte offset of the start of the byte range to lock.
• lCount -- The number of bytes in the range to lock.

Remarks:
Locks a range of bytes in an open file, throwing an exception if the file is already locked. Locking bytes in a file prevents access to those bytes by other processes. You can lock more than one region of a file, but no overlapping regions are allowed.

When you unlock the region, using the UnlockRange() member function, the byte range must correspond exactly to the region that was previously locked. The LockRange() function does not merge adjacent regions; if two locked regions are adjacent, you must unlock each region separately.

Example:

//example for CFile64::LockRange
extern UINT64 lPos;
extern UINT64 lCount;
extern CFile64 file;
file.LockRange( lPos, lCount );

See Also:
CFile64 Overview, Class Members, CFile64::UnlockRange().

CFile64::Open

BOOL Open(LPCTSTR lpFileName, DWORD dwDesiredAccess, DWORD dwShareMode, DWORD dwCreationDistribution, CFileException* pError = NULL, LPSECURITY_ATTRIBUTES lpSecurityAttributes = NULL, DWORD dwFlagsAndAttributes = 0, HANDLE hTemplateFile = NULL );

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

Parameters:

• lpFileName -- Points to a null-terminated string that specifies the name of the object (file, pipe, mailslot, communications resource, disk device, console, or directory) to create or open. See the SDK function CreateFile for further details.
• dwDesiredAccess -- The number of bytes in the range to lock.
• lCount -- Specifies the type of access to the object. An application can obtain read access, write access, read-write access, or device query access. See the SDK function CreateFile() for further details.
• dwShareMode -- Set of bit flags that specifies how the object can be shared. If dwShareMode is 0, the object cannot be shared. Subsequent open operations on the object will fail, until the handle is closed. See the SDK function CreateFile() for further details.
• lpSecurityAttributes -- Pointer to a SECURITY_ATTRIBUTES structure that determines whether the returned handle can be inherited by child processes. If lpSecurityAttributes is NULL, the handle cannot be inherited.
• dwCreationDisposition -- Specifies which action to take on files that exist, and which action to take when files do not exist. For more information about this parameter, see the Remarks section. See the SDK function CreateFile() for further details.
• dwFlagsAndAttributes -- Specifies the file attributes and flags for the file. See the SDK function CreateFile() for further details.
• hTemplateFile -- Specifies a handle with GENERIC_READ access to a template file. The template file supplies file attributes and extended attributes for the file being created. See the SDK function CreateFile() for further details.
• 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 CFile64 constructor. The two functions form a "safe" method for opening a file where a failure is a normal, expected condition.

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 CFile64::Open
CFile64 f;
CFileException e;
char* pFileName = "test.dat";
if( !f.Open( pFileName, GENERIC_READ, 0, OPEN_EXISTING, &e ) )
    {
#ifdef _DEBUG
    afxDump << "File could not be opened " << e.m_cause << "\n";
#endif
    }

See Also:
CFile64 Overview, Class Members, CFile64::CFile64(), CFile64::Close().

CFile64::Read

DWORD Read(void* lpBuf, DWORD dwCount);
throw(CFileException);

Return Value:
The number of bytes transferred to the buffer. Note that for all CFile64 classes, the return value may be less than nCount if the end of file was reached.

Parameters:

• lpBuf -- Pointer to the user-supplied buffer that is to receive the data read from the file.
• dwCount -- The maximum number of bytes to be read from the file.

Remarks:
Reads data into a buffer from the file associated with the CFile64 object.

Currently this function only allows reading of up to ULONG_MAX (4294967295) bytes as Win32 has only a 4 GB address space (1 - 2 GB's of which is unavailable to user mode applications). This will only be remedied with the arrival of the Win64 API <g>.

Example:

//example for CFile64::Read
extern CFile64 CFile64;
char pbuf[100];
DWORD dwBytesRead = CFile64.Read( pbuf, 100 );

See Also:
CFile64 Overview, Class Members.

CFile64::Seek

LONG Seek(const UINT64& lDistanceToMove, SeekPosition MoveMethod, BOOL bForward);
throw(CFileException);

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:

• lDistanceToMove -- Number of bytes to move the pointer.
• nMoveMethod -- Pointer movement mode. Must be one of the following values:
  • CFile64::begin -- Move the file pointer lOff bytes forward from the beginning of the file.
  • CFile64::current -- Move the file pointer lOff bytes from the current position in the file.
  • CFile64::end -- Move the file pointer lOff bytes from the end of the file.
• bForward -- TRUE if the seek is forward with FALSE meaning a backward seek.

Remarks:
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:

//example for CFile64::Seek
extern CFile64 file;
LONG lOffset = 1000, lActual;
lActual = file.Seek( lOffset, CFile64::begin );

See Also:
CFile64 Overview, Class Members.

CFile64::SeekToBegin

void SeekToBegin();
throw(CFileException);

Remarks:
Sets the value of the file pointer to the beginning of the file. SeekToBegin() is equivalent to Seek(0L, CFile64::begin ).

Example:

//example for CFile64::SeekToBegin
extern CFile64 file;
file.SeekToBegin();

See Also:
CFile64 Overview, Class Members.

CFile64::SeekToEnd

UINT64 SeekToEnd();
throw(CFileException);

Return Value:
The length of the file in bytes.

Remarks:
Sets the value of the file pointer to the logical end of the file. SeekToEnd() is equivalent to CFile64::Seek( 0L, CFile64::end ).

Example:

//example for CFile64::SeekToEnd
extern CFile64 file;
UINT64 lActual = file.SeekToEnd();

See Also:
CFile64 Overview, Class Members, CFile64::GetLength(), CFile64::Seek(), CFile64::SeekToBegin().

CFile64::SetFileName

void SetFilePath( LPCTSTR lpszNewName);

Parameters:

• lpszNewName -- Pointer to a string specifying the new filename.

Remarks:
Call this function to specify the path of the file; for example, if the path of a file is not available when a CFile64 object is constructed, call SetFileName() to provide it.

Note SetFileName() does not open the file or create the file; it simply associates the CFile64 object with a path name, which can then be used.

See Also:
CFile64 Overview, Class Members, CFile64::CFile64(), CFile64::GetFileName().

CFile64::SetLength

void SetLength(const UINT64& lNewLen);
throw(CFileException);

Parameters:

• lNewLen -- Desired length of the file in bytes. This value can be larger or smaller than the current length of the file. The file will be extended or truncated as appropriate.

Remarks:
Call this function to change the length of the file.

Example:

//example for CFile64::SetLength
extern CFile64 file;
UINT64 lNewLength = 10000;
file.SetLength( lNewLength );

See Also:
CFile64 Overview, Class Members.

CFile64::UnlockRange

void UnlockRange(const UINT64& lPos, const UINT64& lCount);
throw(CFileException);

Parameters:

• dwPos -- The byte offset of the start of the byte range to unlock.
• dwCount -- The number of bytes in the range to unlock.

Remarks:
Unlocks a range of bytes in an open file. See the description of the LockRange() member function for details.

Example:

//example for CFile64::UnlockRange
extern INT64 lPos;
extern INT64 lCount;
extern CFile64 file;
file.UnlockRange( lPos, lCount );

See Also:
CFile64 Overview, Class Members, CFile64::LockRange().

CFile64::Write

void Write(const void* lpBuf, DWORD dwCount );
throw(CFileException);

Parameters:

• lpBuf -- A pointer to the user-supplied buffer that contains the data to be written to the file.
• dwCount -- The number of bytes to be transferred from the buffer.

Remarks:
Writes data from a buffer to the file associated with the CFile64 object.

Write throws an exception in response to several conditions, including the disk-full condition.

Currently this function only allows reading of up to ULONG_MAX (4294967295) bytes as Win32 has only a 4 GB address space (1 - 2 GB's of which is unavailable to user mode applications). This will only be remedied with the arrival of the Win64 API <g>.

Example:

//example for CFile64::Write
extern CFile64 CFile64;
char pbuf[100];
CFile64.Write( pbuf, 100 );

See Also:
CFile64 Overview, Class Members, CFile64::Read().

CFile64::operator HANDLE();

Return Value:
The operating-system file handle for an open file.

Remarks:
Use of operator HANDLE() is not recommended, instead you should use the member functions exposed through the CFile64 interface.

See Also:
CFile64 Overview, Class Members.

Contacting the Author

PJ Naughter
Email: pjn@indigo..ie
Web: http://www.naughter.com
11th February 1998