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.
- 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:
CFile64 fileTest;
char* pFileName = "test.dat";
TRY
{
fileTest.Open( pFileName, CFile64::modeWrite );
}
CATCH_ALL( e )
{
fileTest.Abort();
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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.
