CAtlTemporaryFile Class
The latest version of this topic can be found at CAtlTemporaryFile Class.
This class provides methods for the creation and use of a temporary file.
Important
This class and its members cannot be used in applications that execute in the Windows Runtime.
Syntax
class CAtlTemporaryFile
Members
Public Constructors
| Name | Description |
|---|---|
| CAtlTemporaryFile::CAtlTemporaryFile | The constructor. |
| CAtlTemporaryFile::~CAtlTemporaryFile | The destructor. |
Public Methods
| Name | Description |
|---|---|
| CAtlTemporaryFile::Close | Call this method to close a temporary file and either delete its contents or store them under the specified file name. |
| CAtlTemporaryFile::Create | Call this method to create a temporary file. |
| CAtlTemporaryFile::Flush | Call this method to force any data remaining in the file buffer to be written to the temporary file. |
| CAtlTemporaryFile::GetPosition | Call this method to get the current file pointer position. |
| CAtlTemporaryFile::GetSize | Call this method to get the size in bytes of the temporary file. |
| CAtlTemporaryFile::HandsOff | Call this method to disassociate the file from the CAtlTemporaryFile object. |
| CAtlTemporaryFile::HandsOn | Call this method to open an existing temporary file and position the pointer at the end of the file. |
| CAtlTemporaryFile::LockRange | Call this method to lock a region in the file to prevent other processes from accessing it. |
| CAtlTemporaryFile::Read | Call this method to read data from the temporary file starting at the position indicated by the file pointer. |
| CAtlTemporaryFile::Seek | Call this method to move the file pointer of the temporary file. |
| CAtlTemporaryFile::SetSize | Call this method to set the size of the temporary file. |
| CAtlTemporaryFile::TempFileName | Call this method to return the name of the temporary file. |
| CAtlTemporaryFile::UnlockRange | Call this method to unlock a region of the temporary file. |
| CAtlTemporaryFile::Write | Call this method to write data to the temporary file starting at the position indicated by the file pointer. |
Public Operators
| Name | Description |
|---|---|
| CAtlTemporaryFile::operator HANDLE | Returns a handle to the temporary file. |
Remarks
CAtlTemporaryFile makes it easy to create and use a temporary file. The file is automatically named, opened, closed, and deleted. If the file contents are required after the file is closed, they can be saved to a new file with a specified name.
Requirements
Header: atlfile.h
Example
See the example for CAtlTemporaryFile::CAtlTemporaryFile.
CAtlTemporaryFile::CAtlTemporaryFile
The constructor.
CAtlTemporaryFile() throw();
Remarks
A file is not actually opened until a call is made to CAtlTemporaryFile::Create.
Example
// Declare the temporary file object
CAtlTemporaryFile myTempFile;
// Create the temporary file, without caring where it
// will be created, but with both read and write access.
ATLVERIFY (myTempFile.Create(NULL, GENERIC_READ|GENERIC_WRITE) == S_OK);
// Create some data to write to the file
int nBuffer[100];
DWORD bytes_written = 0, bytes_read = 0;
int i;
for (i = 0; i < 100; i++)
nBuffer[i] = i;
// Write some data to the file
myTempFile.Write(&nBuffer, sizeof(nBuffer), &bytes_written);
// Confirm it was written ok
ATLASSERT(bytes_written == sizeof(nBuffer));
// Flush the data to disk
ATLVERIFY(myTempFile.Flush() == S_OK);
// Reset the file pointer to the beginning of the file
ATLVERIFY(myTempFile.Seek(0, FILE_BEGIN) == S_OK);
// Read in the data
myTempFile.Read(&nBuffer, sizeof(nBuffer), bytes_read);
// Confirm it was read ok
ATLASSERT(bytes_read == sizeof(nBuffer));
// Close the file, making a copy of it at another location
ATLVERIFY(myTempFile.Close(_T("c:\\temp\\mydata.tmp")) == S_OK);
CAtlTemporaryFile::~CAtlTemporaryFile
The destructor.
~CAtlTemporaryFile() throw();
Remarks
The destructor calls CAtlTemporaryFile::Close.
CAtlTemporaryFile::Close
Call this method to close a temporary file and either delete its contents or store them under the specified file name.
HRESULT Close(LPCTSTR szNewName = NULL) throw();
Parameters
szNewName
The name for the new file to store the contents of the temporary file in. If this argument is NULL, the contents of the temporary file are deleted.
Return Value
Returns S_OK on success, or an error HRESULT on failure.
Example
See the example for CAtlTemporaryFile::CAtlTemporaryFile.
CAtlTemporaryFile::Create
Call this method to create a temporary file.
HRESULT Create(LPCTSTR pszDir = NULL, DWORD dwDesiredAccess = GENERIC_WRITE) throw();
Parameters
pszDir
The path for the temporary file. If this is NULL, GetTempPath will be called to assign a path.
dwDesiredAccess
The desired access. See dwDesiredAccess in CreateFile in the Windows SDK.
Return Value
Returns S_OK on success, or an error HRESULT on failure.
Example
See the example for CAtlTemporaryFile::CAtlTemporaryFile.
CAtlTemporaryFile::Flush
Call this method to force any data remaining in the file buffer to be written to the temporary file.
HRESULT Flush() throw();
Return Value
Returns S_OK on success, or an error HRESULT on failure.
Remarks
Similar to CAtlTemporaryFile::HandsOff, except that the file is not closed.
Example
See the example for CAtlTemporaryFile::CAtlTemporaryFile.
CAtlTemporaryFile::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
To change the file pointer position, use CAtlTemporaryFile::Seek.
CAtlTemporaryFile::GetSize
Call this method to get the size in bytes of the temporary 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.
CAtlTemporaryFile::HandsOff
Call this method to disassociate the file from the CAtlTemporaryFile object.
HRESULT HandsOff() throw();
Return Value
Returns S_OK on success, or an error HRESULT on failure.
Remarks
HandsOff and CAtlTemporaryFile::HandsOn are used to disassociate the file from the object, and reattach it if needed. HandsOff will force any data remaining in the file buffer to be written to the temporary file, and then close the file. If you want to close and delete the file permanently, or if you want to close and retain the contents of the file with a given name, use CAtlTemporaryFile::Close.
CAtlTemporaryFile::HandsOn
Call this method to open an existing temporary file and position the pointer at the end of the file.
HRESULT HandsOn() throw();
Return Value
Returns S_OK on success, or an error HRESULT on failure.
Remarks
CAtlTemporaryFile::HandsOff and HandsOn are used to disassociate the file from the object, and reattach it if needed.
CAtlTemporaryFile::LockRange
Call this method to lock a region in the temporary 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
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. To successfully unlock a region, use CAtlTemporaryFile::UnlockRange, ensuring the byte range corresponds 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.
CAtlTemporaryFile::operator HANDLE
Returns a handle to the temporary file.
operator HANDLE() throw();
CAtlTemporaryFile::Read
Call this method to read data from the temporary file starting at the position indicated by the file pointer.
HRESULT Read(
LPVOID pBuffer,
DWORD nBufSize,
DWORD& nBytesRead) 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.
Return Value
Returns S_OK on success, or an error HRESULT on failure.
Remarks
Calls CAtlFile::Read. To change the position of the file pointer, call CAtlTemporaryFile::Seek.
Example
See the example for CAtlTemporaryFile::CAtlTemporaryFile.
CAtlTemporaryFile::Seek
Call this method to move the file pointer of the temporary file.
HRESULT Seek(
LONGLONG nOffset,
DWORD dwFrom = FILE_CURRENT) throw();
Parameters
nOffset
The offset, in bytes, 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 CAtlFile::Seek. To obtain the current file pointer position, call CAtlTemporaryFile::GetPosition.
Example
See the example for CAtlTemporaryFile::CAtlTemporaryFile.
CAtlTemporaryFile::SetSize
Call this method to set the size of the temporary 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 CAtlFile::SetSize. On return, the file pointer is positioned at the end of the file.
CAtlTemporaryFile::TempFileName
Call this method to return the name of temporary file.
LPCTSTR TempFileName() throw();
Return Value
Returns the LPCTSTR pointing to the file name.
Remarks
The file name is generated in CAtlTemporaryFile::CAtlTemporaryFile with a call to the GetTempFileWindows SDK function. The file extension will always be "TFR" for the temporary file.
CAtlTemporaryFile::UnlockRange
Call this method to unlock a region of the temporary 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 CAtlFile::UnlockRange.
CAtlTemporaryFile::Write
Call this method to write data to the temporary file starting at the position indicated by the file pointer.
HRESULT Write(
LPCVOID pBuffer,
DWORD nBufSize,
DWORD* pnBytesWritten = NULL) 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.
pnBytesWritten
The number of bytes written.
Return Value
Returns S_OK on success, or an error HRESULT on failure.
Remarks
Calls CAtlFile::Write.
Example
See the example for CAtlTemporaryFile::CAtlTemporaryFile.