IOCTL_BATTERY_QUERY_TAG código de control
Recupera la etiqueta actual de la batería.
Para realizar esta operación, llame a la función DeviceIoControl con los parámetros siguientes.
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
Parámetros
-
hDevice
-
Identificador de la batería desde la que se va a recuperar la etiqueta. Para recuperar un identificador de dispositivo, llame a la función CreateFile .
-
dwIoControlCode
-
Código de control para la operación. Este valor identifica la operación específica que se va a realizar y el tipo de dispositivo en el que se va a realizar. Use IOCTL_BATTERY_QUERY_TAG para esta operación.
-
lpInBuffer
-
Puntero a un búfer de entrada de ULONG . El valor indica el número de milisegundos que se esperarán si no hay batería. Un valor de -1 indica que la solicitud esperará indefinidamente (o hasta que se cancele por algún otro evento).
-
nInBufferSize
-
Tamaño del búfer de entrada, en bytes.
-
lpOutBuffer
-
Puntero a un búfer de salida de ULONG . Si se ejecuta correctamente, este búfer contiene la etiqueta de batería actual, que puede ser cualquier valor excepto BATTERY_TAG_INVALID. Si se produce un error, si GetLastError devuelve el código de error ERROR_FILE_NOT_FOUND, este búfer contiene el valor BATTERY_TAG_INVALID.
-
nOutBufferSize
-
Tamaño del búfer de salida, en bytes.
-
lpBytesReturned
-
Puntero a una variable que recibe el tamaño de los datos almacenados en el búfer lpOutBuffer , en bytes.
Si el búfer de salida es demasiado pequeño para devolver datos, se produce un error en la llamada, GetLastError devuelve el código de error ERROR_INSUFFICIENT_BUFFER y el recuento de bytes devuelto es cero.
Si lpOverlapped es NULL (E/S no superpuesta), lpBytesReturned no puede ser NULL.
Si lpOverlapped no es NULL (E/S superpuesta), lpBytesReturned puede ser NULL. Si se trata de una operación superpuesta, puede recuperar el número de bytes devueltos mediante una llamada a la función GetOverlappedResult . Si hDevice está asociado a un puerto de finalización de E/S, puede obtener el número de bytes devueltos llamando a la función GetQueuedCompletionStatus .
-
lpOverlapped
-
Puntero a una estructura SUPERPUESTA .
Si hDevice se abrió con la marca FILE_FLAG_OVERLAPPED , lpOverlapped debe apuntar a una estructura SUPERPUESTA válida. En este caso, DeviceIoControl se realiza como una operación superpuesta (asincrónica). Si el dispositivo se abrió con la marca FILE_FLAG_OVERLAPPED y lpOverlapped es NULL, la función produce un error de maneras impredecibles.
Si hDevice se abrió sin especificar la marca FILE_FLAG_OVERLAPPED , lpOverlapped se omite y la función DeviceIoControl no devuelve hasta que se haya completado la operación o hasta que se produzca un error.
Valor devuelto
Si la operación se completa correctamente, DeviceIoControl devuelve un valor distinto de cero.
Si se produce un error en la operación o está pendiente, DeviceIoControl devuelve cero. Para obtener información de error extendida, llame a GetLastError.
Todas las solicitudes de información de batería se completarán con el estado de ERROR_NO_SUCH_DEVICE (o ERROR_FILE_NOT_FOUND en Windows 10 versión 1809 y anteriores) siempre que el elemento BatteryTag de la solicitud no coincida con el de la etiqueta de batería actual. Esto garantiza que la información de la batería devuelta coincida con la de la batería solicitada (consulte Etiquetas de batería para obtener más información).
Comentarios
Este IOCTL de batería recupera la etiqueta actual de la batería. La etiqueta de batería es un valor único distinto de cero que cambia cuando la batería física se vuelve a insertar, reemplaza o se somete a cualquier cambio de características. Consulte la sección Etiquetas de batería del tema Información general de la batería para obtener más información sobre cuándo cambia una etiqueta de batería, cómo detectar el cambio y cómo debe continuar una aplicación después de un cambio de etiqueta de batería. Cuando una batería no esté presente, esta solicitud esperará el tiempo indicado y, si todavía no hay batería presente, devolverá ERROR_FILE_NOT_FOUND y establecerá la etiqueta de batería en BATTERY_TAG_INVALID. (Consulte Información sobre baterías para obtener más información).
Todas las solicitudes de otra información de batería requieren que el autor de la llamada proporcione la etiqueta de batería coincidente. Esto garantiza que el autor de la llamada recibe información para la misma batería para cada solicitud y garantiza que el autor de la llamada tenga en cuenta los cambios de batería sin sondeo constante.
Para conocer las implicaciones de la E/S superpuesta en esta operación, consulte la sección Comentarios del tema DeviceIoControl .
Ejemplos
Para obtener un ejemplo, vea Enumerar dispositivos de batería.
Requisitos
| Requisito | Value |
|---|---|
| Cliente mínimo compatible |
Windows XP [solo aplicaciones de escritorio] |
| Servidor mínimo compatible |
Windows Server 2003 [solo aplicaciones de escritorio] |
| Encabezado |
|