/usr/share/gtk-doc/html/telepathy-spec/Client.html is in telepathy-specification 0.27.3-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
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 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 | <?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd" "">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<title>Client — Telepathy D-Bus Interface Specification</title>
<link rel="stylesheet" href="style.css" type="text/css"/>
<link rel="shortcut icon" type="image/png" media="all" href="favicon.png" />
<script src="jquery.min.js"></script>
<script src="magic.js"></script>
</head>
<body>
<div class="header">
<h1>Interface <abbr title='org.freedesktop.Telepathy.Client'>Client</abbr></h1>
<a href="index.html">Interface Index</a>
(<a href="interfaces.html">Compact</a>)
| <a href="#summary">Summary</a>
| <a href="#description">Description</a>
| <a href="#properties">Properties</a>
</div>
<div class="main">
<div class="summary">
<a name="summary"></a>
<h3>Properties</h3>
<table class="summary">
<tr>
<td><a href="Client.html#Property:Interfaces">Interfaces</a></td>
<td>
as
(<a href="generic-types.html#Simple-Type:DBus_Interface" title="Array of Simple Type DBus_Interface">DBus_Interface_List</a>)
</td>
<td>Read only</td>
<td></td>
<td>
</td>
</tr>
</table>
</div>
<div class="annotation added"><span class="version">Added in 0.17.26. </span>(as a stable interface)</div>
<a name="description"></a>
<h3>Description</h3>
<div class="docstring" xmlns="http://www.w3.org/1999/xhtml">
<p>Telepathy clients use connection managers, the channel dispatcher
and optionally the account manager to provide useful
functionality.</p>
<p>User interface processes are the obvious example of Telepathy
clients, but they can provide other functionality, such as
address-book synchronization.</p>
<p>Every running or activatable process with a well-known
name of the form org.freedesktop.Telepathy.Client.<em>clientname</em>
should be probed by the channel dispatcher to discover its
capabilities. Each client is either an <em>observer</em>, an
<em>approver</em>, a <em>channel handler</em>, or some combination
of these.</p>
<div class="rationale"><h5>Rationale:</h5><div>
<p>Activatable services (those with a D-Bus <code>.service</code>
file) must be supported so that we can run clients
in response to channel creation.</p>
<p>Non-activatable services (those that do not register a D-Bus
<code>.service</code> file for their well-known name, but do
request it at runtime) must be supported so that we can have
programs that process channels, but only if they are already
running - for instance, a full-screen media centre
application might do this.</p>
</div></div>
<p>The client name, <em>clientname</em>, MUST be a non-empty string of
ASCII digits, letters, dots and/or underscores, starting with a
letter, and without sets of two consecutive dots or a dot
followed by a digit. For non-activatable services, it MAY contain a
part that is generated per instance at runtime.</p>
<div class="rationale"><h5>Rationale:</h5><div>
<p>If each of a client Foo's instances should be able to manipulate
channels separately, the instance with unique name
<code>:1.25</code> might request a well-known name like
<code>org.freedesktop.Telepathy.Client.Foo._1._25</code>.</p>
<p>(Note that well-known bus-name components may not start with a
digit, so o.f.T.Client.Foo.1.25 would not be acceptable.)</p>
</div></div>
<p>Each Client MUST export an object whose object path may be
determined by replacing '.' with '/' in the well-known name and
prepending '/'. This object represents its API as a Telepathy
client; the channel dispatcher will call its methods and read
its properties when appropriate.</p>
<p>As an optimization, activatable clients SHOULD install a file
<code><a href="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">$XDG_DATA_DIRS</a>/telepathy/clients/<em>clientname</em>.client</code>
containing a cached version of its immutable properties,
so that for most clients, the channel dispatcher can
just read a file to discover capabilities, instead of
having to service-activate the client immediately in order to fetch
its read-only properties. However, the D-Bus API is canonical, and
the channel dispatcher MUST support clients without such a file.</p>
<p>Non-activatable clients MAY install a <code>.client</code> file,
but there's not much point in them doing so.</p>
<p>The .client files MUST contain UTF-8 text with the same syntax
as
<a href="http://standards.freedesktop.org/desktop-entry-spec/latest/">Desktop
Entry files</a> (although the allowed groups, keys and values differ).
Every <code>.client</code> file MUST contain a group whose name is
the name of this interface.</p>
<p>The groups, keys and values in the <code>.client</code> file are
defined by individual interfaces. Each interface that can usefully
cache information in the <code>.client</code> file SHOULD correspond
to a group with the same name.</p>
</div>
<div class="outset properties property">
<a name="properties"></a>
<h1>Properties</h1>
<div>
Accessed using the <a
href="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties">org.freedesktop.DBus.Properties</a>
interface.
</div>
<div class="inset property">
<a name="Property:Interfaces"></a>
<span class="permalink">(<a href="Client.html#Property:Interfaces">Permalink</a>)</span>
<h2>
Interfaces — as
(<a href="generic-types.html#Simple-Type:DBus_Interface" title="Array of Simple Type DBus_Interface">DBus_Interface_List</a>)
</h2>
<div class="access">Read only</div>
<div class="docstring" xmlns="http://www.w3.org/1999/xhtml">
<p>A list of the extra interfaces provided by this client.
This SHOULD include at least one of
<a href="Client_Observer.html" namespace="org.freedesktop.Telepathy" title="Interface org.freedesktop.Telepathy.Client.Observer">Client.Observer</a>,
<a href="Client_Approver.html" namespace="org.freedesktop.Telepathy" title="Interface org.freedesktop.Telepathy.Client.Approver">Client.Approver</a> or
<a href="Client_Handler.html" namespace="org.freedesktop.Telepathy" title="Interface org.freedesktop.Telepathy.Client.Handler">Client.Handler</a>.</p>
<p>In the <code>.client</code> file, this is represented by key
"<code>Interfaces</code>" in the group named after this interface.
The value of the key is a list of interface names each followed by
a semicolon (so it always ends with a semicolon unless it is empty),
i.e. a key of type "strings" as described in the Desktop Entry
specification.</p>
</div>
</div>
</div>
</div>
</body>
</html>
|