[Telepathy] [patch] Spec clarifications for Renaming and
channel-specific handles
Simon McVittie
simon.mcvittie at collabora.co.uk
Mon Apr 9 04:58:33 PDT 2007
Proposed spec clarifications attached, since the Merge Monkey
<http://projects.collabora.co.uk/~monkey/> isn't currently working.
-------------- next part --------------
New patches:
[Insist that handle names are distinct between channels with channel-specific handles, and between general-purpose handles and any such channel
Simon McVittie <simon.mcvittie at collabora.co.uk>**20070409114358]
<
> {
hunk ./spec/Channel_Interface_Group.xml 129
</tp:docstring>
</tp:flag>
<tp:flag suffix="Channel_Specific_Handles" value="256">
- <tp:docstring>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>
The members of this group have handles which are specific to
this channel, and are not valid as general-purpose handles on
the connection. Depending on the channel, it may be possible to
hunk ./spec/Channel_Interface_Group.xml 137
call GetHandleOwners to find the owners of these handles, which
should be done if you wish to eg subscribe to the contact's
presence.
+ </p>
+
+ <p>
+ To avoid ambiguity, connection managers must ensure that any
+ given handle is not simultaneously a general-purpose handle and a
+ channel-specific handle, and must ensure that any given handle
+ is not a channel-specific handle in more than one channel.
+ If the protocol does not already ensure this, the connection
+ manager must alter the strings associated with the handles,
+ for example prefixing channel-specific names with the channel's
+ name.
+ </p>
</tp:docstring>
</tp:flag>
<tp:flag suffix="Only_One_Group" value="512">
}
[Specify the interaction between GetSelfHandle and Renaming
Simon McVittie <simon.mcvittie at collabora.co.uk>**20070409114503]
<
> {
hunk ./spec/Connection.xml 71
</arg>
<tp:docstring>
Get the handle which represents the user on this connection, which will
- remain valid for the lifetime of this connection or until the user's
- identifier changes. This is always a CONTACT type handle.
+ remain valid for the lifetime of this connection, or until a change
+ in the user's identifier is signalled by the Renamed signal on the
+ Renaming interface (if present). This is always a CONTACT type handle.
</tp:docstring>
<tp:possible-errors>
<tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
}
[Specify that HoldHandles is idempotent, matching current CM behaviour (we're not doing distributed refcounting - if clients want refcounting they should implement it themselves)
Simon McVittie <simon.mcvittie at collabora.co.uk>**20070409114612]
<
> {
hunk ./spec/Connection.xml 100
A array of integer handles to hold
</tp:docstring>
</arg>
- <tp:docstring>
- Notify the connection manger that your client is holding a copy
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Notify the connection manger that your client is holding a copy
of handles which may not be in use in any existing channel or
list, and were not obtained by using the RequestHandles method. For
example, a handle observed in an emitted signal, or displayed
hunk ./spec/Connection.xml 108
somewhere in the UI that is not associated with a channel. The
connection manager must not deallocate a handle where any clients
have used this method to indicate it is in use until the ReleaseHandle
- method is called, or the clients disappear from the bus.
+ method is called, or the clients disappear from the bus.</p>
+
+ <p>Note that HoldHandles is idempotent - calling it multiple times
+ is equivalent to calling it once. If a handle is "referenced" by
+ several components which share a D-Bus unique name, the client
+ should perform reference counting internally, and only call
+ ReleaseHandles when none of the cooperating components need the
+ handle any longer.</p>
</tp:docstring>
<tp:possible-errors>
<tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
hunk ./spec/Connection.xml 224
Explicitly notify the connection manager that your client is no
longer holding any references to the given handles, and that they
may be deallocated if they are not held by any other clients or
- referenced by any existing channels.
+ referenced by any existing channels. See HoldHandles for notes.
</tp:docstring>
<tp:possible-errors>
<tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
}
[Specify that Renaming does not cause MembersChanged to be emitted too, matching Idle behaviour
Simon McVittie <simon.mcvittie at collabora.co.uk>**20070409114614]
<
> {
hunk ./spec/Connection_Interface_Renaming.xml 34
The handle of the new identifier
</tp:docstring>
</arg>
- <tp:docstring>
- Emitted when the unique identifier of a contact on the server changes.
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Emitted when the unique identifier of a contact on the server
+ changes.</p>
+
+ <p>If the contact's original handle is associated with any channel
+ (i.e. it would be returned by GetHandle()) then the client
+ must behave as though their new handle is now associated with that
+ channel.</p>
+
+ <p>If the contact's old handle is in any of the member lists of
+ a channel which has the groups interface and does not have the
+ Channel_Specific_Handles flag, then it is silently removed
+ and the new handle is added. No MembersChanged signal is emitted,
+ as this would be redundant with the Renamed signal; this makes
+ client support for this interface somewhat important.
+ </p>
+
+ <p>In general, other objects with associated handles or lists of
+ handles must have behaviour equivalent to the above.
+ </p>
+
+ <p>However, if a client has held the handle with HoldHandles, the
+ "hold" is <strong>not</strong> transferred to the new handle.</p>
+
+ <p>The handles may be either general-purpose or channel-specific;
+ the constraints placed on the names of channel-specific handles
+ must avoid unambiguity. If the original handle is general-purpose,
+ the new handle must be general-purpose; if the original handle
+ is channel-specific, the new handle must be channel-specific in
+ the same channel.
+ </p>
</tp:docstring>
</signal>
<method name="RequestRename">
}
[In RequestRename, say nothing about the validity of the handles - that's up to the spec for GetSelfHandle and Renaming. However, do specify that the CM might have to normalize the new identifier.
Simon McVittie <simon.mcvittie at collabora.co.uk>**20070409115007]
<
> {
hunk ./spec/Connection_Interface_Renaming.xml 73
The desired identifier
</tp:docstring>
</arg>
- <tp:docstring>
- Request that the users own identifier is changed on the server. Success
- is indicated by a Renamed signal being emitted. A new handle will be
- allocated for the user's new identifier, and remain valid for the
- lifetime of the connection.
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Request that the user's own identifier is changed on the server.
+ If successful, a Renamed signal will be emitted for the current
+ "self handle" as returned by GetSelfHandle.</p>
+ <p>It is protocol-dependent how the identifier that's actually
+ used will be derived from the supplied identifier; some sort of
+ normalization might take place.</p>
</tp:docstring>
<tp:possible-errors>
<tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
}
[Strongly recommend support for the Renaming interface - clients that don't support it will be very confused by CMs that use it, e.g. Idle.
Simon McVittie <simon.mcvittie at collabora.co.uk>**20070409115124]
<
> {
hunk ./spec/Connection_Interface_Renaming.xml 89
<tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
</tp:possible-errors>
</method>
- <tp:docstring>
- An interface on connections to support protocols where the unique
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An interface on connections to support protocols where the unique
identifiers of contacts can change. Because handles are immutable,
this is represented by a pair of handles, that representing the
hunk ./spec/Connection_Interface_Renaming.xml 93
- old name, and that representing the new one.
+ old name, and that representing the new one.</p>
+ <p>Client support for this interface is strongly recommended, as the
+ semantics of the interface mean that clients that do not listen for
+ the Renamed signal and update their internal state accordingly
+ will become very confused when used with connection managers that
+ do support it.</p>
</tp:docstring>
</interface>
</node>
}
Context:
[Document Media_Stream_Base_Proto so telepathy-glib will be 100% documented
Simon McVittie <simon.mcvittie at collabora.co.uk>**20070405161308]
[Correctly put docstrings for Media_Stream_Type inside the <tp:docstring>
Simon McVittie <simon.mcvittie at collabora.co.uk>**20070405161248]
[s/LocalPending/Local_Pending and s/RemotePending/Remote_Pending
Guillaume Desmottes <guillaume.desmottes at collabora.co.uk>**20070404182048]
[Fix FSF address in regression tests too
Simon McVittie <simon.mcvittie at collabora.co.uk>**20070329101642]
[Fix address (FSF moved ages ago)
Thomas Zander <zander at kde.org>**20070327173439]
[add ID to GetDBusNames/DBusNamesChanged
Dafydd Harries <dafydd.harries at collabora.co.uk>**20070321194610]
[improve docstrings
Dafydd Harries <dafydd.harries at collabora.co.uk>**20070321165739]
[make DBusNamesChanged emit added/removed rather than all participants
Dafydd Harries <dafydd.harries at collabora.co.uk>**20070321165701]
[TubeClosed is a signal, not a method
Dafydd Harries <dafydd.harries at collabora.co.uk>**20070321163452]
[fix copyright year
Dafydd Harries <dafydd.harries at collabora.co.uk>**20070321162209]
[add tube initiator to ListTubes
Dafydd Harries <dafydd.harries at collabora.co.uk>**20070321151904]
[GetDBusNames/DBusNamesChanges
Dafydd Harries <dafydd.harries at collabora.co.uk>**20070321150209]
[include Channel_Type_Tubes.xml in all.xml
Dafydd Harries <dafydd.harries at collabora.co.uk>**20070321144403]
[fix grouping in all.xml
Dafydd Harries <dafydd.harries at collabora.co.uk>**20070321144345]
[add Channel.Type.Tubes
Dafydd Harries <dafydd.harries at collabora.co.uk>**20070321143450]
[remove unnecessary import from make_all_async.py
Dafydd Harries <dafydd.harries at collabora.co.uk>**20070319173331]
[bump version to 0.15.0.1
robert.mcqueen at collabora.co.uk**20070222201635]
[Include s:stun-server and q:stun-port in list of well-known connection parameters
Simon McVittie <simon.mcvittie at collabora.co.uk>**20070321160836]
[GetHandleOwners raises NotAvailable for channels you shouldn't have called it on (those without CHANNEL_SPECIFIC_HANDLES)
Simon McVittie <simon.mcvittie at collabora.co.uk>**20070320170901]
[Adapt Python errors generator so it can be run on all.xml
Simon McVittie <simon.mcvittie at collabora.co.uk>**20070302123656]
[[Copied from Gabble] Alter genginterface.py so it doesn't need dbus-python or Python 2.4
Simon McVittie <simon.mcvittie at collabora.co.uk>**20070302114508]
[TAG telepathy-spec 0.15.0
robert.mcqueen at collabora.co.uk**20070222195944]
Patch bundle hash:
4121b7cda711b4d3d75b994313e979c4280a8bf4
More information about the Telepathy
mailing list