4
4
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
5
<title>org.freedesktop.UPower</title>
5
<title>UPower Reference Manual: org.freedesktop.UPower</title>
6
6
<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
7
7
<link rel="home" href="index.html" title="UPower Reference Manual">
8
8
<link rel="up" href="ref-dbus.html" title="D-Bus API Reference">
9
9
<link rel="prev" href="ref-dbus.html" title="D-Bus API Reference">
10
10
<link rel="next" href="Device.html" title="org.freedesktop.UPower.Device">
11
<meta name="generator" content="GTK-Doc V1.19 (XML mode)">
11
<meta name="generator" content="GTK-Doc V1.19.1 (XML mode)">
12
12
<link rel="stylesheet" href="style.css" type="text/css">
14
14
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
15
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
17
<td><a accesskey="p" href="ref-dbus.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
18
<td><a accesskey="u" href="ref-dbus.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
19
<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
20
<th width="100%" align="center">UPower Reference Manual</th>
21
<td><a accesskey="n" href="Device.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
23
<tr><td colspan="5" class="shortcuts">
24
<a href="#UPower.synopsis" class="shortcut">Top</a>
15
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="10"><tr valign="middle">
16
<td width="100%" align="left">
17
<a href="#" class="shortcut">Top</a>
26
19
<a href="#UPower.description" class="shortcut">Description</a>
30
23
<a href="#UPower.properties" class="shortcut">Properties</a>
32
25
<a href="#UPower.signals" class="shortcut">Signals</a>
27
<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
28
<td><a accesskey="u" href="ref-dbus.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
29
<td><a accesskey="p" href="ref-dbus.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
30
<td><a accesskey="n" href="Device.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
35
32
<div class="refentry">
36
33
<a name="UPower"></a><div class="titlepage"></div>
37
34
<div class="refnamediv"><table width="100%"><tr>
44
41
<div class="refsynopsisdiv">
46
43
<pre class="synopsis"><a class="link" href="UPower.html#UPower.EnumerateDevices">EnumerateDevices</a>(out'ao'devices)
47
<a class="link" href="UPower.html#UPower.AboutToSleep">AboutToSleep</a>(in's'action)
48
<a class="link" href="UPower.html#UPower.Suspend">Suspend</a>()
49
<a class="link" href="UPower.html#UPower.SuspendAllowed">SuspendAllowed</a>(out'b'allowed)
50
<a class="link" href="UPower.html#UPower.Hibernate">Hibernate</a>()
51
<a class="link" href="UPower.html#UPower.HibernateAllowed">HibernateAllowed</a>(out'b'allowed)
44
<a class="link" href="UPower.html#UPower.GetDisplayDevice">GetDisplayDevice</a>(out'o'device)
45
<a class="link" href="UPower.html#UPower.GetCriticalAction">GetCriticalAction</a>(out's'action)
54
48
<div class="refsect1">
55
49
<a name="id-1.2.3.4"></a><h2>Signals</h2>
56
50
<pre class="synopsis"><a class="link" href="UPower.html#UPower::DeviceAdded">DeviceAdded</a>('o'device)
57
51
<a class="link" href="UPower.html#UPower::DeviceRemoved">DeviceRemoved</a>('o'device)
58
<a class="link" href="UPower.html#UPower::DeviceChanged">DeviceChanged</a>('o'device)
59
<a class="link" href="UPower.html#UPower::Changed">Changed</a>()
60
<a class="link" href="UPower.html#UPower::Sleeping">Sleeping</a>()
61
<a class="link" href="UPower.html#UPower::NotifySleep">NotifySleep</a>('s'action)
62
<a class="link" href="UPower.html#UPower::Resuming">Resuming</a>()
63
<a class="link" href="UPower.html#UPower::NotifyResume">NotifyResume</a>('s'action)
66
54
<div class="refsect1">
74
62
<div class="refsect1">
75
63
<a name="id-1.2.3.6"></a><h2>Properties</h2>
76
64
<pre class="synopsis"><a class="link" href="UPower.html#UPower:DaemonVersion">'DaemonVersion'</a>read's'
77
<a class="link" href="UPower.html#UPower:CanSuspend">'CanSuspend'</a>read'b'
78
<a class="link" href="UPower.html#UPower:CanHibernate">'CanHibernate'</a>read'b'
79
65
<a class="link" href="UPower.html#UPower:OnBattery">'OnBattery'</a>read'b'
80
<a class="link" href="UPower.html#UPower:OnLowBattery">'OnLowBattery'</a>read'b'
81
66
<a class="link" href="UPower.html#UPower:LidIsClosed">'LidIsClosed'</a>read'b'
82
67
<a class="link" href="UPower.html#UPower:LidIsPresent">'LidIsPresent'</a>read'b'
83
<a class="link" href="UPower.html#UPower:LidForceSleep">'LidForceSleep'</a>read'b'
84
68
<a class="link" href="UPower.html#UPower:IsDocked">'IsDocked'</a>read'b'
162
146
<div class="refsect2">
163
147
<a name="id-1.2.3.8.5"></a><h3>
164
<a name="UPower.AboutToSleep"></a>AboutToSleep ()</h3>
165
<pre class="programlisting">AboutToSleep (in's'action)</pre>
168
This method tells UPower that the Suspend() or Hibernate() method
169
is about to be called.
170
This allows UPower to emit the Suspending signal whilst
171
session activities are happening that have to be done before the
172
suspend process is started.
175
This method would typically be called by the session power
176
management daemon, before it locks the screen and waits for the
177
screen to fade to black.
178
The session power management component would then call Suspend() or
179
Hibernate() when these syncronous tasks have completed.
182
If this method is not called than nothing bad will happen and
183
Suspend() or Hibernate() will block for the required second.
148
<a name="UPower.GetDisplayDevice"></a>GetDisplayDevice ()</h3>
149
<pre class="programlisting">GetDisplayDevice (out'o'device)</pre>
152
Get the object to the "display device", a composite device that represents the
153
status icon to show in desktop environments. You can also access the object directly
154
as its path is guaranteed to be /org/freedesktop/UPower/devices/DisplayDevice.
155
The following standard org.freedesktop.UPower.Device
156
properties will be defined (only <code class="literal">IsPresent</code> takes a special meaning):
158
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
159
<li class="listitem">
160
<span class="bold"><strong>Type: </strong></span>the type of the display device, UPS or Battery. Note that this value can change, as opposed to real devices.</li>
161
<li class="listitem">
162
<span class="bold"><strong>State: </strong></span>the power state of the display device, such as Charging or Discharging.</li>
163
<li class="listitem">
164
<span class="bold"><strong>Percentage: </strong></span>the amount of energy left on the device.</li>
165
<li class="listitem">
166
<span class="bold"><strong>Energy: </strong></span>Amount of energy (measured in Wh) currently available in the power source.</li>
167
<li class="listitem">
168
<span class="bold"><strong>EnergyFull: </strong></span>Amount of energy (measured in Wh) in the power source when it's considered full.</li>
169
<li class="listitem">
170
<span class="bold"><strong>EnergyRate: </strong></span>Amount of energy being drained from the source, measured in W. If positive, the source is being discharged, if negative it's being charged.</li>
171
<li class="listitem">
172
<span class="bold"><strong>TimeToEmpty: </strong></span>Number of seconds until the power source is considered empty.</li>
173
<li class="listitem">
174
<span class="bold"><strong>TimeToFull: </strong></span>Number of seconds until the power source is considered full.</li>
175
<li class="listitem">
176
<span class="bold"><strong>IsPresent: </strong></span>Whether a status icon using this information should be presented.</li>
177
<li class="listitem">
178
<span class="bold"><strong>IconName: </strong></span>An icon name representing the device state.</li>
179
<li class="listitem">
180
<span class="bold"><strong>WarningLevel: </strong></span>The same as the overall <code class="literal">WarningLevel</code>
185
<div class="variablelist"><table border="0" class="variablelist">
187
<col align="left" valign="top">
191
<td><p><span class="term"><em class="parameter"><code>device</code></em>:</span></p></td>
192
<td>An object path for the "display device.</td>
196
<div class="refsect2">
197
<a name="id-1.2.3.8.8"></a><h3>
198
<a name="UPower.GetCriticalAction"></a>GetCriticalAction ()</h3>
199
<pre class="programlisting">GetCriticalAction (out's'action)</pre>
202
When the system's power supply is critical (critically low batteries or UPS),
203
the system will take this action. Possible values are:
205
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
206
<li class="listitem"><span class="bold"><strong>HybridSleep: </strong></span></li>
207
<li class="listitem"><span class="bold"><strong>Hibernate: </strong></span></li>
208
<li class="listitem"><span class="bold"><strong>PowerOff: </strong></span></li>
185
212
<div class="variablelist"><table border="0" class="variablelist">
191
218
<td><p><span class="term"><em class="parameter"><code>action</code></em>:</span></p></td>
193
The sleep action type, e.g. <code class="literal">suspend</code> or
194
<code class="literal">hibernate</code>.
199
<div class="refsect2">
200
<a name="id-1.2.3.8.10"></a><h3>
201
<a name="UPower.Suspend"></a>Suspend ()</h3>
202
<pre class="programlisting">Suspend ()</pre>
205
Suspends the computer into a low power state.
206
System state is not preserved if the power is lost.
209
If AboutToSleep() has not been called then UPower will send
210
the Sleeping() signal and block for one second.
213
If AboutToSleep() has been called less than one second
214
before this method is called then UPower will block for the
215
remaining time to complete one second of delay.
217
<div class="variablelist"><table border="0" class="variablelist">
219
<col align="left" valign="top">
225
<div class="refsect2">
226
<a name="id-1.2.3.8.15"></a><h3>
227
<a name="UPower.SuspendAllowed"></a>SuspendAllowed ()</h3>
228
<pre class="programlisting">SuspendAllowed (out'b'allowed)</pre>
231
Check if the caller has (or can get) the PolicyKit privilege to call
232
<code class="function">Suspend</code>.
234
<div class="variablelist"><table border="0" class="variablelist">
236
<col align="left" valign="top">
240
<td><p><span class="term"><em class="parameter"><code>allowed</code></em>:</span></p></td>
241
<td>TRUE if allowed, otherwise FALSE</td>
245
<div class="refsect2">
246
<a name="id-1.2.3.8.18"></a><h3>
247
<a name="UPower.Hibernate"></a>Hibernate ()</h3>
248
<pre class="programlisting">Hibernate ()</pre>
251
Hibernates the computer into a low power state.
252
System state is preserved if the power is lost.
255
If AboutToSleep() has not been called then UPower will send
256
the Sleeping() signal and block for one second.
259
If AboutToSleep() has been called less than one second
260
before this method is called then UPower will block for the
261
remaining time to complete one second of delay.
263
<div class="variablelist"><table border="0" class="variablelist">
265
<col align="left" valign="top">
271
<div class="refsect2">
272
<a name="id-1.2.3.8.23"></a><h3>
273
<a name="UPower.HibernateAllowed"></a>HibernateAllowed ()</h3>
274
<pre class="programlisting">HibernateAllowed (out'b'allowed)</pre>
277
Check if the caller has (or can get) the PolicyKit privilege to call
278
<code class="function">Hibernate</code>.
280
<div class="variablelist"><table border="0" class="variablelist">
282
<col align="left" valign="top">
286
<td><p><span class="term"><em class="parameter"><code>allowed</code></em>:</span></p></td>
287
<td>TRUE if allowed, otherwise FALSE</td>
219
<td>A string representing the critical action configured and available.</td>
327
259
<td>Object path of device that was removed.</td>
331
<div class="refsect2">
332
<a name="id-1.2.3.9.8"></a><h3>
333
<a name="UPower::DeviceChanged"></a>The DeviceChanged signal</h3>
334
<pre class="programlisting">DeviceChanged ('o'device)</pre>
337
Emitted when a device changed.
339
<div class="variablelist"><table border="0" class="variablelist">
341
<col align="left" valign="top">
345
<td><p><span class="term"><em class="parameter"><code>device</code></em>:</span></p></td>
346
<td>Object path of device that was changed.</td>
350
<div class="refsect2">
351
<a name="id-1.2.3.9.11"></a><h3>
352
<a name="UPower::Changed"></a>The Changed signal</h3>
353
<pre class="programlisting">Changed ()</pre>
356
Emitted when one or more properties on the object changes.
358
<div class="variablelist"><table border="0" class="variablelist">
360
<col align="left" valign="top">
366
<div class="refsect2">
367
<a name="id-1.2.3.9.14"></a><h3>
368
<a name="UPower::Sleeping"></a>The Sleeping signal</h3>
369
<pre class="programlisting">Sleeping ()</pre>
372
This signal is sent when the session is about to be suspended or
376
This signal is DEPRECATED. Use NotifySleep() instead.
378
<div class="variablelist"><table border="0" class="variablelist">
380
<col align="left" valign="top">
386
<div class="refsect2">
387
<a name="id-1.2.3.9.18"></a><h3>
388
<a name="UPower::NotifySleep"></a>The NotifySleep signal</h3>
389
<pre class="programlisting">NotifySleep ('s'action)</pre>
392
This signal is sent when the session is about to be suspended or
394
Session and system programs have one second to do anything required
395
before the sleep action is taken (such as sending out Avahi or
398
<div class="variablelist"><table border="0" class="variablelist">
400
<col align="left" valign="top">
404
<td><p><span class="term"><em class="parameter"><code>action</code></em>:</span></p></td>
406
The sleep action type, e.g. suspend,
412
<div class="refsect2">
413
<a name="id-1.2.3.9.21"></a><h3>
414
<a name="UPower::Resuming"></a>The Resuming signal</h3>
415
<pre class="programlisting">Resuming ()</pre>
418
This signal is sent when the session has just returned from
419
Suspend() or Hibernate().
422
This signal is DEPRECATED. Use NotifyResume() instead.
424
<div class="variablelist"><table border="0" class="variablelist">
426
<col align="left" valign="top">
432
<div class="refsect2">
433
<a name="id-1.2.3.9.25"></a><h3>
434
<a name="UPower::NotifyResume"></a>The NotifyResume signal</h3>
435
<pre class="programlisting">NotifyResume ('s'action)</pre>
438
This signal is sent when the session has just returned from
439
Suspend() or Hibernate().
440
Session and system programs can then do anything required (such as
441
sending out Avahi or Jabber messages).
443
<div class="variablelist"><table border="0" class="variablelist">
445
<col align="left" valign="top">
449
<td><p><span class="term"><em class="parameter"><code>action</code></em>:</span></p></td>
451
The sleep action type, e.g. suspend,
457
263
<div class="refsect1">
458
264
<a name="id-1.2.3.10"></a><h2>Property Details</h2>
476
282
<div class="refsect2">
477
283
<a name="id-1.2.3.10.5"></a><h3>
478
<a name="UPower:CanSuspend"></a>The "CanSuspend" property</h3>
479
<pre class="programlisting">'CanSuspend'read'b'
483
Whether the system is able to suspend.
485
<div class="variablelist"><table border="0" class="variablelist">
487
<col align="left" valign="top">
493
<div class="refsect2">
494
<a name="id-1.2.3.10.8"></a><h3>
495
<a name="UPower:CanHibernate"></a>The "CanHibernate" property</h3>
496
<pre class="programlisting">'CanHibernate'read'b'
500
Whether the system is able to hibernate.
502
<div class="variablelist"><table border="0" class="variablelist">
504
<col align="left" valign="top">
510
<div class="refsect2">
511
<a name="id-1.2.3.10.11"></a><h3>
512
284
<a name="UPower:OnBattery"></a>The "OnBattery" property</h3>
513
285
<pre class="programlisting">'OnBattery'read'b'
528
300
<div class="refsect2">
529
<a name="id-1.2.3.10.14"></a><h3>
530
<a name="UPower:OnLowBattery"></a>The "OnLowBattery" property</h3>
531
<pre class="programlisting">'OnLowBattery'read'b'
535
Indicates whether the system is running on battery power and if the battery is critically low.
536
This property is provided for convenience.
538
<div class="variablelist"><table border="0" class="variablelist">
540
<col align="left" valign="top">
546
<div class="refsect2">
547
<a name="id-1.2.3.10.17"></a><h3>
301
<a name="id-1.2.3.10.8"></a><h3>
548
302
<a name="UPower:LidIsClosed"></a>The "LidIsClosed" property</h3>
549
303
<pre class="programlisting">'LidIsClosed'read'b'
580
334
<div class="refsect2">
581
<a name="id-1.2.3.10.23"></a><h3>
582
<a name="UPower:LidForceSleep"></a>The "LidForceSleep" property</h3>
583
<pre class="programlisting">'LidForceSleep'read'b'
587
If the system really has to sleep when the lid is closed.
588
Some laptops actually melt (!) if the lid is closed and the
589
computer keeps running. We blacklist those, and do something
590
sane for the other machines.
593
This allows us to set the default session policy to not
594
suspend on lid close if the laptop is docked, and be sure
595
the machine is not going to melt.
597
<div class="variablelist"><table border="0" class="variablelist">
599
<col align="left" valign="top">
605
<div class="refsect2">
606
<a name="id-1.2.3.10.27"></a><h3>
335
<a name="id-1.2.3.10.14"></a><h3>
607
336
<a name="UPower:IsDocked"></a>The "IsDocked" property</h3>
608
337
<pre class="programlisting">'IsDocked'read'b'
added
removed
doc/html/UPower.html
