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.

See also

Class Overview
CAtlFile Class