From 806462d8f6c3a2c0fac3488e94763e46ecef896c Mon Sep 17 00:00:00 2001 From: Bastien Nocera Date: Fri, 7 Dec 2012 16:42:54 +0100 Subject: Add idle-inhibit D-Bus service spec --- idle-inhibit/.gitignore | 3 + idle-inhibit/Makefile | 17 + idle-inhibit/README | 20 + idle-inhibit/docbook-params.xsl | 39 + idle-inhibit/html/style.css | 127 +++ idle-inhibit/org.freedesktop.ScreenSaver.xml | 38 + idle-inhibit/specification.xml | 114 +++ idle-inhibit/tools/resolve-type.xsl | 122 +++ idle-inhibit/tools/spec-to-docbook.xsl | 1242 ++++++++++++++++++++++++++ idle-inhibit/tools/spec-to-introspect.xsl | 144 +++ 10 files changed, 1866 insertions(+) create mode 100644 idle-inhibit/.gitignore create mode 100644 idle-inhibit/Makefile create mode 100644 idle-inhibit/README create mode 100644 idle-inhibit/docbook-params.xsl create mode 100644 idle-inhibit/html/style.css create mode 100644 idle-inhibit/org.freedesktop.ScreenSaver.xml create mode 100644 idle-inhibit/specification.xml create mode 100644 idle-inhibit/tools/resolve-type.xsl create mode 100644 idle-inhibit/tools/spec-to-docbook.xsl create mode 100644 idle-inhibit/tools/spec-to-introspect.xsl diff --git a/idle-inhibit/.gitignore b/idle-inhibit/.gitignore new file mode 100644 index 0000000..551e415 --- /dev/null +++ b/idle-inhibit/.gitignore @@ -0,0 +1,3 @@ + +/html/*.html +reference.xml diff --git a/idle-inhibit/Makefile b/idle-inhibit/Makefile new file mode 100644 index 0000000..8c651ba --- /dev/null +++ b/idle-inhibit/Makefile @@ -0,0 +1,17 @@ + +SPEC = org.freedesktop.ScreenSaver.xml + +all: html/index.html + +html/index.html: reference.xml docbook-params.xsl specification.xml + xmlto --skip-validation -o html/ -x docbook-params.xsl xhtml specification.xml + +reference.xml: tools/spec-to-docbook.xsl $(SPEC) + xsltproc tools/spec-to-docbook.xsl $(SPEC) > $@ + +clean: + rm -f reference.xml + rm -f html/*.html + +upload: all + rsync -Hvax html/./ specs.freedesktop.org:/srv/specifications.freedesktop.org/www/idle-inhibition-service/./ diff --git a/idle-inhibit/README b/idle-inhibit/README new file mode 100644 index 0000000..72a9997 --- /dev/null +++ b/idle-inhibit/README @@ -0,0 +1,20 @@ +Generating the specification consists of separate steps: + +1. Use an xslt processor to create a DocBook XML document from the Telepathy + Introspection document using the provided stylesheet: + +$ xsltproc tools/spec-to-docbook.xsl \ + org.freedesktop.Secrets.xml >reference.xml + +2. Convert specification.xml and reference.xml to a suitable output format + (specification.xml includes reference.xml), eg html: + +$ xmlto --skip-validation -o html -p params-html.xsl xhtml specification.xml + +If you choose a different directory for html generation, be sure to copy +html/style.css to that location. + +Then open the resulting html/index.html in your favourite browser. + + +Michael Leupold diff --git a/idle-inhibit/docbook-params.xsl b/idle-inhibit/docbook-params.xsl new file mode 100644 index 0000000..5d8591a --- /dev/null +++ b/idle-inhibit/docbook-params.xsl @@ -0,0 +1,39 @@ + + + + + + + + 3 + 0 + + book toc + part nop + chapter toc + + style.css + ansi + 1 + 0 + 1 + + diff --git a/idle-inhibit/html/style.css b/idle-inhibit/html/style.css new file mode 100644 index 0000000..f8a03b0 --- /dev/null +++ b/idle-inhibit/html/style.css @@ -0,0 +1,127 @@ +/* reference.css, a stylesheet for reference documentation + * generated by the DocBook XSL Stylesheets */ +/* $Id: reference.css 8234 2009-02-09 12:10:48Z xmldoc $ */ + +div.legalnotice { + font-size: 80%; +} + +div.note, div.tip, div.warning { + margin-left: 5%; + margin-right: 10%; + padding: 5px; +} + +div.note, div.tip { + border-left: solid #d5dee3 20px; + border-right: solid #d5dee3 20px; +} + +div.note, div.tip { + border-left: solid palegreen 20px; + border-right: solid palegreen 20px; +} + +div.warning { + border-left: solid yellow 20px; + border-right: solid yellow 20px; +} + +div.note p, div.tip p, div.warning p { + margin-top: 0px; + margin-bottom: 4px; +} + +div.note h3, div.tip h3, div.warning h3 { + margin-top: 0; +} + +div.informalexample { + background-color: #d5dee3; + border-top-width: 2px; + border-top-style: double; + border-top-color: #d3d3d3; + border-bottom-width: 2px; + border-bottom-style: double; + border-bottom-color: #d3d3d3; + padding: 4px; + margin: 0em; + margin-left: 2em; +} + +pre.programlisting, pre.synopsis { + whitespace: pre; + font-family: monospace; + background-color: #d5dee3; + border-top-width: 1px; + border-top-style: single; + border-top-color: #d3d3d3; + border-bottom-width: 1px; + border-bottom-style: single; + border-bottom-color: #d3d3d3; + padding: 4px; + margin: 0em; + margin-top: 6px; + margin-bottom: 6px; +} + +div.informalexample pre { + whitespace: pre; + font-family: monospace; + border-top-width: 0px; + border-bottom-width: 0px; + padding: 0px; +} + +/* Parameter and PI titles */ + div.refnamediv h2 { + font-size: 2em; +} + +div.funcsynopsis, code.fieldsynopsis, +div.refsect2 div.refsynopsisdiv { + padding: 0.5em; + background-color: #F4F4F4; + border: 1px solid gray; + display: block; + width: 80%; +} + +div.refsynopsisdiv code.fieldsynopsis { + padding: 0; + border: 0; +} + +code.fieldsynopsis span.modifier { + min-width: 8em; + display: inline-block; +} + +code.fieldsynopsis span.type { + min-width: 11em; + display: inline-block; +} + +code.fieldsynopsis span.varname { + min-width: 11em; + display: inline-block; + font-size: 1.1em; + font-weight: bold; +} + +div.funcprototype-spacer { + max-height: 0.5em; +} + +table.funcprototype-table * td { + font-size: 0.9em; +} + +table.funcprototype-table * td code.funcdef { + font-size: 1.1em; +} + +b.fsfunc { + display: inline-block; + min-width: 11em; +} \ No newline at end of file diff --git a/idle-inhibit/org.freedesktop.ScreenSaver.xml b/idle-inhibit/org.freedesktop.ScreenSaver.xml new file mode 100644 index 0000000..23278ad --- /dev/null +++ b/idle-inhibit/org.freedesktop.ScreenSaver.xml @@ -0,0 +1,38 @@ + + + Idle Inhibition Service API Specification + 0.1 + + Copyright (C) 2012 Bastien Nocera <hadess@hadess.net> + + + + + The Idle Inhibition Service manages the inhibition requests. + + + + Inhibit idleness for the caller application. + + + A unique identifier for the application, usually a reverse domain (such as 'org.freedesktop.example'). + + + + A human-readable and possibly translated string explaining the reason why idleness is inhibited (such as 'Playing a movie'). + + + + A cookie uniquely representing the inhibition request, to be passed to UnInhibit when done. + + + + Disable inhibit idleness for the caller application. + + + A cookie representing the inhibition request, as returned by the 'Inhibit' function. + + + + + diff --git a/idle-inhibit/specification.xml b/idle-inhibit/specification.xml new file mode 100644 index 0000000..48bff67 --- /dev/null +++ b/idle-inhibit/specification.xml @@ -0,0 +1,114 @@ + + + + Idle Inhibition Service Draft + + Idle Inhibition Service 0.1 DRAFT + + + + + Bastien + Nocera + + GNOME core Developer +
+ hadess@hadess.net +
+ + + + + + 2012 + The Idle Inhibition Service API Authors + + + + + + API Documentation + + Introduction + + The Idle Inhibition Service API allows client applications to inhibit a + user's login session from becoming idle. + + The service is usually implemented by the session manager, or anothe daemon + running inside the user's session, and communicating with the platform software + to avoid the idle, and the consequences of becoming idle. + + This API was designed by GNOME and KDE developers with the goal of having + a common way to inhibit idleness. + + + + Consequences of idleness + + Depending on the user session software running, idleness can have multiple + consequences, including, but not limited to: + + + Screen backlight dimming + Screensaver animation replacing the desktop content + Instant messenging client going to "auto-away" + Computer suspending or hibernating + + + + 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.. + + + + + API documentation + + Idle inhibition is achieved by the application calling an + Inhibit + function on a well-known D-Bus name. + + Inhibition will stop when the + UnInhibit function is called, or the application disconnects from the D-Bus + session bus (which usually happens upon exit). + + + + API notes + + The D-Bus service name is intentionally, 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. + + For the same reasons, inhibition of suspend, hibernation, or user-switching (amongst + others) is not supported in the API. + + + + + + D-Bus API Reference + + + + + + + + + References + + + kde-api + KDE Screenlocker D-Bus API + + + + gnome-impl + GNOME org.freedesktop.ScreenSaver proxy implementation + + + + + diff --git a/idle-inhibit/tools/resolve-type.xsl b/idle-inhibit/tools/resolve-type.xsl new file mode 100644 index 0000000..a37f2af --- /dev/null +++ b/idle-inhibit/tools/resolve-type.xsl @@ -0,0 +1,122 @@ + + + + + + + + + + + + + + + + + + + + + + + Node doesn't contain a type. + + + + + + + + + + + + ObjectPath + String + Byte + Boolean + Int16 + UInt16 + Int32 + UInt32 + Int64 + UInt64 + Double + Signature + Variant + + Dict< + + + + , + + + + > + + + Array< + + + + > + + + + + Unknown DBus Type + + + + + + + + + + + + + + Dict< + + + , + + + + > + + + + Unspecified type . + + + + + diff --git a/idle-inhibit/tools/spec-to-docbook.xsl b/idle-inhibit/tools/spec-to-docbook.xsl new file mode 100644 index 0000000..a6b18a3 --- /dev/null +++ b/idle-inhibit/tools/spec-to-docbook.xsl @@ -0,0 +1,1242 @@ + + + + + + + + + + + + + + + + + + + + + + IN + OUT + + + + + + + + + + + + + + + + . + + + + + + + + + + + + + + + + + + + + + + ERR: cannot find D-Bus interface, method, + signal or property called ' + + ' + + + + + + + + + + + + + ERR: Cannot use tp:member-ref when not in an + <interface> + + + + + + + + + + ERR: interface + + has no signal/method/property called + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Added in version . + + + + + + + + + Changed in version : + + + + Changed in version + + + + + + + + Deprecated since version . + + + + + + + + + + + + + Errors + + + + + + types + Types + + + + + + +
+ Simple types + +
+ + + +
+ Enumerated types + +
+ + + +
+ Sets of flags + +
+ + + +
+ Struct types + +
+ + + +
+ Map types + +
+ + + +
+ Types defined elsewhere + + + +
+ + + + + + + <xsl:attribute name="xml:id"> + <xsl:value-of select="concat(../@namespace, '.', translate(@name, ' ', ''))"/> + </xsl:attribute> + <literal><xsl:value-of select="concat(../@namespace, '.', translate(@name, ' ', ''))"/></literal> + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + This interface is + and is likely to cause havoc to your API/ABI if bindings are generated. + Don't include it in libraries that care about compatibility. + + + + + + + + + Implementations of this interface must also implement: + + + + + + + + + + + + + + + + + + + Methods + + + + + + + + Signals + + + + + + + + Properties + + + + + + + + + + + Methods + + + + + + + Signals + + + + + + + Telepathy Properties + + Accessed using the + + org.freedesktop.Telepathy.Properties + + + + + + + + + + + D-Bus Properties + + Accessed using the org.freedesktop.DBus.Properties interface. + + + + + + + + + + + + + + + + ERR: missing @name on a tp:flags type + + + + + + ERR: missing @type on tp:flags type + + + + + +
+ + + + <literal><xsl:value-of select="@name"/></literal> + + + + + + + + + + + + + + + + + + + = + + + + + + + + + + + (Undocumented) + + + + + + +
+ + + + + + + ERR: missing @name on a tp:enum type + + + + + + ERR: missing @type on tp:enum type + + + + + +
+ + + + <literal><xsl:value-of select="@name"/></literal> + + + + + + + + + + + + + + + + + + + = + + + + + + + + + + + (Undocumented) + + + + + + +
+ + + + + + + + + + + + READ + + + WRITE + + + READWRITE + + + + ERR: unknown or missing value for + @access on property + + : ' + + ' + + + + + + + + + + + + + + + + + + + + + + + READ + + + WRITE + + + READWRITE + + + + ERR: unknown or missing value for + @access on property + + : ' + + ' + + + + + + + + + + + + + + + + + + + + + + + + ERR: property + + does not have an interface as parent + + + + + + ERR: missing @name on a property of + + + + + + + + ERR: missing @type on property + + : ' + + ' + + + + + + + + + + + + + + + + − + + + + + + + + + + + + + +
+ + + + + <literal><xsl:value-of select="@name"/></literal> + + + + + In bindings that need a separate name, arrays of + should be called + . + + +
+ Members + + + +
+
+ + + + + + − + + + + + + + ERR: missing @name on a tp:simple-type + + + + + + ERR: missing @type on tp:simple-type + + + + + +
+ + + + + <literal><xsl:value-of select="@name"/> − <xsl:value-of select="@type"/></literal> + + + + + + + +
+ + + + + + + ERR: missing @name on a tp:external-type + + + + + + ERR: missing @type on tp:external-type + + + + + + + + + + + − + + Defined by: + + + + + − ( + + , + ) + + + + − a{ + + → + } + + + +
+ + + + + <literal> + <xsl:value-of select="@name"/> + </literal> + + + + + + + + In bindings that need a separate name, arrays of + should be called + . + + + Arrays of don't generally + make sense. + + + + + struct + + + + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ERR: method + + does not have an interface as parent + + + + + + ERR: missing @name on a method of + + + + + + + + + ERR: an arg of method + + has no type + + + + + + + ERR: an 'in' arg of method + + has no name + + + + + + + INFO: an 'out' arg of method + + has no name + + + + + + ERR: an arg of method + + has direction neither 'in' nor 'out' + + + + + + + + + + + <literal><xsl:value-of select="concat(../@name, concat('.', @name))"/></literal> + + + + + + + + + + + + + + + + Possible errors + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ( + + + + ) + + + + + + + + + a{ + + + + } + + + + + + + ERR: Unable to find type ' + + ' + + + + + + + + ERR: tp:type ' + + ' has D-Bus type ' + + ' but has been used with type=' + + ' + + + + + + + + + + + + ( + + + + + ) + + + + + + + + + + + + + + + + + + + + + + + + + + + + (undocumented) + + + + + + + + + + + + + + + + + + + (generic description) + + + (Undocumented.) + + + + + + + + + + + ERR: signal + + does not have an interface as parent + + + + + + ERR: missing @name on a signal of + + + + + + + + + ERR: an arg of signal + + has no type + + + + + ERR: an arg of signal + + has no name + + + + + + + + + ERR: an arg of signal + + has direction other than 'in' + + + + + + + + + + + <literal><xsl:value-of select="concat(../@name, concat('.', @name))"/></literal> + + + + + + + + + + + + + + + + + + + <xsl:value-of select="tp:title"/> + + + + + + + + + + + interfaces + Interfaces + + + + + + errors + + + + + + + + + + + + + + Stray text: {{{ + + }}} + + + + + + + Unrecognised element: { + + } + + + + + + + diff --git a/idle-inhibit/tools/spec-to-introspect.xsl b/idle-inhibit/tools/spec-to-introspect.xsl new file mode 100644 index 0000000..2468237 --- /dev/null +++ b/idle-inhibit/tools/spec-to-introspect.xsl @@ -0,0 +1,144 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + -- cgit v1.2.3-54-g00ecf