IOCTL_BATTERY_QUERY_INFORMATION código de control
Recupera una variedad de información para 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_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
);
Parámetros
-
hDevice
-
Un asa a la batería en la que se va a devolver la información. 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_INFORMATION para esta operación.
-
lpInBuffer
-
Puntero a una estructura de BATTERY_QUERY_INFORMATION .
-
nInBufferSize
-
Tamaño del búfer de entrada, en bytes.
-
lpOutBuffer
-
Puntero al búfer de devolución. El tipo de datos (y, por lo tanto, el tamaño) del búfer de devolución depende de la información solicitada en el miembro BATTERY_QUERY_INFORMATION_LEVEL de la estructura de BATTERY_QUERY_INFORMATION de entrada.
En la tabla siguiente se muestran los datos devueltos por un nivel de información determinado.
Nivel de información Datos devueltos BatteryDeviceName Cadena Unicode terminada en NULL que especifica el nombre de la batería. BatteryEstimatedTime ULONG que especifica el tiempo de ejecución de la batería estimado, en segundos. Si la tasa de purga proporcionada en el miembro AtRate de la estructura BATTERY_QUERY_INFORMATION es cero, este cálculo se basa en la tasa actual de purga. Si AtRate es distinto de cero, el tiempo devuelto es el tiempo de ejecución esperado para la tasa especificada. Si se desconoce el tiempo estimado (por ejemplo, la batería no se descarga y AtRate es cero), se devuelve BATTERY_UNKNOWN_TIME . Tenga en cuenta que este valor no es muy preciso en algunos sistemas de batería. El valor puede variar ampliamente en función del uso de energía actual, lo que podría verse afectado por la actividad del disco y otros factores. No hay ningún mecanismo de notificación para los cambios en este valor. BatteryGranularityInformation Matriz de longitud variable de BATTERY_REPORTING_SCALE estructuras que contiene la granularidad del informe para la capacidad de la batería que se devuelve de IOCTL_BATTERY_QUERY_STATUS. Se devuelven varias entradas cuando la granularidad depende de la capacidad actual de la batería. Consulte BATTERY_REPORTING_SCALE para obtener la interpretación de la matriz de entradas. El número de entradas se indica mediante el tamaño del búfer devuelto y se puede calcular como (lpBytesReturned /sizeof (BATTERY_REPORTING_SCALE)). El número máximo de entradas que se devolverán es cuatro. BatteryInformation Estructura BATTERY_INFORMATION . BatteryManufactureDate Estructura BATTERY_MANUFACTURE_DATE . BatteryManufactureName Cadena Unicode terminada en NULL que contiene el nombre del fabricante de la batería. BatterySerialNumber Cadena Unicode terminada en NULL que contiene el número de serie de la batería. BatteryTemperature ULONG que contiene la temperatura actual de la batería, en 10ths de un grado Kelvin. BatteryUniqueID Cadena Unicode terminada en NULL que identifica de forma única la batería. Este valor se puede usar para realizar un seguimiento de una batería específica. En el caso de las baterías inteligentes, este identificador será la concatenación del nombre del fabricante, el nombre del dispositivo, la fecha de fabricación y una representación imprimible del número de serie. Este valor no está pensado para mostrarse al usuario. -
nOutBufferSize
-
Tamaño del búfer de salida, en bytes. Según el nivel de información de los datos solicitados, puede ser un búfer de tamaño variable.
-
lpBytesReturned
-
Puntero a una variable que recibe el tamaño de los datos devueltos 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.
Cierta información sobre las baterías es opcional o puede no tener sentido para algunas baterías. Si el tipo determinado de datos solicitado no está disponible para la batería actual, se devuelve ERROR_INVALID_FUNCTION .
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 una variedad de información para la batería. La estructura de parámetros de entrada, BATTERY_QUERY_INFORMATION, indica el tipo de información que se va a devolver y cuándo se debe devolver la información de la batería. El tipo de datos y el contenido del búfer de salida varían en función de los datos solicitados.
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 |
|