code de contrôle IOCTL_BATTERY_QUERY_INFORMATION
Récupère une variété d’informations pour la batterie.
Pour effectuer cette opération, appelez la fonction DeviceIoControl avec les paramètres suivants.
BOOL DeviceIoControl(
(HANDLE) hDevice, // handle to battery
IOCTL_BATTERY_QUERY_INFORMATION, // dwIoControlCode
(LPVOID) lpInBuffer, // input buffer
(DWORD) nInBufferSize, // size of input buffer
(LPVOID) lpOutBuffer, // output buffer
(DWORD) nOutBufferSize, // size of output buffer
(LPDWORD) lpBytesReturned, // number of bytes returned
(LPOVERLAPPED) lpOverlapped // OVERLAPPED structure
);
Paramètres
-
hDevice
-
Handle de la batterie sur laquelle les informations doivent être retournées. Pour récupérer un handle d’appareil, appelez la fonction CreateFile .
-
dwIoControlCode
-
Code de contrôle pour l’opération. Cette valeur identifie l’opération spécifique à effectuer et le type d’appareil sur lequel l’effectuer. Utilisez IOCTL_BATTERY_QUERY_INFORMATION pour cette opération.
-
lpInBuffer
-
Pointeur vers une structure BATTERY_QUERY_INFORMATION .
-
nInBufferSize
-
Taille de la mémoire tampon d’entrée, en octets.
-
lpOutBuffer
-
Pointeur vers la mémoire tampon de retour. Le type de données (et, par conséquent, la taille) de la mémoire tampon de retour dépend des informations demandées dans le BATTERY_QUERY_INFORMATION_LEVEL membre de la structure de BATTERY_QUERY_INFORMATION d’entrée.
Le tableau suivant montre les données retournées par un niveau d’informations donné.
Niveau d’information Données retournées BatteryDeviceName Chaîne Unicode terminée par null qui spécifie le nom de la batterie. BatteryEstimatedTime ULONG qui spécifie la durée d’exécution estimée de la batterie, en secondes. Si le débit de drainage fourni dans le membre AtRate de la structure BATTERY_QUERY_INFORMATION est égal à zéro, ce calcul est basé sur le taux actuel de drainage. Si AtRate est différent de zéro, l’heure retournée correspond à l’heure d’exécution attendue pour le taux donné. Si la durée estimée est inconnue (par exemple, la batterie ne se décharge pas et AtRate est zéro), BATTERY_UNKNOWN_TIME est retourné. Notez que cette valeur n’est pas très précise sur certains systèmes de batterie. La valeur peut varier considérablement en fonction de l’utilisation actuelle de l’alimentation, qui peut être affectée par l’activité du disque et d’autres facteurs. Il n’existe aucun mécanisme de notification pour les modifications apportées à cette valeur. BatteryGranularityInformation Tableau de longueur variable de structures BATTERY_REPORTING_SCALE qui contient la granularité des rapports pour la capacité de la batterie retournée par IOCTL_BATTERY_QUERY_STATUS. Plusieurs entrées sont retournées lorsque la granularité dépend de la capacité actuelle de la batterie. Consultez BATTERY_REPORTING_SCALE pour l’interprétation du tableau d’entrées. Le nombre d’entrées est indiqué par la taille de la mémoire tampon retournée et peut être calculé comme (lpBytesReturned / sizeof (BATTERY_REPORTING_SCALE)). Le nombre maximal d’entrées qui seront retournées est de quatre. BatteryInformation Structure BATTERY_INFORMATION . BatteryManufactureDate Structure BATTERY_MANUFACTURE_DATE . BatteryManufactureName Chaîne Unicode terminée par null qui contient le nom du fabricant de la batterie. BatterySerialNumber Chaîne Unicode terminée par null qui contient le numéro de série de la batterie. BatteryTemperature ULONG qui contient la température actuelle de la batterie, en 10e degré Kelvin. BatteryUniqueID Chaîne Unicode terminée par null qui identifie de façon unique la batterie. Cette valeur peut être utilisée pour suivre une batterie spécifique. Dans le cas des batteries intelligentes, cet ID correspond à la concaténation du nom du fabricant, du nom de l’appareil, de la date de fabrication et d’une représentation imprimable du numéro de série. Cette valeur n’est pas destinée à être affichée à l’utilisateur. -
nOutBufferSize
-
Taille de la mémoire tampon de sortie en octets. Selon le niveau d’informations des données demandées, il peut s’agir d’une mémoire tampon de taille variable.
-
lpBytesReturned
-
Pointeur vers une variable qui reçoit la taille des données retournées dans la mémoire tampon lpOutBuffer , en octets.
Si la mémoire tampon de sortie est trop petite pour retourner des données, l’appel échoue, GetLastError retourne le code d’erreur ERROR_INSUFFICIENT_BUFFER et le nombre d’octets retourné est égal à zéro.
Si lpOverlapped a la valeur NULL (E/S nonoverlapped), lpBytesReturned ne peut pas être NULL.
Si lpOverlapped n’a pas la valeur NULL (E/S superposées), lpBytesReturned peut avoir la valeur NULL. S’il s’agit d’une opération qui se chevauche, vous pouvez récupérer le nombre d’octets retournés en appelant la fonction GetOverlappedResult . Si hDevice est associé à un port d’achèvement des E/S, vous pouvez obtenir le nombre d’octets retournés en appelant la fonction GetQueuedCompletionStatus .
-
lpOverlapped
-
Pointeur vers une structure CHEVAUCHEMENT .
Si hDevice a été ouvert avec l’indicateur FILE_FLAG_OVERLAPPED , lpOverlapped doit pointer vers une structure OVERLAPPED valide. Dans ce cas, DeviceIoControl est effectué en tant qu’opération superposée (asynchrone). Si l’appareil a été ouvert avec l’indicateur FILE_FLAG_OVERLAPPED et que lpOverlapped a la valeur NULL, la fonction échoue de manière imprévisible.
Si hDevice a été ouvert sans spécifier l’indicateur de FILE_FLAG_OVERLAPPED , lpOverlapped est ignoré et la fonction DeviceIoControl ne retourne pas tant que l’opération n’est pas terminée ou jusqu’à ce qu’une erreur se produise.
Valeur retournée
Si l’opération se termine correctement, DeviceIoControl retourne une valeur différente de zéro.
Si l’opération échoue ou est en attente, DeviceIoControl retourne zéro. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.
Certaines informations sur les batteries sont facultatives ou peuvent n’avoir aucun sens pour certaines batteries. Si le type particulier de données demandé n’est pas disponible pour la batterie actuelle, ERROR_INVALID_FUNCTION est retourné.
Toutes les demandes d’informations sur la batterie se terminent avec la status de ERROR_NO_SUCH_DEVICE (ou ERROR_FILE_NOT_FOUND dans Windows 10 version 1809 et antérieure) chaque fois que l’élément BatteryTag de la demande ne correspond pas à celui de la balise de batterie actuelle. Cela garantit que les informations sur la batterie retournées correspondent à celles de la batterie demandée (pour plus d’informations, consultez Étiquettes de batterie ).
Notes
Cette batterie IOCTL récupère une variété d’informations pour la batterie. La structure des paramètres d’entrée, BATTERY_QUERY_INFORMATION, indique le type d’informations à retourner et le moment où les informations sur la batterie doivent être retournées. Le type de données et le contenu de la mémoire tampon de sortie varient en fonction des données demandées.
Pour connaître les implications des E/S qui se chevauchent sur cette opération, consultez la section Remarques de la rubrique DeviceIoControl .
Exemples
Pour obtenir un exemple, consultez Énumération des appareils de batterie.
Spécifications
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge |
Windows XP [applications de bureau uniquement] |
| Serveur minimal pris en charge |
Windows Server 2003 [applications de bureau uniquement] |
| En-tête |
|