CAtlTemporaryFile Class

 

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 CAtlTemporaryFile Class.

This class provides methods for the creation and use of a temporary file.

System_CAPS_ICON_important.jpg Important

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

class CAtlTemporaryFile

Public Constructors

NameDescription
CAtlTemporaryFile::CAtlTemporaryFileThe constructor.
CAtlTemporaryFile::~CAtlTemporaryFileThe destructor.

Public Methods

NameDescription
CAtlTemporaryFile::CloseCall this method to close a temporary file and either delete its contents or store them under the specified file name.
CAtlTemporaryFile::CreateCall this method to create a temporary file.
CAtlTemporaryFile::FlushCall this method to force any data remaining in the file buffer to be written to the temporary file.
CAtlTemporaryFile::GetPositionCall this method to get the current file pointer position.
CAtlTemporaryFile::GetSizeCall this method to get the size in bytes of the temporary file.
CAtlTemporaryFile::HandsOffCall this method to disassociate the file from the CAtlTemporaryFile object.
CAtlTemporaryFile::HandsOnCall this method to open an existing temporary file and position the pointer at the end of the file.
CAtlTemporaryFile::LockRangeCall this method to lock a region in the file to prevent other processes from accessing it.
CAtlTemporaryFile::ReadCall this method to read data from the temporary file starting at the position indicated by the file pointer.
CAtlTemporaryFile::SeekCall this method to move the file pointer of the temporary file.
CAtlTemporaryFile::SetSizeCall this method to set the size of the temporary file.
CAtlTemporaryFile::TempFileNameCall this method to return the name of the temporary file.
CAtlTemporaryFile::UnlockRangeCall this method to unlock a region of the temporary file.
CAtlTemporaryFile::WriteCall this method to write data to the temporary file starting at the position indicated by the file pointer.

Public Operators

NameDescription
CAtlTemporaryFile::operator HANDLEReturns a handle to the temporary file.

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.

Header: atlfile.h

See the example for 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);

The destructor.

~CAtlTemporaryFile() throw();

Remarks

The destructor calls 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.

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.

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.

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.

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.

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.

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.

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.

Returns a handle to the temporary file.

operator HANDLE() throw();

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.

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.

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.

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.

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.

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.

Class Overview
CAtlFile Class

Show: