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
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
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for