Windows Implementation (IOCTL)
Relevant source files
The following files were used as context for generating this wiki page:
The Windows implementation of the battery crate provides a bridge between the cross-platform unified API and the Windows-specific power management system. It utilizes Input/Output Control (IOCTL) codes to communicate with battery device drivers through the Windows API, specifically leveraging windows-sys for FFI bindings.
This module is responsible for identifying system batteries, querying their static information (such as design capacity and chemistry), and monitoring their dynamic status (such as current charge rate and voltage). The implementation maps these OS-specific responses into SI measurement units used throughout the library.
Sources: src/platform/mod.rs:18-22, README.md
Architecture Overview
The Windows backend is structured into several layers, separating high-level Rust traits from low-level FFI calls and Windows data structures.
Component Hierarchy
- PowerManager: Implements the
BatteryManagertrait, responsible for initializing the discovery of battery devices. - PowerIterator: Handles the iteration over available battery devices on the system.
- PowerDevice: Implements the
BatteryDevicetrait, representing a specific battery and holding its current state. - FFI Layer: Contains idiomatic Rust wrappers around Windows C-style structs like
BATTERY_INFORMATIONandBATTERY_STATUS.
Sources: src/platform/mod.rs:18-22, src/platform/traits.rs:12-23
The diagram above shows the relationship between the cross-platform traits and the Windows-specific IOCTL implementation.
Data Structures and FFI Wrappers
The implementation wraps Windows Power Management structures to provide type-safe access and helper methods for battery properties.
Battery Information
The BatteryInformation struct wraps the Windows BATTERY_INFORMATION structure. It provides access to static hardware capabilities and design specifications.
| Field / Method | Description | Source |
|---|---|---|
is_system_battery | Checks if the device is a system battery using BATTERY_SYSTEM_BATTERY flag. | info.rs:52 |
is_relative | Determines if capacity is reported as a relative percentage (BATTERY_CAPACITY_RELATIVE). | info.rs:57 |
technology | Converts the Chemistry byte array into a Technology enum. | info.rs:61 |
designed_capacity | The theoretical capacity of a new battery (mWh). | info.rs:70 |
full_charged_capacity | The current maximum capacity when fully charged (mWh). | info.rs:75 |
cycle_count | Number of charge/discharge cycles; returns None if the value is zero. | info.rs:79 |
Sources: src/platform/windows/ffi/ioctl/info.rs:10-86
Battery Status
The BatteryStatus struct wraps BATTERY_STATUS, representing the real-time state of the battery.
The logic flow for determining the battery State based on Windows PowerState flags.
Sources: src/platform/windows/ffi/ioctl/status.rs:57-65
Implementation Details
State Mapping
The Windows implementation maps internal PowerState bitmasks to the library's State enum. Specifically, if a battery is marked as "Power on line" but is not "Charging," it is treated as State::Full.
Sources: src/platform/windows/ffi/ioctl/status.rs:61
Capacity and Rate Handling
Windows provides these values through the status IOCTL. The wrapper handles "Unknown" constants defined by the Windows API:
- Voltage: Returns
Noneif equal toBATTERY_UNKNOWN_VOLTAGE. - Capacity: Returns
Noneif equal toBATTERY_UNKNOWN_CAPACITY. - Rate: Returns the absolute value of the rate, or
Noneif equal toBATTERY_UNKNOWN_RATE.
Sources: src/platform/windows/ffi/ioctl/status.rs:68-88
Technology Identification
Battery technology is determined by parsing the Chemistry field in the BATTERY_INFORMATION struct. This field is a 4-byte array (e.g., "LiOn", "NiCd") which is converted to a string and matched against the Technology enum.
Sources: src/platform/windows/ffi/ioctl/info.rs:61-67, src/types/technology.rs:25-47
Summary
The Windows Implementation (IOCTL) provides a robust interface for battery data on Windows 7 and later. By wrapping the complex Windows Power Management IOCTLs in idiomatic Rust structures, it allows the battery crate to provide accurate energy, capacity, and state information while abstracting away the low-level Win32 API details.
Sources: README.md:32, src/platform/windows/ffi/ioctl/mod.rs