355
355
access="read" tp:name-for-bindings="Initiator_Handle">
356
356
<tp:added version="0.17.13">(as stable API)</tp:added>
357
357
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
358
<p>The contact who initiated the channel. For channels requested by the
358
<p>The contact who initiated the channel; for instance, the contact
359
who invited the local user to a chatroom, or the contact who
360
initiated a call.</p>
362
<p>This does <em>not</em> necessarily represent the contact who
363
created the underlying protocol-level construct. For instance, if
364
Rob creates a chatroom, Will joins that chatroom, and Will invites Simon
365
to join it, then Simon will see Will as the InitiatorHandle of the
366
channel representing the chatroom.</p>
369
<p>The room creator is generally a less useful piece of information
370
than the inviter, is less likely to be available at invitation
371
time (i.e. can't necessarily be an immutable property), and is
372
less likely to be available at all. The creator of a chatroom
373
is not currently available via Telepathy; if added in future, it
374
is likely to be made available as a property on the Chatroom
376
href="http://bugs.freedesktop.org/show_bug.cgi?id=23151">bug 23151</a>).</p>
379
<p>For channels requested by the
359
380
local user, this MUST be the value of
360
381
<tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.SelfHandle</tp:dbus-ref>
361
382
at the time the channel was created (i.e. not a channel-specific
365
<p>The careful wording about the self-handle is because the Renaming
366
interface can cause the return from Connection.GetSelfHandle to
367
change. It's something of a specification bug that we don't signal
368
this in the Connection interface yet.</p>
386
<p>On some protocols, the SelfHandle may change (as signalled by
388
namespace="org.freedesktop.Telepathy">Connection.SelfHandleChanged</tp:dbus-ref>),
389
but this property is immutable. Hence, locally-requested channels'
390
InitiatorHandle and InitiatorID may not match the current
391
SelfHandle; <tp:member-ref>Requested</tp:member-ref> can be used to
392
determine whether the channel was created locally.</p>
371
395
<p>For channels requested by a remote user, this MUST be their handle.
448
472
information, by taking the first 7 components.</p>
451
<p>Each channel may have an immutable handle associated with it, which
452
may be any handle type, such as a contact, room or list handle,
453
indicating that the channel is for communicating with that handle.</p>
455
<p>If a channel does not have a handle (an "anonymous channel" with
456
Target_Handle = 0 and Target_Handle_Type = Handle_Type_None), it
457
means that the channel is defined by some other terms, such as it
458
may be a transient group defined only by its members as visible
459
through the <tp:dbus-ref
460
namespace="org.freedesktop.Telepathy">Channel.Interface.Group</tp:dbus-ref>
463
<p>Other optional interfaces can be implemented to indicate other available
475
<p>Each channel has a number of immutable properties (which cannot vary
476
after the channel has been announced with <tp:dbus-ref
477
namespace='ofdT.Connection.Interface.Requests'>NewChannels</tp:dbus-ref>),
478
provided to clients in the
479
<tp:dbus-ref namespace='ofdT.Client.Observer'>ObserveChannels</tp:dbus-ref>,
480
<tp:dbus-ref namespace='ofdT.Client.Approver'>AddDispatchOperation</tp:dbus-ref> and
481
<tp:dbus-ref namespace='ofdT.Client.Handler'>HandleChannels</tp:dbus-ref>
482
methods to permit immediate identification of the channel. This interface
483
contains immutable properties common to all channels. In brief:</p>
486
<li><tp:member-ref>ChannelType</tp:member-ref> specifies the kind of
487
communication carried out on this channel;</li>
488
<li><tp:member-ref>TargetHandleType</tp:member-ref>,
489
<tp:member-ref>TargetHandle</tp:member-ref> and
490
<tp:member-ref>TargetID</tp:member-ref> specify the entity with which
491
this channel communicates, such as the other party in a 1-1 call, or
492
the name of a multi-user chat room;</li>
493
<li><tp:member-ref>InitiatorHandle</tp:member-ref> and
494
<tp:member-ref>InitiatorID</tp:member-ref> specify who created this
496
<li><tp:member-ref>Requested</tp:member-ref> indicates whether the local
497
user requested this channel, or whether it is an incoming call, a text
498
conversation started by a remote contact, a chatroom invitation,
502
<p>Other optional <tp:member-ref>Interfaces</tp:member-ref> can be
503
implemented to indicate other available
464
504
functionality, such as <tp:dbus-ref
465
505
namespace="org.freedesktop.Telepathy">Channel.Interface.Group</tp:dbus-ref>
466
506
if the channel contains a number of contacts, <tp:dbus-ref
467
507
namespace="org.freedesktop.Telepathy">Channel.Interface.Password</tp:dbus-ref>
468
508
to indicate that a channel may have a password set to require entry, and
470
namespace="org.freedesktop.Telepathy">Properties</tp:dbus-ref> for
471
extra data about channels which represent chat rooms or voice calls. The
472
interfaces implemented may not vary after the channel's creation has been
473
signalled to the bus (with the connection's <tp:dbus-ref
474
namespace="org.freedesktop.Telepathy.Connection">NewChannel</tp:dbus-ref>
510
namespace="org.freedesktop.Telepathy">Channel.Interface.ChatState</tp:dbus-ref>
511
for typing notifications. The interfaces implemented may not vary after
512
the channel has been created. These other interfaces (along with the
513
interface named by <tp:member-ref>ChannelType</tp:member-ref>) may
514
themselves specify immutable properties to be announced up-front along
515
with the properties on this interface.</p>
517
<p>Some channels are “anonymous”, with
518
<tp:member-ref>TargetHandleType</tp:member-ref> set to <code>None</code>,
519
which indicates that the channel is defined by some other properties. For
520
instance, transient ad-hoc chat rooms may be defined only by their members (as visible
521
through the <tp:dbus-ref
522
namespace="ofdT.Channel.Interface">Group</tp:dbus-ref>
523
interface), and <tp:dbus-ref
524
namespace='ofdT.Channel.Type'>ContactSearch</tp:dbus-ref>
525
channels represent a single search attempt for a particular <tp:dbus-ref
526
namespace='ofdT.Channel.Type.ContactSearch'>Server</tp:dbus-ref>.</p>
477
528
<p>Specific connection manager implementations may implement channel types and
478
529
interfaces which are not contained within this specification in order to
added
removed
spec/Channel.xml
