code de contrôle IOCTL_BATTERY_QUERY_TAG

Récupère l’étiquette actuelle de 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_TAG,     // 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

Poignée de la batterie à partir de laquelle l’étiquette doit être récupérée. Pour récupérer un handle d’appareil, appelez la fonction CreateFile .

dwIoControlCode

Code de contrôle de 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_TAG pour cette opération.

lpInBuffer

Pointeur vers une mémoire tampon d’entrée ULONG . La valeur indique le nombre de millisecondes à attendre s’il n’y a pas de batterie. La valeur -1 indique que la demande attendra indéfiniment (ou jusqu’à ce qu’elle soit annulée par un autre événement).

nInBufferSize

Taille de la mémoire tampon d’entrée, en octets.

lpOutBuffer

Pointeur vers une mémoire tampon de sortie ULONG . En cas de réussite, cette mémoire tampon contient la balise de batterie actuelle, qui peut être n’importe quelle valeur à l’exception de BATTERY_TAG_INVALID. En cas d’échec, si GetLastError retourne le code d’erreur ERROR_FILE_NOT_FOUND, cette mémoire tampon contient la valeur BATTERY_TAG_INVALID.

nOutBufferSize

Taille de la mémoire tampon de sortie en octets.

lpBytesReturned

Pointeur vers une variable qui reçoit la taille des données stockées dans la mémoire tampon lpOutBuffer , en octets.

Si la mémoire tampon de sortie est trop petite pour renvoyer des données, l’appel échoue, GetLastError retourne le code d’erreur ERROR_INSUFFICIENT_BUFFER et le nombre d’octets retournés 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 qui se chevauchent), 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 d’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 CHEVAUCHEMENT VALIDE . Dans ce cas, DeviceIoControl est effectué comme une opération qui se chevauche (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.

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 l’étiquette actuelle de la batterie. La balise de batterie est une valeur unique différente de zéro qui change lorsque la batterie physique est réinsérée, remplacée ou subit des modifications caractéristiques. Consultez la section Étiquettes de batterie dans la rubrique Vue d’ensemble des informations sur la batterie pour plus d’informations sur le changement d’étiquette de batterie, la façon de détecter la modification et la façon dont une application doit procéder après un changement d’étiquette de batterie. Lorsqu’une batterie n’est pas présente, cette demande attend l’heure indiquée et, s’il n’y a toujours pas de batterie présente, elle retourne ERROR_FILE_NOT_FOUND et définit l’étiquette de la batterie sur BATTERY_TAG_INVALID. (Pour plus d’informations, consultez Informations sur la batterie.)

Toutes les demandes d’autres informations sur la batterie nécessitent que l’appelant fournisse l’étiquette de batterie correspondante. Cela garantit que l’appelant reçoit des informations pour la même batterie pour chaque requête et garantit que l’appelant est conscient des changements de batterie sans interrogation constante.

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

Voir aussi

Informations sur la batterie

Codes de contrôle de gestion de l’alimentation

DeviceIoControl

IOCTL_BATTERY_QUERY_INFORMATION

IOCTL_BATTERY_QUERY_STATUS

IOCTL_BATTERY_SET_INFORMATION