Power management

Power management

SYNOPSIS

package require twapi

get_device_power_state DEVICEHANDLE

get_power_status

SetThreadExecutionState EXECUTIONSTATE

start_power_monitor SCRIPT

stop_power_monitor POWER_ID

suspend_system ?options?

DESCRIPTION

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

Overview

The command suspend_system may be used to put the system in stand by or hibernate states. You can prevent the system from being suspended due to inactivity through the SetThreadExecutionState command.

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.

SetThreadExecutionState EXECUTIONSTATE

Refer to the Windows SDK documentation for details.

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.

suspend_system ?options?

Places the system in a stand by or hibernate state. The command takes the following options:

-state STATE	STATE must be one of standby (default) or hibernate depending on the state into which the system is to be placed.
-force BOOLEAN	If false (default), the system sends a PBT_ATMQUERYSUSPEND message to all applications before placing the system in stand by or hibernate states. If this option is specified as true, the message is not sent and the system is immediately placed into the appropriate state.
-disablewakeevents BOOLEAN	If false (default), system wake events remain enabled. If true they are disabled.

COPYRIGHT

Copyright © 2008 Ashok P. Nadkarni