Channel.xml 26.3 KB
Newer Older
1 2
<?xml version="1.0" ?>
<node name="/Channel" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
3 4 5
  <tp:copyright>Copyright © 2005-2009 Collabora Limited</tp:copyright>
  <tp:copyright>Copyright © 2005-2009 Nokia Corporation</tp:copyright>
  <tp:copyright>Copyright © 2006 INdT</tp:copyright>
6 7
  <tp:license xmlns="http://www.w3.org/1999/xhtml">
    <p>This library is free software; you can redistribute it and/or
8 9
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
10
version 2.1 of the License, or (at your option) any later version.</p>
11

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

17
<p>You should have received a copy of the GNU Lesser General Public
18
License along with this library; if not, write to the Free Software
19
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p>
20
  </tp:license>
21
  <interface name="org.freedesktop.Telepathy.Channel">
22

23
    <property name="ChannelType" type="s" tp:type="DBus_Interface"
24
      access="read" tp:name-for-bindings="Channel_Type">
25
      <tp:added version="0.17.7"/>
26 27 28 29 30 31
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>The channel's type. This cannot change once the channel has
          been created.</p>

        <p>For compatibility between older connection managers and newer
          clients, if this is unavailable or is an empty string,
Will Thompson's avatar
Will Thompson committed
32 33
          clients MUST use the result of calling
          <tp:member-ref>GetChannelType</tp:member-ref>.</p>
34 35 36 37 38

        <tp:rationale>
          The GetAll method lets clients retrieve all properties in one
          round-trip, which is desirable.
        </tp:rationale>
39 40 41 42 43 44 45 46

        <p>When requesting a channel, the request MUST specify a channel
          type, and the request MUST fail if the specified channel type
          cannot be supplied.</p>

        <tp:rationale>
          Common sense.
        </tp:rationale>
47 48 49
      </tp:docstring>
    </property>

50 51
    <property name="Interfaces" tp:name-for-bindings="Interfaces"
      type="as" tp:type="DBus_Interface[]" access="read">
52
      <tp:added version="0.17.7"/>
53 54 55 56 57 58 59
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Extra interfaces provided by this channel. This SHOULD NOT include
          the channel type and the Channel interface itself, and cannot
          change once the channel has been created.</p>

        <p>For compatibility between older connection managers and newer
          clients, if this is unavailable, or if this is an empty list and
Will Thompson's avatar
Will Thompson committed
60 61 62 63 64 65
          <tp:member-ref>ChannelType</tp:member-ref> is an empty string,
          clients MUST use the result of calling
          <tp:member-ref>GetInterfaces</tp:member-ref> instead. If this is an
          empty list but ChannelType is non-empty, clients SHOULD NOT call
          GetInterfaces; this implies that connection managers that implement
          the ChannelType property MUST also implement the Interfaces property
66 67 68 69 70 71
          correctly.</p>

        <tp:rationale>
          The GetAll method lets clients retrieve all properties in one
          round-trip, which is desirable.
        </tp:rationale>
72

73 74 75 76
        <p>When requesting a channel with a particular value for this
          property, the request must fail without side-effects unless the
          connection manager expects to be able to provide a channel whose
          interfaces include at least the interfaces requested.</p>
77 78 79
      </tp:docstring>
    </property>

80 81
    <property name="TargetHandle" type="u" access="read" tp:type="Handle"
      tp:name-for-bindings="Target_Handle">
82
      <tp:added version="0.17.7"/>
83 84 85
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>The handle (a representation for the identifier) of the contact,
          chatroom, etc. with which this handle communicates. Its type
Will Thompson's avatar
Will Thompson committed
86 87
          is given by the <tp:member-ref>TargetHandleType</tp:member-ref>
          property.</p>
88 89

        <p>This is fixed for the lifetime of the channel, so channels which
90 91 92 93
          could potentially be used to communicate with multiple contacts,
          and do not have an identity of their own (such as a Handle_Type_Room
          handle), must have TargetHandleType set to Handle_Type_None and
          TargetHandle set to 0.</p>
94 95 96 97 98

        <p>Unlike in the telepathy-spec 0.16 API, there is no particular
          uniqueness guarantee - there can be many channels with the same
          (channel type, handle type, handle) tuple. This is necessary
          to support conversation threads in XMPP and SIP, for example.</p>
99 100

        <p>If this is present in a channel request, it must be nonzero,
101 102 103
          <tp:member-ref>TargetHandleType</tp:member-ref>
          MUST be present and not Handle_Type_None, and
          <tp:member-ref>TargetID</tp:member-ref> MUST NOT be
104
          present. Properties from
105
          <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface">Addressing1</tp:dbus-ref>
106
          MUST NOT be present.</p>
107 108

        <p>The channel that satisfies the request MUST either:</p>
109 110 111 112 113 114 115 116 117

        <ul>
          <li>have the specified TargetHandle property; or</li>
          <li>have <tp:member-ref>TargetHandleType</tp:member-ref> =
            Handle_Type_None, TargetHandle = 0, and be configured such that
            it could communicate with the specified handle in some other way
            (e.g. have the requested contact handle in its Group
            interface)</li>
        </ul>
118 119 120
      </tp:docstring>
    </property>

121 122
    <property name="TargetID" tp:name-for-bindings="Target_ID"
      type="s" access="read">
Simon McVittie's avatar
Simon McVittie committed
123
      <tp:added version="0.17.9"/>
124 125 126 127 128 129 130 131 132 133 134 135 136 137

      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>The string that would result from inspecting the
          <tp:member-ref>TargetHandle</tp:member-ref>
          property (i.e. the identifier in the IM protocol of the contact,
          room, etc. with which this channel communicates), or the empty
          string if the TargetHandle is 0.</p>

        <tp:rationale>
          <p>The presence of this property avoids the following race
            condition:</p>

          <ul>
            <li>New channel C is signalled with target handle T</li>
Will Thompson's avatar
Will Thompson committed
138 139 140
            <li>Client calls <tp:dbus-ref
              namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref>(CONTACT,
              [T])</li>
141
            <li>Channel C closes, removing the last reference to handle T</li>
Will Thompson's avatar
Will Thompson committed
142 143 144
            <li><tp:dbus-ref
              namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref>(CONTACT,
              [T]) returns an error</li>
145 146 147 148 149 150 151
          </ul>
        </tp:rationale>

        <p>If this is present in a channel request,
          <tp:member-ref>TargetHandleType</tp:member-ref>
          MUST be present and not Handle_Type_None, and
          <tp:member-ref>TargetHandle</tp:member-ref> MUST NOT be
152
          present. Properties from
153
          <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface">Addressing1</tp:dbus-ref>
154 155 156
          MUST NOT be present.The request MUST fail with error InvalidHandle,
          without side-effects, if the requested TargetID would not be
          accepted by
157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173
          <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection">RequestHandles</tp:dbus-ref>.</p>

        <p>The returned channel must be related to the handle corresponding
          to the given identifier, in the same way as if TargetHandle
          had been part of the request instead.</p>

        <tp:rationale>
          <p>Requesting channels with a string identifier saves a round-trip
            (the call to RequestHandles). It also allows the channel
            dispatcher to accept a channel request for an account that is not
            yet connected (and thus has no valid handles), bring the account
            online, and pass on the same parameters to the new connection's
            CreateChannel method.</p>
        </tp:rationale>
      </tp:docstring>
    </property>

174
    <property name="TargetHandleType" type="u" access="read"
175
      tp:type="Handle_Type" tp:name-for-bindings="Target_Handle_Type">
176
      <tp:added version="0.17.7"/>
177
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
Will Thompson's avatar
Will Thompson committed
178
        <p>The type of <tp:member-ref>TargetHandle</tp:member-ref>.</p>
179 180 181

        <p>If this is omitted from a channel request, connection managers
          SHOULD treat this as equivalent to Handle_Type_None.</p>
182 183 184 185 186

        <p>If this is omitted or is Handle_Type_None,
          <tp:member-ref>TargetHandle</tp:member-ref> and
          <tp:member-ref>TargetID</tp:member-ref> MUST be omitted from the
          request.</p>
187 188 189
      </tp:docstring>
    </property>

190
    <method name="Close" tp:name-for-bindings="Close">
191 192
      <tp:docstring>
        Request that the channel be closed. This is not the case until
Will Thompson's avatar
Will Thompson committed
193 194
        the <tp:member-ref>Closed</tp:member-ref> signal has been emitted, and
        depending on the connection
195 196 197 198
        manager this may simply remove you from the channel on the server,
        rather than causing it to stop existing entirely. Some channels
        such as contact list channels may not be closed.
      </tp:docstring>
199 200 201 202 203 204 205 206 207 208 209 210 211 212 213
      <tp:possible-errors>
        <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
        <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
        <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
          <tp:docstring>
            This channel may never be closed, e.g. a contact list
          </tp:docstring>
        </tp:error>
        <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
          <tp:docstring>
            This channel is not currently in a state where it can be closed,
            e.g. a non-empty user-defined contact group
          </tp:docstring>
        </tp:error>
      </tp:possible-errors>
214
    </method>
215

216
    <signal name="Closed" tp:name-for-bindings="Closed">
217 218 219 220 221 222 223
      <tp:docstring>
        Emitted when the channel has been closed. Method calls on the
        channel are no longer valid after this signal has been emitted,
        and the connection manager may then remove the object from the bus
        at any point.
      </tp:docstring>
    </signal>
224

225
    <method name="GetChannelType" tp:name-for-bindings="Get_Channel_Type">
226
      <tp:deprecated version="0.17.7">Use the ChannelType
227
        property if possible.</tp:deprecated>
228 229
      <arg direction="out" type="s" tp:type="DBus_Interface"
        name="Channel_Type">
230 231
        <tp:docstring>The interface name</tp:docstring>
      </arg>
232
      <tp:docstring>
Will Thompson's avatar
Will Thompson committed
233 234 235
        Returns the interface name for the type of this channel.  Clients
        SHOULD use the <tp:member-ref>ChannelType</tp:member-ref> property
        instead, falling back to this method only if necessary.
236 237 238 239 240

        <tp:rationale>
          The GetAll method lets clients retrieve all properties in one
          round-trip.
        </tp:rationale>
241 242
      </tp:docstring>
    </method>
243

244
    <method name="GetHandle" tp:name-for-bindings="Get_Handle">
245
      <tp:deprecated version="0.17.7">Use the TargetHandleType
246
        and TargetHandle properties if possible.</tp:deprecated>
247 248
      <arg direction="out" type="u" tp:type="Handle_Type"
        name="Target_Handle_Type">
249
        <tp:docstring>
250
          The same as TargetHandleType.
251 252
        </tp:docstring>
      </arg>
253
      <arg direction="out" type="u" tp:type="Handle" name="Target_Handle">
254
        <tp:docstring>
255
          The same as TargetHandle.
256 257
        </tp:docstring>
      </arg>
258 259 260
      <tp:docstring>
        Returns the handle type and number if this channel represents a
        communication with a particular contact, room or server-stored list, or
261
        zero if it is transient and defined only by its contents. Clients
Will Thompson's avatar
Will Thompson committed
262 263
        SHOULD use the <tp:member-ref>TargetHandle</tp:member-ref> and
        <tp:member-ref>TargetHandleType</tp:member-ref> properties instead,
264 265 266 267 268 269
        falling back to this method only if necessary.

        <tp:rationale>
          The GetAll method lets clients retrieve all properties in one
          round-trip.
        </tp:rationale>
270 271
      </tp:docstring>
    </method>
272

273
    <method name="GetInterfaces" tp:name-for-bindings="Get_Interfaces">
274
      <tp:deprecated version="0.17.7">Use the Interfaces
275
        property if possible.</tp:deprecated>
276 277
      <arg direction="out" type="as" tp:type="DBus_Interface[]"
        name="Interfaces">
278 279 280 281
        <tp:docstring>
          An array of the D-Bus interface names
        </tp:docstring>
      </arg>
282 283
      <tp:docstring>
        Get the optional interfaces implemented by the channel.
Will Thompson's avatar
Will Thompson committed
284 285
        Clients SHOULD use the <tp:member-ref>Interfaces</tp:member-ref>
        property instead, falling back to this method only if necessary.
286 287 288 289 290

        <tp:rationale>
          The GetAll method lets clients retrieve all properties in one
          round-trip.
        </tp:rationale>
291 292
      </tp:docstring>
    </method>
293

294 295
    <property name="Requested" tp:name-for-bindings="Requested"
      type="b" access="read">
Simon McVittie's avatar
Simon McVittie committed
296
      <tp:added version="0.17.13">(as stable API)</tp:added>
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
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>True if this channel was created in response to a local request,
          such as a call to
          <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.RequestChannel</tp:dbus-ref>
          or
          <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>.</p>

        <tp:rationale>
          <p>The idea of this property is to distinguish between "incoming"
            and "outgoing" channels, in a way that doesn't break down when
            considering special cases like contact lists that are automatically
            created on connection to the server, or chatrooms that an
            IRC proxy/bouncer like irssi-proxy or bip was already in.</p>

          <p>The reason we want to make that distinction is that UIs for
            things that the user explicitly requested should start up
            automatically, whereas for incoming messages and VoIP calls we
            should first ask the user whether they want to open the messaging
            UI or accept the call.</p>
        </tp:rationale>

        <p>If the channel was not explicitly requested (even if it was
          created as a side-effect of a call to one of those functions,
          e.g. because joining a Tube in a MUC context on XMPP implies
          joining that MUC), then this property is false.</p>

        <p>For compatibility with older connection managers, clients SHOULD
          assume that this property is true if they see a channel announced
          by the
          <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.NewChannel</tp:dbus-ref>
          signal with the suppress_handler parameter set to true.</p>

        <tp:rationale>
          <p>In a correct connection manager, the only way to get such a
            channel is to request it.</p>
        </tp:rationale>

        <p>Clients MAY additionally assume that this property is false
          if they see a channel announced by the NewChannel signal with the
          suppress_handler parameter set to false.</p>

        <tp:rationale>
          <p>This is more controversial, since it's possible to get that
            parameter set to false by requesting a channel. However, there's
            no good reason to do so, and we've deprecated this practice.</p>

          <p>In the particular case of the channel dispatcher, the only
            side-effect of wrongly thinking a channel is unrequested
            is likely to be that the user has to confirm that they want to
            use it, so it seems fairly harmless to assume in the channel
            dispatcher that channels with suppress_handler false are
            indeed unrequested.</p>
        </tp:rationale>
350 351 352 353 354 355

        <p>It does not make sense for this property to be in channel
          requests—it will always be true for channels returned by
          CreateChannel, and callers of EnsureChannel cannot control whether an
          existing channel was originally requested locally—so it MUST NOT
          be accepted.</p>
356 357 358 359 360
      </tp:docstring>
    </property>

    <property name="InitiatorHandle" type="u" tp:type="Contact_Handle"
      access="read" tp:name-for-bindings="Initiator_Handle">
Simon McVittie's avatar
Simon McVittie committed
361
      <tp:added version="0.17.13">(as stable API)</tp:added>
362
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384
        <p>The contact who initiated the channel; for instance, the contact
          who invited the local user to a chatroom, or the contact who
          initiated a call.</p>

        <p>This does <em>not</em> necessarily represent the contact who
          created the underlying protocol-level construct. For instance, if
          Rob creates a chatroom, Will joins that chatroom, and Will invites Simon
          to join it, then Simon will see Will as the InitiatorHandle of the
          channel representing the chatroom.</p>

        <tp:rationale>
          <p>The room creator is generally a less useful piece of information
            than the inviter, is less likely to be available at invitation
            time (i.e. can't necessarily be an immutable property), and is
            less likely to be available at all. The creator of a chatroom
            is not currently available via Telepathy; if added in future, it
            is likely to be made available as a property on the Chatroom
            interface (<a
              href="http://bugs.freedesktop.org/show_bug.cgi?id=23151">bug 23151</a>).</p>
        </tp:rationale>

        <p>For channels requested by the
385 386 387 388 389 390
          local user, this MUST be the value of
          <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.SelfHandle</tp:dbus-ref>
          at the time the channel was created (i.e. not a channel-specific
          handle).</p>

        <tp:rationale>
391 392
          <p>On some protocols, the SelfHandle may change (as signalled by
            <tp:dbus-ref
Xavier Claessens's avatar
Xavier Claessens committed
393
              namespace="org.freedesktop.Telepathy">Connection.SelfContactChanged</tp:dbus-ref>),
394 395 396 397
            but this property is immutable. Hence, locally-requested channels'
            InitiatorHandle and InitiatorID may not match the current
            SelfHandle; <tp:member-ref>Requested</tp:member-ref> can be used to
            determine whether the channel was created locally.</p>
398 399 400 401 402 403 404 405
        </tp:rationale>

        <p>For channels requested by a remote user, this MUST be their handle.
          If unavailable or not applicable, this MUST be 0 (for instance,
          contact lists are not really initiated by anyone in particular, and
          it's easy to imagine a protocol where chatroom invitations can be
          anonymous).</p>

Will Thompson's avatar
Will Thompson committed
406 407 408
        <p>For channels with the <tp:dbus-ref
            namespace="org.freedesktop.Telepathy.Channel.Interface">Group</tp:dbus-ref>
          interface, this SHOULD be the same
409 410 411 412 413 414 415 416 417 418 419 420 421
          contact who is signalled as the "Actor" causing the self-handle
          to be placed in the local-pending set.</p>

        <p>This SHOULD NOT be a channel-specific handle, if possible.</p>

        <p>It does not make sense for this property to be in channel
          requests - the initiator will always be the local user - so it
          MUST NOT be accepted.</p>
      </tp:docstring>
    </property>

    <property name="InitiatorID" type="s" access="read"
      tp:name-for-bindings="Initiator_ID">
Simon McVittie's avatar
Simon McVittie committed
422
      <tp:added version="0.17.13">(as stable API)</tp:added>
423 424 425 426 427 428 429 430 431 432 433 434
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>The string that would result from inspecting the
          <tp:member-ref>InitiatorHandle</tp:member-ref>
          property (i.e. the initiator's identifier in the IM protocol).</p>

        <tp:rationale>
          <p>The presence of this property avoids the following race
            condition:</p>

          <ul>
            <li>New StreamedMedia channel C is signalled with initiator
              handle I</li>
Will Thompson's avatar
Will Thompson committed
435 436 437
            <li>Client calls <tp:dbus-ref
              namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref>(CONTACT,
              [I])</li>
438
            <li>Channel C closes, removing the last reference to handle I</li>
Will Thompson's avatar
Will Thompson committed
439 440 441
            <li><tp:dbus-ref
              namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref>(CONTACT,
              [I]) returns an error</li>
442 443 444 445 446 447 448 449 450 451 452
            <li>Client can indicate that a call was missed, but not who
              called!</li>
          </ul>
        </tp:rationale>

        <p>It does not make sense for this property to be in channel
          requests - the initiator will always be the local user - so it
          MUST NOT be accepted.</p>
      </tp:docstring>
    </property>

453 454
    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
    <p>All communication in the Telepathy framework is carried out via channel
455 456
    objects which are created and managed by connections. This interface must
    be implemented by all channel objects, along with one single channel type,
Will Thompson's avatar
Will Thompson committed
457 458
    such as <tp:dbus-ref
    namespace="org.freedesktop.Telepathy">Channel.Type.ContactList</tp:dbus-ref>
459
    which represents a list of people (such as a buddy list) or <tp:dbus-ref
Will Thompson's avatar
Will Thompson committed
460 461
    namespace="org.freedesktop.Telepathy">Channel.Type.Text</tp:dbus-ref> which
    represents a channel over which textual messages are sent and received.</p>
462

463
    <p>Each Channel's object path MUST start with the object path of
Will Thompson's avatar
Will Thompson committed
464 465 466 467
      its associated <tp:dbus-ref
      namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>, followed
      by '/'. There MAY be any number of additional object-path components,
      which clients MUST NOT attempt to parse.</p>
468 469 470 471 472 473 474

    <tp:rationale>
      <p>This ensures that Channel object paths are unique, even between
        Connections and CMs, because Connection object paths are
        guaranteed-unique via their link to the well-known bus name.</p>

      <p>If all connection managers in use are known to comply with at least
475
        spec version 0.17.10, then the Connection's object path can
476 477 478 479
        even be determined from the Channel's without any additional
        information, by taking the first 7 components.</p>
    </tp:rationale>

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
    <p>Each channel has a number of immutable properties (which cannot vary
      after the channel has been announced with <tp:dbus-ref
        namespace='ofdT.Connection.Interface.Requests'>NewChannels</tp:dbus-ref>),
      provided to clients in the
      <tp:dbus-ref namespace='ofdT.Client.Observer'>ObserveChannels</tp:dbus-ref>,
      <tp:dbus-ref namespace='ofdT.Client.Approver'>AddDispatchOperation</tp:dbus-ref> and
      <tp:dbus-ref namespace='ofdT.Client.Handler'>HandleChannels</tp:dbus-ref>
      methods to permit immediate identification of the channel. This interface
      contains immutable properties common to all channels. In brief:</p>

    <ul>
      <li><tp:member-ref>ChannelType</tp:member-ref> specifies the kind of
        communication carried out on this channel;</li>
      <li><tp:member-ref>TargetHandleType</tp:member-ref>,
        <tp:member-ref>TargetHandle</tp:member-ref> and
        <tp:member-ref>TargetID</tp:member-ref> specify the entity with which
        this channel communicates, such as the other party in a 1-1 call, or
        the name of a multi-user chat room;</li>
      <li><tp:member-ref>InitiatorHandle</tp:member-ref> and
        <tp:member-ref>InitiatorID</tp:member-ref> specify who created this
        channel;</li>
      <li><tp:member-ref>Requested</tp:member-ref> indicates whether the local
        user requested this channel, or whether it is an incoming call, a text
        conversation started by a remote contact, a chatroom invitation,
        etc.</li>
    </ul>

    <p>Other optional <tp:member-ref>Interfaces</tp:member-ref> can be
      implemented to indicate other available
Will Thompson's avatar
Will Thompson committed
509 510 511 512 513 514
      functionality, such as <tp:dbus-ref
        namespace="org.freedesktop.Telepathy">Channel.Interface.Group</tp:dbus-ref>
      if the channel contains a number of contacts, <tp:dbus-ref
        namespace="org.freedesktop.Telepathy">Channel.Interface.Password</tp:dbus-ref>
      to indicate that a channel may have a password set to require entry, and
      <tp:dbus-ref
515 516 517 518 519 520 521 522 523 524 525 526 527 528
        namespace="org.freedesktop.Telepathy">Channel.Interface.ChatState</tp:dbus-ref>
      for typing notifications. The interfaces implemented may not vary after
      the channel has been created. These other interfaces (along with the
      interface named by <tp:member-ref>ChannelType</tp:member-ref>) may
      themselves specify immutable properties to be announced up-front along
      with the properties on this interface.</p>

    <p>Some channels are “anonymous”, with
      <tp:member-ref>TargetHandleType</tp:member-ref> set to <code>None</code>,
      which indicates that the channel is defined by some other properties. For
      instance, transient ad-hoc chat rooms may be defined only by their members (as visible
      through the <tp:dbus-ref
        namespace="ofdT.Channel.Interface">Group</tp:dbus-ref>
      interface), and <tp:dbus-ref
529
        namespace='ofdT.Channel.Type'>ContactSearch</tp:dbus-ref>
530
      channels represent a single search attempt for a particular <tp:dbus-ref
531
        namespace='ofdT.Channel.Type.ContactSearch'>Server</tp:dbus-ref>.</p>
532

533
    <p>Specific connection manager implementations may implement channel types and
534 535 536 537 538 539
    interfaces which are not contained within this specification in order to
    support further functionality. To aid interoperability between client and
    connection manager implementations, the interfaces specified here should be
    used wherever applicable, and new interfaces made protocol-independent
    wherever possible. Because of the potential for 3rd party interfaces adding
    methods or signals with conflicting names, the D-Bus interface names should
540
    always be used to invoke methods and bind signals.</p>
541
    </tp:docstring>
542

543
    <tp:changed version="0.17.7">Previously we guaranteed that, for
544 545 546 547 548 549
      any handle type other than Handle_Type_None, and for any channel type
      and any handle, there would be no more than one channel with that
      combination of channel type, handle type and handle. This guarantee
      has now been removed in order to accommodate features like message
      threads.
    </tp:changed>
550

551
    <tp:changed version="0.17.10">Previously we did not explicitly
552 553 554
      guarantee that Channels' object paths had the Connection's object path
      as a prefix.
    </tp:changed>
555 556 557
  </interface>
</node>
<!-- vim:set sw=2 sts=2 et ft=xml: -->