Click here to Skip to main content
15,867,308 members
Articles / Desktop Programming / MFC
Article

CFile64 - File System Wrapper

Rate me:
Please Sign up or sign in to vote.
3.40/5 (6 votes)
3 Mar 2000 75.8K   1.2K   27   6
A freeware MFC class to encapsulate the Win32 64 bit file system API.
  • 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


    License

    This article has no explicit license attached to it but may contain usage terms in the article text or the download files themselves. If in doubt please contact the author via the discussion board below.

    A list of licenses authors might use can be found here


    Written By
    United States United States
    This member has not yet provided a Biography. Assume it's interesting and varied, and probably something to do with programming.

    Comments and Discussions

     
    GeneralGetLength() function is sometimes broken Pin
    Winnibibo10-May-07 4:05
    Winnibibo10-May-07 4:05 
    Questionhow to determine if file is already open !!! Pin
    Balkrishna Talele11-Jan-06 23:18
    Balkrishna Talele11-Jan-06 23:18 
    GeneralFile Copy and Directory Copy Pin
    12-Oct-01 23:30
    suss12-Oct-01 23:30 
    GeneralRe: File Copy and Directory Copy Pin
    Abin23-Jan-04 4:38
    Abin23-Jan-04 4:38 
    Generalfile system Pin
    7-Jan-01 7:48
    suss7-Jan-01 7:48 
    GeneralRe: file system Pin
    krism6-Feb-02 1:40
    krism6-Feb-02 1:40 

    General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

    Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.