LibreHardwareMonitorLib Stores all hardware groups and decides which devices should be enabled and updated. Creates a new instance with basic initial . Creates a new instance with additional . Computer settings that will be transferred to each . Contains computer information table read in accordance with System Management BIOS (SMBIOS) Reference Specification. Triggers the method for the given observer. Observer who call to devices. Triggers the method with the given visitor for each device in each group. Observer who call to devices. If hasn't been opened before, opens , and triggers the private method depending on which categories are enabled. If opened before, removes all and triggers . If opened before, removes all and recreates it. specific additional settings passed to its . Speed of Fan in RPM. Speed of Fan in percentage 0-100. This can e.g. be used to set fan curve when is . Temperature of Fan in degrees Celsius. This can e.g. be used to set fan curve when is . Support for the NZXT GRID+ V3 devices. Support for the Kraken X (X42, X52, X62 or X72) devices. Support for the KrakenZ devices. Initializes a new instance of the class. The group. The thread. The affinity. Gets the specified . The group. The thread. . Gets the CPUID. Gets the CPU index. Sets the default fan speed. Gets a sensor value. Current pmlog struct, used with pmlog-support/start. Legacy pmlogdataoutput struct, used with ADL2_New_QueryPMLogData_Get. Type of the sensor. The sensor. The factor. If set to true, resets the sensor value to null. true if sensor is supported, false otherwise Gets the OverdriveN temperature. The type. The sensor. The minimum temperature. The scale. If set to true, resets the sensor value to null. Gets the Overdrive6 power. The type. The sensor. Initializes a new instance of the class. Component name. Identifier that will be assigned to the device. Based on Additional settings passed by the . Gets the device identifier. This structure describes a group-specific affinity. Initializes a new instance of the struct. The group. The mask. Gets a single group affinity. The group. The index. . Gets the group. Gets the mask. Determines whether the specified is equal to this instance. The to compare with this instance. true if the specified is equal to this instance; otherwise, false. Returns a hash code for this instance. A hash code for this instance, suitable for use in hashing algorithms and data structures like a hash table. Implements the == operator. The a1. The a2. The result of the operator. Implements the != operator. The a1. The a2. The result of the operator. Object representing a component of the computer. Individual information can be read from the . Creates a new instance based on the data provided. Component name. Identifier that will be assigned to the device. Based on Additional settings passed by the . Event triggered when is closing. Collection of identifiers representing the purpose of the hardware. Handler that will trigger the actions assigned to it when the event occurs. Component returned to the assigned action(s). Basic abstract with methods for the class which can store all hardware and decides which devices are to be checked and updated. Triggered when a new is registered. Triggered when a is removed. Gets a list of all known . Can be updated by . List of all enabled devices. Gets or sets a value indicating whether collecting information about devices should be enabled and updated. if a given category of devices is already enabled. Gets or sets a value indicating whether collecting information about: devices should be enabled and updated. if a given category of devices is already enabled. Gets or sets a value indicating whether collecting information about devices should be enabled and updated. if a given category of devices is already enabled. Gets or sets a value indicating whether collecting information about or devices should be enabled and updated. if a given category of devices is already enabled. Gets or sets a value indicating whether collecting information about devices should be enabled and updated. if a given category of devices is already enabled. Gets or sets a value indicating whether collecting information about devices should be enabled and updated. if a given category of devices is already enabled. Gets or sets a value indicating whether collecting information about devices should be enabled and updated. if a given category of devices is already enabled. Gets or sets a value indicating whether collecting information about devices should be enabled and updated. if a given category of devices is already enabled. Gets or sets a value indicating whether collecting information about devices should be enabled and updated. if a given category of devices is already enabled. Gets or sets a value indicating whether collecting information about devices should be enabled and updated. if a given category of devices is already enabled. Generates full LibreHardwareMonitor report for devices that have been enabled. A formatted text string with library, OS and hardware information. Represents a unique / identifier in text format with a / separator. Creates a new identifier instance based on the base and additional elements. Base identifier being the beginning of the new one. Additional parts by which the base will be extended. Creates a new identifier instance based on the supplied . If available the identifier will consist of the vendor-id, product-id and serial number of the HidDevice. Alternatively a platform dependent identifier based on the usb device-path is generated. The this identifier will be created for. Abstract parent with logic for the abstract class that stores data. Accepts the observer for this instance. Computer observer making the calls. Call the method for all child instances (called only from visitors). Computer observer making the calls. A group of devices from one category in one list. Gets a list that stores information about in a given group. Report containing most of the known information about all in this . A formatted text string with hardware information. Stop updating this group in the future. Handler that will trigger the actions assigned to it when the event occurs. Component returned to the assigned action(s). Abstract object that stores information about a device. All sensors are available as an array of . Can contain . Type specified in . Gets a unique hardware ID that represents its location. Gets or sets device name. Gets the device that is the parent of the current hardware. For example, the motherboard is the parent of SuperIO. Gets an array of all sensors such as , , etc. Gets child devices, e.g. of the . Report containing most of the known information about the current device. A formatted text string with hardware information. Refreshes the information stored in array. An that will be triggered when a new sensor appears. An that will be triggered when one of the sensors is removed. Gets rarely changed hardware properties that can't be represented as sensors. Abstract object that represents additional parameters included in . Gets a parameter default value defined by library. Gets a parameter description defined by library. Gets a unique parameter ID that represents its location. Gets or sets information whether the given is the default for . Gets a parameter name defined by library. Gets the sensor that is the data container for the given parameter. Gets or sets the current value. Category of what type the selected sensor is. Stores the readed value and the time in which it was recorded. of the sensor. The time code during which the was recorded. Gets the value of the sensor Gets the time code during which the was recorded. Stores information about the readed values and the time in which they were collected. Gets the unique identifier of this sensor for a given . Gets a maximum value recorded for the given sensor. Gets a minimum value recorded for the given sensor. Gets or sets a sensor name. By default determined by the library. Gets the last recorded value for the given sensor. Gets a list of recorded values for the given sensor. Resets a value stored in . Resets a value stored in . Clears the values stored in . Abstract object that stores information about the limits of . Upper limit of value. Lower limit of value. Abstract object that stores information about the critical limits of . Critical upper limit of value. Critical lower limit of value. Abstract object that stores settings passed to , and . Returns information whether the given collection of settings contains a value assigned to the given key. Key to which the setting value is assigned. Assigns a setting option to a given key. Key to which the setting value is assigned. Text setting value. Gets a setting option assigned to the given key. Key to which the setting value is assigned. Default value. Removes a setting with the specified key from the settings collection. Key to which the setting value is assigned. Base interface for creating observers who call to devices. Refreshes the values of all in all on selected . Instance of the computer to be revisited. Refreshes the values of all on selected . Instance of the hardware to be revisited. Refreshes the values on selected . Instance of the sensor to be revisited. Refreshes the values on selected . Instance of the parameter to be revisited. Writes a debug message to the output window and appends it to the debug log file when ECIO_GIGABYTE_CONTROLLER_DEBUG is defined. This method only performs logging when the ECIO_GIGABYTE_CONTROLLER_DEBUG compilation symbol is defined. The log file is named "EcioPortGigabyteController_DebugLog.txt" and is appended to with each call. Use this method for diagnostic purposes during development or troubleshooting. The message to log. This text is written to both the debug output and the log file. Chipset temperature [℃] CPU temperature [℃] CPU Package temperature [℃] motherboard temperature [℃] "T_Sensor" temperature sensor reading [℃] "T_Sensor 2" temperature sensor reading [℃] VRM temperature [℃] CPU Core voltage [mV] CPU_Opt fan [RPM] VRM heat sink fan [RPM] Chipset fan [RPM] Water Pump [RPM] Water flow sensor reading [RPM] CPU current [A] "Water_In" temperature sensor reading [℃] "Water_Out" temperature sensor reading [℃] Water block temperature sensor reading [℃] An unsafe but universal implementation for the ACPI Embedded Controller IO interface for Windows It is unsafe because of possible race condition between this application and the PC firmware when writing to the EC registers. For a safe approach ACPI/WMI methods have to be used, but those are different for each motherboard model. This is a controller present on some Gigabyte motherboards for both Intel and AMD, that is in custom firmware loaded onto the 2nd ITE EC. It can be accessed by using memory mapped IO, mapping its internal RAM onto main RAM via the ISA Bridge. This class can disable it so that the regular IT87XX code can drive the fans. Enable/Disable Fan Control true on success Restore settings back to initial values Selects another bank. Memory from 0x10-0xAF swaps to data from new bank. Beware to select the default bank 0 after changing. Bank selection is reset after power cycle. New bank index. Can be a value of 0-3. Known motherboard models detected/recognized by LibreHardwareMonitor. Represents the motherboard of a computer with its and as . Creates motherboard instance by retrieving information from and creates a new based on data from and . table containing motherboard data. Additional settings passed by . Gets the . Gets the . Gets the name obtained from . Always Gets the information. Motherboard itself cannot be updated. Update instead. Closes using . Opens the mutexes. Closes the mutexes. Composite class containing information about the selected . Creates a new instance and assigns values. Name of the selected component. Description of the selected component. Default value of the selected component. Gets a name of the parent . Gets a description of the parent . Gets a default value of the parent . Thermal Grizzly WireView Pro II power monitor. Max RPM according to the8auer. This is a custom made fan. Time the fan needs to ramp up by 10%. Fan speed for this device is an approximation based on the curve configuration and current temperatures.
The device itself does not report actual fan speed. Represents an error that occurs during communication with a PSU controller over USB. The HID device associated with the communication error. Cannot be null. The error message that describes the nature of the communication failure. Represents an error that occurs during communication with a PSU controller over USB. The HID device associated with the communication error. Cannot be null. The error message that describes the nature of the communication failure. Observer making calls to selected component 's. Creates a new observer instance. Instance of the that triggers events during visiting the . Goes through all the components of the specified with its . Computer class instance that is derived from the interface. Goes through all the components of the specified with its . Hardware class instance that is derived from the interface. Goes through all the components of the specified using . Sensor class instance that is derived from the interface. Goes through all the components of the specified . Parameter class instance that is derived from the interface. System enclosure security status based on DMTF SMBIOS Reference Specification v.3.3.0, Chapter 7.4.3. System enclosure state based on DMTF SMBIOS Reference Specification v.3.3.0, Chapter 7.4.2. System enclosure type based on DMTF SMBIOS Reference Specification v.3.3.0, Chapter 7.4.1. Processor family based on DMTF SMBIOS Reference Specification v.3.3.0, Chapter 7.5.2. Processor characteristics based on DMTF SMBIOS Reference Specification v.3.3.0, Chapter 7.5.9. Processor type based on DMTF SMBIOS Reference Specification v.3.3.0, Chapter 7.5.1. Processor socket based on DMTF SMBIOS Reference Specification v.3.3.0, Chapter 7.5.5. System wake-up type based on DMTF SMBIOS Reference Specification v.3.3.0, Chapter 7.2.2. Cache associativity based on DMTF SMBIOS Reference Specification v.3.3.0, Chapter 7.8.5. Processor cache level. Memory type. Initializes a new instance of the class. The data. The strings. Gets the byte. The offset. . Gets the word. The offset. . Gets the dword. The offset. . Gets the qword. The offset. . Gets the string. The offset. . Motherboard BIOS information obtained from the SMBIOS table. Gets the BIOS release date. Gets the size of the physical device containing the BIOS. Gets the string number of the BIOS Vendor’s Name. Gets the string number of the BIOS Version. This value is a free-form string that may contain Core and OEM version information. Gets the size. . Gets the date. The bios date. . System information obtained from the SMBIOS table. Gets the family associated with system. This text string identifies the family to which a particular computer belongs. A family refers to a set of computers that are similar but not identical from a hardware or software point of view. Typically, a family is composed of different computer models, which have different configurations and pricing points. Computers in the same family often have similar branding and cosmetic features. Gets the manufacturer name associated with system. Gets the product name associated with system. Gets the serial number string associated with system. Gets the version string associated with system. Gets System enclosure obtained from the SMBIOS table. Gets the asset tag associated with the enclosure or chassis. Gets Gets or sets the system enclosure lock. System enclosure lock is present if . Otherwise, either a lock is not present or it is unknown if the enclosure has a lock. Gets the string describing the chassis or enclosure manufacturer name. Gets the number of power cords associated with the enclosure or chassis. Gets the state of the enclosure’s power supply (or supplies) when last booted. Gets the height of the enclosure, in 'U's. A U is a standard unit of measure for the height of a rack or rack-mountable component and is equal to 1.75 inches or 4.445 cm. A value of 0 indicates that the enclosure height is unspecified. Gets the physical security status of the enclosure when last booted. Gets the string describing the chassis or enclosure serial number. Gets the string describing the chassis or enclosure SKU number. Gets the thermal state of the enclosure when last booted. Gets Gets the number of null-terminated string representing the chassis or enclosure version. Motherboard information obtained from the SMBIOS table. Gets the value that represents the manufacturer's name. Gets the value that represents the motherboard's name. Gets the value that represents the motherboard's serial number. Gets the value that represents the motherboard's revision number. Processor information obtained from the SMBIOS table. Gets the characteristics of the processor. Gets the value that represents the number of cores per processor socket. Gets the value that represents the number of enabled cores per processor socket. Gets the value that represents the current processor speed (in MHz). Gets the external Clock Frequency, in MHz. If the value is unknown, the field is set to 0. Gets Gets the handle. The handle. Gets the identifier. Gets the L1 cache handle. Gets the L2 cache handle. Gets the L3 cache handle. Gets the string number of Processor Manufacturer. Gets the value that represents the maximum processor speed (in MHz) supported by the system for this processor socket. Gets Gets the value that represents the string number for the serial number of this processor. This value is set by the manufacturer and normally not changeable. Gets Gets the string number for Reference Designation. Gets the value that represents the number of threads per processor socket. Gets the value that represents the string number describing the Processor. Cache information obtained from the SMBIOS table. Gets Gets Gets the handle. Gets the value that represents the installed cache size. Gets the cache designation. . Memory information obtained from the SMBIOS table. Gets the string number of the string that identifies the physically labeled bank where the memory device is located. Gets the string number of the string that identifies the physically-labeled socket or board position where the memory device is located. Gets the string number for the manufacturer of this memory device. Gets the string number for the part number of this memory device. Gets the string number for the serial number of this memory device. Gets the size of the memory device. If the value is 0, no memory device is installed in the socket. If the value is 0xFFFF, the size is unknown. Gets the value that identifies the maximum capable speed of the device, in mega transfers per second (MT/s). Gets the configured speed of the device, in mega transfers per second (MT/s). Gets the configured voltage of this memory device, in millivolts (mV). Gets the type of this memory device. The type. Reads and processes information encoded in an SMBIOS table. Initializes a new instance of the class. Gets Gets Gets Gets Gets Gets Gets Report containing most of the information that could be read from the SMBIOS table. A formatted text string with computer information and the entire SMBIOS table. Gets all available smart attributes. Initializes a new instance of the class. The SMART attribute. Type of the sensor or null if no sensor is to be created. If there exists more than one attribute with the same sensor channel and type, then a sensor is created only for the first attribute. The name to be used for the sensor, or null if no sensor is created. True to hide the sensor initially. Helper to calculate the disk performance with base timestamps https://docs.microsoft.com/en-us/windows/win32/cimwin32prov/win32-perfrawdata Initializes static members of the class. Gets the processor group count. Sets the processor group affinity for the current thread. The processor group affinity. The previous processor group affinity. All OK, but need to wait. All OK, but need restart. All OK but need mode change. All OK, but with warning. ADL function completed successfully. Generic Error. Most likely one or more of the Escape calls to the driver failed! ADL not initialized. One of the parameter passed is invalid. One of the parameter size is invalid. Invalid ADL index passed. Invalid controller index passed. Invalid display index passed. Function not supported by the driver. Null Pointer error. Call can't be made due to disabled adapter. Invalid Callback. Display Resource conflict. Failed to update some of the values. Can be returned by set request that include multiple values if not all values were successfully committed. There's no Linux XDisplay in Linux Console environment. list of sensors defined by ADL_PMLOG_SENSORS Reserved list of sensors defined by ADL_PMLOG_SENSORS Sample rate in milliseconds Reserved Pointer to memory address containing logging data Structure version Current driver sample rate Timestamp of last update Reserved Memory size in bytes. Memory type in string. Highest default performance level Memory bandwidth in Mbytes/s HyperMemory size in bytes. Invisible Memory size in bytes. Visible Memory size in bytes. Vram vendor ID Memory Bandiwidth that is calculated and finalized on the driver side, grab and go. Memory Bit Rate that is calculated and finalized on the driver side, grab and go. Adapter properties flags from ctl_adapter_properties_flags_t. The graphics_adapter_properties field is a bitmask of these values. The operation was successful NvidiaML was not first initialized with nvmlInit() A supplied argument is invalid The requested operation is not available on target device The current user does not have permission for operation A query to find an object was unsuccessful An input argument is not large enough A device's external power cables are not properly attached NVIDIA driver is not loaded User provided timeout passed NVIDIA Kernel detected an interrupt issue with a GPU NvidiaML Shared Library couldn't be found or loaded Local version of NvidiaML doesn't implement this function infoROM is corrupted The GPU has fallen off the bus or has otherwise become inaccessible The GPU requires a reset before it can be used again The GPU control device has been blocked by the operating system/cgroups RM detects a driver/library version mismatch An operation cannot be performed because the GPU is currently in use An public driver error occurred Helper class to find STM32 COM ports based on VID and PID. Finds the names of all available COM ports that match the specified USB vendor ID (VID) and product ID (PID). The USB vendor ID to match. The USB product ID to match. A list of strings containing the names of matching COM ports.
The list is empty if no matching ports are found. Writes a debug message to both the output window and a log file when ISA_BRIDGE_EC_DEBUG is defined. The log entry is timestamped and appended to the file 'PawnIo_IsaBridgeEc_DebugLog.txt' in the application's working directory. This method only produces output when compiled with the ISA_BRIDGE_EC_DEBUG symbol defined. The message to log. This should provide relevant information for debugging purposes. Gets a value indicating whether PawnIO is installed on the system. Retrieves the version information for the installed PawnIO. Gets a value indicating whether the underlying handle is currently valid and open. Contains basic information about the operating system. Statically checks if the current system and . Gets information about whether the current system is 64 bit. Gets information about whether the current system is Unix based. Returns true if the current system is Windows 8 or a more recent Windows version The length of the inline array. Gets a ref to an individual element of the inline array. ⚠ Important ⚠: When this struct is on the stack, do not let the returned reference outlive the stack frame that defines it. Gets this inline array as a span. ⚠ Important ⚠: When this struct is on the stack, do not let the returned span outlive the stack frame that defines it. Gets this inline array as a span. ⚠ Important ⚠: When this struct is on the stack, do not let the returned span outlive the stack frame that defines it. Copies the fixed array to a new string up to the specified length regardless of whether there are null terminating characters. Thrown when is less than 0 or greater than . Copies the fixed array to a new string, stopping before the first null terminator character or at the end of the fixed array (whichever is shorter). Gets or sets bit 0 in the field. Gets or sets bit 1 in the field. Gets or sets bit 2 in the field. Gets or sets bit 3 in the field. Gets or sets bit 4 in the field. Gets or sets bit 5 in the field. Gets or sets bit 6 in the field. Gets or sets bit 7 in the field. Gets or sets bit 8 in the field. Gets or sets bit 9 in the field. Gets or sets bit 10 in the field. Gets or sets bit 11 in the field. Gets or sets bit 12 in the field. Gets or sets bit 13 in the field. Gets or sets bits 14-31 in the field. Allowed values are [0..262143]. Gets or sets bits 0-1 in the field. Allowed values are [0..3]. Gets or sets bit 2 in the field. Gets or sets bits 3-63 in the field. Allowed values are [0..2305843009213693951]. The length of the inline array. Gets this inline array as a span. ⚠ Important ⚠: When this struct is on the stack, do not let the returned span outlive the stack frame that defines it. Gets this inline array as a span. ⚠ Important ⚠: When this struct is on the stack, do not let the returned span outlive the stack frame that defines it. The length of the inline array. Gets this inline array as a span. ⚠ Important ⚠: When this struct is on the stack, do not let the returned span outlive the stack frame that defines it. Gets this inline array as a span. ⚠ Important ⚠: When this struct is on the stack, do not let the returned span outlive the stack frame that defines it. The length of the inline array. Gets this inline array as a span. ⚠ Important ⚠: When this struct is on the stack, do not let the returned span outlive the stack frame that defines it. Gets this inline array as a span. ⚠ Important ⚠: When this struct is on the stack, do not let the returned span outlive the stack frame that defines it. Gets or sets bit 0 in the field. Gets or sets bit 1 in the field. Gets or sets bit 2 in the field. Gets or sets bits 3-63 in the field. Allowed values are [0..2305843009213693951]. Gets or sets bit 0 in the field. Gets or sets bit 1 in the field. Gets or sets bits 2-5 in the field. Allowed values are [0..15]. Gets or sets bits 6-63 in the field. Allowed values are [0..288230376151711743]. Gets or sets bit 0 in the field. Gets or sets bit 1 in the field. Gets or sets bit 2 in the field. Gets or sets bit 3 in the field. Gets or sets bits 4-15 in the field. Allowed values are [0..4095]. Gets or sets bits 16-31 in the field. Allowed values are [0..65535]. Contains extern methods from "GDI32.dll". Contains extern methods from "ntdll.dll". Retrieves the specified system information. One of the values enumerated in SYSTEM_INFORMATION_CLASS, which indicate the kind of system information to be retrieved. These include the following values. Read more on learn.microsoft.com. A pointer to a buffer that receives the requested information. The size and structure of this information varies depending on the value of the SystemInformationClass parameter: Read more on learn.microsoft.com. The size of the buffer pointed to by the SystemInformation parameter, in bytes. An optional pointer to a location where the function writes the actual size of the information requested. If that size is less than or equal to the SystemInformationLength parameter, the function copies the information into the SystemInformation buffer; otherwise, it returns an NTSTATUS error code and returns in ReturnLength the size of buffer required to receive the requested information. Read more on learn.microsoft.com. Returns an NTSTATUS success or error code. The forms and significance of NTSTATUS error codes are listed in the Ntstatus.h header file available in the DDK, and are described in the DDK documentation. The NtQuerySystemInformation function and the structures that it returns are internal to the operating system and subject to change from one release of Windows to another. To maintain the compatibility of your application, it is better to use the alternate functions previously mentioned instead. If you do use NtQuerySystemInformation, access the function through run-time dynamic linking. This gives your code an opportunity to respond gracefully if the function has been changed or removed from the operating system. Signature changes, however, may not be detectable. This function has no associated import library. You must use the LoadLibrary and GetProcAddress functions to dynamically link to Ntdll.dll. Read more on learn.microsoft.com. The length of the inline array. Gets a ref to an individual element of the inline array. ⚠ Important ⚠: When this struct is on the stack, do not let the returned reference outlive the stack frame that defines it. Gets this inline array as a span. ⚠ Important ⚠: When this struct is on the stack, do not let the returned span outlive the stack frame that defines it. Gets this inline array as a span. ⚠ Important ⚠: When this struct is on the stack, do not let the returned span outlive the stack frame that defines it. The length of the inline array. Gets a ref to an individual element of the inline array. ⚠ Important ⚠: When this struct is on the stack, do not let the returned reference outlive the stack frame that defines it. Gets this inline array as a span. ⚠ Important ⚠: When this struct is on the stack, do not let the returned span outlive the stack frame that defines it. Gets this inline array as a span. ⚠ Important ⚠: When this struct is on the stack, do not let the returned span outlive the stack frame that defines it. The length of the inline array. Gets a ref to an individual element of the inline array. ⚠ Important ⚠: When this struct is on the stack, do not let the returned reference outlive the stack frame that defines it. Gets this inline array as a span. ⚠ Important ⚠: When this struct is on the stack, do not let the returned span outlive the stack frame that defines it. Gets this inline array as a span. ⚠ Important ⚠: When this struct is on the stack, do not let the returned span outlive the stack frame that defines it. The length of the inline array. Gets a ref to an individual element of the inline array. ⚠ Important ⚠: When this struct is on the stack, do not let the returned reference outlive the stack frame that defines it. Gets this inline array as a span. ⚠ Important ⚠: When this struct is on the stack, do not let the returned span outlive the stack frame that defines it. Gets this inline array as a span. ⚠ Important ⚠: When this struct is on the stack, do not let the returned span outlive the stack frame that defines it. The length of the inline array. Gets a ref to an individual element of the inline array. ⚠ Important ⚠: When this struct is on the stack, do not let the returned reference outlive the stack frame that defines it. Gets this inline array as a span. ⚠ Important ⚠: When this struct is on the stack, do not let the returned span outlive the stack frame that defines it. Gets this inline array as a span. ⚠ Important ⚠: When this struct is on the stack, do not let the returned span outlive the stack frame that defines it. The length of the inline array. Gets a ref to an individual element of the inline array. ⚠ Important ⚠: When this struct is on the stack, do not let the returned reference outlive the stack frame that defines it. Gets this inline array as a span. ⚠ Important ⚠: When this struct is on the stack, do not let the returned span outlive the stack frame that defines it. Gets this inline array as a span. ⚠ Important ⚠: When this struct is on the stack, do not let the returned span outlive the stack frame that defines it. The length of the inline array. Gets a ref to an individual element of the inline array. ⚠ Important ⚠: When this struct is on the stack, do not let the returned reference outlive the stack frame that defines it. Gets this inline array as a span. ⚠ Important ⚠: When this struct is on the stack, do not let the returned span outlive the stack frame that defines it. Gets this inline array as a span. ⚠ Important ⚠: When this struct is on the stack, do not let the returned span outlive the stack frame that defines it. Contains battery information. Generally, a warning state occurs before a low state, but you should not assume it will. It is possible to poll a battery and find that neither alert level has occurred, and poll the battery again and find it discharged to the extent that both levels have been achieved. This may indicate that you are not polling often enough. It may also indicate that the battery is unable to hold a charge for very long and is discharging more rapidly than you expected. Such a battery may be nearing the end of its useful life, or it may be damaged. The battery capabilities. This member can be one or more of the following values. | Value | Meaning | |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |
**BATTERY\_CAPACITY\_RELATIVE**
0x40000000
| Indicates that the battery capacity and rate information are relative, and not in any specific units. If this bit is not set, the reporting units are milliwatt-hours (mWh) for capacity and milliwatts (mW) for rate. If this bit is set, all references to units in the other battery documentation can be ignored. All rate information is reported in units per hour. For example, if the fully charged capacity is reported as 100, a rate of 200 indicates that the battery will use all of its capacity in half an hour.
| |
**BATTERY\_IS\_SHORT\_TERM**
0x20000000
| Indicates that the normal operation is for a fail-safe function. If this bit is not set the battery is expected to be used during normal system usage.
| |
**BATTERY\_SET\_CHARGE\_SUPPORTED**
0x00000001
| Indicates that set information requests of the type BatteryCharge are supported by this battery device.
| |
**BATTERY\_SET\_DISCHARGE\_SUPPORTED**
0x00000002
| Indicates that set information requests of the type BatteryDischarge are supported by this battery device.
| |
**BATTERY\_SYSTEM\_BATTERY**
0x80000000
| Indicates that the battery can provide general power to run the system.
| Read more on learn.microsoft.com. The battery technology. This member can be one of the following values. | Value | Meaning | |------------------------------------------------------------------------------|------------------------------------------------------------| |
0
| Nonrechargeable battery, for example, alkaline.
| |
1
| Rechargeable battery, for example, lead acid.
| Read more on learn.microsoft.com. Reserved. An abbreviated character string that indicates the battery's chemistry. This string is not necessarily zero-terminated. The following is a partial list of abbreviations that can be returned and the associated chemistries. | Unicode string | Meaning | |----------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------| |
**PbAc**
| Lead Acid
| |
**LION**
| Lithium Ion
| |
**Li-I**
| Lithium Ion
| |
**NiCd**
| Nickel Cadmium
| |
**NiMH**
| Nickel Metal Hydride
| |
**NiZn**
| Nickel Zinc
| |
**RAM**
| Rechargeable Alkaline-Manganese
| Other chemistries may appear in the future and your code should be able to handle them. Read more on learn.microsoft.com. The theoretical capacity of the battery when new, in mWh unless BATTERY\_CAPACITY\_RELATIVE is set. In that case, the units are undefined. The battery's current fully charged capacity in mWh (or relative). Compare this value to **DesignedCapacity** to estimate the battery's wear. The manufacturer's suggested capacity, in mWh, at which a low battery alert should occur. Definitions of low vary from manufacturer to manufacturer. In general, a warning state will occur before a low state, but you should not assume that it always will. To reduce risk of data loss, this value is usually used as the default setting for the critical battery alarm. The manufacturer's suggested capacity, in mWh, at which a warning battery alert should occur. Definitions of warning vary from manufacturer to manufacturer. In general, a warning state will occur before a low state, but you should not assume that it always will. To reduce risk of data loss, this value is usually used as the default setting for the low battery alarm. A bias from zero, in mWh, which is applied to battery reporting. Some batteries reserve a small charge that is biased out of the battery's capacity values to show "0" as the critical battery level. Critical bias is analogous to setting a fuel gauge to show "empty" when there are several liters of fuel left. The number of charge/discharge cycles the battery has experienced. This provides a means to determine the battery's wear. If the battery does not support a cycle counter, this member is zero. Contains battery query information. Some information about batteries is optional or may be meaningless for some batteries. If the particular type of data requested is not available for the current battery, then ERROR\_INVALID\_FUNCTION is returned. The current battery tag for the battery. Only information for a battery matching the tag can be returned. Whenever this value does not match the battery's current tag, the IOCTL request will be completed with ERROR\_FILE\_NOT\_FOUND. This indicates to the caller that the battery associated with the tag longer exists. The caller may opt to use the [**IOCTL\_BATTERY\_QUERY\_TAG**](ioctl-battery-query-tag.md) operation to determine the tag of the newly installed battery, if one exists. (See [Battery Tags](battery-information.md) for more information.) When a query information request is made, this value is verified. In addition, if the request is in progress while this value changes, the request is aborted with the status of ERROR\_FILE\_NOT\_FOUND. Read more on learn.microsoft.com. The level of the battery information being queried. The data returned by the IOCTL depends on this value. This member can be one of the following values. | Value | Meaning | |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |
**BatteryDeviceName**
4
| Null-terminated Unicode string that contains the battery's name.
| |
**BatteryEstimatedTime**
3
| A **ULONG** that specifies the estimated battery run time, in seconds. If the rate of drain provided in the **AtRate** member of the **BATTERY\_QUERY\_INFORMATION** structure is zero, this calculation is based on the present rate of drain. If **AtRate** is nonzero, the time returned is the expected run time for the given rate. If the estimated time is unknown (for example, the battery is not discharging and the **AtRate** specified was zero), the return value is BATTERY\_UNKNOWN\_TIME. Note that this value is not very accurate on some battery systems, and may vary widely depending on present power usage, which could be affected by disk activity and other factors. There is no notification mechanism for changes in this value.
| |
**BatteryGranularityInformation**
1
| An array of [**BATTERY\_REPORTING\_SCALE**](/windows/desktop/api/WinNT/ns-winnt-battery_reporting_scale) structures, never more than four entries.
| |
**BatteryInformation**
0
| A [**BATTERY\_INFORMATION**](battery-information-str.md) structure.
| |
**BatteryManufactureDate**
5
| A [**BATTERY\_MANUFACTURE\_DATE**](battery-manufacture-date-str.md) structure.
| |
**BatteryManufactureName**
6
| Null-terminated Unicode string that specifies the name of the manufacturer of the battery.
| |
**BatterySerialNumber**
8
| Null-terminated Unicode string that specifies the battery's serial number.
| |
**BatteryTemperature**
2
| A **ULONG** that specifies the battery's current temperature, in 10ths of a degree Kelvin.
| |
**BatteryUniqueID**
7
| Null-terminated Unicode string that uniquely identifies the battery. This value can be used to track a specific battery. In the case of smart batteries, this ID would be the concatenation of the manufacturer's name, device name, date of manufacture, and a printable representation of the serial number.
This value is not intended to be displayed to the user.
| Read more on learn.microsoft.com. This member is used only if **InformationLevel** is BatteryEstimatedTime. If this member is nonzero, it is a rate of drain that will be used to calculate the time until the battery is discharged for the BatteryEstimatedTime of an individual battery. It must be specified in mW, and must be a negative value to represent a battery discharge rate. Read more on learn.microsoft.com. Contains the current state of the battery. The BATTERY\_CRITICAL flag in the **PowerState** member of this structure indicates a hardware "battery critical" condition. This critical level is set by the battery manufacturer, not by the user in the "critical battery alarm." It generally means that the battery system has calculated that the battery is totally drained, and any power being drawn is beyond what is expected. The battery state. This member can be zero, one, or more of the following values. | Value | Meaning | |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------| |
**BATTERY\_CHARGING**
0x00000004
| Indicates that the battery is currently charging.
| |
**BATTERY\_CRITICAL**
0x00000008
| Indicates that battery failure is imminent. See the Remarks section for more information.
| |
**BATTERY\_DISCHARGING**
0x00000002
| Indicates that the battery is currently discharging.
| |
**BATTERY\_POWER\_ON\_LINE**
0x00000001
| Indicates that the system has access to AC power, so no batteries are being discharged.
| Read more on learn.microsoft.com. The current battery capacity, in mWh (or relative). This value can be used to generate a "gas gauge" display by dividing it by **FullChargedCapacity** member of the [**BATTERY\_INFORMATION**](battery-information-str.md) structure. If the capacity is unavailable, this member is BATTERY\_UNKNOWN\_CAPACITY. The current battery voltage across the battery terminals, in millivolts (mv). If the voltage is unavailable, this member is BATTERY\_UNKNOWN\_VOLTAGE. The current rate of battery charge or discharge. This value will be in milliwatts unless the battery rate information is relative, in which case it will be in arbitrary units per hour. To determine if battery information is relative, examine the BATTERY\_CAPACITY\_RELATIVE flag in the **Capabilities** member of the [**BATTERY\_INFORMATION**](battery-information-str.md) structure. A nonzero, positive rate indicates charging; a negative rate indicates discharging. Some batteries report only discharging rates. If the rate is unavailable, this member is BATTERY\_UNKNOWN\_RATE. If the state of the battery or power source changes, the rate may become available. Contains information about the conditions under which the battery status is to be retrieved. Requests for battery information are postponed until one of the following occurs: - The time-out expires (assuming **Timeout** is not -1). - The battery's current status does not match **PowerState**. - The battery's capacity is below **LowCapacity**. - The battery's capacity is above **HighCapacity**. - The battery tag changes. When any one of these conditions is satisfied, the data is collected and the operation returns. This allows applications to monitor typical dynamic battery information without polling the device. Before using either of the two Capacity conditions, make sure the battery supports them by using the [**IOCTL\_BATTERY\_QUERY\_STATUS**](ioctl-battery-query-status.md) control code with a time-out of zero. Examine the results to determine if the **Capacity** member is supported (that is, not BATTERY\_UNKNOWN\_CAPACITY). Read more on learn.microsoft.com. The current battery tag for the battery. Only information for a battery matching the tag can be returned. Whenever this value does not match the battery's current tag, the [**DeviceIoControl**](/windows/desktop/api/ioapiset/nf-ioapiset-deviceiocontrol) operation will fail with an error code of ERROR\_FILE\_NOT\_FOUND, which indicates to the caller that the battery for which it has a tag is no longer installed The caller may opt to use the [**IOCTL\_BATTERY\_QUERY\_TAG**](ioctl-battery-query-tag.md) operation to determine the tag of the newly installed battery, if any. In addition, if the request is in progress when the battery is removed, or the tag changes, the operation is aborted with the status of ERROR\_FILE\_NOT\_FOUND. (See [Battery Tags](battery-information.md) for more information.) The number of milliseconds the request will wait for the condition specified by the **PowerState**, **LowCapacity**, and **HighCapacity** members before completing. A value of -1 indicates that the request will wait indefinitely for the conditions to be satisfied. A value of zero indicates that the requested battery information is to be returned immediately, regardless of the other conditions. Any other value indicates that the request should wait that length of time, or until any one of the other conditions is satisfied. If the computer has entered sleep mode, the clock will continue to run, but exhausting the count will not wake the computer up. If the count is exhausted when the computer is awoken, and other conditions are satisfied, the call will return immediately on awakening. Read more on learn.microsoft.com. Zero, one, or more of the following status bits, which indicate the state of the battery. It is identical to the **PowerState** member of the [**BATTERY\_STATUS**](battery-status-str.md) structure. | Value | Meaning | |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------| |
**BATTERY\_CHARGING**
0x00000004
| Indicates that the battery is currently charging.
| |
**BATTERY\_CRITICAL**
0x00000008
| Indicates that battery failure is imminent. See the Remarks section for more information.
| |
**BATTERY\_DISCHARGING**
0x00000002
| Indicates that the battery is currently discharging.
| |
**BATTERY\_POWER\_ON\_LINE**
0x00000001
| Indicates that the battery has access to AC power.
| Read more on learn.microsoft.com. The current battery capacity, in mWh (or relative). This value is identical to the **Capacity** member of the [**BATTERY\_STATUS**](battery-status-str.md) structure. The current battery capacity, in mWh (or relative). This value is identical to the **Capacity** member of the [**BATTERY\_STATUS**](battery-status-str.md) structure. Provides disk performance information. Learn more about this API from learn.microsoft.com. The number of bytes read. The number of bytes written. The time it takes to complete a read. The time it takes to complete a write. The idle time. The number of read operations. The number of write operations. The depth of the queue. The cumulative count of I/Os that are associated I/Os. An associated I/O is a fragmented I/O, where multiple I/Os to a disk are required to fulfill the original logical I/O request. The most common example of this scenario is a file that is fragmented on a disk. The multiple I/Os are counted as split I/O counts. Read more on learn.microsoft.com. The system time stamp when a query for this structure is returned. Use this member to synchronize between the file system driver and a caller. Read more on learn.microsoft.com. The unique number for a device that identifies it to the storage manager that is indicated in the StorageManagerName member. The name of the storage manager that controls this device. Examples of storage managers are "PhysDisk," "FTDISK," and "DMIO". Read more on learn.microsoft.com. Represents a processor group-specific affinity, such as the affinity of a thread. Learn more about this API from learn.microsoft.com. A bitmap that specifies the affinity for zero or more processors within the specified group. The processor group number. This member is reserved. Contains information about the current state of both physical and virtual memory, including extended memory. MEMORYSTATUSEX reflects the state of memory at the time of the call. It also reflects the size of the paging file at that time. The operating system can enlarge the paging file up to the maximum size set by the administrator. The physical memory sizes returned include the memory from all nodes. Read more on learn.microsoft.com. The size of the structure, in bytes. You must set this member before calling GlobalMemoryStatusEx. Read more on learn.microsoft.com. A number between 0 and 100 that specifies the approximate percentage of physical memory that is in use (0 indicates no memory use and 100 indicates full memory use). The amount of actual physical memory, in bytes. The amount of physical memory currently available, in bytes. This is the amount of physical memory that can be immediately reused without having to write its contents to disk first. It is the sum of the size of the standby, free, and zero lists. The current committed memory limit for the system or the current process, whichever is smaller, in bytes. To get the system-wide committed memory limit, call GetPerformanceInfo. The maximum amount of memory the current process can commit, in bytes. This value is equal to or smaller than the system-wide available commit value. To calculate the system-wide available commit value, call GetPerformanceInfo and subtract the value of CommitTotal from the value of CommitLimit. The size of the user-mode portion of the virtual address space of the calling process, in bytes. This value depends on the type of process, the type of processor, and the configuration of the operating system. For example, this value is approximately 2 GB for most 32-bit processes on an x86 processor and approximately 3 GB for 32-bit processes that are large address aware running on a system with 4-gigabyte tuning enabled. The amount of unreserved and uncommitted memory currently in the user-mode portion of the virtual address space of the calling process, in bytes. Reserved. This value is always 0. The **HRESULT** data type is the same as the [SCODE](scode.md) data type. An **HRESULT** value consists of the following fields: - A 1-bit code indicating severity, where zero represents success and 1 represents failure. - A 4-bit reserved value. - An 11-bit code indicating responsibility for the error or warning, also known as a facility code. - A 16-bit code describing the error or warning. Most MAPI interface methods and functions return **HRESULT** values to provide detailed cause formation. **HRESULT** values are also used widely in OLE interface methods. OLE provides several macros for converting between **HRESULT** values and **SCODE** values, another common data type for error handling. > [!NOTE] > In 64-bit MAPI, **HRESULT** is still a 32-bit value. For information about the OLE use of **HRESULT** values, see the *OLE Programmer's Reference*. For more information about the use of these values in MAPI, see [Error Handling](error-handling-in-mapi.md) and any of the following interface methods: [IABLogon::GetLastError](iablogon-getlasterror.md) [IMAPISupport::GetLastError](imapisupport-getlasterror.md) [IMAPIControl::GetLastError](imapicontrol-getlasterror.md) [IMAPITable::GetLastError](imapitable-getlasterror.md) [IMAPIProp::GetLastError](imapiprop-getlasterror.md) [IMAPIViewAdviseSink::OnPrint](imapiviewadvisesink-onprint.md) Read more on learn.microsoft.com. A pointer to the IErrorInfo interface that provides more information about the error. You can specify to use the current IErrorInfo interface, or new IntPtr(-1) to ignore the current IErrorInfo interface and construct the exception just from the error code. , if it does not reflect an error. The LUID structure is an opaque structure that specifies an identifier that is guaranteed to be unique on the local machine. For more information, see the reference page for LUID in the Microsoft Windows SDK documentation. Learn more about this API from learn.microsoft.com. A pointer to a null-terminated, constant, ANSI character string. A pointer to the first character in the string. The content should be considered readonly, as it was typed as constant in the SDK. Gets the number of characters up to the first null character (exclusive). Returns a with a copy of this character array, decoding as UTF-8. A , or if is . Returns a span of the characters in this string, up to the first null character (exclusive). A pointer to a null-terminated, constant character string. A pointer to the first character in the string. The content should be considered readonly, as it was typed as constant in the SDK. Gets the number of characters up to the first null character (exclusive). Returns a with a copy of this character array, up to the first null character (exclusive). A , or if is . Returns a span of the characters in this string, up to the first null character (exclusive). A pointer to a constant, empty-string terminated list of null-terminated strings that uses UTF-16 encoding. A pointer to the first character in the string. The content should be considered readonly, as it was typed as constant in the SDK. Gets the number of characters in this null-terminated string list, excluding the final null terminator. Returns a with a copy of this character array. A , or if is . Returns a span of the characters in this string. Returns a span of the characters in this string, up to the first null character (exclusive). A pointer to an empty-string terminated list of null-terminated strings that uses UTF-16 encoding. A pointer to the first character in the string. Returns a span of the characters in this string. The length of the inline array. Gets a ref to an individual element of the inline array. ⚠ Important ⚠: When this struct is on the stack, do not let the returned reference outlive the stack frame that defines it. Gets this inline array as a span. ⚠ Important ⚠: When this struct is on the stack, do not let the returned span outlive the stack frame that defines it. Gets this inline array as a span. ⚠ Important ⚠: When this struct is on the stack, do not let the returned span outlive the stack frame that defines it. The length of the inline array. Gets a ref to an individual element of the inline array. ⚠ Important ⚠: When this struct is on the stack, do not let the returned reference outlive the stack frame that defines it. Gets this inline array as a span. ⚠ Important ⚠: When this struct is on the stack, do not let the returned span outlive the stack frame that defines it. Gets this inline array as a span. ⚠ Important ⚠: When this struct is on the stack, do not let the returned span outlive the stack frame that defines it. The length of the inline array. Gets a ref to an individual element of the inline array. ⚠ Important ⚠: When this struct is on the stack, do not let the returned reference outlive the stack frame that defines it. Gets this inline array as a span. ⚠ Important ⚠: When this struct is on the stack, do not let the returned span outlive the stack frame that defines it. Gets this inline array as a span. ⚠ Important ⚠: When this struct is on the stack, do not let the returned span outlive the stack frame that defines it. Copies the fixed array to a new string up to the specified length regardless of whether there are null terminating characters. Thrown when is less than 0 or greater than . Copies the fixed array to a new string, stopping before the first null terminator character or at the end of the fixed array (whichever is shorter). Represents a Win32 handle that can be closed with . The length of the inline array. Gets a ref to an individual element of the inline array. ⚠ Important ⚠: When this struct is on the stack, do not let the returned reference outlive the stack frame that defines it. Gets this inline array as a span. ⚠ Important ⚠: When this struct is on the stack, do not let the returned span outlive the stack frame that defines it. Gets this inline array as a span. ⚠ Important ⚠: When this struct is on the stack, do not let the returned span outlive the stack frame that defines it. Contains extern methods from "CFGMGR32.dll". Contains extern methods from "KERNEL32.dll". Contains macros. Contains extern methods from "SETUPAPI.dll". The CM_Get_Device_Interface_List_Size function retrieves the buffer size that must be passed to the CM_Get_Device_Interface_List function. (Unicode) Caller-supplied pointer to a location that receives the required length, in characters, of a buffer to hold the multiple Unicode strings that will be returned by CM_Get_Device_Interface_List. Read more on learn.microsoft.com. Supplies a GUID that identifies a device interface class. Read more on learn.microsoft.com. Caller-supplied pointer to a NULL-terminated string that represents a device instance ID. If specified, the function retrieves the length of symbolic link names for the device interfaces that are supported by the device, for the specified class. If this value is NULL, or if it points to a zero-length string, the function retrieves the length of symbolic link names for all interfaces that belong to the specified class. Read more on learn.microsoft.com. Contains one of the following caller-supplied flags: This doc was truncated. Read more on learn.microsoft.com. If the operation succeeds, the function returns CR_SUCCESS. Otherwise, it returns one of the error codes with the CR_ prefix as defined in Cfgmgr32.h. > [!NOTE] > The cfgmgr32.h header defines CM_Get_Device_Interface_List_Size as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see [Conventions for Function Prototypes](/windows/win32/intl/conventions-for-function-prototypes). Read more on learn.microsoft.com. The CM_Get_Device_Interface_List function retrieves a list of device interface instances that belong to a specified device interface class. (Unicode) Supplies a GUID that identifies a device interface class. Caller-supplied pointer to a NULL-terminated string that represents a device instance ID. If specified, the function retrieves device interfaces that are supported by the device for the specified class. If this value is NULL, or if it points to a zero-length string, the function retrieves all interfaces that belong to the specified class. Caller-supplied pointer to a buffer that receives multiple, NULL-terminated Unicode strings, each representing the symbolic link name of an interface instance. Caller-supplied value that specifies the length, in characters, of the buffer pointed to by Buffer. Call CM_Get_Device_Interface_List_Size to determine the required buffer size. Contains one of the following caller-supplied flags: If the operation succeeds, the function returns CR_SUCCESS. Otherwise, it returns one of the error codes with the CR_ prefix as defined in Cfgmgr32.h. The following table includes some of the more common error codes that this function might return. This doc was truncated. Between calling CM_Get_Device_Interface_List_Size to get the size of the list and calling CM_Get_Device_Interface_List to get the list, a new device interface can be added to the system causing the size returned to no longer be valid.  Callers should be robust to that condition and retry getting the size and the list if CM_Get_Device_Interface_List returns CR_BUFFER_SMALL. The CM_Locate_DevNode function obtains a device instance handle to the device node that is associated with a specified device instance ID on the local machine. (Unicode) A pointer to a device instance handle that CM_Locate_DevNode retrieves. The retrieved handle is bound to the local machine. A pointer to a NULL-terminated string representing a device instance ID. If this value is NULL, or if it points to a zero-length string, the function retrieves a device instance handle to the device at the root of the device tree. A variable of ULONG type that supplies one of the following flag values that apply if the caller supplies a device instance identifier: If the operation succeeds, CM_Locate_DevNode returns CR_SUCCESS. Otherwise, the function returns one of the CR_Xxx error codes that are defined in Cfgmgr32.h. For information about using device instance handles that are bound to the local machine, see CM_Get_Child. > [!NOTE] > The cfgmgr32.h header defines CM_Locate_DevNode as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see [Conventions for Function Prototypes](/windows/win32/intl/conventions-for-function-prototypes). Read more on learn.microsoft.com. The CM_Get_DevNode_Property function retrieves a device instance property. Device instance handle that is bound to the local machine. Pointer to a DEVPROPKEY structure that represents the device property key of the requested device instance property. Pointer to a DEVPROPTYPE-typed variable that receives the property-data-type identifier of the requested device instance property, where the property-data-type identifier is the bitwise OR between a base-data-type identifier and, if the base-data type is modified, a property-data-type modifier. Pointer to a buffer that receives the requested device instance property. CM_Get_DevNode_Property retrieves the requested property only if the buffer is large enough to hold all the property value data. The pointer can be NULL. The size, in bytes, of the PropertyBuffer buffer. If PropertyBuffer is set to NULL, *PropertyBufferSize must be set to zero. As output, if the buffer is not large enough to hold all the property value data, CM_Get_DevNode_Property returns the size of the data, in bytes, in *PropertyBufferSize. Reserved. Must be set to zero. If the operation succeeds, the function returns CR_SUCCESS. Otherwise, it returns one of the CR_-prefixed error codes defined in Cfgmgr32.h. CM_Get_DevNode_Property is part of the Unified Device Property Model. Determines whether media are accessible for a device. Learn more about this API from learn.microsoft.com. Enables or disables the mechanism that ejects media, for those devices possessing that locking capability. The **IOCTL_STORAGE_MEDIA_REMOVAL** control code is valid only for devices that support removable media. Ejects media from a SCSI device. **IOCTL_STORAGE_EJECT_MEDIA** may or may not be supported on SCSI devices that support removable media. Loads media into a device. The **IOCTL_STORAGE_LOAD_MEDIA** control code is valid only for devices that support loadable media. Enables or disables the mechanism that ejects media. Disabling the mechanism locks the drive. The driver tracks **IOCTL_STORAGE_EJECTION_CONTROL** requests by caller. It ignores requests to enable the ejection mechanism unless it has received a request to disable the ejection mechanism from the same caller. This prevents other callers from unlocking the drive. Enables or disables media change notification. Disabling media change notification prevents the GUID_IO_MEDIA_ARRIVAL and GUID_IO_MEDIA_REMOVAL events. Learn more about this API from learn.microsoft.com. Retrieves the geometry information for the device. (IOCTL_STORAGE_GET_MEDIA_TYPES) This device I/O control operation is for all class drivers, as well as non-SCSI hard drives and floppy disk devices. Retrieves information about the types of media supported by a device. Learn more about this API from learn.microsoft.com. Retrieves the serial number of a USB device. Learn more about this API from learn.microsoft.com. Retrieves the hotplug configuration of the specified device. Refer to the Remarks section in the reference page for [STORAGE_HOTPLUG_INFO](ns-winioctl-storage_hotplug_info.md) for more information about hotplug devices. Sets the hotplug configuration of the specified device. Refer to the Remarks section in the reference page for [STORAGE_HOTPLUG_INFO](ns-winioctl-storage_hotplug_info.md) for more information about hotplug devices. This operation sets only the **DeviceHotplug** member of the [STORAGE_HOTPLUG_INFO](ns-winioctl-storage_hotplug_info.md) structure passed in. Read more on learn.microsoft.com. Retrieves the device type, device number, and, for a partitionable device, the partition number of a device. The values in the [STORAGE_DEVICE_NUMBER](ns-winioctl-storage_device_number.md) structure are guaranteed to remain unchanged until the device is removed or the system is restarted. It is not guaranteed to be persistent across device restarts or system restarts. Retrieves the geometry information for the device. (IOCTL_STORAGE_READ_CAPACITY) Learn more about this API from learn.microsoft.com. Windows applications can use this control code to set the temperature threshold of a device (when it's supported by the device). Learn more about this API from learn.microsoft.com. Windows applications can use this control code to return properties of a storage device or adapter. The request indicates the kind of information to retrieve, such as inquiry data for a device or capabilities and limitations of an adapter. Learn more about this API from learn.microsoft.com. Windows applications can use this control code to return the properties of a storage device or adapter. The optional output buffer returned through the *lpOutBuffer* parameter can be one of several structures depending on the value of the **PropertyId** member of the [STORAGE_PROPERTY_QUERY](ns-winioctl-storage_property_query.md) structure pointed to by the *lpInBuffer* parameter. These values are enumerated by the [STORAGE_PROPERTY_ID](ne-winioctl-storage_property_id.md) enumeration. If the **QueryType** member of the **STORAGE_PROPERTY_QUERY** is set to **PropertyExistsQuery** then no structure is returned. The IOCTL_STORAGE_MANAGE_DATA_SET_ATTRIBUTES control code communicates attribute information to the volume manager and storage system device. Use the **IOCTL_STORAGE_MANAGE_DATA_SET_ATTRIBUTES** control code for sending storage system-specific information to the volume manager and storage system. The input buffers passed through the *lpInBuffer* parameter start with a [DEVICE_MANAGE_DATA_SET_ATTRIBUTES](ns-winioctl-device_manage_data_set_attributes.md) structure but may contain additional parameters before the list of data set ranges depending on the value of the **Action** member of the **DEVICE_MANAGE_DATA_SET_ATTRIBUTES** structure. The output buffers returned through the *lpOutBuffer* parameter start with a [DEVICE_MANAGE_DATA_SET_ATTRIBUTES_OUTPUT](ns-winioctl-device_manage_data_set_attributes.md) structure but then can contain additional data depending on the value of the **Action** member of the **DEVICE_MANAGE_DATA_SET_ATTRIBUTES_OUTPUT** structure pointed to by the *lpOutBuffer* parameter. These values are one of the values for the [DEVICE_DATA_MANAGEMENT_SET_ACTION](/windows/desktop/DevIO/device-data-management-set-action) data type. Value | Parameters structure | Output block structure ------|----------------------|----------------------- **DeviceDsmAction_Trim** | None | None **DeviceDsmAction_Notification** | [DEVICE_DSM_NOTIFICATION_PARAMETERS](ns-winioctl-device_dsm_notification_parameters.md) | None **DeviceDsmAction_OffloadRead** | [DEVICE_DSM_OFFLOAD_READ_PARAMETERS](ns-winioctl-device_dsm_offload_read_parameters.md) | [STORAGE_OFFLOAD_READ_OUTPUT](ns-winioctl-storage_offload_read_output.md) **DeviceDsmAction_OffloadWrite** | [DEVICE_DSM_OFFLOAD_WRITE_PARAMETERS](ns-winioctl-device_dsm_offload_write_parameters.md) | [STORAGE_OFFLOAD_WRITE_OUTPUT](ns-winioctl-storage_offload_write_output.md) **DeviceDsmAction_Allocation** | None | [DEVICE_DATA_SET_LB_PROVISIONING_STATE](ns-winioctl-device_data_set_lb_provisioning_state.md) **DeviceDsmAction_Repair** | [DEVICE_DATA_SET_REPAIR_PARAMETERS](ns-winioctl-device_data_set_repair_parameters.md) | None **DeviceDsmAction_Scrub** | None | None **DeviceDsmAction_Resiliency** | None | None Read more on learn.microsoft.com. The IOCTL_STORAGE_REINITIALIZE_MEDIA ioctl (winioctl.h) offloads the erasure process to the storage device. There is no guarantee as to the successful deletion or recoverability of the data on the storage device after command completion. This IOCTL is limited to data disks in regular Windows. In WinPE, this IOCTL is supported for both boot and data disks. There may be cached data from the storage device in the system. To ensure there is no cached data from the storage device before erasure, call FSCTL_LOCK_VOLUME. The operating system does not ensure all outstanding requests to the storage device are completed before issuing the erasure command to the device. Read more on learn.microsoft.com. Windows applications can use this control code to query the storage device for detailed firmware information. Learn more about this API from learn.microsoft.com. Windows applications can use this control code to download a firmware image to the target device, but not activate it. Learn more about this API from learn.microsoft.com. Windows applications can use this control code to activate a firmware image on a specified device. Learn more about this API from learn.microsoft.com. Windows applications can use this control code to specify a maximum operational power consumption level for a storage device. This IOCTL is sent to the device driver with a maximum power value that the driver is expected to honor. This IOCTL then returns with a value that represents what the device driver is actually capable of achieving. This value could be equal to, less than, or greater than the desired value that was sent originally. For example, consider a storage device driver that implements three operational power states that have a maximum power consumption level of 10 watts, 8 watts, and 6 watts. If the caller of this IOCTL specifies that the device should not consume more than 9 watts, it must choose its 8 watt state because that is the highest state it has that is still less than 9 watts. If the caller of this IOCTL specifies that the device should not consume more than 5 watts, the device driver will pick the 6 watt state because 6 watts is the minimum value the device can function at. Read more on learn.microsoft.com. The IOCTL_STORAGE_RPMB_COMMAND ioctl (winioctl.h) sends an RPMB command to the underlying storage device. Retrieves information about the physical disk's geometry:\_type, number of cylinders, tracks per cylinder, sectors per track, and bytes per sector. If the operation completes successfully, the return value is nonzero. If the operation fails or is pending, the return value is zero. To get extended error information, call [**GetLastError**](../errhandlingapi/nf-errhandlingapi-getlasterror.md). Learn more about this API from learn.microsoft.com. Retrieves information about the type, size, and nature of a disk partition. The **IOCTL_DISK_GET_PARTITION_INFO** control code is only supported on MBR-formatted disks. The disk support can be summarized as follows. Disk type | IOCTL_DISK_GET_PARTITION_INFO | IOCTL_DISK_GET_PARTITION_INFO_EX ----------|-------------------------------|--------------------------------- Basic master boot record (MBR) | Yes | Yes Basic GUID partition table (GPT) | No | Yes Dynamic MBR boot/system | Yes | Yes Dynamic MBR data | Yes | No Dynamic GPT boot/system | No | Yes Dynamic GPT data | No | No Currently, GPT is supported only on 64-bit systems. If the partition is on a disk formatted as type master boot record (MBR), partition size totals are limited. For more information, see the Remarks section of [IOCTL_DISK_SET_DRIVE_LAYOUT](ni-winioctl-ioctl_disk_set_drive_layout.md). Read more on learn.microsoft.com. Sets partition information for the specified disk partition. If the partition is on a disk formatted as type master boot record (MBR), partition size totals are limited. For more information, see the Remarks section of [IOCTL_DISK_SET_DRIVE_LAYOUT](ni-winioctl-ioctl_disk_set_drive_layout.md). Retrieves information for each entry in the partition tables for a disk. If the operation completes successfully, the return value is nonzero. If the operation fails or is pending, the return value is zero. To get extended error information, call [**GetLastError**](../errhandlingapi/nf-errhandlingapi-getlasterror.md). This operation retrieves information for each primary partition as well as each logical drive. To determine whether the entry is an extended or unused partition, check the [Disk Partition Types](/windows/desktop/FileIO/disk-partition-types). Partitions a disk as specified by drive layout and partition information data. If the operation completes successfully, the return value is nonzero. If the operation fails or is pending, the return value is zero. To get extended error information, call [**GetLastError**](../errhandlingapi/nf-errhandlingapi-getlasterror.md). If the partition is on a disk formatted as type master boot record (MBR), partition size totals cannot exceed 2 TB per MBR disk. For example, a disk of type MBR can have a single 2-TB partition, two 1-TB partitions, or any combination that does not total more than 2 TB. If more space is required, a disk formatted as type GUID partition table (GPT) should be used. If third-party partitioning tools are used to work around this limitation on disks of type MBR larger than 2 TB, configuration operations via the disk partitioning IOCTL control codes will be limited. Verifies the specified extent on a fixed disk. Learn more about this API from learn.microsoft.com. Formats a specified, contiguous set of tracks on a floppy disk. To provide additional parameters, use IOCTL_DISK_FORMAT_TRACKS_EXinstead. Learn more about this API from learn.microsoft.com. Directs the disk device to map one or more blocks to its spare-block pool. (IOCTL_DISK_REASSIGN_BLOCKS) The [REASSIGN_BLOCKS](ns-winioctl-reassign_blocks.md) structure that the **IOCTL_DISK_REASSIGN_BLOCKS** control code uses only supports drives where the Logical Block Address (LBA) fits into a 4-byte value (typically up to 2 TB). For larger drives the [REASSIGN_BLOCKS_EX](ns-winioctl-reassign_blocks_ex.md) structure that the [IOCTL_DISK_REASSIGN_BLOCKS_EX](ni-winioctl-ioctl_disk_reassign_blocks_ex.md) control code uses supports 8-byte LBAs. For compatibility, the **IOCTL_DISK_REASSIGN_BLOCKS** control code and **REASSIGN_BLOCKS** structure should be used where possible. Enables performance counters that provide disk performance information. To disable the performance counters enabled by this control code, use the [IOCTL_DISK_PERFORMANCE_OFF](ni-winioctl-ioctl_disk_performance_off.md) control code. Determines whether the specified disk is writable. Learn more about this API from learn.microsoft.com. Formats a specified, contiguous set of tracks on a floppy disk. This device I/O control operation is for floppy disk devices only. It is impossible to determine how many bad track numbers will be returned by this control code, so you should set the size of the array pointed to by the lpOutBuffer parameter to the following: `(total number of tracks on the floppy disk) * sizeof(BAD_TRACK_NUMBER)` Read more on learn.microsoft.com. Disables the performance counters that provide disk performance information. To enable these performance counters, use the [IOCTL_DISK_PERFORMANCE](ni-winioctl-ioctl_disk_performance.md) control code. Retrieves extended information about the type, size, and nature of a disk partition. The **IOCTL_DISK_GET_PARTITION_INFO_EX** control code is supported on basic disks. It is only supported on dynamic disks that are boot or system disks, or have retained entries in the partition table. The [DiskPart.exe](/windows-server/administration/windows-commands/diskpart) command **RETAIN** can be used to do this for other dynamic simple partitions. The disk support can be summarized as follows. Disk type | IOCTL_DISK_GET_PARTITION_INFO | IOCTL_DISK_GET_PARTITION_INFO_EX ----------|-------------------------------|--------------------------------- Basic master boot record (MBR) | Yes | Yes Basic GUID partition table (GPT) | No | Yes Dynamic MBR boot/system | Yes | Yes Dynamic MBR data | Yes | No Dynamic GPT boot/system | No | Yes Dynamic GPT data | No | No Currently, GPT is supported only on 64-bit systems. If the partition is on a disk formatted as type master boot record (MBR), partition size totals are limited. For more information, see the Remarks section of [IOCTL_DISK_SET_DRIVE_LAYOUT](ni-winioctl-ioctl_disk_set_drive_layout.md). Read more on learn.microsoft.com. Sets partition information for the specified disk partition, including layout information for AT and EFI (Extensible Firmware Interface) partitions. If the partition is on a disk formatted as type master boot record (MBR), partition size totals are limited. For more information, see the Remarks section of [IOCTL_DISK_SET_DRIVE_LAYOUT](ni-winioctl-ioctl_disk_set_drive_layout.md). Retrieves extended information for each entry in the partition tables for a disk. If the operation completes successfully, the return value is nonzero. If the operation fails or is pending, the return value is zero. To get extended error information, call [**GetLastError**](../errhandlingapi/nf-errhandlingapi-getlasterror.md). This operation retrieves information for each primary partition as well as each logical drive. To determine whether the entry is an extended or unused partition, check the [Disk Partition Types](/windows/desktop/FileIO/disk-partition-types). Partitions a disk according to the specified drive layout and partition information data. If the operation completes successfully, the return value is nonzero. If the operation fails or is pending, the return value is zero. To get extended error information, call [**GetLastError**](../errhandlingapi/nf-errhandlingapi-getlasterror.md). When specifying a **GUID** partition table (GPT) as the [PARTITION_STYLE](ne-winioctl-partition_style.md) of the [CREATE_DISK](ns-winioctl-create_disk.md) structure, an application should wait for the MSR partition arrival before sending the **IOCTL_DISK_SET_DRIVE_LAYOUT_EX** control code. For more information about device notification, see [RegisterDeviceNotification](../winuser/nf-winuser-registerdevicenotificationa.md). When creating and manipulating an Extended Boot Record (EBR), the first entry of the EBR should point to the logical drive that immediately follows the EBR and the next EBR should lie after the end of the current logical drive and before the start of the next logical drive. If the partition is on a disk formatted as type master boot record (MBR), partition size totals are limited. For more information, see the Remarks section of [IOCTL_DISK_SET_DRIVE_LAYOUT](ni-winioctl-ioctl_disk_set_drive_layout.md). Read more on learn.microsoft.com. Initializes the specified disk and disk partition table using the information in the CREATE_DISK structure. When specifying a GUID partition table (GPT) as the [PARTITION_STYLE](./ne-winioctl-partition_style.md) of the [CREATE_DISK](ns-winioctl-create_disk.md) structure, an application should wait for the MSR partition arrival before sending the [IOCTL_DISK_SET_DRIVE_LAYOUT_EX](ni-winioctl-ioctl_disk_set_drive_layout_ex.md) control code. For more information about device notification, see [RegisterDeviceNotification](../winuser/nf-winuser-registerdevicenotificationa.md). Retrieves the length of the specified disk, volume, or partition. Volume handles do not have access to the full volume. To read or write to the last few sectors of a volume, you must call [FSCTL_ALLOW_EXTENDED_DASD_IO](ni-winioctl-fsctl_allow_extended_dasd_io.md), which instructs the file system to not perform any boundary checks. This operation should be used instead of [IOCTL_DISK_GET_PARTITION_INFO_EX](ni-winioctl-ioctl_disk_get_partition_info_ex.md) for volumes that do not have partition info—such as partition type or number of hidden sectors. Read more on learn.microsoft.com. Retrieves extended information about the physical disk's geometry:\_type, number of cylinders, tracks per cylinder, sectors per track, and bytes per sector. If the operation completes successfully, the return value is nonzero. If the operation fails, or is pending, the return value is zero. To get extended error information, call [**GetLastError**](../errhandlingapi/nf-errhandlingapi-getlasterror.md). Learn more about this API from learn.microsoft.com. Directs the disk device to map one or more blocks to its spare-block pool. (IOCTL_DISK_REASSIGN_BLOCKS_EX) The [REASSIGN_BLOCKS_EX](ns-winioctl-reassign_blocks_ex.md) structure that the **IOCTL_DISK_REASSIGN_BLOCKS_EX** control code uses supports 8-byte Logical Block Addresses (LBA). For compatibility, the [IOCTL_DISK_REASSIGN_BLOCKS](ni-winioctl-ioctl_disk_reassign_blocks.md) control code and [REASSIGN_BLOCKS](ns-winioctl-reassign_blocks.md) structure should be used where the LBA fits in the 4-byte LBA that the **REASSIGN_BLOCKS** structure supports (typically drives up to 2 TB). Enlarges the specified partition. You can extend or shrink a live partition, and the partition can be open for sharing during the extend or shrink operation. You do not need to lock a partition that you are extending, nor do you need to shut down other applications or services during the extend operation. For more information, see [DISK_GROW_PARTITION](ns-winioctl-disk_grow_partition.md). Read more on learn.microsoft.com. Retrieves the disk cache configuration data. To set the disk cache information, use the [IOCTL_DISK_SET_CACHE_INFORMATION](ni-winioctl-ioctl_disk_set_cache_information.md) control code. Sets the disk configuration data. To retrieve the cache information, use the [IOCTL_DISK_GET_CACHE_INFORMATION](ni-winioctl-ioctl_disk_get_cache_information.md) control code. Removes the boot signature from the master boot record, so that the disk will be formatted from sector zero to the end of the disk. Learn more about this API from learn.microsoft.com. Invalidates the cached partition table and re-enumerates the device. This operation is used in synchronizing the system view of the specified disk device when the partition table of the disk is directly modified. Be sure to perform this operation when you update the usable space for a disk so that the system will update its partition table. You can update the properties of a live volume, and the volume can be open for sharing during the update operation. You do not need to lock a volume that you are updating, nor do you need to shut down other applications or services during the update operation. Read more on learn.microsoft.com. Retrieves the attributes of the specified disk device. Learn more about this API from learn.microsoft.com. Sets the attributes of the specified disk device. Learn more about this API from learn.microsoft.com. Clears all Volume Shadow Copy Service (VSS) hardware-based shadow copy (also called "snapshot") information from the disk. The disk whose handle is used when this IOCTL is issued might be in the offline state when the IOCTL is issued. If the disk is put in the offline state by using the disk management Microsoft Management Console (MMC) snap-in, the disk will have its read-only attribute set, which will cause this IOCTL to fail. However, if the disk partition utility (Diskpart.exe) is used to put the disk in the offline state, the read-only attribute for the disk is not set. For this reason, it is best to use the disk partition utility to put a disk in the offline state. > [!NOTE] > One side effect of using this IOCTL is that Disk Management tools will now report an additional partition on GPT disks of the type "UNKNOWN." This 256KB partition is created by using the IOCTL and is the shadow copy partition that is used in the restore process. The partition is expected and can be ignored by system administrators. Read more on learn.microsoft.com. Retrieves the parameters of the specified device. Learn more about this API from learn.microsoft.com. Retrieves the current status of the specified device. Learn more about this API from learn.microsoft.com. Retrieves the product data for the specified device. Learn more about this API from learn.microsoft.com. Sets the state of the device's insert/eject port, door, or keypad. Learn more about this API from learn.microsoft.com. Retrieves the status of all elements or a specified number of elements of a particular type. Learn more about this API from learn.microsoft.com. Initializes the status of all elements or the specified elements of a particular type. Learn more about this API from learn.microsoft.com. Sets the changer's robotic transport mechanism to the specified element address. This optimizes moving or exchanging media by positioning the transport beforehand. Learn more about this API from learn.microsoft.com. Moves a piece of media from a source element to one destination, and the piece of media originally in the first destination to a second destination. To swap two pieces of media, specify the source as the value for the second destination. Moves a piece of media to a destination. Learn more about this API from learn.microsoft.com. Physically recalibrates a transport element. Recalibration may involve returning the transport to its home position. Learn more about this API from learn.microsoft.com. Retrieves the volume tag information for the specified elements. Learn more about this API from learn.microsoft.com. Enables or disables the placement of line status and modem status values into the regular data stream that an application acquires through the ReadFile function. > [!NOTE] > An application that uses this scheme must examine each character in the data stream to determine the presence of modem-status or line-status data. The following values follow the designated escape character in the data stream if the **LSRMST_INSERT** mode has been turned on. Value | Meaning ------|-------- **SERIAL_LSRMST_ESCAPE** | Indicates the reception of the escape character itself into the data stream. **SERIAL_LSRMST_LSR_DATA** | Indicates that a line status change occurred, and data was available in the receive hardware buffer. Following this **BYTE** is a **BYTE** value of the line status register is the **BYTE** present in the receive hardware buffer when the line status change was processed. **SERIAL_LSRMST_LSR_NODATA** | Indicates that a line status change occurred, but no data was available in the receive hardware buffer. **SERIAL_LSRMST_MST** | Indicates that a modem status change occurred. Following this **BYTE** is a **BYTE** that is the value of the modem status register when the modem status change was processed. Read more on learn.microsoft.com. Retrieves the batterys current tag. If the operation completes successfully, [**DeviceIoControl**](/windows/desktop/api/ioapiset/nf-ioapiset-deviceiocontrol) returns a nonzero value. If the operation fails or is pending, [**DeviceIoControl**](/windows/desktop/api/ioapiset/nf-ioapiset-deviceiocontrol) returns zero. To get extended error information, call [**GetLastError**](/windows/desktop/api/errhandlingapi/nf-errhandlingapi-getlasterror). All requests for battery information will complete with the status of ERROR_NO_SUCH_DEVICE (or ERROR_FILE_NOT_FOUND in **Windows 10 version 1809 and earlier**) whenever the BatteryTag element of the request does not match that of the current battery tag. This ensures that the returned battery information matches that of the requested battery (see [Battery Tags](battery-information.md) for more information). This battery IOCTL retrieves the battery's current tag. The battery tag is a unique nonzero value that changes when the physical battery is reinserted, replaced, or undergoes any characteristic changes. See the Battery Tags section in the [Battery Information](battery-information.md) overview topic for more detail on when a battery tag changes, how to detect the change, and how an application should proceed after a battery tag change. When a battery is not present, this request will wait the indicated time, and if there is still no battery present, then it will return **ERROR\_FILE\_NOT\_FOUND** and set the battery tag to **BATTERY\_TAG\_INVALID**. (See Battery Information for more information.) All requests for other battery information require the caller to supply the matching battery tag. This ensures that the caller is receiving information for the same battery for every request and ensures that the caller is aware of battery changes without constant polling. For the implications of overlapped I/O on this operation, see the Remarks section of the [**DeviceIoControl**](/windows/desktop/api/ioapiset/nf-ioapiset-deviceiocontrol) topic. Read more on learn.microsoft.com. Retrieves a variety of information for the battery. If the operation completes successfully, [**DeviceIoControl**](/windows/desktop/api/ioapiset/nf-ioapiset-deviceiocontrol) returns a nonzero value. If the operation fails or is pending, [**DeviceIoControl**](/windows/desktop/api/ioapiset/nf-ioapiset-deviceiocontrol) returns zero. To get extended error information, call [**GetLastError**](/windows/desktop/api/errhandlingapi/nf-errhandlingapi-getlasterror). Some information about batteries is optional or may be meaningless for some batteries. If the particular type of data requested is not available for the current battery, then **ERROR\_INVALID\_FUNCTION** is returned. All requests for battery information will complete with the status of ERROR_NO_SUCH_DEVICE (or ERROR_FILE_NOT_FOUND in **Windows 10 version 1809 and earlier**) whenever the BatteryTag element of the request does not match that of the current battery tag. This ensures that the returned battery information matches that of the requested battery (see [Battery Tags](battery-information.md) for more information). This battery IOCTL retrieves a variety of information for the battery. The input parameter structure, [**BATTERY\_QUERY\_INFORMATION**](battery-query-information-str.md), indicates the type of information to be returned and when the battery information should be returned. The data type and contents of the output buffer vary based on the data requested. For the implications of overlapped I/O on this operation, see the Remarks section of the [**DeviceIoControl**](/windows/desktop/api/ioapiset/nf-ioapiset-deviceiocontrol) topic. Read more on learn.microsoft.com. Sets various battery information. If the operation completes successfully, [**DeviceIoControl**](/windows/desktop/api/ioapiset/nf-ioapiset-deviceiocontrol) returns a nonzero value. If the operation fails or is pending, [**DeviceIoControl**](/windows/desktop/api/ioapiset/nf-ioapiset-deviceiocontrol) returns zero. To get extended error information, call [**GetLastError**](/windows/desktop/api/errhandlingapi/nf-errhandlingapi-getlasterror). All requests for battery information will complete with the status of ERROR_NO_SUCH_DEVICE (or ERROR_FILE_NOT_FOUND in **Windows 10 version 1809 and earlier**) whenever the BatteryTag element of the request does not match that of the current battery tag. This ensures that the returned battery information matches that of the requested battery (see [Battery Tags](battery-information.md) for more information). All requests to set battery information will complete with the status of ERROR\_FILE\_NOT\_FOUND if the battery tag of the request does not match that of the current battery tag. For the implications of overlapped I/O on this operation, see the Remarks section of the [**DeviceIoControl**](/windows/desktop/api/ioapiset/nf-ioapiset-deviceiocontrol) topic. Read more on learn.microsoft.com. Retrieves the current status of the battery. If the operation completes successfully, [**DeviceIoControl**](/windows/desktop/api/ioapiset/nf-ioapiset-deviceiocontrol) returns a nonzero value. If the operation fails or is pending, [**DeviceIoControl**](/windows/desktop/api/ioapiset/nf-ioapiset-deviceiocontrol) returns zero. To get extended error information, call [**GetLastError**](/windows/desktop/api/errhandlingapi/nf-errhandlingapi-getlasterror). All requests for battery information will complete with the status of ERROR_NO_SUCH_DEVICE (or ERROR_FILE_NOT_FOUND in **Windows 10 version 1809 and earlier**) whenever the BatteryTag element of the request does not match that of the current battery tag. This ensures that the returned battery information matches that of the requested battery (see [Battery Tags](battery-information.md) for more information). This battery IOCTL retrieves the status of the battery at the time the operation returns. The input parameter structure, [**BATTERY\_WAIT\_STATUS**](battery-wait-status-str.md), indicates when the battery status is to be processed and returned. Requests for battery status can be for immediate return or can be set to wait for a particular condition before completing. For example, a request for battery information can be made that waits until the battery capacity reaches a specified point or the battery state changes. All requests for battery information will complete with the status of **ERROR\_FILE\_NOT\_FOUND** whenever the **BatteryTag** element of the request does not match that of the current battery tag. (See [Battery Tags](battery-information.md) for more information.) This is used to ensure that the returned battery information matches that of the requested battery. For the implications of overlapped I/O on this operation, see the Remarks section of the [**DeviceIoControl**](/windows/desktop/api/ioapiset/nf-ioapiset-deviceiocontrol) topic. Read more on learn.microsoft.com. The IOCTL_EMI_GET_VERSION control code retrieves the current version of the EMI interface supported by the device. Learn more about this API from learn.microsoft.com. The IOCTL_EMI_GET_METADATA_SIZE control code retrieves the size of the EMI metadata object that can be obtained from the device by issuing an IOCTL_EMI_GET_METADATA request. Learn more about this API from learn.microsoft.com. The IOCTL_EMI_GET_METADATA control code retrieves EMI metadata from a device. Learn more about this API from learn.microsoft.com. The IOCTL_EMI_GET_MEASUREMENT control code retrieves the current energy measurement and the time at which the measurement was taken. Learn more about this API from learn.microsoft.com. The IOCTL_VMGENCOUNTER_READ control code retrieves a virtual machine generation identifier. To perform this operation, call the DeviceIoControl function with the following parameters. 
BOOL WINAPI DeviceIoControl( (HANDLE)       hDevice,         // handle to device (DWORD)        IOCTL_VMGENCOUNTER_READ, // dwIoControlCode(LPDWORD)      lpInBuffer,      // input buffer (DWORD)        nInBufferSize,   // size of input buffer (LPDWORD)      lpOutBuffer,     // output buffer (DWORD)        nOutBufferSize,  // size of output buffer (LPDWORD)      lpBytesReturned, // number of bytes returned (LPOVERLAPPED) lpOverlapped );  // OVERLAPPED structure
 This doc was truncated. Read more on learn.microsoft.com. Retrieves the physical location of a specified volume on one or more disks. In Windows 8 and Windows Server 2012, this code is supported by the following technologies. Technology | Supported -----------|---------- Server Message Block (SMB) 3.0 protocol | No SMB 3.0 Transparent Failover (TFO) | No SMB 3.0 with Scale-out File Shares (SO) | No Cluster Shared Volume File System (CsvFS) | Yes Read more on learn.microsoft.com. Brings a volume online. When a volume is offline, all read, write, and IOCTL requests fail with **ERROR_NOT_READY**. You cannot take the system or boot volume offline. When a volume is online, all requests sent to the volume are honored. When a volume that is online is dismounted, the next call to open the volume causes it to be mounted. Taking the volume offline prevents the dismounted volume from being mounted again. To take a volume offline, use the [IOCTL_VOLUME_OFFLINE](ni-winioctl-ioctl_volume_offline.md) control code. In Windows 8 and Windows Server 2012, this code is supported by the following technologies. Technology | Supported -----------|---------- Server Message Block (SMB) 3.0 protocol | No SMB 3.0 Transparent Failover (TFO) | No SMB 3.0 with Scale-out File Shares (SO) | No Cluster Shared Volume File System (CsvFS) | No Read more on learn.microsoft.com. Takes a volume offline. Applications must first successfully dismount the file system - via [FSCTL_DISMOUNT_VOLUME](ni-winioctl-fsctl_dismount_volume.md) - before using **IOCTL_VOLUME_OFFLINE**. When a volume that is online is dismounted, the next call to open the volume causes it to be mounted. Taking the volume offline using the same volume handle as was used for the dismount prevents the dismounted volume from being mounted again. When a volume is online, all requests sent to the volume are honored. When a volume that is online is dismounted, the next call to open the volume causes it to be mounted. Taking the volume offline prevents the dismounted volume from being mounted again. To bring a volume online, use the [IOCTL_VOLUME_ONLINE](ni-winioctl-ioctl_volume_online.md) control code. In Windows 8 and Windows Server 2012, this code is supported by the following technologies. Technology | Supported -----------|---------- Server Message Block (SMB) 3.0 protocol | No SMB 3.0 Transparent Failover (TFO) | No SMB 3.0 with Scale-out File Shares (SO) | No Cluster Shared Volume File System (CsvFS) | No Read more on learn.microsoft.com. Determines whether the specified volume is clustered. The **IOCTL_VOLUME_IS_CLUSTERED** control code is valid only if the Cluster service is running. The **ERROR_GEN_FAILURE** error indicates that the computer that currently owns the disk on which the volume resides is a server cluster node, but either the disk is a Physical Disk resource currently in an offline state or the disk is not a Physical Disk resource. To determine which of these situations exists, use the following steps: 1. Call the [ClusterEnum](../clusapi/nf-clusapi-clusterenum.md) function to enumerate all Physical Disk resources in the cluster. 1. Search each enumerated Physical Disk resource for the volume by calling the [ClusterResourceControl](../clusapi/nf-clusapi-clusterresourcecontrol.md) function with [CLUSCTL_RESOURCE_STORAGE_GET_DISK_INFO](/previous-versions/windows/desktop/mscs/clusctl-resource-storage-get-disk-info). If you cannot find the volume among the Physical Disk resources in the cluster, the volume does not reside on a Physical Disk resource. The **ERROR_INVALID_FUNCTION** error indicates that the computer that currently owns the disk on which the volume resides is not a server cluster node or the disk is not a Physical Disk resource. To determine whether a computer is a server cluster node, call the [GetNodeClusterState](../clusapi/nf-clusapi-getnodeclusterstate.md) function. In Windows 8 and Windows Server 2012, this code is supported by the following technologies. Technology | Supported -----------|---------- Server Message Block (SMB) 3.0 protocol | No SMB 3.0 Transparent Failover (TFO) | No SMB 3.0 with Scale-out File Shares (SO) | No Cluster Shared Volume File System (CsvFS) | Yes Read more on learn.microsoft.com. Retrieves the attributes for a volume. In Windows 8 and Windows Server 2012, this code is supported by the following technologies. Technology | Supported -----------|---------- Server Message Block (SMB) 3.0 protocol | No SMB 3.0 Transparent Failover (TFO) | No SMB 3.0 with Scale-out File Shares (SO) | No Cluster Shared Volume File System (CsvFS) | Yes Read more on learn.microsoft.com. Determines whether a volume is a CSV volume. If the operation completes successfully, [**DeviceIoControl**](/windows/desktop/api/ioapiset/nf-ioapiset-deviceiocontrol) returns a nonzero value. If the operation fails or is pending, [**DeviceIoControl**](/windows/desktop/api/ioapiset/nf-ioapiset-deviceiocontrol) returns zero (0). To get extended error information, call [**GetLastError**](/windows/desktop/api/errhandlingapi/nf-errhandlingapi-getlasterror). Learn more about this API from learn.microsoft.com. Retrieves the supported backlight levels. If the operation completes successfully, [**DeviceIoControl**](/windows/desktop/api/ioapiset/nf-ioapiset-deviceiocontrol) returns a nonzero value. If the operation fails or is pending, [**DeviceIoControl**](/windows/desktop/api/ioapiset/nf-ioapiset-deviceiocontrol) returns zero. To get extended error information, call [**GetLastError**](/windows/desktop/api/errhandlingapi/nf-errhandlingapi-getlasterror). Each element in the *lpOutBuffer* array is one byte in length. Therefore, upon return, the *lpBytesReturned* parameter indicates the number of supported levels. Each level is a value from 0 to 100. The larger the value, the brighter the backlight. All levels are supported whether the power source is AC or DC. The header file used to build applications that include this functionality, Ntddvdeo.h, is included in the Microsoft Windows Driver Development Kit (DDK). For information on obtaining the DDK, see [https://www.microsoft.com/whdc/devtools/ddk/default.mspx](https://msdn.microsoft.com/windows/hardware/gg454513). Alternatively, you can define this control code as follows: This doc was truncated. Read more on learn.microsoft.com. Retrieves the current AC and DC backlight levels and the current power state. If the operation completes successfully, [**DeviceIoControl**](/windows/desktop/api/ioapiset/nf-ioapiset-deviceiocontrol) returns a nonzero value. If the operation fails or is pending, [**DeviceIoControl**](/windows/desktop/api/ioapiset/nf-ioapiset-deviceiocontrol) returns zero. To get extended error information, call [**GetLastError**](/windows/desktop/api/errhandlingapi/nf-errhandlingapi-getlasterror). The header file used to build applications that include this functionality, Ntddvdeo.h, is included in the Microsoft Windows Driver Development Kit (DDK). For information on obtaining the DDK, see [https://www.microsoft.com/whdc/devtools/ddk/default.mspx](https://msdn.microsoft.com/windows/hardware/gg454513). Alternatively, you can define this control code as follows: This doc was truncated. Read more on learn.microsoft.com. Sets the current AC and DC backlight levels. If the operation completes successfully, [**DeviceIoControl**](/windows/desktop/api/ioapiset/nf-ioapiset-deviceiocontrol) returns a nonzero value. If the operation fails or is pending, [**DeviceIoControl**](/windows/desktop/api/ioapiset/nf-ioapiset-deviceiocontrol) returns zero. To get extended error information, call [**GetLastError**](/windows/desktop/api/errhandlingapi/nf-errhandlingapi-getlasterror). The values specified in the **ucACBrightness** and **ucDCBrightness** members of the [**DISPLAY\_BRIGHTNESS**](/previous-versions/windows/desktop/legacy/aa372686(v=vs.85)) structure must have been previously returned by [**IOCTL\_VIDEO\_QUERY\_SUPPORTED\_BRIGHTNESS**](ioctl-video-query-supported-brightness.md). For example, if the supported values are 10, 20, 30, 40, 50, 60, 70, 80, 90, and 100, then using a value of 33 would be an error. The header file used to build applications that include this functionality, Ntddvdeo.h, is included in the Microsoft Windows Driver Development Kit (DDK). For information on obtaining the DDK, see [https://www.microsoft.com/whdc/devtools/ddk/default.mspx](https://msdn.microsoft.com/windows/hardware/gg454513). Alternatively, you can define this control code as follows: This doc was truncated. Read more on learn.microsoft.com. This I/O control code (IOCTL) is sent by a user-mode service or application to issue an IN direction transfer on the endpoint that corresponds to the specified pipe ID in the input buffer. (IOCTL_GENERICUSBFN_TRANSFER_IN) If this I/O control code (IOCTL) is being called synchronously, set the lpOverlapped parameter to NULL. If this IOCTL is called asynchronously, assign the lpOverlapped parameter to a pointer to an OVERLAPPED structure that contains a handle to an event object. The event objects signal when the operation is completed. The return value is a BOOL value that indicates success or failure of the operation. TRUE indicates success, FALSE otherwise. Read more on learn.microsoft.com. This I/O control code (IOCTL) is sent by a user-mode service or application to issue an IN direction transfer on the endpoint that corresponds to the specified pipe ID in the input buffer. (IOCTL_GENERICUSBFN_TRANSFER_IN_APPEND_ZERO_PKT) If this I/O control code (IOCTL) is being called synchronously, set the lpOverlapped parameter to NULL. If this IOCTL is called asynchronously, assign the lpOverlapped parameter to a pointer to an OVERLAPPED structure that contains a handle to an event object. The event objects signal when the operation is completed. The return value is a BOOL value that indicates success or failure of the operation. TRUE indicates success, FALSE otherwise. Read more on learn.microsoft.com. This I/O control code (IOCTL) is sent by a user-mode service or application to issue an OUT direction transfer on the endpoint that corresponds to the specified pipe ID in the input buffer. If this I/O control code (IOCTL) is being called synchronously, set the lpOverlapped parameter to NULL. If this IOCTL is called asynchronously, assign the lpOverlapped parameter to a pointer to an OVERLAPPED structure that contains a handle to an event object. The event objects signal when the operation is completed. The return value is a BOOL value that indicates success or failure of the operation. TRUE indicates success, FALSE otherwise. Read more on learn.microsoft.com. This I/O control code (IOCTL) is sent by a user mode service or application to request a zero-length control status handshake on endpoint 0 in the IN direction. If this I/O control code (IOCTL) is being called synchronously, set the lpOverlapped parameter to NULL. If this IOCTL is called asynchronously, assign the lpOverlapped parameter to a pointer to an OVERLAPPED structure that contains a handle to an event object. The event objects signal when the operation is completed. The return value is a BOOL value that indicates success or failure of the operation. TRUE indicates success, FALSE otherwise. Read more on learn.microsoft.com. This I/O control code (IOCTL) is sent by a user-mode service or application to complete a zero-length control status handshake on endpoint 0 in the OUT direction. If this I/O control code (IOCTL) is being called synchronously, set the lpOverlapped parameter to NULL. If this IOCTL is called asynchronously, assign the lpOverlapped parameter to a pointer to an OVERLAPPED structure that contains a handle to an event object. The event objects signal when the operation is completed. The return value is a BOOL value that indicates success or failure of the operation. TRUE indicates success, FALSE otherwise. Read more on learn.microsoft.com. This I/O control code (IOCTL) is sent by the user-mode service or application to retrieve information about a device's available pipes as configured in the registry. If this I/O control code (IOCTL) is being called synchronously, set the lpOverlapped parameter to NULL. If this IOCTL is called asynchronously, assign the lpOverlapped parameter to a pointer to an OVERLAPPED structure that contains a handle to an event object. The event objects signal when the operation is completed. The return value is a BOOL value that indicates success or failure of the operation. TRUE indicates success, FALSE otherwise. Read more on learn.microsoft.com. This I/O control code (IOCTL) is sent by a user-mode service or application to get the state of the specified Universal Serial Bus (USB) pipe. If this I/O control code (IOCTL) is being called synchronously, set the lpOverlapped parameter to NULL. If this IOCTL is called asynchronously, assign the lpOverlapped parameter to a pointer to an OVERLAPPED structure that contains a handle to an event object. The event objects signal when the operation is completed. The return value is a BOOL value that indicates success or failure of the operation. TRUE indicates success, FALSE otherwise. Read more on learn.microsoft.com. This I/O control code (IOCTL) is sent by a user-mode service or application to set the state of the specified Universal Serial Bus (USB) pipe. The pipe will send STALL transaction packets to the host when stalled. For more information, see the USB specification. If this I/O control code (IOCTL) is being called synchronously, set the lpOverlapped parameter to NULL. If this IOCTL is called asynchronously, assign the lpOverlapped parameter to a pointer to an OVERLAPPED structure that contains a handle to an event object. The event objects signal when the operation is completed. The return value is a BOOL value that indicates success or failure of the operation. TRUE indicates success, FALSE otherwise. Read more on learn.microsoft.com. This I/O control code (IOCTL) is sent by a user-mode service or application to notify GenericUSBFn.sys to activate the Universal Serial Bus (USB). Once activated, the bus is prepared to process bus events and handle traffic. If this I/O control code (IOCTL) is being called synchronously, set the lpOverlapped parameter to NULL. If this IOCTL is called asynchronously, assign the lpOverlapped parameter to a pointer to an OVERLAPPED structure that contains a handle to an event object. The event objects signal when the operation is completed. The return value is a BOOL value that indicates success or failure of the operation. TRUE indicates success, FALSE otherwise. Read more on learn.microsoft.com. This IOCTL code is nevtot supported. If this I/O control code (IOCTL) is being called synchronously, set the lpOverlapped parameter to NULL. If this IOCTL is called asynchronously, assign the lpOverlapped parameter to a pointer to an OVERLAPPED structure that contains a handle to an event object. The event objects signal when the operation is completed. The return value is a BOOL value that indicates success or failure of the operation. TRUE indicates success, FALSE otherwise. Read more on learn.microsoft.com. This I/O control code (IOCTL) is sent by a user-mode service or application to register for Universal Serial Bus (USB) event. If this I/O control code (IOCTL) is being called synchronously, set the lpOverlapped parameter to NULL. If this IOCTL is called asynchronously, assign the lpOverlapped parameter to a pointer to an OVERLAPPED structure that contains a handle to an event object. The event objects signal when the operation is completed. The return value is a BOOL value that indicates success or failure of the operation. TRUE indicates success, FALSE otherwise. Read more on learn.microsoft.com. This I/O control code (IOCTL) is sent by a user-mode service or application to retrieve information about a device's available pipes as configured in the registry. If this I/O control code (IOCTL) is being called synchronously, set the lpOverlapped parameter to NULL. If this IOCTL is called asynchronously, assign the lpOverlapped parameter to a pointer to an OVERLAPPED structure that contains a handle to an event object. The event objects signal when the operation is completed. The return value is a BOOL value that indicates success or failure of the operation. TRUE indicates success, FALSE otherwise. Read more on learn.microsoft.com. This I/O control code (IOCTL) is sent by a user-mode service or application to get the entire interface descriptor set for a function on the device.This IOCTL request does not retrieve the interface descriptor set for the entire device.Universal Serial Bus (USB) interface descriptor set for a function on the device. This request must be sent after sending the IOCTL_GENERICUSBFN_ACTIVATE_USB_BUS request. The length of the entire interface descriptor is variable. The class driver might need to send this IOCTL request twice to get the entire descriptor set. If the length of the entire descriptor set is greater than the specified output buffer length, UFX sets the Size member of USBFN_INTERFACE_INFO to the actual buffer length and fails the request with STATUS_BUFFER_TOO_SMALL. The driver must then allocated an output buffer of length specified by Size and resend the request. If this I/O control code (IOCTL) is being called synchronously, set the lpOverlapped parameter to NULL. If this IOCTL is called asynchronously, assign the lpOverlapped parameter to a pointer to an OVERLAPPED structure that contains a handle to an event object. The event objects signal when the operation is completed. The return value is a BOOL value that indicates success or failure of the operation. TRUE indicates success, FALSE otherwise. Read more on learn.microsoft.com. This I/O control code (IOCTL) is sent by a user-mode service or application to register a string descriptor.Universal Serial Bus (USB) string descriptor. This request must be sent after sending the IOCTL_GENERICUSBFN_ACTIVATE_USB_BUS request. If this I/O control code (IOCTL) is being called synchronously, set the lpOverlapped parameter to NULL. If this IOCTL is called asynchronously, assign the lpOverlapped parameter to a pointer to an OVERLAPPED structure that contains a handle to an event object. The event objects signal when the operation is completed. The return value is a BOOL value that indicates success or failure of the operation. TRUE indicates success, FALSE otherwise. Read more on learn.microsoft.com. The IOCTL_USB_DIAGNOSTIC_MODE_ON I/O control has been deprecated. Do not use. Learn more about this API from learn.microsoft.com. The IOCTL_USB_DIAGNOSTIC_MODE_OFF I/O control has been deprecated. Do not use. Learn more about this API from learn.microsoft.com. The IOCTL_USB_GET_ROOT_HUB_NAME I/O control request is used with the USB_ROOT_HUB_NAME structure to retrieve the symbolic link name of the root hub.IOCTL_USB_GET_ROOT_HUB_NAME is a user-mode I/O control request. Learn more about this API from learn.microsoft.com. The IOCTL_GET_HCD_DRIVERKEY_NAME I/O control request retrieves the driver key name in the registry for a USB host controller driver. To get the driver key name in the registry, you must perform the following tasks: This doc was truncated. Read more on learn.microsoft.com. The IOCTL_KEYBOARD_QUERY_ATTRIBUTES request returns information about the keyboard attributes. Learn more about this API from learn.microsoft.com. The IOCTL_KEYBOARD_SET_TYPEMATIC request sets the keyboard typematic settings. Learn more about this API from learn.microsoft.com. The IOCTL_KEYBOARD_SET_INDICATORS request sets the keyboard indicators. Learn more about this API from learn.microsoft.com. The IOCTL_KEYBOARD_QUERY_TYPEMATIC request returns the keyboard typematic settings. Learn more about this API from learn.microsoft.com. The IOCTL_KEYBOARD_QUERY_INDICATORS request returns information about the keyboard indicators. Learn more about this API from learn.microsoft.com. The IOCTL_KEYBOARD_QUERY_INDICATOR_TRANSLATION request returns information about the mapping between scan codes and keyboard indicators. Learn more about this API from learn.microsoft.com. The IOCTL_KEYBOARD_QUERY_EXTENDED_ATTRIBUTES request returns information about the extended keyboard attributes. Learn more about this API from learn.microsoft.com. The IOCTL_MOUSE_QUERY_ATTRIBUTES request returns information about the mouse attributes. Learn more about this API from learn.microsoft.com. Retrieves information about a Pulse Width Modulation (PWM) controller. This information does not change after the controller is initialized. To perform this operation, call the DeviceIoControl function with the following parameters. 
BOOL WINAPI DeviceIoControl( (HANDLE)       hDevice,         // handle to device (DWORD)        IOCTL_PWM_CONTROLLER_GET_INFO, // dwIoControlCode(LPDWORD)      NULL,      // input buffer (DWORD)        0,   // size of input buffer (LPDWORD)      lpOutBuffer,     // output buffer (DWORD)        nOutBufferSize,  // size of output buffer (LPDWORD)      lpBytesReturned, // number of bytes returned (LPOVERLAPPED) lpOverlapped );  // OVERLAPPED structure
 This doc was truncated. Read more on learn.microsoft.com. Retrieves the effective output signal period of the Pulse Width Modulation (PWM) controller as it would be measured on its output channels. To perform this operation, call the DeviceIoControl function with the following parameters. 
BOOL WINAPI DeviceIoControl( (HANDLE)       hDevice,         // handle to device (DWORD)        IOCTL_PWM_CONTROLLER_GET_ACTUAL_PERIOD, // dwIoControlCode(LPDWORD)      NULL,      // input buffer (DWORD)        0,   // size of input buffer (LPDWORD)      lpOutBuffer,     // output buffer (DWORD)        nOutBufferSize,  // size of output buffer (LPDWORD)      lpBytesReturned, // number of bytes returned (LPOVERLAPPED) lpOverlapped );  // OVERLAPPED structure
 This doc was truncated. Read more on learn.microsoft.com. Sets the output signal period of a Pulse Width Modulation (PWM) controller to a suggested value. To perform this operation, call the DeviceIoControl function with the following parameters. 
BOOL WINAPI DeviceIoControl( (HANDLE)       hDevice,         // handle to device (DWORD)        IOCTL_PWM_CONTROLLER_SET_DESIRED_PERIOD, // dwIoControlCode(LPDWORD)      lpInBuffer,      // input buffer (DWORD)        nInBufferSize,   // size of input buffer (LPDWORD)      lpOutBuffer,     // output buffer (DWORD)        nOutBufferSize,  // size of output buffer (LPDWORD)      lpBytesReturned, // number of bytes returned (LPOVERLAPPED) lpOverlapped );  // OVERLAPPED structure
 This doc was truncated. Read more on learn.microsoft.com. Retrieves the current duty cycle percentage for a pin or channel. The control code returns the percentage as a PWM_PIN_GET_ACTIVE_DUTY_CYCLE_PERCENTAGE_OUTPUT structure. To perform this operation, call the DeviceIoControl function with the following parameters. 
BOOL WINAPI DeviceIoControl( (HANDLE)       hDevice,         // handle to device (DWORD)        IOCTL_PWM_PIN_GET_ACTIVE_DUTY_CYCLE_PERCENTAGE, // dwIoControlCode(LPDWORD)      NULL,      // input buffer (DWORD)        0,   // size of input buffer (LPDWORD)      lpOutBuffer,     // output buffer (DWORD)        nOutBufferSize,  // size of output buffer (LPDWORD)      lpBytesReturned, // number of bytes returned (LPOVERLAPPED) lpOverlapped );  // OVERLAPPED structure
 This doc was truncated. Read more on learn.microsoft.com. Set a desired duty cycle percentage value for the controller pin or channel. The control code specifies the percentage as a PWM_PIN_SET_ACTIVE_DUTY_CYCLE_PERCENTAGE_INPUT structure. To perform this operation, call the DeviceIoControl function with the following parameters. 
BOOL WINAPI DeviceIoControl( (HANDLE)       hDevice,         // handle to device (DWORD)        IOCTL_PWM_PIN_SET_ACTIVE_DUTY_CYCLE_PERCENTAGE, // dwIoControlCode(LPDWORD)      lpInBuffer,      // input buffer (DWORD)        nInBufferSize,   // size of input buffer (LPDWORD)      NULL,      // output buffer (DWORD)        0,  // size of output buffer (LPDWORD)      lpBytesReturned, // number of bytes returned (LPOVERLAPPED) lpOverlapped );  // OVERLAPPED structure
 This doc was truncated. Read more on learn.microsoft.com. Retrieves the current signal polarity of the pin or channel. The control code gets the signal polarity as a PWM_PIN_GET_POLARITY_OUTPUT structure. The signal polarity is either Active High or Active Low, as defined in the PWM_POLARITY enumeration. To perform this operation, call the DeviceIoControl function with the following parameters. 
BOOL WINAPI DeviceIoControl( (HANDLE)       hDevice,         // handle to device (DWORD)        IOCTL_PWM_PIN_GET_POLARITY, // dwIoControlCode(LPDWORD)      NULL,      // input buffer (DWORD)        0,   // size of input buffer (LPDWORD)      lpOutBuffer,     // output buffer (DWORD)        nOutBufferSize,  // size of output buffer (LPDWORD)      lpBytesReturned, // number of bytes returned (LPOVERLAPPED) lpOverlapped );  // OVERLAPPED structure
 This doc was truncated. Read more on learn.microsoft.com. Sets the signal polarity of the pin or channel. The control code sets the signal polarity based on a PWM_PIN_SET_POLARITY_INPUT structure. The signal polarity is either Active High or Active Low, as defined in the PWM_POLARITY enumeration. To perform this operation, call the DeviceIoControl function with the following parameters. 
BOOL WINAPI DeviceIoControl( (HANDLE)       hDevice,         // handle to device (DWORD)        IOCTL_PWM_PIN_SET_POLARITY, // dwIoControlCode(LPDWORD)      lpInBuffer,      // input buffer (DWORD)        nInBufferSize,   // size of input buffer (LPDWORD)      NULL,      // output buffer (DWORD)        0,  // size of output buffer (LPDWORD)      lpBytesReturned, // number of bytes returned (LPOVERLAPPED) lpOverlapped );  // OVERLAPPED structure
 This doc was truncated. Read more on learn.microsoft.com. Starts generation of Pulse Width Modulation (PWM) signal on a pin or channel. To check whether a pin is started, use IOCTL_PWM_PIN_IS_STARTED. To perform this operation, call the DeviceIoControl function with the following parameters. 
BOOL WINAPI DeviceIoControl( (HANDLE)       hDevice,         // handle to device (DWORD)        IOCTL_PWM_PIN_START, // dwIoControlCode(LPDWORD)      NULL,      // input buffer (DWORD)        0,   // size of input buffer (LPDWORD)      NULL,      // output buffer (DWORD)        0,  // size of output buffer (LPDWORD)      lpBytesReturned, // number of bytes returned (LPOVERLAPPED) lpOverlapped );  // OVERLAPPED structure
 This doc was truncated. Read more on learn.microsoft.com. Stops generation of Pulse Width Modulation (PWM) signal on a pin or channel. To check whether a pin is started, use IOCTL_PWM_PIN_IS_STARTED. To perform this operation, call the DeviceIoControl function with the following parameters. 
BOOL WINAPI DeviceIoControl( (HANDLE)       hDevice,         // handle to device (DWORD)        IOCTL_PWM_PIN_STOP, // dwIoControlCode(LPDWORD)      NULL,      // input buffer (DWORD)        0,   // size of input buffer (LPDWORD)      NULL,      // output buffer (DWORD)        0,  // size of output buffer (LPDWORD)      lpBytesReturned, // number of bytes returned (LPOVERLAPPED) lpOverlapped );  // OVERLAPPED structure
 This doc was truncated. Read more on learn.microsoft.com. Retrieves the state of signal generation for a pin or channel. Each pin has a state of started or stopped as a PWM_PIN_IS_STARTED_OUTPUT structure. To perform this operation, call the DeviceIoControl function with the following parameters. 
BOOL WINAPI DeviceIoControl( (HANDLE)       hDevice,         // handle to device (DWORD)        IOCTL_PWM_PIN_IS_STARTED, // dwIoControlCode(LPDWORD)      NULL,      // input buffer (DWORD)        0,   // size of input buffer (LPDWORD)      lpOutBuffer,     // output buffer (DWORD)        nOutBufferSize,  // size of output buffer (LPDWORD)      lpBytesReturned, // number of bytes returned (LPOVERLAPPED) lpOverlapped );  // OVERLAPPED structure
 This doc was truncated. Read more on learn.microsoft.com. Closes an open object handle. A valid handle to an open object. If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError. If the application is running under a debugger, the function will throw an exception if it receives either a handle value that is not valid or a pseudo-handle value. This can happen if you close a handle twice, or if you call CloseHandle on a handle returned by the FindFirstFile function instead of calling the FindClose function. The CloseHandle function closes handles to the following objects: This doc was truncated. Read more on learn.microsoft.com. Retrieves information about the system's current usage of both physical and virtual memory. (GlobalMemoryStatusEx) A pointer to a MEMORYSTATUSEX structure that receives information about current memory availability. Read more on learn.microsoft.com. If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError. You can use the GlobalMemoryStatusEx function to determine how much memory your application can allocate without severely impacting other applications. The information returned by the GlobalMemoryStatusEx function is volatile. There is no guarantee that two sequential calls to this function will return the same information. The ullAvailPhys member of the MEMORYSTATUSEX structure at lpBuffer includes memory for all NUMA nodes. Read more on learn.microsoft.com. Retrieves a pseudo handle for the calling thread. The return value is a pseudo handle for the current thread. A pseudo handle is a special constant that is interpreted as the current thread handle. The calling thread can use this handle to specify itself whenever a thread handle is required. Pseudo handles are not inherited by child processes. This handle has the THREAD_ALL_ACCESS access right to the thread object. For more information, see Thread Security and Access Rights. Windows Server 2003 and Windows XP:  This handle has the maximum access allowed by the security descriptor of the thread to the primary token of the process. The function cannot be used by one thread to create a handle that can be used by other threads to refer to the first thread. The handle is always interpreted as referring to the thread that is using it. A thread can create a "real" handle to itself that can be used by other threads, or inherited by other processes, by specifying the pseudo handle as the source handle in a call to the DuplicateHandle function. The pseudo handle need not be closed when it is no longer needed. Calling the CloseHandle function with this handle has no effect. If the pseudo handle is duplicated by DuplicateHandle, the duplicate handle must be closed. Do not create a thread while impersonating a security context. The call will succeed, however the newly created thread will have reduced access rights to itself when calling GetCurrentThread. The access rights granted this thread will be derived from the access rights the impersonated user has to the process. Some access rights including THREAD_SET_THREAD_TOKEN and THREAD_GET_CONTEXT may not be present, leading to unexpected failures. Read more on learn.microsoft.com. Returns the number of active processor groups in the system. If the function succeeds, the return value is the number of active processor groups in the system. If the function fails, the return value is zero. To compile an application that uses this function, set _WIN32_WINNT >= 0x0601. For more information, see Using the Windows Headers. Sets the processor group affinity for the specified thread. A handle to the thread. The handle must have the THREAD_SET_INFORMATION access right. For more information, see Thread Security and Access Rights. Read more on learn.microsoft.com. A GROUP_AFFINITY structure that specifies the processor group affinity to be used for the specified thread. A pointer to a GROUP_AFFINITY structure to receive the thread's previous group affinity. This parameter can be NULL. If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, use GetLastError. Starting with Windows 11 and Windows Server 2022, on a system with more than 64 processors, process and thread affinities span all processors in the system, across all processor groups, by default. The SetThreadGroupAffinity function restricts a thread's affinity to the processors over the single processor group specified by the given GroupAffinity. This group will also become the thread's primary group. To compile an application that uses this function, set _WIN32_WINNT >= 0x0601. For more information, see Using the Windows Headers. Read more on learn.microsoft.com. Enumerates all system firmware tables of the specified type. A pointer to a buffer that receives the list of firmware tables. If this parameter is NULL, the return value is the required buffer size. For more information on the contents of this buffer, see the Remarks section. Read more on learn.microsoft.com. The size of the pFirmwareTableBuffer buffer, in bytes. If the function succeeds, the return value is the number of bytes written to the buffer. This value will always be less than or equal to BufferSize. If the function fails because the buffer is not large enough, the return value is the required buffer size, in bytes. This value is always greater than BufferSize. If the function fails for any other reason, the return value is zero. To get extended error information, call GetLastError. Starting with Windows 10, version 1803, Universal Windows apps can access the System Management BIOS (SMBIOS) information by declaring the smbios restricted capability in the app manifest. See Access SMBIOS information from a Universal Windows App for details. Only raw SMBIOS (RSMB) firmware tables can be accessed from a Universal Windows app. As of Windows Server 2003 with Service Pack 1 (SP1), applications cannot access the \Device\PhysicalMemory object. Access to this object is limited to kernel-mode drivers. This change affects applications read System Management BIOS (SMBIOS) or other BIOS data stored in the lowest 1MB of physical memory. Applications have the following alternatives to read data from low physical memory: This doc was truncated. Read more on learn.microsoft.com. Retrieves the specified firmware table from the firmware table provider. The identifier of the firmware table. This identifier is little endian, you must reverse the characters in the string. For example, FACP is an ACPI provider, as described in the Signature field of the DESCRIPTION_HEADER structure in the ACPI specification (see the [Advanced Configuration and Power Interface (ACPI) Specification](https://uefi.org/htmlspecs/ACPI_Spec_6_4_html/). Therefore, use 'PCAF' to specify the FACP table, as shown in the following example: retVal = GetSystemFirmwareTable('ACPI', 'PCAF', pBuffer, BUFSIZE); For more information, see the Remarks section of the EnumSystemFirmwareTables function. Read more on learn.microsoft.com. A pointer to a buffer that receives the requested firmware table. If this parameter is NULL, the return value is the required buffer size. For more information on the contents of this buffer, see the Remarks section. Read more on learn.microsoft.com. The size of the pFirmwareTableBuffer buffer, in bytes. If the function succeeds, the return value is the number of bytes written to the buffer. This value will always be less than or equal to BufferSize. If the function fails because the buffer is not large enough, the return value is the required buffer size, in bytes. This value is always greater than BufferSize. If the function fails for any other reason, the return value is zero. To get extended error information, call GetLastError. Starting with Windows 10, version 1803, Universal Windows apps can access the System Management BIOS (SMBIOS) information by declaring the smbios restricted capability in the app manifest. See Access SMBIOS information from a Universal Windows App for details. Only raw SMBIOS (RSMB) firmware tables can be accessed from a Universal Windows app. As of Windows Server 2003 with Service Pack 1 (SP1), applications cannot access the \Device\PhysicalMemory object. Access to this object is limited to kernel-mode drivers. This change affects applications read System Management BIOS (SMBIOS) or other BIOS data stored in the lowest 1MB of physical memory. Applications have the following alternatives to read data from low physical memory: This doc was truncated. Read more on learn.microsoft.com. Creates or opens a file or I/O device. The most commonly used I/O devices are as follows:\_file, file stream, directory, physical disk, volume, console buffer, tape drive, communications resource, mailslot, and pipe. (Unicode) The name of the file or device to be created or opened. You may use either forward slashes (/) or backslashes (\\) in this name. In the ANSI version of this function, the name is limited to MAX_PATH characters. To extend this limit to 32,767 wide characters, use this Unicode version of the function and prepend "\\\\?\\" to the path. For more information, see Naming Files, Paths, and Namespaces. For information on special device names, see Defining an MS-DOS Device Name. To create a file stream, specify the name of the file, a colon, and then the name of the stream. For more information, see File Streams.
Tip Starting with Windows 10, version 1607, for the unicode version of this function (CreateFileW), you can opt-in to remove the MAX_PATH limitation without prepending "\\?\". See the "Maximum Path Length Limitation" section of Naming Files, Paths, and Namespaces for details.
 Read more on learn.microsoft.com. The requested access to the file or device, which can be summarized as read, write, both or neither zero). The most commonly used values are GENERIC_READ, GENERIC_WRITE, or both (GENERIC_READ | GENERIC_WRITE). For more information, see Generic Access Rights, File Security and Access Rights, File Access Rights Constants, and ACCESS_MASK. If this parameter is zero, the application can query certain metadata such as file, directory, or device attributes without accessing that file or device, even if GENERIC_READ access would have been denied. You cannot request an access mode that conflicts with the sharing mode that is specified by the dwShareMode parameter in an open request that already has an open handle. For more information, see the Remarks section of this topic and Creating and Opening Files. Read more on learn.microsoft.com. The requested sharing mode of the file or device, which can be read, write, both, delete, all of these, or none (refer to the following table). Access requests to attributes or extended attributes are not affected by this flag. If this parameter is zero and CreateFile succeeds, the file or device cannot be shared and cannot be opened again until the handle to the file or device is closed. For more information, see the Remarks section. You cannot request a sharing mode that conflicts with the access mode that is specified in an existing request that has an open handle. CreateFile would fail and the GetLastError function would return ERROR_SHARING_VIOLATION. To enable a process to share a file or device while another process has the file or device open, use a Read more on learn.microsoft.com. A pointer to a SECURITY_ATTRIBUTES structure that contains two separate but related data members: an optional security descriptor, and a Boolean value that determines whether the returned handle can be inherited by child processes. This parameter can be NULL. If this parameter is NULL, the handle returned by CreateFile cannot be inherited by any child processes the application may create and the file or device associated with the returned handle gets a default security descriptor. The lpSecurityDescriptor member of the structure specifies a SECURITY_DESCRIPTOR for a file or device. If this member is NULL, the file or device associated with the returned handle is assigned a default security descriptor. CreateFile ignores the lpSecurityDescriptor member when opening an existing file or device, but continues to use the bInheritHandle member. The bInheritHandle member of the structure specifies whether the returned handle can be inherited. For more information, see the Remarks section. Read more on learn.microsoft.com. An action to take on a file or device that exists or does not exist. For devices other than files, this parameter is usually set to OPEN_EXISTING. For more information, see the Remarks section. Read more on learn.microsoft.com. The file or device attributes and flags, FILE_ATTRIBUTE_NORMAL being the most common default value for files. This parameter can include any combination of the available file attributes (FILE_ATTRIBUTE_*). All other file attributes override FILE_ATTRIBUTE_NORMAL. This parameter can also contain combinations of flags (FILE_FLAG_*) for control of file or device caching behavior, access modes, and other special-purpose flags. These combine with any FILE_ATTRIBUTE_* values. This parameter can also contain Security Quality of Service (SQOS) information by specifying the SECURITY_SQOS_PRESENT flag. Additional SQOS-related flags information is presented in the table following the attributes and flags tables.
Note When CreateFile opens an existing file, it generally combines the file flags with the file attributes of the existing file, and ignores any file attributes supplied as part of dwFlagsAndAttributes. Special cases are detailed in Creating and Opening Files.
Some of the following file attributes and flags may only apply to files and not necessarily all other types of devices that CreateFile can open. For additional information, see the Remarks section of this topic and Creating and Opening Files. For more advanced access to file attributes, see SetFileAttributes. For a complete list of all file attributes with their values and descriptions, see File Attribute Constants. This doc was truncated. Read more on learn.microsoft.com. A valid handle to a template file with the GENERIC_READ access right. The template file supplies file attributes and extended attributes for the file that is being created. This parameter can be NULL. When opening an existing file, CreateFile ignores this parameter. When opening a new encrypted file, the file inherits the discretionary access control list from its parent directory. For additional information, see File Encryption. Read more on learn.microsoft.com. If the function succeeds, the return value is an open handle to the specified file, device, named pipe, or mail slot. If the function fails, the return value is INVALID_HANDLE_VALUE. To get extended error information, call GetLastError. CreateFile was originally developed specifically for file interaction but has since been expanded and enhanced to include most other types of I/O devices and mechanisms available to Windows developers. This section attempts to cover the varied issues developers may experience when using CreateFile in different contexts and with different I/O types. The text attempts to use the word file only when referring specifically to data stored in an actual file on a file system. However, some uses of file may be referring more generally to an I/O object that supports file-like mechanisms. This liberal use of the term file is particularly prevalent in constant names and parameter names because of the previously mentioned historical reasons. When an application is finished using the object handle returned by CreateFile, use the CloseHandle function to close the handle. This not only frees up system resources, but can have wider influence on things like sharing the file or device and committing data to disk. Specifics are noted within this topic as appropriate. Windows Server 2003 and Windows XP: A sharing violation occurs if an attempt is made to open a file or directory for deletion on a remote computer when the value of the dwDesiredAccess parameter is the DELETE access flag (0x00010000) OR'ed with any other access flag, and the remote file or directory has not been opened with FILE_SHARE_DELETE. To avoid the sharing violation in this scenario, open the remote file or directory with the DELETE access right only, or call DeleteFile without first opening the file or directory for deletion. Some file systems, such as the NTFS file system, support compression or encryption for individual files and directories. On volumes that have a mounted file system with this support, a new file inherits the compression and encryption attributes of its directory. You cannot use CreateFile to control compression, decompression, or decryption on a file or directory. For more information, see Creating and Opening Files, File Compression and Decompression, and File Encryption. Windows Server 2003 and Windows XP: For backward compatibility purposes, CreateFile does not apply inheritance rules when you specify a security descriptor in lpSecurityAttributes. To support inheritance, functions that later query the security descriptor of this file may heuristically determine and report that inheritance is in effect. For more information, see Automatic Propagation of Inheritable ACEs. As stated previously, if the lpSecurityAttributes parameter is NULL, the handle returned by CreateFile cannot be inherited by any child processes your application may create. The following information regarding this parameter also applies: This doc was truncated. Read more on learn.microsoft.com. Releases, decommits, or releases and decommits a region of pages within the virtual address space of the calling process. A pointer to the base address of the region of pages to be freed. If the _dwFreeType_ parameter is **MEM_RELEASE**, this parameter must be the base address returned by the [VirtualAlloc](/windows/win32/api/memoryapi/nf-memoryapi-virtualalloc) function when the region of pages is reserved. Read more on learn.microsoft.com. The size of the region of memory to be freed, in bytes. If the _dwFreeType_ parameter is **MEM_RELEASE**, this parameter must be 0 (zero). The function frees the entire region that is reserved in the initial allocation call to [VirtualAlloc](/windows/win32/api/memoryapi/nf-memoryapi-virtualalloc). If the _dwFreeType_ parameter is **MEM_DECOMMIT**, the function decommits all memory pages that contain one or more bytes in the range from the _lpAddress_ parameter to `(lpAddress+dwSize)`. This means, for example, that a 2-byte region of memory that straddles a page boundary causes both pages to be decommitted. If _lpAddress_ is the base address returned by [VirtualAlloc](/windows/win32/api/memoryapi/nf-memoryapi-virtualalloc) and _dwSize_ is 0 (zero), the function decommits the entire region that is allocated by **VirtualAlloc**. After that, the entire region is in the reserved state. Read more on learn.microsoft.com. If the function succeeds, the return value is nonzero. If the function fails, the return value is 0 (zero). To get extended error information, call [GetLastError](/windows/win32/api/errhandlingapi/nf-errhandlingapi-getlasterror). Each page of memory in a process virtual address space has a [Page State](/windows/win32/Memory/page-state). The **VirtualFree** function can decommit a range of pages that are in different states, some committed and some uncommitted. This means that you can decommit a range of pages without first determining the current commitment state of each page. Decommitting a page releases its physical storage, either in memory or in the paging file on disk. If a page is decommitted but not released, its state changes to reserved. Subsequently, you can call [VirtualAlloc](/windows/win32/api/memoryapi/nf-memoryapi-virtualalloc) to commit it, or **VirtualFree** to release it. Attempts to read from or write to a reserved page results in an access violation exception. The **VirtualFree** function can release a range of pages that are in different states, some reserved and some committed. This means that you can release a range of pages without first determining the current commitment state of each page. The entire range of pages originally reserved by the [VirtualAlloc](nf-memoryapi-virtualalloc.md) function must be released at the same time. If a page is released, its state changes to free, and it is available for subsequent allocation operations. After memory is released or decommited, you can never refer to the memory again. Any information that may have been in that memory is gone forever. Attempting to read from or write to a free page results in an access violation exception. If you need to keep information, do not decommit or free memory that contains the information. The **VirtualFree** function can be used on an AWE region of memory, and it invalidates any physical page mappings in the region when freeing the address space. However, the physical page is not deleted, and the application can use them. The application must explicitly call [FreeUserPhysicalPages](nf-memoryapi-freeuserphysicalpages.md) to free the physical pages. When the process is terminated, all resources are cleaned up automatically. **Windows 10, version 1709 and later and Windows 11:** To delete the enclave when you finish using it, call [DeleteEnclave](../enclaveapi/nf-enclaveapi-deleteenclave.md). You cannot delete a VBS enclave by calling the **VirtualFree** or [VirtualFreeEx](nf-memoryapi-virtualfreeex.md) function. You can still delete an SGX enclave by calling **VirtualFree** or **VirtualFreeEx**. **Windows 10, version 1507, Windows 10, version 1511, Windows 10, version 1607 and Windows 10, version 1703:** To delete the enclave when you finish using it, call the **VirtualFree** or [VirtualFreeEx](nf-memoryapi-virtualfreeex.md) function and specify the following values: - The base address of the enclave for the _lpAddress_ parameter. - 0 for the _dwSize_ parameter. - **MEM_RELEASE** for the _dwFreeType_ parameter. Read more on learn.microsoft.com. Reserves, commits, or changes the state of a region of pages in the virtual address space of the calling process. (VirtualAlloc) The starting address of the region to allocate. If the memory is being reserved, the specified address is rounded down to the nearest multiple of the allocation granularity. If the memory is already reserved and is being committed, the address is rounded down to the next page boundary. To determine the size of a page and the allocation granularity on the host computer, use the [GetSystemInfo](/windows/win32/api/sysinfoapi/nf-sysinfoapi-getsysteminfo) function. If this parameter is **NULL**, the system determines where to allocate the region. If this address is within an enclave that you have not initialized by calling [InitializeEnclave](/windows/win32/api/enclaveapi/nf-enclaveapi-initializeenclave), **VirtualAlloc** allocates a page of zeros for the enclave at that address. The page must be previously uncommitted, and will not be measured with the EEXTEND instruction of the Intel Software Guard Extensions programming model. If the address is within an enclave that you initialized, then the allocation operation fails with the **ERROR_INVALID_ADDRESS** error. That is true for enclaves that do not support dynamic memory management (i.e. SGX1). SGX2 enclaves will permit allocation, and the page must be accepted by the enclave after it has been allocated. Read more on learn.microsoft.com. The size of the region, in bytes. If the _lpAddress_ parameter is **NULL**, this value is rounded up to the next page boundary. Otherwise, the allocated pages include all pages containing one or more bytes in the range from _lpAddress_ to _lpAddress_+_dwSize_. This means that a 2-byte range straddling a page boundary causes both pages to be included in the allocated region. The memory protection for the region of pages to be allocated. If the pages are being committed, you can specify any one of the [memory protection constants](/windows/win32/Memory/memory-protection-constants). If the function succeeds, the return value is the base address of the allocated region of pages. If the function fails, the return value is **NULL**. To get extended error information, call [GetLastError](/windows/win32/api/errhandlingapi/nf-errhandlingapi-getlasterror). Each page has an associated [page state](/windows/win32/Memory/page-state). The **VirtualAlloc** function can perform the following operations: - Commit a region of reserved pages - Reserve a region of free pages - Simultaneously reserve and commit a region of free pages **VirtualAlloc** cannot reserve a reserved page. It can commit a page that is already committed. This means you can commit a range of pages, regardless of whether they have already been committed, and the function will not fail. You can use **VirtualAlloc** to reserve a block of pages and then make additional calls to **VirtualAlloc** to commit individual pages from the reserved block. This enables a process to reserve a range of its virtual address space without consuming physical storage until it is needed. If the _lpAddress_ parameter is not **NULL**, the function uses the _lpAddress_ and _dwSize_ parameters to compute the region of pages to be allocated. The current state of the entire range of pages must be compatible with the type of allocation specified by the _flAllocationType_ parameter. Otherwise, the function fails and none of the pages are allocated. This compatibility requirement does not preclude committing an already committed page, as mentioned previously. To execute dynamically generated code, use **VirtualAlloc** to allocate memory and the [VirtualProtect](/windows/win32/api/memoryapi/nf-memoryapi-virtualprotect) function to grant **PAGE_EXECUTE** access. The **VirtualAlloc** function can be used to reserve an [Address Windowing Extensions](/windows/win32/Memory/address-windowing-extensions) (AWE) region of memory within the virtual address space of a specified process. This region of memory can then be used to map physical pages into and out of virtual memory as required by the application. The **MEM_PHYSICAL** and **MEM_RESERVE** values must be set in the _AllocationType_ parameter. The **MEM_COMMIT** value must not be set. The page protection must be set to **PAGE_READWRITE**. The [VirtualFree](/windows/win32/api/memoryapi/nf-memoryapi-virtualfree) function can decommit a committed page, releasing the page's storage, or it can simultaneously decommit and release a committed page. It can also release a reserved page, making it a free page. When creating a region that will be executable, the calling program bears responsibility for ensuring cache coherency via an appropriate call to [FlushInstructionCache](/windows/win32/api/processthreadsapi/nf-processthreadsapi-flushinstructioncache) once the code has been set in place. Otherwise attempts to execute code out of the newly executable region may produce unpredictable results. Read more on learn.microsoft.com. Sends a control code directly to a specified device driver, causing the corresponding device to perform the corresponding operation. A handle to the device on which the operation is to be performed. The device is typically a volume, directory, file, or stream. To retrieve a device handle, use the CreateFile function. For more information, see Remarks. Read more on learn.microsoft.com. The control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. For a list of the control codes, see Remarks. The documentation for each control code provides usage details for the lpInBuffer, nInBufferSize, lpOutBuffer, and nOutBufferSize parameters. Read more on learn.microsoft.com. A pointer to the input buffer that contains the data required to perform the operation. The format of this data depends on the value of the dwIoControlCode parameter. This parameter can be NULL if dwIoControlCode specifies an operation that does not require input data. Read more on learn.microsoft.com. The size of the input buffer, in bytes. A pointer to the output buffer that is to receive the data returned by the operation. The format of this data depends on the value of the dwIoControlCode parameter. This parameter can be NULL if dwIoControlCode specifies an operation that does not return data. Read more on learn.microsoft.com. The size of the output buffer, in bytes. A pointer to a variable that receives the size of the data stored in the output buffer, in bytes. If the output buffer is too small to receive any data, the call fails, GetLastError returns ERROR_INSUFFICIENT_BUFFER, and lpBytesReturned is zero. If the output buffer is too small to hold all of the data but can hold some entries, some drivers will return as much data as fits. In this case, the call fails, GetLastError returns ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data received. Your application should call DeviceIoControl again with the same operation, specifying a new starting point. If lpOverlapped is NULL, lpBytesReturned cannot be NULL. Even when an operation returns no output data and lpOutBuffer is NULL, DeviceIoControl makes use of lpBytesReturned. After such an operation, the value of lpBytesReturned is meaningless. If lpOverlapped is not NULL, lpBytesReturned can be NULL. If this parameter is not NULL and the operation returns data, lpBytesReturned is meaningless until the overlapped operation has completed. To retrieve the number of bytes returned, call GetOverlappedResult. If hDevice is associated with an I/O completion port, you can retrieve the number of bytes returned by calling GetQueuedCompletionStatus. Read more on learn.microsoft.com. A pointer to an OVERLAPPED structure. If hDevice was opened without specifying FILE_FLAG_OVERLAPPED, lpOverlapped is ignored. If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, the operation is performed as an overlapped (asynchronous) operation. In this case, lpOverlapped must point to a valid OVERLAPPED structure that contains a handle to an event object. Otherwise, the function fails in unpredictable ways. For overlapped operations, DeviceIoControl returns immediately, and the event object is signaled when the operation has been completed. Otherwise, the function does not return until the operation has been completed or an error occurs. Read more on learn.microsoft.com. If the operation completes successfully, the return value is nonzero (TRUE). If the operation fails or is pending, the return value is zero. To get extended error information, call GetLastError. To retrieve a handle to the device, you must call the CreateFile function with either the name of a device or the name of the driver associated with a device. To specify a device name, use the following format: \\\\.\DeviceName DeviceIoControl can accept a handle to a specific device. For example, to open a handle to the logical drive A: with CreateFile, specify \\\\.\a:. Alternatively, you can use the names \\\\.\PhysicalDrive0, \\\\.\PhysicalDrive1, and so on, to open handles to the physical drives on a system. You should specify the FILE_SHARE_READ and FILE_SHARE_WRITE access flags when calling CreateFile to open a handle to a device driver. However, when you open a communications resource, such as a serial port, you must specify exclusive access. Use the other CreateFile parameters as follows when opening a device handle: This doc was truncated. Read more on learn.microsoft.com. Frees the loaded dynamic-link library (DLL) module and, if necessary, decrements its reference count. A handle to the loaded library module. The LoadLibrary, LoadLibraryEx, GetModuleHandle, or GetModuleHandleEx function returns this handle. Read more on learn.microsoft.com. If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call the GetLastError function. The system maintains a per-process reference count for each loaded module. A module that was loaded at process initialization due to load-time dynamic linking has a reference count of one. The reference count for a module is incremented each time the module is loaded by a call to LoadLibrary. The reference count is also incremented by a call to LoadLibraryEx unless the module is being loaded for the first time and is being loaded as a data or image file. The reference count is decremented each time the FreeLibrary or FreeLibraryAndExitThread function is called for the module. When a module's reference count reaches zero or the process terminates, the system unloads the module from the address space of the process. Before unloading a library module, the system enables the module to detach from the process by calling the module's DllMain function, if it has one, with the DLL_PROCESS_DETACH value. Doing so gives the library module an opportunity to clean up resources allocated on behalf of the current process. After the entry-point function returns, the library module is removed from the address space of the current process. It is not safe to call FreeLibrary from DllMain. For more information, see the Remarks section in DllMain. Calling FreeLibrary does not affect other processes that are using the same module. Use caution when calling FreeLibrary with a handle returned by GetModuleHandle. The GetModuleHandle function does not increment a module's reference count, so passing this handle to FreeLibrary can cause a module to be unloaded prematurely. A thread that must unload the DLL in which it is executing and then terminate itself should call FreeLibraryAndExitThread instead of calling FreeLibrary and ExitThread separately. Otherwise, a race condition can occur. For details, see the Remarks section of FreeLibraryAndExitThread. Read more on learn.microsoft.com. Loads the specified module into the address space of the calling process. (LoadLibraryW) The name of the module. This can be either a library module (a .dll file) or an executable module (an .exe file). If the specified module is an executable module, static imports are not loaded; instead, the module is loaded as if by LoadLibraryEx with the `DONT_RESOLVE_DLL_REFERENCES` flag. The name specified is the file name of the module and is not related to the name stored in the library module itself, as specified by the LIBRARY keyword in the module-definition (.def) file. If the string specifies a full path, the function searches only that path for the module. If the string specifies a relative path or a module name without a path, the function uses a standard search strategy to find the module; for more information, see the Remarks. If the function cannot find the module, the function fails. When specifying a path, be sure to use backslashes (\\), not forward slashes (/). For more information about paths, see Naming a File or Directory. If the string specifies a module name without a path and the file name extension is omitted, the function appends the default library extension ".DLL" to the module name. To prevent the function from appending ".DLL" to the module name, include a trailing point character (.) in the module name string. Read more on learn.microsoft.com. If the function succeeds, the return value is a handle to the module. If the function fails, the return value is NULL. To get extended error information, call GetLastError. To enable or disable error messages displayed by the loader during DLL loads, use the SetErrorMode function. LoadLibrary can be used to load a library module into the address space of the process and return a handle that can be used in GetProcAddress to get the address of a DLL function. LoadLibrary can also be used to load other executable modules. For example, the function can specify an .exe file to get a handle that can be used in FindResource or LoadResource. However, do not use LoadLibrary to run an .exe file. Instead, use the CreateProcess function. If the specified module is a DLL that is not already loaded for the calling process, the system calls the DLL's DllMain function with the DLL_PROCESS_ATTACH value. If DllMain returns TRUE, LoadLibrary returns a handle to the module. If DllMain returns FALSE, the system unloads the DLL from the process address space and LoadLibrary returns NULL. It is not safe to call LoadLibrary from DllMain. For more information, see the Remarks section in DllMain. Module handles are not global or inheritable. A call to LoadLibrary by one process does not produce a handle that another process can use — for example, in calling GetProcAddress. The other process must make its own call to LoadLibrary for the module before calling GetProcAddress. If lpFileName does not include a path and there is more than one loaded module with the same base name and extension, the function returns a handle to the module that was loaded first. If no file name extension is specified in the lpFileName parameter, the default library extension .dll is appended. However, the file name string can include a trailing point character (.) to indicate that the module name has no extension. When no path is specified, the function searches for loaded modules whose base name matches the base name of the module to be loaded. If the name matches, the load succeeds. Otherwise, the function searches for the file. The first directory searched is the directory containing the image file used to create the calling process (for more information, see the CreateProcess function). Doing this allows private dynamic-link library (DLL) files associated with a process to be found without adding the process's installed directory to the PATH environment variable. If a relative path is specified, the entire relative path is appended to every token in the DLL search path list. To load a module from a relative path without searching any other path, use GetFullPathName to get a nonrelative path and call LoadLibrary with the nonrelative path. For more information on the DLL search order, see Dynamic-Link Library Search Order. The search path can be altered using the SetDllDirectory function. This solution is recommended instead of using SetCurrentDirectory or hard-coding the full path to the DLL. If a path is specified and there is a redirection file for the application, the function searches for the module in the application's directory. If the module exists in the application's directory, LoadLibrary ignores the specified path and loads the module from the application's directory. If the module does not exist in the application's directory, LoadLibrary loads the module from the specified directory. For more information, see Dynamic Link Library Redirection. If you call LoadLibrary with the name of an assembly without a path specification and the assembly is listed in the system compatible manifest, the call is automatically redirected to the side-by-side assembly. The system maintains a per-process reference count on all loaded modules. Calling LoadLibrary increments the reference count. Calling the FreeLibrary or FreeLibraryAndExitThread function decrements the reference count. The system unloads a module when its reference count reaches zero or when the process terminates (regardless of the reference count). Windows Server 2003 and Windows XP:  The Visual C++ compiler supports a syntax that enables you to declare thread-local variables: _declspec(thread). If you use this syntax in a DLL, you will not be able to load the DLL explicitly using LoadLibrary on versions of Windows prior to Windows Vista. If your DLL will be loaded explicitly, you must use the thread local storage functions instead of _declspec(thread). For an example, see Using Thread Local Storage in a Dynamic Link Library.

Security Remarks

Do not use the SearchPath function to retrieve a path to a DLL for a subsequent LoadLibrary call. The SearchPath function uses a different search order than LoadLibrary and it does not use safe process search mode unless this is explicitly enabled by calling SetSearchPathMode with BASE_SEARCH_PATH_ENABLE_SAFE_SEARCHMODE. Therefore, SearchPath is likely to first search the user’s current working directory for the specified DLL. If an attacker has copied a malicious version of a DLL into the current working directory, the path retrieved by SearchPath will point to the malicious DLL, which LoadLibrary will then load. Do not make assumptions about the operating system version based on a LoadLibrary call that searches for a DLL. If the application is running in an environment where the DLL is legitimately not present but a malicious version of the DLL is in the search path, the malicious version of the DLL may be loaded. Instead, use the recommended techniques described in Getting the System Version. Read more on learn.microsoft.com. Retrieves the address of an exported function or variable from the specified dynamic-link library (DLL). A handle to the DLL module that contains the function or variable. The LoadLibrary, LoadLibraryEx, LoadPackagedLibrary, or GetModuleHandle function returns this handle. The GetProcAddress function does not retrieve addresses from modules that were loaded using the LOAD_LIBRARY_AS_DATAFILE flag. For more information, see LoadLibraryEx. Read more on learn.microsoft.com. The function or variable name, or the function's ordinal value. If this parameter is an ordinal value, it must be in the low-order word; the high-order word must be zero. If the function succeeds, the return value is the address of the exported function or variable. If the function fails, the return value is NULL. To get extended error information, call GetLastError. The spelling and case of a function name pointed to by lpProcName must be identical to that in the EXPORTS statement of the source DLL's module-definition (.def) file. The exported names of functions may differ from the names you use when calling these functions in your code. This difference is hidden by macros used in the SDK header files. For more information, see Conventions for Function Prototypes. The lpProcName parameter can identify the DLL function by specifying an ordinal value associated with the function in the EXPORTS statement. GetProcAddress verifies that the specified ordinal is in the range 1 through the highest ordinal value exported in the .def file. The function then uses the ordinal as an index to read the function's address from a function table. If the .def file does not number the functions consecutively from 1 to N (where N is the number of exported functions), an error can occur where GetProcAddress returns an invalid, non-NULL address, even though there is no function with the specified ordinal. If the function might not exist in the DLL module—for example, if the function is available only on Windows Vista but the application might be running on Windows XP—specify the function by name rather than by ordinal value and design your application to handle the case when the function is not available, as shown in the following code fragment. This doc was truncated. Read more on learn.microsoft.com. Creates an that represents a given . The win32 error to be wrapped. An . Learn more in the documentation for this API. The SetupDiDestroyDeviceInfoList function deletes a device information set and frees all associated memory. A handle to the device information set to delete. The function returns TRUE if it is successful. Otherwise, it returns FALSE and the logged error can be retrieved with a call to GetLastError. Learn more about this API from learn.microsoft.com. The SetupDiGetClassDevs function returns a handle to a device information set that contains requested device information elements for a local computer. (Unicode) A pointer to the GUID for a device setup class or a device interface class. This pointer is optional and can be NULL. For more information about how to set ClassGuid, see the following Remarks section. A pointer to a NULL-terminated string that specifies: This doc was truncated. Read more on learn.microsoft.com. A handle to the top-level window to be used for a user interface that is associated with installing a device instance in the device information set. This handle is optional and can be NULL. A variable of type DWORD that specifies control options that filter the device information elements that are added to the device information set. This parameter can be a bitwise OR of zero or more of the following flags. For more information about combining these flags, see the following Remarks section. If the operation succeeds, SetupDiGetClassDevs returns a handle to a device information set that contains all installed devices that matched the supplied parameters. If the operation fails, the function returns INVALID_HANDLE_VALUE. To get extended error information, call GetLastError. The caller of SetupDiGetClassDevs must delete the returned device information set when it is no longer needed by calling SetupDiDestroyDeviceInfoList. Call SetupDiGetClassDevsEx to retrieve the devices for a class on a remote computer.

Device Setup Class Control Options

Use the following filtering options to control whether SetupDiGetClassDevs returns devices for all device setup classes or only for a specified device setup class: This doc was truncated. Read more on learn.microsoft.com. The SECURITY_ATTRIBUTES structure contains the security descriptor for an object and specifies whether the handle retrieved by specifying this structure is inheritable. The size, in bytes, of this structure. Set this value to the size of the **SECURITY\_ATTRIBUTES** structure. A pointer to a [**SECURITY\_DESCRIPTOR**](../winnt/ns-winnt-security_descriptor.md) structure that controls access to the object. If the value of this member is **NULL**, the object is assigned the default security descriptor associated with the [*access token*](/windows/win32/secauthz/access-tokens) of the calling process. This is not the same as granting access to everyone by assigning a **NULL** [*discretionary access control list*](/windows/win32/secauthz/dacls-and-aces) (DACL). By default, the default DACL in the access token of a process allows access only to the user represented by the access token. For information about creating a security descriptor, see [Creating a Security Descriptor](/windows/win32/secauthz/creating-a-security-descriptor-for-a-new-object-in-c--). Read more on learn.microsoft.com. A Boolean value that specifies whether the returned handle is inherited when a new process is created. If this member is **TRUE**, the new process inherits the handle. Represents a Win32 handle that can be closed with . The length of the inline array. Gets a ref to an individual element of the inline array. ⚠ Important ⚠: When this struct is on the stack, do not let the returned reference outlive the stack frame that defines it. Gets this inline array as a span. ⚠ Important ⚠: When this struct is on the stack, do not let the returned span outlive the stack frame that defines it. Gets this inline array as a span. ⚠ Important ⚠: When this struct is on the stack, do not let the returned span outlive the stack frame that defines it.