Share via

CAtlFile Class

  • Article

 

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at CAtlFile Class.

This class provides a thin wrapper around the Windows file-handling API.

Important

This class and its members cannot be used in applications that execute in the Windows Runtime.

Syntax

class CAtlFile : public CHandle

Members

Public Constructors

Name Description
CAtlFile::CAtlFile The constructor.

Public Methods

Name Description
CAtlFile::Create Call this method to create or open a file.
CAtlFile::Flush Call this method to clear the buffers for the file and cause all buffered data to be written to the file.
CAtlFile::GetOverlappedResult Call this method to get the results of an overlapped operation on the file.
CAtlFile::GetPosition Call this method to get the current file pointer position from the file.
CAtlFile::GetSize Call this method to get the size in bytes of the file.
CAtlFile::LockRange Call this method to lock a region in the file to prevent other processes from accessing it.
CAtlFile::Read Call this method to read data from a file starting at the position indicated by the file pointer.
CAtlFile::Seek Call this method to move the file pointer of the file.
CAtlFile::SetSize Call this method to set the size of the file.
CAtlFile::UnlockRange Call this method to unlock a region of the file.
CAtlFile::Write Call this method to write data to the file starting at the position indicated by the file pointer.

Protected Data Members

Name Description
CAtlFile::m_pTM Pointer to CAtlTransactionManager object

Remarks

Use this class when file-handling needs are relatively simple, but more abstraction than the Windows API provides is required, without including MFC dependencies.

Inheritance Hierarchy

CHandle

CAtlFile

Requirements

Header: atlfile.h

CAtlFile::CAtlFile

The constructor.

CAtlFile() throw();
CAtlFile(CAtlTransactionManager* pTM = NULL) throw();
CAtlFile(CAtlFile& file) throw();
explicit CAtlFile(HANDLE hFile) throw();

Parameters

file
The file object.

hFile
The file handle.

pTM
Pointer to CAtlTransactionManager object

Remarks

The copy constructor transfers ownership of the file handle from the original CAtlFile object to the newly constructed object.

CAtlFile::Create

Call this method to create or open a file.

HRESULT Create(
    LPCTSTR szFilename,
    DWORD dwDesiredAccess,
    DWORD dwShareMode,
    DWORD dwCreationDisposition,
    DWORD dwFlagsAndAttributes = FILE_ATTRIBUTE_NORMAL,
    LPSECURITY_ATTRIBUTES lpsa = NULL,
    HANDLE hTemplateFile = NULL) throw();

Parameters

szFilename
The file name.

dwDesiredAccess
The desired access. See dwDesiredAccess in CreateFile in the Windows SDK.

dwShareMode
The share mode. See dwShareMode in CreateFile.

dwCreationDisposition
The creation disposition. See dwCreationDisposition in CreateFile.

dwFlagsAndAttributes
The flags and attributes. See dwFlagsAndAttributes in CreateFile.

lpsa
The security attributes. See lpSecurityAttributes in CreateFile.

hTemplateFile
The template file. See hTemplateFile in CreateFile.

Return Value

Returns S_OK on success, or an error HRESULT on failure.

Remarks

Calls CreateFile to create or open the file.

CAtlFile::Flush

Call this method to clear the buffers for the file and cause all buffered data to be written to the file.

HRESULT Flush() throw();

Return Value

Returns S_OK on success, or an error HRESULT on failure.

Remarks

Calls FlushFileBuffers to flush buffered data to the file.

CAtlFile::GetOverlappedResult

Call this method to get the results of an overlapped operation on the file.

HRESULT GetOverlappedResult(
    LPOVERLAPPED pOverlapped,
    DWORD& dwBytesTransferred,
    BOOL bWait) throw();

Parameters

pOverlapped
The overlapped structure. See lpOverlapped in GetOverlappedResult in the Windows SDK.

dwBytesTransferred
The bytes transferred. See lpNumberOfBytesTransferred in GetOverlappedResult.

bWait
The wait option. See bWait in GetOverlappedResult.

Return Value

Returns S_OK on success, or an error HRESULT on failure.

Remarks

Calls GetOverlappedResult to get the results of an overlapped operation on the file.

CAtlFile::GetPosition

Call this method to get the current file pointer position.

HRESULT GetPosition(ULONGLONG& nPos) const throw();

Parameters

nPos
The position in bytes.

Return Value

Returns S_OK on success, or an error HRESULT on failure.

Remarks

Calls SetFilePointer to get the current file pointer position.

CAtlFile::GetSize

Call this method to get the size in bytes of the file.

HRESULT GetSize(ULONGLONG& nLen) const throw();

Parameters

nLen
The number of bytes in the file.

Return Value

Returns S_OK on success, or an error HRESULT on failure.

Remarks

Calls GetFileSize to get the size in bytes of the file.

CAtlFile::LockRange

Call this method to lock a region in the file to prevent other processes from accessing it.

HRESULT LockRange(ULONGLONG nPos, ULONGLONG nCount) throw();

Parameters

nPos
The position in the file where the lock should begin.

nCount
The length of the byte range to be locked.

Return Value

Returns S_OK on success, or an error HRESULT on failure.

Remarks

Calls LockFile to lock a region in the file. 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 a region, using CAtlFile::UnlockRange, the byte range must correspond exactly to the region that was previously locked. LockRange does not merge adjacent regions; if two locked regions are adjacent, you must unlock each separately.

CAtlFile::m_pTM

Pointer to a CAtlTransactionManager object.

CAtlTransactionManager* m_pTM;

Remarks

CAtlFile::Read

Call this method to read data from a file starting at the position indicated by the file pointer.

HRESULT Read(
    LPVOID pBuffer,
    DWORD nBufSize) throw();

HRESULT Read(
    LPVOID pBuffer,
    DWORD nBufSize,
    DWORD& nBytesRead) throw();

HRESULT Read(
    LPVOID pBuffer,
    DWORD nBufSize,
    LPOVERLAPPED pOverlapped) throw();

HRESULT Read(
    LPVOID pBuffer,
    DWORD nBufSize,
    LPOVERLAPPED pOverlapped,
    LPOVERLAPPED_COMPLETION_ROUTINE pfnCompletionRoutine) throw();

Parameters

pBuffer
Pointer to the buffer that will receive the data read from the file.

nBufSize
The buffer size in bytes.

nBytesRead
The number of bytes read.

pOverlapped
The overlapped structure. See lpOverlapped in ReadFile in the Windows SDK.

pfnCompletionRoutine
The completion routine. See lpCompletionRoutine in ReadFileEx in the Windows SDK.

Return Value

Returns S_OK on success, or an error HRESULT on failure.

Remarks

The first three forms call ReadFile, the last ReadFileEx to read data from the file. Use CAtlFile::Seek to move the file pointer.

CAtlFile::Seek

Call this method to move the file pointer of the file.

HRESULT Seek(
    LONGLONG nOffset,
    DWORD dwFrom = FILE_CURRENT) throw();

Parameters

nOffset
The offset from the starting point given by dwFrom.

dwFrom
The starting point (FILE_BEGIN, FILE_CURRENT, or FILE_END).

Return Value

Returns S_OK on success, or an error HRESULT on failure.

Remarks

Calls SetFilePointer to move the file pointer.

CAtlFile::SetSize

Call this method to set the size of the file.

HRESULT SetSize(ULONGLONG nNewLen) throw();

Parameters

nNewLen
The new length of the file in bytes.

Return Value

Returns S_OK on success, or an error HRESULT on failure.

Remarks

Calls SetFilePointer and SetEndOfFile to set the size of the file. On return, the file pointer is positioned at the end of the file.

CAtlFile::UnlockRange

Call this method to unlock a region of the file.

HRESULT UnlockRange(ULONGLONG nPos, ULONGLONG nCount) throw();

Parameters

nPos
The position in the file where the unlock should begin.

nCount
The length of the byte range to be unlocked.

Return Value

Returns S_OK on success, or an error HRESULT on failure.

Remarks

Calls UnlockFile to unlock a region of the file.

CAtlFile::Write

Call this method to write data to the file starting at the position indicated by the file pointer.

HRESULT Write(
    LPCVOID pBuffer,
    DWORD nBufSize,
    LPOVERLAPPED pOverlapped,
    LPOVERLAPPED_COMPLETION_ROUTINE pfnCompletionRoutine) throw();

HRESULT Write(
    LPCVOID pBuffer,
    DWORD nBufSize,
    DWORD* pnBytesWritten = NULL) throw();

HRESULT Write(
    LPCVOID pBuffer,
    DWORD nBufSize,
    LPOVERLAPPED pOverlapped) throw();

Parameters

pBuffer
The buffer containing the data to be written to the file.

nBufSize
The number of bytes to be transferred from the buffer.

pOverlapped
The overlapped structure. See lpOverlapped in WriteFile in the Windows SDK.

pfnCompletionRoutine
The completion routine. See lpCompletionRoutine in WriteFileEx in the Windows SDK.

pnBytesWritten
The bytes written.

Return Value

Returns S_OK on success, or an error HRESULT on failure.

Remarks

The first three forms call WriteFile, the last calls WriteFileEx to write data to the file. Use CAtlFile::Seek to move the file pointer.

See Also

Marquee Sample
Class Overview
CHandle Class