1
<?xml version="1.0"?><!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
4
<refentrytitle role="top_of_page">org.freedesktop.UPower</refentrytitle>
7
<refname>org.freedesktop.UPower</refname>
8
<refpurpose>UPower interface</refpurpose>
10
<refsynopsisdiv role="synopsis">
11
<title role="synopsis.title">Methods</title>
12
<synopsis><link linkend="UPower.EnumerateDevices">EnumerateDevices</link> (out 'ao' devices)
13
<link linkend="UPower.AboutToSleep">AboutToSleep</link> ()
14
<link linkend="UPower.Suspend">Suspend</link> ()
15
<link linkend="UPower.SuspendAllowed">SuspendAllowed</link> (out 'b' allowed)
16
<link linkend="UPower.Hibernate">Hibernate</link> ()
17
<link linkend="UPower.HibernateAllowed">HibernateAllowed</link> (out 'b' allowed)
20
<refsect1 role="signal_proto">
21
<title role="signal_proto.title">Signals</title>
22
<synopsis><link linkend="UPower::DeviceAdded">DeviceAdded</link> ('o' device)
23
<link linkend="UPower::DeviceRemoved">DeviceRemoved</link> ('o' device)
24
<link linkend="UPower::DeviceChanged">DeviceChanged</link> ('o' device)
25
<link linkend="UPower::Changed">Changed</link> ()
26
<link linkend="UPower::Sleeping">Sleeping</link> ()
27
<link linkend="UPower::Resuming">Resuming</link> ()
30
<refsect1 role="impl_interfaces">
31
<title role="impl_interfaces.title">Implemented Interfaces</title>
33
Objects implementing org.freedesktop.UPower also implements
34
org.freedesktop.DBus.Introspectable,
35
org.freedesktop.DBus.Properties
38
<refsect1 role="properties">
39
<title role="properties.title">Properties</title>
40
<synopsis><link linkend="UPower:DaemonVersion">'DaemonVersion'</link> read 's'
41
<link linkend="UPower:CanSuspend">'CanSuspend'</link> read 'b'
42
<link linkend="UPower:CanHibernate">'CanHibernate'</link> read 'b'
43
<link linkend="UPower:OnBattery">'OnBattery'</link> read 'b'
44
<link linkend="UPower:OnLowBattery">'OnLowBattery'</link> read 'b'
45
<link linkend="UPower:LidIsClosed">'LidIsClosed'</link> read 'b'
46
<link linkend="UPower:LidIsPresent">'LidIsPresent'</link> read 'b'
49
<refsect1 role="desc">
50
<title role="desc.title">Description</title>
54
The DeviceKit-power service is available via the system message
55
bus. To access the service, use
56
the <literal>org.freedesktop.UPower</literal> interface on
57
the <literal>/org/freedesktop/UPower</literal> object on
58
the D-Bus system bus service with the well-known
59
name <literal>org.freedesktop.UPower</literal>.
64
$ dbus-send --print-reply \
66
--dest=org.freedesktop.UPower \
67
/org/freedesktop/UPower \
68
org.freedesktop.UPower.EnumerateDevices
70
method return sender=:1.386 -> dest=:1.451 reply_serial=2
72
object path "/org/freedesktop/UPower/devices/line_power_AC"
73
object path "/org/freedesktop/UPower/devices/battery_BAT0"
81
<refsect1 role="details"><title role="details.title">Details</title><refsect2><title><anchor role="function" id="UPower.EnumerateDevices"/>EnumerateDevices ()</title><indexterm><primary>EnumerateDevices</primary><secondary>UPower</secondary></indexterm><programlisting>EnumerateDevices (out 'ao' devices)</programlisting></refsect2>
83
Enumerate all power objects on the system.
85
<variablelist role="params"><varlistentry><term><parameter>devices</parameter>:</term><listitem><simpara>An array of object paths for devices.</simpara></listitem></varlistentry></variablelist><refsect2><title><anchor role="function" id="UPower.AboutToSleep"/>AboutToSleep ()</title><indexterm><primary>AboutToSleep</primary><secondary>UPower</secondary></indexterm><programlisting>AboutToSleep ()</programlisting></refsect2>
87
This method tells UPower that the Suspend() or Hibernate() method
88
is about to be called.
89
This allows UPower to emit the Suspending signal whilst
90
session activities are happening that have to be done before the
91
suspend process is started.
94
This method would typically be called by the session power
95
management daemon, before it locks the screen and waits for the
96
screen to fade to black.
97
The session power management component would then call Suspend() or
98
Hibernate() when these syncronous tasks have completed.
101
If this method is not called than nothing bad will happen and
102
Suspend() or Hibernate() will block for the required second.
104
<variablelist role="params"/><refsect2><title><anchor role="function" id="UPower.Suspend"/>Suspend ()</title><indexterm><primary>Suspend</primary><secondary>UPower</secondary></indexterm><programlisting>Suspend ()</programlisting></refsect2>
106
Suspends the computer into a low power state.
107
System state is not preserved if the power is lost.
110
If AboutToRequestSleep() has not been called then UPower will send
111
the Sleeping() signal and block for one second.
114
If AboutToRequestSleep() has been called less than one second
115
before this method is called then UPower will block for the
116
remaining time to complete one second of delay.
118
<variablelist role="params"/><refsect2><title><anchor role="function" id="UPower.SuspendAllowed"/>SuspendAllowed ()</title><indexterm><primary>SuspendAllowed</primary><secondary>UPower</secondary></indexterm><programlisting>SuspendAllowed (out 'b' allowed)</programlisting></refsect2>
120
Check if the caller has (or can get) the PolicyKit privilege to call
121
<link linkend="Power.Suspend"><function>Suspend</function></link>.
123
<variablelist role="params"><varlistentry><term><parameter>allowed</parameter>:</term><listitem><simpara>TRUE if allowed, otherwise FALSE</simpara></listitem></varlistentry></variablelist><refsect2><title><anchor role="function" id="UPower.Hibernate"/>Hibernate ()</title><indexterm><primary>Hibernate</primary><secondary>UPower</secondary></indexterm><programlisting>Hibernate ()</programlisting></refsect2>
125
Hibernates the computer into a low power state.
126
System state is preserved if the power is lost.
129
If AboutToRequestSleep() has not been called then UPower will send
130
the Sleeping() signal and block for one second.
133
If AboutToRequestSleep() has been called less than one second
134
before this method is called then UPower will block for the
135
remaining time to complete one second of delay.
137
<variablelist role="params"/><refsect2><title><anchor role="function" id="UPower.HibernateAllowed"/>HibernateAllowed ()</title><indexterm><primary>HibernateAllowed</primary><secondary>UPower</secondary></indexterm><programlisting>HibernateAllowed (out 'b' allowed)</programlisting></refsect2>
139
Check if the caller has (or can get) the PolicyKit privilege to call
140
<link linkend="Power.Hibernate"><function>Hibernate</function></link>.
142
<variablelist role="params"><varlistentry><term><parameter>allowed</parameter>:</term><listitem><simpara>TRUE if allowed, otherwise FALSE</simpara></listitem></varlistentry></variablelist></refsect1>
143
<refsect1 role="signals"><title role="signals.title">Signal Details</title><refsect2><title><anchor role="function" id="UPower::DeviceAdded"/>The DeviceAdded signal</title><indexterm><primary>DeviceAdded</primary><secondary>UPower</secondary></indexterm><programlisting>DeviceAdded ('o' device)</programlisting></refsect2>
145
Emitted when a device is added.
147
<variablelist role="params"><varlistentry><term><parameter>device</parameter>:</term><listitem><simpara>Object path of device that was added.</simpara></listitem></varlistentry></variablelist><refsect2><title><anchor role="function" id="UPower::DeviceRemoved"/>The DeviceRemoved signal</title><indexterm><primary>DeviceRemoved</primary><secondary>UPower</secondary></indexterm><programlisting>DeviceRemoved ('o' device)</programlisting></refsect2>
149
Emitted when a device is removed.
151
<variablelist role="params"><varlistentry><term><parameter>device</parameter>:</term><listitem><simpara>Object path of device that was removed.</simpara></listitem></varlistentry></variablelist><refsect2><title><anchor role="function" id="UPower::DeviceChanged"/>The DeviceChanged signal</title><indexterm><primary>DeviceChanged</primary><secondary>UPower</secondary></indexterm><programlisting>DeviceChanged ('o' device)</programlisting></refsect2>
153
Emitted when a device changed.
155
<variablelist role="params"><varlistentry><term><parameter>device</parameter>:</term><listitem><simpara>Object path of device that was changed.</simpara></listitem></varlistentry></variablelist><refsect2><title><anchor role="function" id="UPower::Changed"/>The Changed signal</title><indexterm><primary>Changed</primary><secondary>UPower</secondary></indexterm><programlisting>Changed ()</programlisting></refsect2>
157
Emitted when one or more properties on the object changes.
159
<variablelist role="params"/><refsect2><title><anchor role="function" id="UPower::Sleeping"/>The Sleeping signal</title><indexterm><primary>Sleeping</primary><secondary>UPower</secondary></indexterm><programlisting>Sleeping ()</programlisting></refsect2>
161
This signal is sent when the session is about to be suspended or
163
Session and system programs have one second to do anything required
164
before the sleep action is taken (such as sending out Avahi or
167
<variablelist role="params"/><refsect2><title><anchor role="function" id="UPower::Resuming"/>The Resuming signal</title><indexterm><primary>Resuming</primary><secondary>UPower</secondary></indexterm><programlisting>Resuming ()</programlisting></refsect2>
169
This signal is sent when the session has just returned from
170
Suspend() or Hibernate().
171
Session and system programs can then do anything required (such as
172
sending out Avahi or Jabber messages).
174
<variablelist role="params"/></refsect1>
175
<refsect1 role="property_details"><title role="property_details.title">Property Details</title><refsect2><title><anchor role="function" id="UPower:DaemonVersion"/>The "DaemonVersion" property</title><indexterm><primary>DaemonVersion</primary><secondary>UPower</secondary></indexterm><programlisting>'DaemonVersion' read 's'
176
</programlisting></refsect2><para>
177
Version of the running daemon, e.g. <literal>002</literal>.
178
</para><variablelist role="params"/><refsect2><title><anchor role="function" id="UPower:CanSuspend"/>The "CanSuspend" property</title><indexterm><primary>CanSuspend</primary><secondary>UPower</secondary></indexterm><programlisting>'CanSuspend' read 'b'
179
</programlisting></refsect2><para>
180
Whether the system is able to suspend.
181
</para><variablelist role="params"/><refsect2><title><anchor role="function" id="UPower:CanHibernate"/>The "CanHibernate" property</title><indexterm><primary>CanHibernate</primary><secondary>UPower</secondary></indexterm><programlisting>'CanHibernate' read 'b'
182
</programlisting></refsect2><para>
183
Whether the system is able to hibernate.
184
</para><variablelist role="params"/><refsect2><title><anchor role="function" id="UPower:OnBattery"/>The "OnBattery" property</title><indexterm><primary>OnBattery</primary><secondary>UPower</secondary></indexterm><programlisting>'OnBattery' read 'b'
185
</programlisting></refsect2><para>
186
Indicates whether the system is running on battery power.
187
This property is provided for convenience.
188
</para><variablelist role="params"/><refsect2><title><anchor role="function" id="UPower:OnLowBattery"/>The "OnLowBattery" property</title><indexterm><primary>OnLowBattery</primary><secondary>UPower</secondary></indexterm><programlisting>'OnLowBattery' read 'b'
189
</programlisting></refsect2><para>
190
Indicates whether the system is running on battery power and if the battery is critically low.
191
This property is provided for convenience.
192
</para><variablelist role="params"/><refsect2><title><anchor role="function" id="UPower:LidIsClosed"/>The "LidIsClosed" property</title><indexterm><primary>LidIsClosed</primary><secondary>UPower</secondary></indexterm><programlisting>'LidIsClosed' read 'b'
193
</programlisting></refsect2>
195
Indicates if the laptop lid is closed where the display cannot be seen.
197
<variablelist role="params"/><refsect2><title><anchor role="function" id="UPower:LidIsPresent"/>The "LidIsPresent" property</title><indexterm><primary>LidIsPresent</primary><secondary>UPower</secondary></indexterm><programlisting>'LidIsPresent' read 'b'
198
</programlisting></refsect2>
200
If the system has a lid device.
202
<variablelist role="params"/></refsect1>