Windows API Reference

File and I/O Operations

The Win32 API provides a comprehensive set of functions for interacting with the file system and performing input/output operations. This section covers key functions for creating, reading, writing, and managing files and directories.

Core File Functions

These functions are fundamental for most file operations.

Function Name Description
CreateFile Creates or opens a file, directory, disk, or console. Returns a handle to the object.
ReadFile Reads data from a file or device.
WriteFile Writes data to a file or device.
CloseHandle Closes an open object handle. Crucial for releasing resources.
GetFileAttributes Retrieves the attributes of a specified file or directory.
SetFileAttributes Sets the attributes of a specified file or directory.

Directory Management

Functions for working with directories.

Function Name Description
CreateDirectory Creates a new directory.
RemoveDirectory Deletes an empty directory.
FindFirstFile Starts the search for files that match a specified pattern in a directory. Returns a handle for subsequent searches.
FindNextFile Continues a file search started by a previous call to FindFirstFile.
FindClose Closes the search handle returned by FindFirstFile.

File Positioning and Control

Functions for manipulating the current file position and performing other control operations.

Function Name Description
SetFilePointer Moves the file pointer for the specified file.
GetFileSizeEx Retrieves the size of a specified file.
DeviceIoControl Performs a specified operation on a device. Useful for low-level disk operations.

Section Details

CreateFile

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

This is one of the most versatile functions in the Win32 API. It can be used to open existing files, create new ones, and even access other types of objects like pipes and serial ports.

  • lpFileName: The name of the file to be created or opened.
  • dwDesiredAccess: The type of access to the file (e.g., GENERIC_READ, GENERIC_WRITE).
  • dwShareMode: How the file can be shared by other threads or processes.
  • dwCreationDisposition: Specifies what actions to take if the file exists or does not exist.
  • dwFlagsAndAttributes: Specifies the file system attributes and flags for the file.
Always remember to call CloseHandle on the returned handle when you are finished with it to prevent resource leaks.

ReadFile

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

Reads data from the file specified by the hFile handle into the buffer pointed to by lpBuffer.

  • hFile: A handle to the file to be read.
  • lpBuffer: A pointer to the buffer that receives the data read from the file.
  • nNumberOfBytesToRead: The maximum number of bytes to be read.
  • lpNumberOfBytesRead: A pointer to a variable that receives the actual number of bytes read.
  • lpOverlapped: Pointer to an OVERLAPPED structure, used for asynchronous operations.

WriteFile

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

Writes data to the file or device specified by the hFile handle from the buffer pointed to by lpBuffer.

  • hFile: A handle to the file to be written to.
  • lpBuffer: A pointer to a buffer containing the data to be written.
  • nNumberOfBytesToWrite: The number of bytes to write.
  • lpNumberOfBytesWritten: A pointer to a variable that receives the actual number of bytes written.
  • lpOverlapped: Pointer to an OVERLAPPED structure, used for asynchronous operations.

CloseHandle

BOOL CloseHandle(HANDLE hObject);

Closes a single open object handle. After this call, the handle is no longer valid.

  • hObject: A handle to an open object.
Failure to close handles properly can lead to resource leaks, system instability, and performance degradation.

CreateDirectory

BOOL CreateDirectory(LPCTSTR lpPathName, LPSECURITY_ATTRIBUTES lpAttribute);

Creates a new directory with the specified name and attributes.

  • lpPathName: The path of the directory to create.
  • lpAttribute: Security attributes. Can be NULL.

Best Practices

  • Always check the return values of API functions for errors using GetLastError().
  • Handle file I/O errors gracefully (e.g., file not found, access denied).
  • Use appropriate sharing modes when opening files to avoid conflicts.
  • Close all opened file handles using CloseHandle.
  • Consider using asynchronous I/O for performance-critical applications.