summaryrefslogtreecommitdiff
path: root/spec/Connection_Manager.xml
blob: b9bfe81a62ad733931dd5442954cecc9c0489199 (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
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
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
<?xml version="1.0" ?>
<node name="/Connection_Manager" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
  <tp:copyright>Copyright (C) 2005-2012 Collabora Limited</tp:copyright>
  <tp:copyright>Copyright (C) 2005-2008 Nokia Corporation</tp:copyright>
  <tp:copyright>Copyright (C) 2006 INdT</tp:copyright>
  <tp:license xmlns="http://www.w3.org/1999/xhtml">
    <p>This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.</p>

<p>This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
Lesser General Public License for more details.</p>

<p>You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p>
  </tp:license>
  <interface name="im.telepathy1.ConnectionManager">

    <tp:simple-type name="Connection_Manager_Name" type="s">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>The name of a connection manager, found in its well-known
          bus name and object path. This must be a non-empty string of
          ASCII letters, digits and underscores, starting with a letter
          or underscore.
          This is typically the name of the executable with any "telepathy-"
          prefix removed, and any hyphen/minus signs replaced by
          underscores.</p>

        <p>Connection manager names SHOULD NOT be the same as the name of
          the protocol they implement.</p>

        <tp:rationale>
          <p>This is likely to lead to conflicts between different
            implementations of the same protocol (or indeed inability
            to distinguish between the different implementations!). The
            Telepathy project traditionally uses some sort of pun (Haze is
            based on libpurple, Salut implements a protocol often called
            Bonjour, and Wilde implements the OSCAR protocol).</p>
        </tp:rationale>

        <p>Connection manager names SHOULD NOT be the same as the name of
          a library on which they are based.</p>

        <tp:rationale>
          <p>We often abbreviate, for instance, <i>telepathy-haze</i> as
            “Haze”, but abbreviating <i>telepathy-sofiasip</i>—since renamed to
            <i>telepathy-rakia</i> for exactly this reason—to “Sofia-SIP”
            caused confusion between the connection manager and the library it
            uses. Please don't repeat that mistake.</p>
        </tp:rationale>
      </tp:docstring>
      <tp:changed version="0.17.1">Prior to version 0.17.1, the allowed
        characters were not specified</tp:changed>
    </tp:simple-type>

    <tp:simple-type name="Protocol_Name" type="s" array-name="Protocol_Name_List">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>An instant messaging protocol. It must consist only of ASCII
          letters, digits and underscores, and must start
          with a letter or underscore. Where possible, this SHOULD be
          chosen from the following well-known values:</p>

        <ul>
          <li>aim - AOL Instant Messenger (OSCAR or TOC)</li>
          <li>gadugadu - Gadu-Gadu</li>
          <li>groupwise - Novell Groupwise</li>
          <li>icq - ICQ (OSCAR)</li>
          <li>irc - Internet Relay Chat (RFC 1459, 2810-2813)</li>
          <li>jabber - XMPP (RFC 3920, 3921) or Jabber</li>
          <li>local_xmpp - Link-local XMPP (XEP-0174) (Bonjour, Salut)</li>
          <li>msn - MSNP (Windows Live Messenger)</li>
          <li>myspace - MySpaceIM</li>
          <li>mxit - MXit</li>
          <li>napster - Napster</li>
          <li>qq - Tencent QQ</li>
          <li>sametime - IBM Lotus Sametime</li>
          <li>silc - SILC</li>
          <li>sip - Session Initiation Protocol (SIP), with or without
            SIMPLE support</li>
          <li>skype - Skype</li>
          <li>tel - telephony (the
            <abbr title="Public Switched Telephone Network">PSTN</abbr>,
            including GSM, CDMA and fixed-line telephony)</li>
          <li>trepia - Trepia</li>
          <li>yahoo - YMSG (Yahoo! Messenger)</li>
          <li>yahoojp - Japanese version of YMSG</li>
          <li>zephyr - Zephyr</li>
        </ul>

        <tp:rationale>
          <p>Identifiers formed with letters, digits and underscores and not
            starting with a digit are valid in all syntactically-restricted
            strings used in D-Bus, and non-problematic in filenames.</p>

          <p>Telepathy 0.x used hyphen/minus instead of underscore in the
            canonical form of a protocol name, which meant that protocol
            names often had to be transformed between their canonical form,
            and a form that used underscores for use in a D-Bus name.</p>
        </tp:rationale>
      </tp:docstring>
      <tp:changed version="0.17.1">Prior to version 0.17.1, the allowed
        characters were not specified</tp:changed>
      <tp:changed version="0.99.1">
        In Telepathy 0.x, protocol names could contain hyphen/minus signs,
        but not underscores.
      </tp:changed>
    </tp:simple-type>

    <tp:struct name="Param_Spec" array-name="Param_Spec_List">
      <tp:docstring>A struct representing an allowed parameter.</tp:docstring>
      <tp:member type="s" name="Name">
        <tp:docstring>A string parameter name</tp:docstring>
      </tp:member>
      <tp:member type="u" tp:type="Conn_Mgr_Param_Flags" name="Flags">
        <tp:docstring>A bitwise OR of the parameter flags</tp:docstring>
      </tp:member>
      <tp:member type="s" tp:type="DBus_Signature" name="Signature">
        <tp:docstring>A string containing the D-Bus type signature
          for this parameter</tp:docstring>
      </tp:member>
      <tp:member type="v" name="Default_Value">
        <tp:docstring>The default value (if the Has_Default flag is not
          present, there is no default and this takes some dummy value,
          which SHOULD be of the appropriate D-Bus type)</tp:docstring>
      </tp:member>
    </tp:struct>

    <tp:flags name="Conn_Mgr_Param_Flags" value-prefix="Conn_Mgr_Param_Flag" type="u">
      <tp:flag suffix="Required" value="1">
        <tp:docstring>
          This parameter is required for connecting to the server.
        </tp:docstring>
      </tp:flag>
      <tp:flag suffix="Register" value="2">
        <tp:docstring>
          This parameter is required for registering an account on the
          server.
        </tp:docstring>
      </tp:flag>
      <tp:flag suffix="Has_Default" value="4">
        <tp:docstring>
          This parameter has a default value; not providing this
          parameter is equivalent to providing the default.
        </tp:docstring>
      </tp:flag>
      <tp:flag suffix="Secret" value="8">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>This parameter should be considered private or secret; for
            instance, clients should store it in a "password safe" like
            gnome-keyring or kwallet, omit it from debug logs, and use a
            text input widget that hides the value of the parameter.</p>

          <p>(Clients that support older connection managers may also treat
            any parameter whose name contains "password" as though it had this
            flag.)</p>
        </tp:docstring>
        <tp:added version="0.17.2"/>
      </tp:flag>
      <tp:flag suffix="DBus_Property" value="16">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>This parameter is also a D-Bus property on the resulting
            <tp:dbus-ref
              namespace="imt1">Connection</tp:dbus-ref>; a
            parameter named <code>com.example.Duck.Macaroni</code> with this
            flag corresponds to the <code>Macaroni</code> property on the
            <code>com.example.Duck</code> interface.  Its value can be queried
            and possibly changed on an existing Connection using methods on the
            <code>org.freedesktop.DBus.Properties</code> interface.</p>

          <p>When a new value for a parameter with this flag is passed to
            <tp:dbus-ref namespace="imt1">Account.UpdateParameters</tp:dbus-ref>,
            the account manager will attempt to update its value on any running
            connections. Similarly, if the parameter also has the
            <code>Has_Default</code> flag, and is passed in the second argument
            to <code>UpdateParameters</code>, the default value will be applied
            to any running
            connections. Thus, clients generally do not need to directly access
            or update the connection property; instead, they SHOULD manipulate
            <tp:dbus-ref namespace="imt1">Account.Parameters</tp:dbus-ref>.</p>

          <tp:rationale>
            <p>This allows runtime-configurable options to be stored and
              maintained by the <tp:dbus-ref
              namespace='imt1'>AccountManager</tp:dbus-ref>, without needing to
              invent a separate account preference for “properties that should
              be set on the connection as soon as it is created”. It was
              originally invented to manage <tp:dbus-ref
                namespace='imt1.Connection.Interface'>Cellular1</tp:dbus-ref>
              preferences.</p>
          </tp:rationale>
        </tp:docstring>
        <tp:added version="0.17.16"/>
      </tp:flag>
    </tp:flags>

    <tp:mapping name="Protocol_Properties_Map">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>A map from protocol identifiers supported by a connection
          manager to the immutable properties of the corresponding
          <tp:dbus-ref namespace="im.telepathy1"
            >Protocol</tp:dbus-ref> objects.</p>
      </tp:docstring>

      <tp:member name="Name" type="s" tp:type="Protocol_Name">
        <tp:docstring>A protocol name</tp:docstring>
      </tp:member>

      <tp:member name="Properties" type="a{sv}"
        tp:type="Qualified_Property_Value_Map">
        <tp:docstring>The immutable properties of the corresponding
          Protocol object</tp:docstring>
      </tp:member>
    </tp:mapping>

    <property name="Protocols" tp:name-for-bindings="Protocols"
      access="read" type="a{sa{sv}}" tp:type="Protocol_Properties_Map"
      tp:immutable="yes">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>A map from protocol identifiers supported by this connection
          manager to the immutable properties of the corresponding
          <tp:dbus-ref namespace="im.telepathy1"
            >Protocol</tp:dbus-ref> objects.</p>

        <tp:rationale>
          <p>Providing the immutable properties here means that
            when the API of Protocol objects has been finalized,
            most clients will only need one D-Bus round trip to interrogate
            the ConnectionManager about all its protocols.</p>
        </tp:rationale>
      </tp:docstring>
    </property>

    <signal name="NewConnection" tp:name-for-bindings="New_Connection">
      <arg name="Bus_Name" type="s" tp:type="DBus_Bus_Name">
        <tp:docstring>
          The D-Bus service where the connection object can be found
        </tp:docstring>
      </arg>
      <arg name="Object_Path" type="o">
        <tp:docstring>
          The object path of the Connection object on this service
        </tp:docstring>
      </arg>
      <arg name="Protocol" type="s" tp:type="Protocol_Name">
        <tp:docstring>
          The identifier for the protocol this connection uses
        </tp:docstring>
      </arg>
      <tp:docstring>
        Emitted when a new <tp:dbus-ref
        namespace="im.telepathy1">Connection</tp:dbus-ref> object
        is created.
      </tp:docstring>
    </signal>

    <method name="RequestConnection" tp:name-for-bindings="Request_Connection">
      <arg direction="in" name="Protocol" type="s" tp:type="Protocol_Name">
        <tp:docstring>
          The protocol identifier
        </tp:docstring>
      </arg>
      <arg direction="in" name="Parameters" type="a{sv}"
        tp:type="String_Variant_Map">
        <tp:docstring>
          A dictionary mapping parameter names to values of the
          appropriate type, as indicated by the <tp:dbus-ref
          namespace="imt1.Protocol">Parameters</tp:dbus-ref> property
          (which can be retrieved by getting the
          <tp:member-ref>Protocols</tp:member-ref> property) and the
          well-known list of names and value types documented on the
          <tp:type>Connection_Parameter_Name</tp:type> type.
        </tp:docstring>
      </arg>
      <arg direction="out" type="s" tp:type="DBus_Bus_Name" name="Bus_Name">
        <tp:docstring>
          A D-Bus service name where the new Connection object can be found
        </tp:docstring>
      </arg>
      <arg direction="out" type="o" name="Object_Path">
        <tp:docstring>
          The D-Bus object path to the Connection on this service
        </tp:docstring>
      </arg>
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Request a
          <tp:dbus-ref namespace="im.telepathy1">Connection</tp:dbus-ref>
          object representing a given account on a given
          protocol with the given parameters. The method returns the bus name
          and the object path where the new Connection object can be found,
          which should have the status of Connection_Status_Disconnected, to
          allow signal handlers to be attached before connecting is started
          with the
          <tp:dbus-ref namespace="im.telepathy1.Connection">Connect</tp:dbus-ref>
          method.</p>

        <p><strong>Most applications should not use this method</strong>: they
          should instead use the the <tp:dbus-ref
          namespace='imt1.Account'>Connection</tp:dbus-ref> property on an
          <tp:dbus-ref namespace='imt1'>Account</tp:dbus-ref> object obtained
          from the <tp:dbus-ref
          namespace='imt1'>AccountManager</tp:dbus-ref>. This method is used
          internally by the account manager to create connections when
          needed.</p>

        <p>The parameters which must and may be provided in the
        parameters dictionary can be discovered by looking at the
        <tp:dbus-ref
        namespace="imt1.Protocol">Parameters</tp:dbus-ref> property by
        getting the <tp:member-ref>Protocols</tp:member-ref>
        property. These parameters, their types, and their default
        values may be cached in files so that all available connection
        managers do not need to be started to discover which protocols
        are available.</p>

        <p>To request values for these parameters from the user, a client must
        have prior knowledge of the meaning of the parameter names, so the
        well-known names and types defined by the
        <tp:type>Connection_Parameter_Name</tp:type> type should be used where
        appropriate.</p>

        <p>Connection manager authors SHOULD avoid introducing parameters
          whose default values would not be serializable in a
          <code>.manager</code> file.</p>

        <tp:rationale>
          <p>The same serialization format is used in Mission Control
            to store accounts.</p>
        </tp:rationale>

        <p>Every successful RequestConnection call will cause the emission of a
        <tp:member-ref>NewConnection</tp:member-ref> signal for the same newly
        created connection. The
        requester can use the returned object path and service name
        independently of the emission of that signal. In that case this signal
        emission is most useful for, e.g. other processes that are monitoring
        the creation of new connections.</p>
      </tp:docstring>
      <tp:possible-errors>
        <tp:error name="im.telepathy1.Error.NetworkError"/>
        <tp:error name="im.telepathy1.Error.NotImplemented">
          <tp:docstring>
            The requested protocol is not supported by this manager
          </tp:docstring>
        </tp:error>
        <tp:error name="im.telepathy1.Error.NotAvailable">
          <tp:docstring>
            The requested connection already appears to exist
          </tp:docstring>
        </tp:error>
        <tp:error name="im.telepathy1.Error.InvalidArgument">
          <tp:docstring>
            Unrecognised connection parameters
          </tp:docstring>
        </tp:error>
      </tp:possible-errors>
    </method>

    <tp:simple-type name="Connection_Parameter_Name" type="s">
      <tp:added version="0.21.2"/>
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Well-known connection parameter names, along with their expected
          type. Where possible, connection managers should use names and types
          from this list in the <tp:dbus-ref
          namespace='imt1.Protocol'>Parameters</tp:dbus-ref> that may be passed
          to <tp:member-ref>RequestConnection</tp:member-ref>.</p>

        <dl>
          <dt>account (s)</dt>
          <dd>The identifier for the user's account on the server</dd>

          <dt>server (s)</dt>
          <dd>A fully qualified domain name or numeric IPv4 or IPv6 address.
            Using the fully-qualified domain name form is recommended whenever
            possible. If this parameter is specified and the account for that
            protocol also specifies a server, this parameter should override
            that in the user id.</dd>

          <dt>port (q)</dt>
          <dd>A TCP or UDP port number. If this parameter is specified and the
            account for that protocol also specifies a port, this parameter
            should override that in the account.</dd>

          <dt>password (s)</dt>
          <dd>A password associated with the account.</dd>

          <dt>require-encryption (b)</dt>
          <dd>Require encryption for this connection. A connection should fail
            to connect if require-encryption is set and an encrypted connection
            is not possible.</dd>

          <dt>register (b)</dt>
          <dd>This account should be created on the server if it does not
            already exist.</dd>

          <dt>ident (s)</dt>
          <dd>The local username to report to the server if necessary, such as
            in IRC.</dd>

          <dt>fullname (s)</dt>
          <dd>The user's full name if the service requires this when
            authenticating or registering.</dd>

          <dt>stun-server (s)</dt>
          <dd>The IP address or FQDN of a STUN server to use for NAT traversal,
            without any ":port" suffix.</dd>

          <dt>stun-port (q)</dt>
          <dd>The UDP port number on the stun-server to use for STUN. Only
            significant if the stun-server is also supplied.</dd>

          <dt>keepalive-interval (u)</dt>
          <dd>
            <p>The time in seconds between pings sent to the server to ensure
              that the connection is still alive, or <tt>0</tt> to disable such
              pings.</p>

            <p>This parameter is superseded by the <tp:dbus-ref
                namespace='imt1.Connection.Interface.Keepalive1'>KeepaliveInterval</tp:dbus-ref>
              property, which can be updated on an already-established
              connection as well as being specified when requesting the
              connection. Clients SHOULD provide that parameter instead, if
              allowed; new connection managers SHOULD implement it in
              preference to this one.</p>
          </dd>
        </dl>

        <p>The following well-known parameter names correspond to D-Bus
          properties, and thus their <tp:type>Conn_Mgr_Param_Flags</tp:type>
          should include DBus_Property. See that flag for more details on this
          kind of parameter.</p>

        <tp:list-dbus-property-parameters/>
      </tp:docstring>
    </tp:simple-type>

    <property name="Interfaces" tp:name-for-bindings="Interfaces"
      type="as" access="read">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>A list of the extra interfaces provided by this connection manager
          (i.e. extra functionality that can be provided even before a
          connection has been created).</p>

        <p>No interfaces suitable for listing in this property are currently
          defined; it's provided as a hook for possible future
          functionality.</p>

        <p>Connection managers with a non-empty list of Interfaces MUST
          represent them in the <code>.manager</code> file, if they have one,
          as an <code>Interfaces</code> key in the
          group headed <code>[ConnectionManager]</code>, whose value is a list
          of strings each followed by a semicolon.</p>
      </tp:docstring>
      <tp:added version="0.17.8"/>
    </property>

    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
    <p>A D-Bus service which allows connections to be created. The manager
      processes are intended to be started by D-Bus service activation.</p>

    <p>For service discovery, each Telepathy connection manager must have
      a <em>connection manager name</em> (see
      <tp:type>Connection_Manager_Name</tp:type> for syntax).</p>

    <p>The connection manager must then provide a well-known bus name of
      <code>im.telepathy1.ConnectionManager.<em>cmname</em></code>
      where <em>cmname</em> is its connection manager name. If it makes sense
      to start the connection manager using D-Bus service activation, it
      must register that well-known name for service activation by installing
      a .service file.</p>

    <p>Clients can list the running connection managers by calling the
      ListNames method on the D-Bus daemon's org.freedesktop.DBus interface
      and looking for names matching the above pattern; they can list the
      activatable connection managers by calling ListActivatableNames, and
      they should usually combine the two lists to get a complete list of
      running or activatable connection managers.</p>

    <p>When the connection manager is running, it must have an object
      implementing the ConnectionManager interface at the object path
      <code>/im/telepathy1/ConnectionManager/<em>cmname</em></code>.
    </p>

    <p>Connection managers' capabilities can be determined dynamically by
      getting the <tp:member-ref>Protocols</tp:member-ref> property.
      However, since it is inefficient to activate all possible connection
      managers on the system just to find out what they can do, there
      is a standard mechanism to store static information about CMs in
      ".manager files".</p>

    <p>To look up a connection manager's supported protocols, clients
      should search the data directories specified by
      <a href="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">the
        freedesktop.org XDG Base Directory Specification</a> ($XDG_DATA_HOME,
      defaulting to $HOME/.local/share if unset, followed by
      colon-separated paths from $XDG_DATA_DIRS, defaulting to
      /usr/local/share:/usr/share if unset) for the first file named
      <code>telepathy-1/managers/<em>cmname</em>.manager</code> that can be
      read without error and contains a group whose name is the name of this
      interface. This file has the same syntax as a
      <a href="http://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html">freedesktop.org Desktop Entry file</a>.</p>

    <p>Clients must still support connection managers for which no
      <code>.manager</code> file can be found, which they can do by activating
      the connection manager and calling its methods; the
      <code>.manager</code> file is merely an optimization. Connection managers
      whose list of protocols can change at any time (for instance, via
      a plugin architecture) should not install a <code>.manager</code>
      file.</p>

    <p>The <code>.manager</code> file MUST have a group headed
      <code>[im.telepathy1.ConnectionManager]</code>, containing a key
      <code>Interfaces</code> representing
      <tp:member-ref>Interfaces</tp:member-ref> as a sequence of strings
      each followed by a semicolon (the "localestrings" type from the Desktop
      Entry Specification).</p>

    <p>For each protocol name <em>proto</em> that would be returned by
    the keys of the <tp:member-ref>Protocols</tp:member-ref> property,
    the .manager file contains a group headed <code>[im.telepathy1.Protocol
    <em>proto</em>]</code>. For each parameter <em>p</em> that would
    be in the <tp:dbus-ref
    namespace="imt1.Protocol">Parameters</tp:dbus-ref> property
    (retrievable using the <tp:member-ref>Protocols</tp:member-ref>
    property), the .manager file contains a key
    <code>param-<em>p</em></code> with a value consisting of a D-Bus
    signature (a single complete type), optionally followed by a space
    and a space-separated list of flags. The supported flags are:</p>

    <ul>
      <li><code>required</code>, corresponding to
        Conn_Mgr_Param_Flag_Required</li>
      <li><code>register</code>, corresponding
        to Conn_Mgr_Param_Flag_Register</li>
      <li><code>secret</code>, corresponding
        to Conn_Mgr_Param_Flag_Secret</li>
      <li><code>dbus-property</code>, corresponding
        to Conn_Mgr_Param_Flag_DBus_Property</li>
    </ul>

    <p>The group may also contain a key <code>default-<em>p</em></code>
      whose value is a string form of the default value for the parameter.
      If this key exists, it sets the default, and also sets the flag
      Conn_Mgr_Param_Flag_Has_Default. The default value is formatted
      according to the D-Bus signature as follows:</p>

    <dl>
      <dt>s (string)</dt>
        <dd>The UTF-8 string, with the standard backslash escape
          sequences supported by the Desktop Entry Specification
          (the "localestring" type from the Desktop Entry Specification)</dd>
      <dt>o (object path)</dt>
        <dd>The object path as an ASCII string</dd>
      <dt>b (boolean)</dt>
        <dd>"true" (case-insensitively) or "1" means True, "false"
          (case-insensitively) or "0" means False; when writing a file,
          "true" and "false" SHOULD be used</dd>
      <dt>y, q, u, t (8-, 16-, 32-, 64-bit unsigned integer)</dt>
        <dd>ASCII decimal integer</dd>
      <dt>n, i, x (16-, 32-, 64-bit signed integer)</dt>
        <dd>ASCII decimal integer, optionally prefixed with "-"</dd>
      <dt>d (double-precision floating point)</dt>
        <dd>ASCII decimal number</dd>
      <dt>as (array of string), ao (array of object path)</dt>
        <dd>A sequence of UTF-8 strings each followed by a semicolon, with
          any semicolons they contain escaped with a backslash
          (the "localestrings" type from the Desktop Entry Specification)</dd>
    </dl>

    <p>Currently, no other D-Bus signatures are allowed to have default values,
      but clients parsing the .manager file MUST ignore defaults
      that they cannot parse, and treat them as if the
      <code>default-<em>p</em></code> key was not present at all.</p>

    <p>It is not required that a connection manager be able to support multiple
    protocols, or even multiple connections. When a connection is made, a
    service name where the connection object can be found is returned. A
    manager which can only make one connection may then remove itself from its
    well-known bus name, causing a new connection manager to be activated when
    somebody attempts to make a new connection.</p>
    </tp:docstring>

    <tp:changed version="0.17.2">Prior to version 0.17.2, support for
      CMs with no .manager file was not explicitly required.</tp:changed>
    <tp:changed version="0.17.16">Prior to version 0.17.16 the serialization
      of string arrays (signature 'as') was not defined</tp:changed>
    <tp:changed version="0.25.2">Prior to version 0.25.2 the
      serialization of object-path arrays (signature 'ao') was not
      defined</tp:changed>
    <tp:changed version="0.99.1">GetParameters and ListProtocols
      have been removed in favour of the
      <tp:member-ref>Protocols</tp:member-ref> property.</tp:changed>
  </interface>
</node>
<!-- vim:set sw=2 sts=2 et ft=xml: -->