summaryrefslogtreecommitdiffstats
path: root/idle-inhibit/specification.xml
blob: 0e70b23e97cec545ca134ef7c2830190e1d4468d (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
]>
<book xml:id="index" xmlns="http://docbook.org/ns/docbook">
	<bookinfo>
		<title>Idle Inhibition Service Draft</title>
		<releaseinfo>
			Idle Inhibition Service 0.1 DRAFT
		</releaseinfo>

		<authorgroup>
		<author>
			<firstname>Bastien</firstname>
			<surname>Nocera</surname>
			<affiliation>
				<jobtitle>GNOME core Developer</jobtitle>
				<address>
					<email>hadess@hadess.net</email>
				</address>
			</affiliation>
		</author>
		</authorgroup>

		<copyright>
			<year>2012</year>
			<holder>The Idle Inhibition Service API Authors</holder>
		</copyright>

	</bookinfo>

	<part id="description">
		<title>API Documentation</title>
		<chapter id="introduction">
			<title>Introduction</title>

			<para>The Idle Inhibition Service API allows client applications to inhibit a
				user's login session from becoming idle.</para>

			<para>The service is usually implemented by the session manager, or another daemon
			running inside the user's session, and communicating with the platform software
			to avoid becoming idle, and the consequences of becoming idle.</para>

			<para>This API was designed by GNOME and KDE developers with the goal of having
			a common way to inhibit idleness.</para>
		</chapter>

		<chapter id="consequences">
			<title>Consequences of idleness</title>

			<para>Depending on the user session software running, idleness can have multiple
			  consequences, including, but not limited to:
			<itemizedlist>
			  <listitem><para>Screen backlight dimming</para></listitem>
			  <listitem><para>Screensaver animation replacing the desktop content</para></listitem>
			  <listitem><para>Instant messenging client going to "auto-away"</para></listitem>
			  <listitem><para>Computer suspending or hibernating</para></listitem>
			</itemizedlist>
			</para>

			<para>Inhibiting idleness is supposed to stop all those actions from taking place, specifically
			in response to idleness. A user action asking for any of those states would obviously
			be acted upon witout delay.</para>

		</chapter>

		<chapter id='api'>
			<title>API overview</title>

			<para>Idle inhibition is achieved by the application calling an
			<link linkend="org.freedesktop.ScreenSaver.Inhibit"><function>Inhibit</function></link>
			method on a well-known D-Bus name.</para>

			<para>Inhibition will stop when the <link linkend="org.freedesktop.ScreenSaver.UnInhibit"><function>
			UnInhibit</function></link> method is called, or the application disconnects from the D-Bus
			session bus (which usually happens upon exit).</para>

			<para>Implementations of this well-known bus name must have an object
			/org/freedesktop/ScreenSaver which implements the
			<link linkend='org.freedesktop.ScreenSaver'>org.freedesktop.ScreenSaver</link> interface.
			</para>

		</chapter>

		<chapter>
			<title>Design notes</title>

			<para>The D-Bus service name, org.freedesktop.ScreenSaver, intentionally contains
			the word screensaver, as KDE implements the idle inhibition API in a screensaver
			sub-module. It was necessary for the specificed Idle Inhibition Service API to be
			compatible with this existing software.</para>

			<para>KDE's implementation until kde-workspace 4.11.8 lived on the
			/ScreenSaver object, not on /org/freedesktop/ScreenSaver as described in
			this specification. This is fixed in later releases.</para>

			<para>For the same reasons, inhibition of suspend, hibernation, or user-switching (amongst
			others) is not supported in the API.</para>
		</chapter>

	</part>

	<part id="ref-dbus-api">
		<title>D-Bus API Reference</title>

		<xi:include href="reference.xml" xpointer="interfaces" xmlns:xi="http://www.w3.org/2001/XInclude">
			<xi:fallback/>
		</xi:include>

	</part>

	<part>
		<title>References</title>
		<chapter>
		<title>References</title>
		<variablelist>
			<varlistentry>
				<term>kde-api</term>
				<listitem>
					<para>
						<ulink url="https://projects.kde.org/projects/kde/kde-workspace/repository/revisions/master/entry/ksmserver/screenlocker/dbus/org.freedesktop.ScreenSaver.xml">KDE Screenlocker D-Bus API</ulink>
					</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>gnome-impl</term>
				<listitem>
					<para>
						<ulink url="http://git.gnome.org/browse/gnome-settings-daemon/tree/plugins/screensaver-proxy">GNOME org.freedesktop.ScreenSaver proxy implementation</ulink>
					</para>
				</listitem>
			</varlistentry>
		</variablelist>
		</chapter>
	</part>

</book>