File Handling Class-CAtlFile

Features

Below are some of the features of CAtlFile

• Provides a wrapper for the Windows file API.
   
• Allows for easy file handling, such as opening, reading, and writing to files.
   
• Provides methods for working with file attributes and permissions.
   
• It can be used to create, open, and close files.
   
• It can be used to read and write data to files.
   
• It can be used to seek and set the file pointer position.
   
• It can be used to lock and unlock files.

Member Functions

CAtlFile provides several member functions, such as:

1. Create - Creates and opens a new file or overwrites an existing file.
    
2. Read - Reads data from a file.
    
3. Write - Writes data to a file.
    
4. Seek - Changes the current file position.
    
5. GetPosition - Gets the current file position.
    
6. GetSize - Gets the size of the file.
    
7. Flush - Flushes any buffered data into the file.
    
8. Close - Close the file.

Let's discuss some of them in detail.

Create

CAtlFile::Create is a member function of the CAtlFile class in the C++ programming language. It is used to create a new file on a disk with the specified filename and access mode. If the file already exists, it will be truncated to zero length. If the file does not exist, it will be created. The function returns a Boolean value indicating the success or failure of the operation.

Syntax

HRESULT Create(
   LPCTSTR szFileName,
   DWORD dwDesiredAccess = GENERIC_READ | GENERIC_WRITE,
   DWORD dwShareMode = 0,
   DWORD dwCreationDisposition = CREATE_ALWAYS,
   DWORD dwFlagsAndAttributes = FILE_ATTRIBUTE_NORMAL
   LPSECURITY_ATTRIBUTES lpsa = NULL,
   HANDLE hTemplateFile = NULL) throw();
);

Where:

• lpszFileName is the name of the file to create.
   
• dwDesiredAccess is the desired access mode, such as GENERIC_READ or GENERIC_WRITE.
   
• dwShareMode specifies the sharing mode of the file.
   
• dwCreationDisposition specifies the action to take if the file already exists or if it does not exist.
   
• dwFlagsAndAttributes are the file attributes and flags.

Return Value

Return Value	Meaning
S_OK	Success
HRESULT	Failure

Flush

It is used to flush any buffered data to the underlying file or device. This function ensures that any changes made to the file or device are written to disk and that the file or device is in a consistent state. 

Syntax

HRESULT Flush() throw();

Return Value

Return Value	Meaning
S_OK	Success
HRESULT	Failure

GetOverlappedResult

It is used to retrieve the result of an asynchronous file operation that was previously initiated using the CAtlFile::Read or CAtlFile::Write methods with an OVERLAPPED structure. It returns a Boolean value showing whether the operation was successful or not and can also be used to retrieve the number of bytes transferred during the operation.

Syntax

HRESULT GetOverlappedResult(
    LPOVERLAPPED pOverlapped,
    DWORD& dwBytesTransferred,
    BOOL bWait) throw();

Parameter

Parameter	Meaning
dwBytesTransferred	The bytes transferred. See lpNumberOfBytesTransferred in GetOverlappedResult
bWait	The wait option. See bWait in GetOverlappedResult.
pOverlapped	The overlapped structure. See lpOverlapped in GetOverlappedResult in the Windows SDK.

Return Value

Return Value	Meaning
S_OK	Success
HRESULT	Failure

GetPosition

It returns the current position of the file pointer within the file. The return value is a "LONG LONG" data type, which can be used to seek a specific position within the file using the CAtlFile::Seek method. The position is the number of bytes from the beginning of the file.

Syntax

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

Parameter

Parameter	Meaning
nPos	The position in bytes.

Return Value

Return Value	Meaning
S_OK	Success
HRESULT	Failure

GetSize

It is used to retrieve the file size that the CAtlFile object represents. The file size is returned as a "ULONGLONG" data type, which is an unsigned long.

Syntax

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

Parameter

Parameter	Meaning
nLen	The number of bytes in the file.

Return Value

Return Value	Meaning
S_OK	Success
HRESULT	Failure

LockRange

It is used to lock a range of bytes in a file, preventing other processes from accessing that range. This can be useful when working with shared files to ensure that multiple processes do not try to access or modify the same part of the file at the same time. The method takes two arguments: the starting offset of the range to lock and the number of bytes to lock. If the lock is successful, the method returns true; otherwise, it returns false.

Syntax

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

Parameter

Parameter	Meaning
nCount	The length of the byte range to be locked.
nPos	The position in the file where the lock should begin.

Return Value

Return Value	Meaning
S_OK	Success
HRESULT	Failure

m_pTM

CAtlFile::m_pTM is a private member variable of the CAtlFile class of the ATL (Active Template Library) library in C++.

Read 

It is used to read data from a file that has been opened using the CAtlFile::Open method. The method takes three arguments:

• void* pv: A pointer to a buffer where the read data will be stored.
   
• ULONGLONG nCount: The number of bytes to read from the file.
   
• ULONGLONG& nRead: A reference to a variable that will store the number of bytes actually read from the file.

The method returns a HRESULT, which is a value indicating the success or failure of the operation.

Example

Here is an example:

CAtlFile file; 
file.Open(_T("example.txt"), GENERIC_READ); 
char buffer[1024]; 
ULONGLONG bytesRead;
file.Read(buffer, sizeof(buffer), bytesRead); file.Close();

Explanation: This code opens a file named "example.txt" in read-only mode, reads 1024 bytes from the file, stores them in the buffer array, and then closes the file. The number of bytes actually read from the file is stored in the bytesRead variable.

Write

It is used to write data to a file. The method takes a single argument, which is a pointer to the data that is to be written to the file and returns the number of bytes written.

Example

Here is an example:

CAtlFile file; 
file.Create(_T("test.txt"), GENERIC_WRITE, 0, CREATE_ALWAYS); 
char buffer[100] = "Hello, World!"; 
ULONG bytesWritten = 0; 
file.Write(buffer, sizeof(buffer), &bytesWritten);

In this example, the method Create is used to create a new file named "test.txt" and open it for writing. The Write method is then used to write the string "Hello, World!" to the file, and the number of bytes written is stored in the variable bytes written.

SetSize

The SetSize method is used to set the file size that the CAtlFile object represents. The method takes a single argument, which is the new size of the file in bytes. If the file is currently larger than the specified size, the extra data will be truncated. If the file is currently smaller than the specified size, the file will be padded with null characters.

Syntax

HRESULT SetSize(ULONGLONG nNewLen) throw();

Parameter

Parameter	Meaning
nNewLen	The new length of the file in bytes.

Return Value

Return Value	Meaning
S_OK	Success
HRESULT	Failure

UnlockRange

The UnlockRange method is used to unlock a range of bytes in a file that was previously locked by the LockRange method. 

Syntax

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

Parameter

Parameter	Meaning
nCount	The length of the byte range to be locked.
nPos	The position in the file where the lock should begin.

Return Value

Return Value	Meaning
S_OK	Success
HRESULT	Failure

Seek

The Seek method is used to change the current position of the file pointer. The method takes two arguments, the first being the number of bytes to move the file pointer, and the second is the move method, which specifies the point of reference for the move. The move method can be one of the following:

• FILE_BEGIN: The offset is relative to the beginning of the file.
   
• FILE_CURRENT: The offset is relative to the current position of the file pointer.
   
• FILE_END: The offset is relative to the end of the file.
   
• After the Seek method is called, the file pointer will be moved by the specified offset from the specified point of reference.
   

Syntax

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

Parameter

Parameter	Meaning
nOffset	The offset from the starting point given by dwFrom.
dwFrom	The starting point (FILE_BEGIN, FILE_CURRENT, or FILE_END).

Return Value

Return Value	Meaning
S_OK	Success
HRESULT	Failure

Frequently Asked Questions

What method can you use to determine the current file position in a CAtlFile object?

To determine the current file position in a CAtlFile object, you can use the GetPosition method. The GetPosition method returns the current position of the file pointer in bytes from the beginning of the file.

How can you write data to a file using CAtlFile?

You can use the Write method to write data to a file using the CAtlFile class. The Write method writes a specified number of bytes from a buffer to the file. It takes two arguments, a pointer to the buffer containing the data to be written and the number of bytes to be written.

How can you read data from a file using CAtlFile?

The Read method reads a specified number of bytes from the file into a buffer. It takes three arguments, a pointer to the buffer where the read data will be stored, the number of bytes to read, and a pointer to a variable that will store the number of bytes actually read from the file.

Conclusion

In this article, we have discussed the File Handling Class-CAtlFile. It is one of the several classes provided by Active Template Library.

If you want to explore more, here are some related articles - 

• The Template and Typename Keywords in C++
• Set in C++ Standard Template Library
• Algorithms In C++ STL

You may refer to our Guided Path on Code Studios for enhancing your skill set on DSA, Competitive Programming, System Design, etc. Check out essential interview questions, practice our available mock tests, look at the interview bundle for interview preparations, and so much more!

Happy Learning Ninja!