Windows Win32 API - File Operations

File Management Functions

The Windows API provides a comprehensive set of functions for interacting with the file system. These functions allow for creating, opening, reading, writing, and deleting files, as well as managing directories and file attributes.

Creating and Opening Files

Use these functions to create new files or open existing ones for various operations.

CreateFile

Creates or opens a file or I/O device. This is one of the most versatile file I/O functions.

HANDLE CreateFile(
  LPCSTR                lpFileName,
  DWORD                 dwDesiredAccess,
  DWORD                 dwShareMode,
  LPSECURITY_ATTRIBUTES lpSecurityAttributes,
  DWORD                 dwCreationDisposition,
  DWORD                 dwFlagsAndAttributes,
  HANDLE                hTemplateFile
);

Parameters:

lpFileName: The name of the file to be created or opened.
dwDesiredAccess: The generic access rights to the file (e.g., GENERIC_READ, GENERIC_WRITE).
dwShareMode: How the file will be shared.
dwCreationDisposition: How to create or open the file.
dwFlagsAndAttributes: File attributes and flags.
hTemplateFile: A handle to a template file for the file being created.

OpenFile

Opens an existing file. It's an older function but still relevant for certain compatibility scenarios.

int OpenFile(
  LPCSTR lpszName,
  OFSTRUCT *lpReOpenBuff,
  UINT fuStyle
);

Parameters:

lpszName: The name of the file to open.
lpReOpenBuff: Pointer to an OFSTRUCT structure that receives information about the file.
fuStyle: Flags that control the opening of the file.

Reading from and Writing to Files

Once a file handle is obtained, these functions are used to transfer data.

ReadFile

Reads data from a file or I/O device. Reads up to a specified number of bytes from the file handle into the buffer.

BOOL ReadFile(
  HANDLE       hFile,
  LPVOID       lpBuffer,
  DWORD        nNumberOfBytesToRead,
  LPDWORD      lpNumberOfBytesRead,
  LPOVERLAPPED lpOverlapped
);

Parameters:

hFile: Handle to the file.
lpBuffer: Pointer to the buffer that receives the data.
nNumberOfBytesToRead: Number of bytes to read.
lpNumberOfBytesRead: Pointer to the number of bytes actually read.
lpOverlapped: Pointer to an OVERLAPPED structure for asynchronous I/O.

WriteFile

Writes data to a file or I/O device. Writes up to a specified number of bytes from the buffer to the file.

BOOL WriteFile(
  HANDLE       hFile,
  LPCVOID      lpBuffer,
  DWORD        nNumberOfBytesToWrite,
  LPDWORD      lpNumberOfBytesWritten,
  LPOVERLAPPED lpOverlapped
);

Parameters:

hFile: Handle to the file.
lpBuffer: Pointer to the buffer containing the data to write.
nNumberOfBytesToWrite: Number of bytes to write.
lpNumberOfBytesWritten: Pointer to the number of bytes actually written.
lpOverlapped: Pointer to an OVERLAPPED structure for asynchronous I/O.

Closing and Manipulating Files

Essential functions for managing file resources and obtaining file information.

CloseHandle

Closes an open object handle. This is crucial for releasing resources associated with files, processes, and threads.

BOOL CloseHandle(
  HANDLE hObject
);

Parameters:

hObject: A handle to an open object.

SetEndOfFile

Sets the end-of-file position for the specified file. This can truncate or extend a file.

BOOL SetEndOfFile(
  HANDLE hFile
);

Parameters:

hFile: Handle to the file.

GetFileSizeEx

Retrieves the size of the specified file.

BOOL GetFileSizeEx(
  HANDLE         hFile,
  PLARGE_INTEGER lpFileSize
);

Parameters:

hFile: Handle to the file.
lpFileSize: Pointer to a LARGE_INTEGER structure that receives the file size.

Directory Management

Functions for creating, deleting, and navigating through directories.

CreateDirectory

Creates a new directory. If the parent directory does not exist, the function fails.

BOOL CreateDirectory(
  LPCSTR                lpPathName,
  LPSECURITY_ATTRIBUTES lpAttribute
);

Parameters:

lpPathName: The path of the directory to create.
lpAttribute: Security attributes.

RemoveDirectory

Deletes an existing empty directory.

BOOL RemoveDirectory(
  LPCSTR lpPathName
);

Parameters:

lpPathName: The path of the directory to remove.

Important Note: Always check the return values of Win32 API functions. Errors are typically indicated by a return value of 0 (for BOOL functions) or -1 (for some others). Use GetLastError() to retrieve more specific error information.

Development Tip: For robust error handling, consider using structured exception handling (SEH) or C++ exceptions in conjunction with checking API return codes.