CFile64 v1.0

CFile64 v1.0

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

Contents

Features

History

CFile64 class members

Contacting the Author

Features

Provides access to the native 64 bit file system API available on NTFS volumes.
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.

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.

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

CFile64::Attach

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

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.

CFile64::CFile64

CFile64( );

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

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.

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.

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

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.

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.

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

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

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

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

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.

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

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.

Example

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

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://indigo.ie/~pjn
11th February 1998