File handling class - CAtlTemporaryFile

Public Methods

Let us take a look at the public methods provided in this class.

Close

CAtlTemporaryFile::Close: This method is called to close a file, either store the contents of the file to a new file under the specified file name or delete its contents.

Syntax

Syntax of the above method is-

HRESULT Close(LPCTSTR szNewName = NULL) throw();

 

In the above method, the parameter szNewName is the new name of the file that stores the contents of the temporary file.

Note: If the argument of the parameter szNewName = NULL, then it means the contents of the temporary file are deleted.

Return Value	Meaning
S_OK	Success
HRESULT	Failure

Create

CAtlTemporaryFile::Create: This method is used to create or open the temporary file.

Syntax

Syntax of the above method is-

HRESULT Create(LPCTSTR pszDir = NULL, DWORD dwDesiredAccess = GENERIC_WRITE) throw();

 

In the above method, the parameter pszDir store the path of the file. And if pszDir = NULL GetTempPathW, retrieve the path of the directory.

Return Value	Meaning
S_OK	Success
HRESULT	Failure

Flush  

CAtlTemporaryFile::Flush: This method is used to push/force any data remaining in the file buffer so that it can be written to the temporary file. It is similar to the HandsOff method except that the file is not closed in this case.

Syntax

Syntax of the above method is-

HRESULT Flush() throw();

Return Value	Meaning
S_OK	Success
HRESULT	Failure

Get_Position

CAtlTemporaryFile::GetPosition: This method is called to find the current file pointer position. And if you want to change the position of the file pointer, you can use Seek method of CAtlTemporaryFile.

Syntax

Syntax of the above method is-

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

 

The nPos parameter takes the position in bytes.

Return Value	Meaning
S_OK	Success
HRESULT	Failure

Get_Size

CAtlTemporaryFile::GetSize: This method is called to get the size in bytes of the file.

Syntax

Syntax of the above method is-

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

 

The nLen parameter takes the number of bytes in the temporary file.

Return Value	Meaning
S_OK	Success
HRESULT	Failure

Hands_Off

CAtlTemporaryFile::HandsOff: This method is called to disconnect the temporary file from the object. Both HandsOff and HandsOn methods are used to disconnect or reattach the file from the object as per the needs.

The HandsOff method will not permanently close or delete the file; to do this, you can call the Close method; the HandsOff method will push any data remaining in the file buffer so that it can be written to the temporary file and then close the file.

Syntax

Syntax of the above method is-

HRESULT HandsOff() throw();

Return Value	Meaning
S_OK	Success
HRESULT	Failure

Hands_On

CAtlTemporaryFile::HandsOn: HandsOn is one of the member functions of the CAtlTemporaryFile class. In most cases, the temporary file is deleted automatically if it moves out of the scope. Hence, because of this issue, HandsOn is mainly used when one needs to create a temporary file and does not want it to get automatically deleted. 

Using this function, one can open any of the existing temporary files. This function positions the pointer at the end of the file. No parameter is required to pass to this function. It returns a HANDLE type.

Syntax

Syntax of the above method is-

HRESULT HandsOn() throw();

Return Value	Meaning
S_OK	Success
HRESULT	Failure

Lock_Range

CAtlTemporaryFile::LockRange: Nowadays, the security of data is one of the most important things. Also, you want to prevent some application processes from accessing a particular area of any file. LockRange helps in this situation by locking a specific area or region of a file. We need to pass the following two things to this function in order to lock a region:-

1. nPos: The starting position of the lock.
    
2. nCount: The length of the lock, i.e., the byte range.
    

More than one area can be locked, but overlapping areas are not allowed. In order to unlock, we need to use the UnlockRange function. If the adjacent areas are locked in separate calls, then both of them have to be unlocked separately.

Syntax

Syntax of the above method is-

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

Return Value	Meaning
S_OK	Success
HRESULT	Failure

Handle

CAtlTemporaryFile::Handle: Handle is the member function of CAtlTemporaryFile. This function returns the Handle to any of the temporary file.

Syntax

Syntax of the above method is-

operator HANDLE() throw();

Read

CAtlTemporaryFile::Read: This function is used to read a particular area of a file. It takes in the following parameters to read:-

1. pBuffer: It is a pointer to a buffer that will store the read data of the file.
    
2. nBufSize: It denotes the size of the buffer.
    
3. nBytesRead: It denotes the number of bytes read.
    

Syntax

Syntax of the above method is-

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

 

One can also change the pointer using the Seek() function.

Return Value	Meaning
S_OK	Success
HRESULT	Failure

Seek

CAtlTemporaryFile::Seek: This method is called if you want to move the pointer of the temporary file and if you want to get the current file pointer position, call GetPosition Method.

Syntax

Syntax of the above method is-

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

 

The dwFrom parameter defines the starting point from the three values, i.e., FILE_BEGIN, FIEL_END, or FILE_CURRENT.

The nOffset parameter defines the offset in bytes from the point that is given by the dwFrom parameter.

Return Value	Meaning
S_OK	Success
HRESULT	Failure

Set_Size

CAtlTemporaryFile::SetSize: This method is called to set the size of the file.

Syntax

Syntax of the above method is-

HRESULT SetSize(ULONGLONG nNewLen) throw();

 

The nNewLen parameter defines the new length of the temporary file in bytes.

Return Value	Meaning
S_OK	Success
HRESULT	Failure

Temp_File_Name

CAtlTemporaryFile::TempFileName: This method is called to get the name of the temporary file. The extension will be ‘TFR’ for the temporary file.

Syntax

Syntax of the above method is-

LPCTSTR TempFileName() throw();

Return Value	Meaning
LPCTSTR	Pointing to file name

Unlock_Range

CAtlTemporaryFile::UnlockRange: This method is called to unlock a particular region of a temporary file.

Syntax

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

 

The parameter nPos tells about the position from where the unlock should begin in the file.

The nCount parameter tells about the length of the range to be unlocked.

Return Value	Meaning
S_OK	Success
HRESULT	Failure

Write

CAtlTemporaryFile::Write: This method is called to write the data to the temporary file. The data will be written from the position that is indicated by the file pointer.

Syntax

Syntax of the above method is-

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

 

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

The pBuffer parameter tells the buffer having the data to be written to the temporary file.

The pnBytesWritten parameter tells the number of bytes written in the file.

Return Value	Meaning
S_OK	Success
HRESULT	Failure

Frequently Asked Questions

Name the public methods in CAtlTemporaryFile class.

The methods used in the CAtlTemporaryFile class are Flush, Create, Read, HandsOff, HandsOn, Write, Close, etc.

What is the use of the Create method in CAtlTemporaryFile?

The create method of CAtlTemporaryFile is called to make a temporary file.

What is the use of the Read method in CAtlTemporaryFile?

The Read method of CAtlTemporaryFile is used to read a particular area of a file.

Conclusion

Kudos on finishing the blog! We have discussed the CAtlTemporaryFile class in the active template library(ATL). Further, we have discussed various member functions in the CAtlTemporaryFile of the File Handling Class.

This blog has helped to enhance your knowledge of the CAtlTemporaryFile Class in the active template library. Do not stop learning! Read some of our articles on the Active template library:

Thread pooling class-CComApartment

Memory management class-CAutoPtr.

Memory management class-CAutoPtrArray and CAutoPtrList.

 

Refer to our Guided Path to upskill yourself in DSA, Competitive Programming, JavaScript, System Design, and many more! If you want to test your competency in coding, check out the mock test series and participate in the contests hosted on Coding Ninjas Studio! 

We wish you Good Luck! 

Happy Learning!