Core File Functions

The following table lists some of the most frequently used Win32 API functions for file operations:

Function Description
CreateFile Opens or creates a file or device.
ReadFile Reads data from a file or device.
WriteFile Writes data to a file or device.
CloseHandle Closes an open object handle.
DeleteFile Deletes an existing file.
CopyFile Copies an existing file to a new location.
MoveFile Moves an existing file to a new location.
GetFileAttributes Retrieves attributes for a specified file or directory.
SetFileAttributes Sets the attributes for a specified file or directory.

CreateFile

This is arguably the most fundamental function for file manipulation. It returns a handle to an opened file or device, which can then be used by other file I/O functions.

Syntax:

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

Key Parameters:

  • lpFileName: The name of the file.
  • dwDesiredAccess: The type of access to the file (e.g., GENERIC_READ, GENERIC_WRITE).
  • dwShareMode: How the file can be shared.
  • dwCreationDisposition: What to do if the file exists or not (e.g., OPEN_ALWAYS, CREATE_NEW, TRUNCATE_EXISTING).

ReadFile

Used to read data from a file into a buffer.

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

WriteFile

Used to write data from a buffer to a file.

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

CloseHandle

It's crucial to close file handles when they are no longer needed to free up system resources.

BOOL CloseHandle(HANDLE hObject);

DeleteFile

A straightforward function to remove a file from the file system.

BOOL DeleteFile(LPCSTR lpFileName);

CopyFile

Creates a new file that is a copy of an existing file.

BOOL CopyFile(
  LPCSTR lpExistingFileName,
  LPCSTR lpNewFileName,
  BOOL   bFailIfExists
);

MoveFile

Moves an existing file from one location to another.

BOOL MoveFile(
  LPCSTR lpExistingFileName,
  LPCSTR lpNewFileName
);

GetFileAttributes

Allows you to retrieve information about a file's attributes, such as whether it's read-only, hidden, or a directory.

DWORD GetFileAttributes(LPCSTR lpFileName);

SetFileAttributes

Used to modify the attributes of a file.

BOOL SetFileAttributes(
  LPCSTR lpFileName,
  DWORD  dwFileAttributes
);
Note: Error handling is critical when using these functions. Always check the return values and use GetLastError() to determine the cause of failure.

Working with Directories

The Win32 API also provides functions for managing directories:

  • CreateDirectory: Creates a new directory.
  • RemoveDirectory: Removes an existing directory.
  • FindFirstFile / FindNextFile: Used to enumerate the files and subdirectories within a directory.
  • GetCurrentDirectory: Retrieves the current working directory.
  • SetCurrentDirectory: Changes the current directory.

Asynchronous I/O

For performance-critical applications, the Win32 API supports asynchronous file operations using OVERLAPPED structures. This allows an application to initiate a read or write operation and continue executing other tasks without waiting for the operation to complete.

Key functions involved in asynchronous I/O include:

  • CreateFile with FILE_FLAG_OVERLAPPED.
  • ReadFileEx and WriteFileEx.
  • GetOverlappedResult.
  • CancelIo.

Security and Permissions

File operations are subject to security permissions. Functions like CreateFile use security attributes, and specific functions exist to manage Access Control Lists (ACLs) for finer-grained control over file access.