Power management

Power management

SYNOPSIS

package require twapi_power
get_device_power_state DEVICEHANDLE
get_power_status
start_power_monitor SCRIPT
stop_power_monitor POWER_ID

DESCRIPTION

This module provides commands related to power management in a Windows system.

Overview

The current state of the power subsystem, including battery status, can be obtained through the get_power_status command. The state of an individual device can be obtained through the get_device_power_state command.

Changes in the power subsystem state can be monitored through the start_power_monitor and stop_power_monitor.

Commands

get_device_power_state DEVICEHANDLE
Returns 1 if the device indicated by DEVICEHANDLE is fully powered up and 0 if it is in a low-power state. DEVICEHANDLE is a handle to the device or to an object on the device. For example, it can be the handle returned by a get_tcl_channel_handle command corresponding to a Tcl file handle.

DEVICEHANDLE must not be a handle to a display device.
get_power_status
Returns a keyed list containing information about the state of the power system. The list includes the fields in the table below.
-acstatus Indicates the state of the AC power. May have the values on, off or unknown.
-batterystate Indicates the state of the battery charge. May be notpresent, critical, low, high or unknown.
-batterycharging Indicates whether the battery is being charged. May have the values true, false or unknown.
-batterylifepercent Indicates the percentage of the full battery life remaining or has the value unknown.
-batterylifetime Indicates the remaining battery life time in seconds, if known, or has the value unknown.
-batteryfulllifetime Indicates the number of seconds of battery life when it is full, or has the value unknown.
start_power_monitor SCRIPT
Begins monitoring of power state changes. SCRIPT will be invoked when the state of the power subsystem changes, for example, when the system switches to battery power.

The command returns a handle. When no longer required, this handle must be passed to the command stop_power_monitor.

Multiple monitoring scripts may be active at the same time. However, all returned handles must be passed to stop_power_monitor. before the application exits.

The callback script is invoked with two additional arguments. The first argument indicates the type of event and has one of the values in the table below.
apmbatterylow Indicates that the system battery is low.
apmoemevent Indicates an OEM-defined event.
apmpowerstatuschange Indicates a change in the power status. Details may be obtained by calling get_power_status.
apmquerysuspendfailed Indicates that a query to suspend the computer was denied.
apmresumeautomatic Indicates that the system has woken up to handle an event.
apmresumecritical Indicates the system has woken up after a critical system suspension (e.g. due to very low battery) where it was not possible to notify all applications before the suspension.
apmresumesuspend Indicates that the system has resumed normal operation after a suspension.
apmsuspend Indicates the system is about to be suspended and applications should save state and data if necessary.
The callback may be invoked with other values for the event indicator. These should be ignored.

The second argument passed to the callback is only meaningful when the event is apmoemevent. The value of the argument is an OEM-defined event code.

This command requires a threaded build of Tcl and will raise an exception on non-threaded builds.
stop_power_monitor POWER_ID
Stops a previously registered script that monitors the power subsystem. POWER_ID is monitoring handle previously returned by start_power_monitor.

COPYRIGHT

Copyright © 2008 Ashok P. Nadkarni

Tcl Windows API 4.2a5