Windows API Reference

System I/O Operations

This section details the Windows API functions and structures related to Input/Output operations. These APIs allow applications to interact with various hardware and software devices, enabling data transfer and management.

Key Concepts: Handles, Buffers, Asynchronous I/O, File I/O, Device I/O, I/O Control Codes.

Core I/O Functions

The following functions are fundamental for performing I/O operations on Windows:

CreateFile

Creates or opens a file, directory, disk, or other device. It returns a handle that can be used to access the object.

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

Parameters:

Parameter Type Description
lpFileName LPCWSTR The name of the file or device.
dwDesiredAccess DWORD The requested access to the file or device.
dwShareMode DWORD The desired sharing mode.
dwCreationDisposition DWORD Action to take if the file exists or doesn't exist.
dwFlagsAndAttributes DWORD File or device attributes and flags.
hTemplateFile HANDLE Optional handle to a template file.

ReadFile

Reads data from a specified file or overlapping I/O buffer.

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

Parameters:

Parameter Type Description
hFile HANDLE A handle to the file or device.
lpBuffer LPVOID The buffer that receives the data read from the file.
nNumberOfBytesToRead DWORD The maximum number of bytes to be read.
lpNumberOfBytesRead LPDWORD A pointer to a variable that receives the number of bytes read.
lpOverlapped LPOVERLAPPED Pointer to an OVERLAPPED structure, for asynchronous I/O.

WriteFile

Writes data to a specified file or device.

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

Parameters:

Parameter Type Description
hFile HANDLE A handle to the file or device.
lpBuffer LPCVOID The buffer containing the data to be written.
nNumberOfBytesToWrite DWORD The number of bytes to write.
lpNumberOfBytesWritten LPDWORD A pointer to a variable that receives the number of bytes written.
lpOverlapped LPOVERLAPPED Pointer to an OVERLAPPED structure, for asynchronous I/O.

CloseHandle

Closes an open object handle.

BOOL CloseHandle(
  HANDLE hObject
);

Parameters:

Parameter Type Description
hObject HANDLE A handle to the open object.

Asynchronous I/O

Asynchronous I/O allows an application to initiate an I/O operation and continue processing without waiting for the operation to complete. This is typically achieved using the OVERLAPPED structure and functions like ReadFileEx and WriteFileEx, or by using I/O Completion Ports.

OVERLAPPED Structure

Contains information used by the system for overlapped I/O operations.

typedef struct _OVERLAPPED {
  ULONG_PTR Internal;
  ULONG_PTR InternalHigh;
  union {
    struct {
      DWORD Offset;
      DWORD OffsetHigh;
    } DUMMYUNIONNAME;
    PVOID Pointer;
  } DUMMYUNIONNAME2;
  HANDLE    hEvent;
} OVERLAPPED, *LPOVERLAPPED;
Note: Proper management of handles and buffers is crucial for efficient and secure I/O operations. Always check return values for errors.

Device I/O Control

The DeviceIoControl function allows an application to directly send I/O control codes to a device driver, enabling fine-grained control over hardware.

DeviceIoControl

Sends a control code directly to a specified device driver, causing the corresponding device to perform the specified operation.

BOOL DeviceIoControl(
  HANDLE       hDevice,
  DWORD        dwIoControlCode,
  LPVOID       lpInBuffer,
  DWORD        nInBufferSize,
  LPVOID       lpOutBuffer,
  DWORD        nOutBufferSize,
  LPDWORD      lpBytesReturned,
  LPOVERLAPPED lpOverlapped
);

Error Handling

The GetLastError function is essential for diagnosing I/O-related errors. It returns the last error code set by a failed API function.

GetLastError

Retrieves the last error code that was set by a failed function call.

DWORD GetLastError(void);
Process Management Registry