diff options
| -rw-r--r-- | NEWS | 28 | ||||
| -rw-r--r-- | configure.ac | 8 | ||||
| -rw-r--r-- | spec/Channel_Dispatch_Operation.xml | 331 | ||||
| -rw-r--r-- | spec/Channel_Dispatcher.xml | 222 | ||||
| -rw-r--r-- | spec/Channel_Dispatcher_Interface_Operation_List.xml | 138 | ||||
| -rw-r--r-- | spec/Channel_Interface_Call_State.xml | 8 | ||||
| -rw-r--r-- | spec/Channel_Interface_Destroyable.xml | 79 | ||||
| -rw-r--r-- | spec/Channel_Request.xml | 178 | ||||
| -rw-r--r-- | spec/Client.xml | 123 | ||||
| -rw-r--r-- | spec/Client_Approver.xml | 135 | ||||
| -rw-r--r-- | spec/Client_Handler.xml | 268 | ||||
| -rw-r--r-- | spec/Client_Observer.xml | 230 | ||||
| -rw-r--r-- | spec/Makefile.am | 9 | ||||
| -rw-r--r-- | spec/all.xml | 34 | ||||
| -rw-r--r-- | spec/errors.xml | 21 | ||||
| -rw-r--r-- | spec/generic-types.xml | 3 | ||||
| -rw-r--r-- | telepathy-glib/Makefile.am | 3 | ||||
| -rw-r--r-- | telepathy-glib/channel-manager.c | 6 | ||||
| -rw-r--r-- | telepathy-glib/connection.c | 2 | ||||
| -rw-r--r-- | telepathy-glib/versions/0.7.16.abi | 9 |
20 files changed, 1810 insertions, 25 deletions
@@ -1,15 +1,37 @@ -telepathy-glib 0.7.16 (UNRELEASED) +telepathy-glib 0.7.16 (2008-09-26) ================================== +The "could you say that again? I was looking at that bee" release. + Dependencies: -Deprecations: +* To use --enable-gtk-doc you must now have at least gtkdoc 1.10 Enhancements: +* Updated to spec 0.17.12, mainly featuring EnsureChannel + +* We now support EnsureChannel on the Requests interface - to implement this, + put a suitable function pointer in TpChannelManagerIface::ensure_channel + +* Channel factories' RequestChannel implementations no longer need to + validate handles - TpBaseConnection now does this automatically + +* Added a function to compare presence types in order of "availability" + Fixes: -Release notes for projects using code generation: +* The gtkdoc now documents GInterfaces' signals and properties (fd.o #16995, + fd.o #17308) + +* TpBaseConnection::self_handle is unreffed and cleared slightly later, + for the benefit of channel managers that want to use it in their + status-changed(Disconnected) callback + +* Fixed a compiler warning on platforms with daemon(3) in their libc + +* TpChannelManager can no longer be crashed by asking for unsupported + handle types telepathy-glib 0.7.15 (2008-09-18) ================================== diff --git a/configure.ac b/configure.ac index 05a511200..7fc5e8a16 100644 --- a/configure.ac +++ b/configure.ac @@ -11,8 +11,8 @@ AC_PREREQ([2.59]) m4_define([tp_glib_major_version], [0]) m4_define([tp_glib_minor_version], [7]) -m4_define([tp_glib_micro_version], [15]) -m4_define([tp_glib_nano_version], [1]) +m4_define([tp_glib_micro_version], [16]) +m4_define([tp_glib_nano_version], [0]) # If library source has changed since last release, increment revision # If interfaces have been added, removed or changed since last release, @@ -26,9 +26,9 @@ m4_define([tp_glib_nano_version], [1]) # (we don't guarantee that we won't add ABI then remove it again, if it was # never seen in a release). -m4_define([tp_glib_lt_current], [16]) +m4_define([tp_glib_lt_current], [17]) m4_define([tp_glib_lt_revision], [0]) -m4_define([tp_glib_lt_age], [16]) +m4_define([tp_glib_lt_age], [17]) # Some magic m4_define([tp_glib_base_version], diff --git a/spec/Channel_Dispatch_Operation.xml b/spec/Channel_Dispatch_Operation.xml new file mode 100644 index 000000000..dfd4ec3e2 --- /dev/null +++ b/spec/Channel_Dispatch_Operation.xml @@ -0,0 +1,331 @@ +<?xml version="1.0" ?> +<node name="/Channel_Dispatch_Operation" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + + <tp:copyright>Copyright (C) 2008 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright (C) 2008 Nokia Corporation</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="org.freedesktop.Telepathy.ChannelDispatchOperation.DRAFT" + tp:causes-havoc="experimental"> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A channel dispatch operation is an object in the ChannelDispatcher + representing a bundle of unrequested channels being announced to + client + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Client">Approver.DRAFT</tp:dbus-ref> + processes.</p> + + <p>These objects can result from new incoming channels or channels + which are automatically created for some reason, but cannot result + from outgoing requests for channels.</p> + + <p>More specifically, whenever the + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.NewChannels</tp:dbus-ref> + signal contains channels whose + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.FUTURE.Requested</tp:dbus-ref> + property is false, or whenever the + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.NewChannel</tp:dbus-ref> + signal contains a channel with suppress_handler false, + one or more ChannelDispatchOperation objects are created for those + channels.</p> + + <p>(If some channels in a NewChannels signal are in different bundles, + this is an error. The channel dispatcher SHOULD recover by treating + the NewChannels signal as if it had been several NewChannels signals + each containing one channel.)</p> + + <p>First, the channel dispatcher SHOULD construct a list of all the + channel handlers that could handle all the channels, ordered by + priority in some implementation-dependent way. If there are handlers + which could handle all the channels, one channel dispatch operation + SHOULD be created for all the channels. If there are not, one channel + dispatch operation SHOULD be created for each channel, each with + a list of channel handlers that could handle that channel.</p> + + <p>When listing channel handlers, priority SHOULD be given to + channel handlers that are already handling channels from the same + bundle.</p> + + <p>Processing of a channel dispatch operation proceeds as follows. + If the channels in a channel dispatch operation are in the same + bundle as a channel that is already being handled, and the handler + could also handle the channels being dispatched, the channel + dispatcher SHOULD call the handler's + HandleAdditionalChannels + method to see whether the handler will accept the new channels too. + If the handler takes responsibility for the channels, + processing stops, and no approvers are run.</p> + + <p>(FIXME: this is far too subtle and everyone will get it wrong. + Open issue: how else do we address this use case?)</p> + + <tp:rationale> + <p>Some channel types can be picked up "quietly" by an existing + channel handler. If a Text channel is added to an existing + bundle containing a StreamedMedia channel, there shouldn't be + any approvers, flashing icons or notification bubbles, if the + the UI for the StreamedMedia channel can just add a text box + and display the message.</p> + </tp:rationale> + + <p>If not, the channel dispatcher SHOULD send the channel dispatch + operation to all relevant approvers (in parallel) and wait for an + approver to claim the channels or request that they are handled. + See + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client.Approver.DRAFT">AddDispatchOperation</tp:dbus-ref> + for more details on this.</p> + + <p>Finally, if the approver requested it, the channel dispatcher SHOULD + send the channels to a handler.</p> + </tp:docstring> + + <property name="Interfaces" tp:name-for-bindings="Interfaces" + type="as" access="read" tp:type="DBus_Interface[]"> + <tp:docstring> + A list of the extra interfaces provided by this channel dispatch + operation. This property cannot change. + </tp:docstring> + </property> + + <property name="Connection" tp:name-for-bindings="Connection" + type="o" access="read"> + <tp:docstring> + The <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref> + with which the <tp:member-ref>Channels</tp:member-ref> are + associated. The well-known bus name to use can be derived from + this object path by removing the leading '/' and replacing all + subsequent '/' by '.'. This property cannot change. + </tp:docstring> + </property> + + <property name="Account" tp:name-for-bindings="Account" + type="o" access="read"> + <tp:docstring> + The <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref> + with which the <tp:member-ref>Connection</tp:member-ref> + and <tp:member-ref>Channels</tp:member-ref> are + associated. This property cannot change. + </tp:docstring> + </property> + + <property name="Channels" tp:name-for-bindings="Channels" + type="a(oa{sv})" access="read" tp:type="Channel_Details[]"> + <tp:docstring> + The <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Channel</tp:dbus-ref>s + to be dispatched, and their properties. Change notification is via + the <tp:member-ref>ChannelLost</tp:member-ref> signal (channels + cannot be added to this property, only removed). + </tp:docstring> + </property> + + <signal name="ChannelLost" tp:name-for-bindings="Channel_Lost"> + <tp:docstring> + A channel has closed before it could be claimed or handled. + </tp:docstring> + + <arg name="Error" type="s" tp:type="DBus_Error_Name"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The name of a D-Bus error indicating why the channel closed. If + no better reason can be found, + <code>org.freedesktop.Telepathy.Errors.NotAvailable</code> MAY + be used as a fallback; this means that this error SHOULD NOT be + given any more specific meaning.</p> + + <p>FIXME: or should we invent a new OtherError for that purpose?</p> + + <p>FIXME: we need to specify errors for these situations:</p> + + <ul> + <li>kicked from a chatroom</li> + <li>outgoing call rejected</li> + <li>outgoing call timed out</li> + <li>incoming call terminated</li> + </ul> + </tp:docstring> + </arg> + + <arg name="Message" type="s"> + <tp:docstring> + A string associated with the D-Bus error. + </tp:docstring> + </arg> + </signal> + + <property name="PossibleHandlers" tp:name-for-bindings="Possible_Handlers" + type="as" access="read" tp:type="DBus_Well_Known_Name[]"> + <tp:docstring> + The well known bus names (starting with + <code>org.freedesktop.Telepathy.Client.</code>) of the possible + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client">Handler</tp:dbus-ref>s + for these channels. The channel dispatcher MUST place the most + preferred handlers first, according to some reasonable heuristic. + As a result, approvers SHOULD use the first handler by default. + </tp:docstring> + </property> + + <method name="HandleWith" tp:name-for-bindings="Handle_With"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Called by an approver to accept a channel bundle and request that + the given handler be used to handle it.</p> + + <p>If successful, this method will cause the ChannelDispatchOperation + object to disappear, emitting + <tp:member-ref>Finished</tp:member-ref>.</p> + + <p>However, this method may fail because the dispatch has already been + completed and the object has already gone. If this occurs, it + indicates that another approver has asked for the bundle to be + handled by a particular handler. The approver MUST NOT attempt + to interact with the channels further in this case, unless it is + separately invoked as the handler.</p> + + <p>Approvers which are also channel handlers SHOULD use Claim instead + of HandleWith to request that they can handle a channel bundle + themselves.</p> + + <p>(FIXME: list some possible errors)</p> + + <p>If the channel handler raises an error from Handle, this method + MAY respond by raising that same error, even if it is not + specifically documented here.</p> + </tp:docstring> + + <arg direction="in" type="s" tp:type="DBus_Bus_Name" name="Handler"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The well-known bus name (starting with + <code>org.freedesktop.Telepathy.Client.</code>) of the channel + handler that should handle the channel.</p> + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + The selected handler is not a syntactically correct + <tp:type>DBus_Bus_Name</tp:type> or does not start with + "<code>org.freedesktop.Telepathy.Client.</code>". + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + The selected handler is temporarily unable to handle these + channels. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + The selected handler is syntactically correct, but will never + be able to handle these channels (for instance because the channels + do not match its HandlerChannelFilter, or because HandleChannels + raised NotImplemented). + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotYours"> + <tp:docstring> + At the time that HandleWith was called, this dispatch operation was + processing an earlier call to HandleWith. The earlier call has + now succeeded, so some Handler nominated by another approver is + now responsible for the channels. In this situation, the second + call to HandleWith MUST NOT return until the first one has + returned successfully or unsuccessfully, and if the first call + to HandleChannels fails, the channel dispatcher SHOULD try to obey + the choice of Handler made by the second call to HandleWith. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="Claim" tp:name-for-bindings="Claim"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Called by an approver to claim channels for handling + internally. If this method is called successfully, the process + calling this method becomes the handler for the channel, but + <em>does not</em> have the HandleChannels method called on it.</p> + <!-- FIXME: tp:dbus-ref --> + + <p>Clients that call Claim on channels but do not immediately + close them SHOULD implement the Handler interface and its + CurrentlyHandledChannels property.</p> + <!-- FIXME: tp:dbus-ref --> + + <p>Approvers wishing to reject channels MUST call this method to + claim ownership of them, and MUST NOT call + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">Close</tp:dbus-ref> + on the channels unless/until this method returns successfully.</p> + + <tp:rationale> + <p>The channel dispatcher can't know how best to close arbitrary + channel types, so it leaves it up to the approver to do so. + For instance, for Text channels it is necessary + to acknowledge any messages that have already been displayed to + the user first - ideally, the approver would display and then + acknowledge the messages.</p> + </tp:rationale> + + <p>If successful, this method will cause the ChannelDispatchOperation + object to disappear, emitting + <tp:member-ref>Finished</tp:member-ref>, in the same way as for + <tp:member-ref>HandleWith</tp:member-ref>.</p> + + <p>This method may fail because the dispatch operation has already + been completed. Again, see HandleWith for more details. The approver + MUST NOT attempt to interact with the channels further in this + case.</p> + + <p>(FIXME: list some other possible errors)</p> + </tp:docstring> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NotYours"> + <tp:docstring> + At the time that Claim was called, this dispatch operation was + processing a call to HandleWith which has now succeeded, so + some Handler nominated by another approver is now responsible for + the channel. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <signal name="Finished" tp:name-for-bindings="Finished"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Emitted when this dispatch operation finishes. The dispatch + operation is no longer present and further methods must not be + called on it.</p> + + <p>Its object path SHOULD NOT be reused for a subsequent dispatch + operation; the ChannelDispatcher MUST choose object paths + in a way that avoids immediate re-use.</p> + + <tp:rationale> + <p>Otherwise, clients might accidentally call HandleWith or Claim + on a new dispatch operation instead of the one they + intended to handle.</p> + </tp:rationale> + </tp:docstring> + </signal> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Channel_Dispatcher.xml b/spec/Channel_Dispatcher.xml new file mode 100644 index 000000000..822e7dd9a --- /dev/null +++ b/spec/Channel_Dispatcher.xml @@ -0,0 +1,222 @@ +<?xml version="1.0" ?> +<node name="/Channel_Dispatcher" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + + <tp:copyright>Copyright (C) 2008 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright (C) 2008 Nokia Corporation</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="org.freedesktop.Telepathy.ChannelDispatcher.DRAFT" + tp:causes-havoc="experimental"> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The channel dispatcher is responsible for responding to new + channels and launching client processes to handle them. It also + provides functionality for client processes to request that new + channels are created.</p> + + <p>If a channel dispatcher is running, it is responsible for dispatching + new channels on all + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>s + created by the + <tp:dbus-ref namespace="org.freedesktop.Telepathy">AccountManager</tp:dbus-ref>. + Connections not created by the AccountManager are outside the scope + of the channel dispatcher.</p> + + <tp:rationale> + <p>Connections created by standalone Telepathy clients + that do not intend to interact with the channel dispatcher + should be ignored - otherwise, the channel dispatcher would try + to launch handlers for channels that the standalone client + was already handling internally.</p> + </tp:rationale> + + <p>The current channel dispatcher is defined to be the process that + owns the well-known bus name + <code>org.freedesktop.Telepathy.ChannelDispatcher</code> on + the session bus. This process MUST export an object with this + interface at the object path + <code>/org/freedesktop/Telepathy/ChannelDispatcher</code>.</p> + + <p>Until a mechanism exists for making a reasonable automatic choice + of ChannelDispatcher implementation, implementations SHOULD NOT + register as an activatable service for the ChannelDispatcher's + well-known bus name. Instead, it is RECOMMENDED that some component + of the user's session will select and activate a particular + implementation, and that other Telepathy-enabled programs + can detect whether channel request/dispatch functionality is available + by checking whether the ChannelDispatcher's well-known name is in use + at runtime.</p> + + <p>There are three categories of client process defined by this + specification:</p> + + <dl> + <dt>Observer</dt> + <dd><p>Observers monitor the creation of new channels. This + functionality can be used for things like message logging. + All observers are notified simultaneously.</p></dd> + + <dt>Approver</dt> + <dd> + <p>Approvers notify the user that new channels have been created, + and also select which channel handler will be used for the channel, + either by asking the user or by choosing the most appropriate + channel handler.</p> + </dd> + + <dt>Handler</dt> + <dd> + <p>Each new channel or set of channels is passed to exactly one + handler as its final destination. A typical channel handler is a + user interface process handling channels of a particular type.</p> + </dd> + </dl> + </tp:docstring> + + <property name="Interfaces" tp:name-for-bindings="Interfaces" + type="as" access="read" tp:type="DBus_Interface[]"> + <tp:docstring> + A list of the extra interfaces provided by this channel dispatcher. + </tp:docstring> + </property> + + <method name="CreateChannel" tp:name-for-bindings="Create_Channel"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Start a request to create a channel. This initially just creates a + <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest.DRAFT</tp:dbus-ref> + object, which can be used to continue the request and track its + success or failure.</p> + + <tp:rationale> + <p>The request can take a long time - in the worst case, the + channel dispatcher has to ask the account manager to put the + account online, the account manager has to ask the operating + system to obtain an Internet connection, and the operating + system has to ask the user whether to activate an Internet + connection using an on-demand mechanism like dialup.</p> + + <p>This means that using a single D-Bus method call and response + to represent the whole request will tend to lead to that call + timing out, which is not the behaviour we want.</p> + </tp:rationale> + + <p>If this method is called for an Account that is disabled, invalid + or otherwise unusable, no error is signalled until + <tp:dbus-ref + namespace="org.freedesktop.Telepathy">ChannelRequest.DRAFT.Proceed</tp:dbus-ref> + is called, at which point + <tp:dbus-ref + namespace="org.freedesktop.Telepathy">ChannelRequest.DRAFT.Failed</tp:dbus-ref> + is emitted with an appropriate error.</p> + + <tp:rationale> + <p>This means there's only one code path for errors, apart from + InvalidArgument for "that request makes no sense".</p> + + <p>It also means that the request will proceed if the account is + enabled after calling CreateChannel, but before calling + Proceed.</p> + </tp:rationale> + </tp:docstring> + + <arg direction="in" name="Account" type="o"> + <tp:docstring> + The + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref> + for which the new channel is to be created. + </tp:docstring> + </arg> + + <arg direction="in" name="Requested_Properties" type="a{sv}" + tp:type="Qualified_Property_Value_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A dictionary containing desirable properties. This has the same + semantics as the corresponding parameter to + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>. + </p> + + <p>Certain properties will not necessarily make sense in this + dictionary: for instance, + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref> + can only be given if the requester is able to interact with a + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref> + to the desired account.</p> + </tp:docstring> + </arg> + + <arg direction="in" name="User_Action_Time" type="t" + tp:type="Unix_Timestamp64"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The time at which user action occurred, or 0 if this channel + request is for some reason not involving user action. + The <tp:dbus-ref + namespace="org.freedesktop.Telepathy.ChannelRequest.DRAFT">UserActionTime</tp:dbus-ref> + property will be set to this value.</p> + </tp:docstring> + </arg> + + <arg direction="in" name="Preferred_Handler" type="s" + tp:type="DBus_Well_Known_Name"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Either the well-known bus name (starting with + <code>org.freedesktop.Telepathy.Client.</code>) + of the preferred handler for this + channel, or an empty string to indicate that any handler would be + acceptable. The channel dispatcher SHOULD dispatch as many as + possible of the resulting channels (ideally, all of them) + to that handler, and SHOULD remember the preferred handler + so it can try to dispatch subsequent channels in the same bundle + to the same handler.</p> + + <tp:rationale> + <p>This must be the well-known bus name, not the unique name, + to ensure that all handlers do indeed have the Client API, + and the Client object on the handler can be located easily.</p> + + <p>This is partly so the channel dispatcher can call + HandleChannel on it, and partly so the channel dispatcher + can recover state if it crashes and is restarted.</p> + </tp:rationale> + </tp:docstring> + </arg> + + <arg direction="out" name="Request" type="o"> + <tp:docstring> + A + <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest.DRAFT</tp:dbus-ref> + object. + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + The Preferred_Handler is syntactically invalid or does + not start with <code>org.freedesktop.Telepathy.Client.</code>, + the Account does not exist, or one of the Requested_Properties + is invalid + </tp:docstring> + </tp:error> + </tp:possible-errors> + + </method> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Channel_Dispatcher_Interface_Operation_List.xml b/spec/Channel_Dispatcher_Interface_Operation_List.xml new file mode 100644 index 000000000..40cd86e54 --- /dev/null +++ b/spec/Channel_Dispatcher_Interface_Operation_List.xml @@ -0,0 +1,138 @@ +<?xml version="1.0" ?> +<node name="/Channel_Dispatcher_Interface_Operation_List" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + + <tp:copyright>Copyright (C) 2008 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright (C) 2008 Nokia Corporation</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="org.freedesktop.Telepathy.ChannelDispatcher.Interface.OperationList.DRAFT" + tp:causes-havoc="experimental"> + + <tp:requires interface="org.freedesktop.Telepathy.ChannelDispatcher.DRAFT"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>This interface allows users of the ChannelDispatcher to enumerate + all the pending dispatch operations, with change notification.</p> + + <tp:rationale> + <p>The existence of the DispatchOperations property allows a newly + started approver to pick up existing dispatch operations.</p> + + <p>This is on a separate interface so clients that aren't interested + in doing this aren't woken up by its signals.</p> + </tp:rationale> + </tp:docstring> + + <tp:struct name="Dispatch_Operation_Details" + array-name="Dispatch_Operation_Details_List"> + + <tp:docstring> + Details of a channel dispatch operation. + </tp:docstring> + + <tp:member name="Channel_Dispatch_Operation" type="o"> + <tp:docstring> + The object path of the + <tp:dbus-ref + namespace="org.freedesktop.Telepathy">ChannelDispatchOperation</tp:dbus-ref>. + </tp:docstring> + </tp:member> + + <tp:member name="Properties" type="a{sv}" + tp:type="Qualified_Property_Value_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Properties of the channel dispatch operation.</p> + + <p>Connection managers MUST NOT include properties in this mapping + if their values can change. Clients MUST ignore properties + that appear in this mapping if their values can change.</p> + + <tp:rationale> + <p>The rationale is the same as for + <tp:type-ref>Channel_Details</tp:type-ref>.</p> + </tp:rationale> + + <p>Each dictionary MUST contain at least the following keys:</p> + <ul> + <li><tp:dbus-ref>org.freedesktop.Telepathy.ChannelDispatchOperation.DRAFT.Interfaces</tp:dbus-ref></li> + <li><tp:dbus-ref>org.freedesktop.Telepathy.ChannelDispatchOperation.DRAFT.Connection</tp:dbus-ref></li> + <li><tp:dbus-ref>org.freedesktop.Telepathy.ChannelDispatchOperation.DRAFT.Account</tp:dbus-ref></li> + <li><tp:dbus-ref>org.freedesktop.Telepathy.ChannelDispatchOperation.DRAFT.Channels</tp:dbus-ref></li> + <li><tp:dbus-ref>org.freedesktop.Telepathy.ChannelDispatchOperation.DRAFT.PossibleHandlers</tp:dbus-ref></li> + </ul> + </tp:docstring> + </tp:member> + </tp:struct> + + <property + name="DispatchOperations" tp:name-for-bindings="Dispatch_Operations" + type="a(oa{sv})" tp:type="Dispatch_Operation_Details[]" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The list of ChannelDispatchOperation objects currently being + processed. Change notification is via the NewDispatch and + DispatchFinished signals.</p> + </tp:docstring> + </property> + + <signal name="NewDispatchOperation" + tp:name-for-bindings="New_Dispatch_Operation"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Emitted when a dispatch operation is added to + <tp:member-ref>DispatchOperations</tp:member-ref>.</p> + </tp:docstring> + + <arg name="Dispatch_Operation" type="o"> + <tp:docstring> + The dispatch operation that was created. + </tp:docstring> + </arg> + + <arg name="Properties" + type="a{sv}" tp:type="Qualified_Property_Value_Map"> + <tp:docstring> + The same properties that would appear in the Properties member of + <tp:type-ref>Dispatch_Operation_Details</tp:type-ref>. + </tp:docstring> + </arg> + </signal> + + <signal name="DispatchOperationFinished" + tp:name-for-bindings="Dispatch_Operation_Finished"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + Emitted when a dispatch operation finishes (i.e. exactly once per + emission of <tp:dbus-ref + namespace="org.freedesktop.Telepathy">ChannelDispatchOperation.DRAFT.Finished</tp:dbus-ref>). + + <tp:rationale> + Strictly speaking this is redundant with + ChannelDispatchOperation.Finished, but it provides full + change-notification for the DispatchOperations property. + </tp:rationale> + </tp:docstring> + + <arg name="Dispatch_Operation" type="o"> + <tp:docstring> + The dispatch operation that was closed. + </tp:docstring> + </arg> + </signal> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Channel_Interface_Call_State.xml b/spec/Channel_Interface_Call_State.xml index 132137eda..0df6e3472 100644 --- a/spec/Channel_Interface_Call_State.xml +++ b/spec/Channel_Interface_Call_State.xml @@ -101,6 +101,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ unhold the call again. </tp:docstring> </tp:flag> + + <tp:flag suffix="Forwarded" value="8"> + <tp:docstring> + The initiator of the call originally called a contact other than the + current recipient of the call, but the call was then forwarded or + diverted. + </tp:docstring> + </tp:flag> </tp:flags> </interface> diff --git a/spec/Channel_Interface_Destroyable.xml b/spec/Channel_Interface_Destroyable.xml new file mode 100644 index 000000000..2f82e6980 --- /dev/null +++ b/spec/Channel_Interface_Destroyable.xml @@ -0,0 +1,79 @@ +<?xml version="1.0" ?> +<node name="/Channel_Interface_Destroyable" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright (C) 2008 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright (C) 2008 Nokia Corporation</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="org.freedesktop.Telepathy.Channel.Interface.Destroyable.DRAFT" + tp:causes-havoc="experimental"> + <tp:requires interface="org.freedesktop.Telepathy.Channel"/> + <tp:added version="0.17.UNRELEADED">(draft, not API-stable)</tp:added> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>This interface exists to support channels where + <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Channel.Close</tp:dbus-ref> + is insufficiently destructive.</p> + </tp:docstring> + + <method name="Destroy" tp:name-for-bindings="Destroy"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Close the channel abruptly, possibly with loss of data. The + connection manager MUST NOT re-create the channel unless/until + more events occur.</p> + + <tp:rationale> + <p>The main motivating situation for this method is that when a Text + channel with pending messages is closed with Close, it comes back + as an incoming channel (to avoid a race between Close and an + incoming message). If Destroy is called on a Text channel, the CM + should delete all pending messages and close the channel, and + the channel shouldn't be re-created until/unless another message + arrives.</p> + </tp:rationale> + + <p>Most clients SHOULD call + <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Channel.Close</tp:dbus-ref> + instead. However, if a client explicitly intends to destroy the + channel with possible loss of data, it SHOULD call this method + if this interface is supported (according to the + <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Channel.Interfaces</tp:dbus-ref> + property), falling back to Close if not.</p> + + <p>In particular, channel dispatchers SHOULD use this method if + available when terminating channels that cannot be handled + correctly (for instance, if no handler has been installed for + a channel type, or if the handler crashes repeatedly).</p> + + <p>Connection managers do not need to implement this interface on + channels where Close and Destroy would be equivalent.</p> + + <tp:rationale> + <p>Callers need to be able to fall back to Close in any case.</p> + </tp:rationale> + </tp:docstring> + </method> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Channel_Request.xml b/spec/Channel_Request.xml new file mode 100644 index 000000000..25f5b066c --- /dev/null +++ b/spec/Channel_Request.xml @@ -0,0 +1,178 @@ +<?xml version="1.0" ?> +<node name="/Channel_Request" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + + <tp:copyright>Copyright (C) 2008 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright (C) 2008 Nokia Corporation</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="org.freedesktop.Telepathy.ChannelRequest.DRAFT" + tp:causes-havoc="experimental"> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A channel request is an object in the ChannelDispatcher representing + an ongoing request for some channels to be created or found. There + can be any number of ChannelRequest objects at the same time.</p> + + <p>Its well-known bus name is the same as that of the ChannelDispatcher, + "org.freedesktop.Telepathy.ChannelDispatcher".</p> + + <tp:rationale> + <p>See + <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelDispatcher.DRAFT.CreateChannel</tp:dbus-ref> + for rationale for ChannelRequest being a separate object.</p> + </tp:rationale> + </tp:docstring> + + <property name="UserActionTime" tp:name-for-bindings="User_Action_Time" + type="t" tp:type="Unix_Timestamp64" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The time at which user action occurred, or 0 if this channel + request is for some reason not involving user action.</p> + + <p>This corresponds to the _NET_WM_USER_TIME property in + <a href="http://standards.freedesktop.org/wm-spec/wm-spec-latest.html">EWMH</a>.</p> + + <p>This property is set when the channel request is created, + and can never change.</p> + </tp:docstring> + </property> + + <property name="Requests" tp:name-for-bindings="Requests" type="aa{sv}" + tp:type="Qualified_Property_Value_Map[]" + access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An array of dictionaries containing desirable properties for + the channel or channels to be created.</p> + + <tp:rationale> + <p>This is an array so that we could add a CreateChannels method in + future without redefining the API of ChannelRequest.</p> + </tp:rationale> + + <p>This property is set when the channel request is created, + and can never change.</p> + </tp:docstring> + </property> + + <method name="Proceed" tp:name-for-bindings="Proceed"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Proceed with the channel request.</p> + + <tp:rationale> + <p>The client that created this object calls this method + when it has connected signal handlers for + <tp:member-ref>Succeeded</tp:member-ref> and + <tp:member-ref>Failed</tp:member-ref>.</p> + </tp:rationale> + + <p>Clients other than the client which created the ChannelRequest + MUST NOT call this method.</p> + + <p>This method SHOULD return immediately; on success, the request + might still fail, but this will be indicated asynchronously + by the <tp:member-ref>Failed</tp:member-ref> signal.</p> + + <p>Proceed cannot fail, unless clients have got the life-cycle + of a ChannelRequest seriously wrong (e.g. a client calls this + method twice, or a client that did not create the ChannelRequest + calls this method). If it fails, clients SHOULD assume that the + whole ChannelRequest has become useless.</p> + </tp:docstring> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Errors.NotAvailable"> + <tp:docstring> + This method has already been called, so it is no longer + available. Stop calling it. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="Cancel" tp:name-for-bindings="Cancel"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Cancel the channel request. The precise effect depends on the + current progress of the request.</p> + + <p>If the connection manager has not already been asked to create + a channel, then <tp:member-ref>Failed</tp:member-ref> is emitted + immediately, and the channel request is removed.</p> + + <p>If the connection manager has already been asked to create a + channel but has not produced one yet (e.g. if <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref> + has been called, but has not yet returned), then the + ChannelDispatcher will remember that the request has been cancelled. + When the channel appears, it will be closed (if it was newly + created and can be closed), and will not be dispatched to a + handler.</p> + + <p>If the connection manager has already returned a channel, but the + channel has not yet been dispatched to a handler + (e.g. if <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref> + has returned a channel, but the dispatch operation is waiting for + approvers) then the channel dispatcher will not dispatch that + channel to a handler. If the channel was newly created for this + request, the channel dispatcher will close it with Close; otherwise, + the channel dispatcher will ignore it. In either case, + <tp:member-ref>Failed</tp:member-ref> will be emitted when processing + has been completed.</p> + + <p>If Failed is emitted in response to this method, the error SHOULD be + <code>org.freedesktop.Telepathy.Errors.Cancelled</code>.</p> + + <p>If the channel has already been dispatched to a handler, then + it's too late to call this method, and the channel request will + no longer exist.</p> + </tp:docstring> + </method> + + <signal name="Failed" tp:name-for-bindings="Failed"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The channel request has failed. It is no longer present, + and further methods must not be called on it.</p> + </tp:docstring> + + <arg name="Error" type="s" tp:type="DBus_Error_Name"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The name of a D-Bus error. This can come from various sources, + including the error raised by CreateChannel, or an error generated + to represent failure to establish the Connection.</p> + </tp:docstring> + </arg> + + <arg name="Message" type="s"> + <tp:docstring> + If the first argument of the D-Bus error message was a string, + that string. Otherwise, an empty string. + </tp:docstring> + </arg> + </signal> + + <signal name="Succeeded" tp:name-for-bindings="Succeeded"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The channel request has succeeded. It is no longer present, + and further methods must not be called on it.</p> + </tp:docstring> + </signal> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Client.xml b/spec/Client.xml new file mode 100644 index 000000000..da3cfbef4 --- /dev/null +++ b/spec/Client.xml @@ -0,0 +1,123 @@ +<?xml version="1.0" ?> +<node name="/Client" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright (C) 2008 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright (C) 2008 Nokia Corporation</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="org.freedesktop.Telepathy.Client.DRAFT" + tp:causes-havoc="experimental"> + <tp:added version="0.17.UNRELEASED"/> + + <tp: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> + + <tp:rationale> + <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> + </tp:rationale> + + <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> + + <tp:rationale> + <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> + </tp:rationale> + + <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> + </tp:docstring> + + <property name="Interfaces" tp:name-for-bindings="Interfaces" + type="as" access="read" tp:type="DBus_Interface[]"> + <tp: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 + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Client.Observer</tp:dbus-ref>, + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Client.Approver</tp:dbus-ref> or + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Client.Handler</tp:dbus-ref>.</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> + </tp:docstring> + </property> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Client_Approver.xml b/spec/Client_Approver.xml new file mode 100644 index 000000000..c912b128c --- /dev/null +++ b/spec/Client_Approver.xml @@ -0,0 +1,135 @@ +<?xml version="1.0" ?> +<node name="/Client_Approver" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright (C) 2008 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright (C) 2008 Nokia Corporation</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="org.freedesktop.Telepathy.Client.Approver.DRAFT" + tp:causes-havoc="experimental"> + <tp:added version="0.17.UNRELEASED"/> + + <tp:requires interface="org.freedesktop.Telepathy.Client.DRAFT"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Approvers notify the user that new channels have been created, + and allow the user to accept or reject those channels.</p> + + <p>They can also select which channel handler will be used for the + channel, for instance by offering the user a list of possible + handlers rather than just an accept/reject choice.</p> + + <p>However, the Channel Dispatcher must be able to prioritize + possible handlers on its own using some reasonable heuristic, + probably based on user configuration.</p> + + <p>It is possible (and useful) to have an approver and + a channel handler in the same process; this is particularly useful + if a channel handler wants to claim responsibility for particular + channels itself.</p> + + <p>All approvers are notified simultaneously. For instance, in a + desktop system, there might be one approver that displays a + notification-area icon, one that is part of a contact list + window and highlights contacts there, and one that is part + of a full-screen media player.</p> + + <p>Any approver can approve the handling of a channel with a + particular channel handler. Approvers can also request that the + channel is rejected. The first approver to reply gets its decision + acted on; any other approvers that reply at the same time will + get a D-Bus error, indicating that the channel has already been + dealt with.</p> + + <p>Approvers should usually prompt the user and ask for + confirmation, rather than dispatching the channel to a handler + straight away.</p> + </tp:docstring> + + <property name="ApproverChannelFilter" + tp:name-for-bindings="Approver_Channel_Filter" + type="aa{sv}" access="read" tp:type="Channel_Class[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A specification of the channels in which this approver is + interested. The <tp:member-ref>AddDispatchOperation</tp:member-ref> + method should be called by the channel dispatcher whenever the + channels in a channel dispatch operation + match this description.</p> + + <p>(FIXME: what happens if some but not all of the channels + match this?)</p> + + <p>This property works in exactly the same way as the + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Client.Observer.DRAFT.ObserverChannelFilter</tp:dbus-ref> + property. In the .client file, it is represented in the + same way as ObserverChannelFilter, but the group has the same + name as this interface and the keys start with + ApproverChannelFilter instead of ObserverChannelFilter.</p> + </tp:docstring> + </property> + + <method name="AddDispatchOperation" + tp:name-for-bindings="Add_Dispatch_Operation"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Called by the channel dispatcher when a ChannelDispatchOperation + in which the approver has registered an interest is created.</p> + + <p>The channel dispatcher SHOULD call this method on all approvers + at the same time. If no approvers return from this method + successfully (including situations where there are no matching + approvers at all), the channel dispatcher SHOULD consider this + to be an error, and recover by dispatching the channel to the + most preferred handler.</p> + + <tp:rationale> + Processes that aren't approvers shouldn't be making connections + anyway - there should always be at least one approver running. + </tp:rationale> + </tp:docstring> + + <arg name="DispatchOperation" type="o" direction="in"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The + <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelDispatchOperation</tp:dbus-ref> + to be processed.</p> + </tp:docstring> + </arg> + + <arg name="Properties" type="a{sv}" + tp:type="Qualified_Property_Value_Map" direction="in"> + <tp:docstring> + Properties of the channel dispatch operation. This MUST NOT include + properties that could change, SHOULD include as many properties as + possible given that constraint, and MUST include at least the + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.ChannelDispatchOperation.DRAFT">Account</tp:dbus-ref>, + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.ChannelDispatchOperation.DRAFT">Connection</tp:dbus-ref>, + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.ChannelDispatchOperation.DRAFT">Channels</tp:dbus-ref> + and + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.ChannelDispatchOperation.DRAFT">PossibleHandlers</tp:dbus-ref> + properties. + </tp:docstring> + </arg> + </method> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Client_Handler.xml b/spec/Client_Handler.xml new file mode 100644 index 000000000..4e815d030 --- /dev/null +++ b/spec/Client_Handler.xml @@ -0,0 +1,268 @@ +<?xml version="1.0" ?> +<node name="/Client_Handler" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright (C) 2008 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright (C) 2008 Nokia Corporation</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="org.freedesktop.Telepathy.Client.Handler.DRAFT" + tp:causes-havoc="experimental"> + <tp:added version="0.17.UNRELEASED"/> + + <tp:requires interface="org.freedesktop.Telepathy.Client.DRAFT"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Channel handlers are the eventual handler for a channel or a + channel bundle; a typical channel handler is a user interface + process handling channels of a particular type.</p> + + <p>When a new incoming channel (one with + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.FUTURE">Requested</tp:dbus-ref> + = TRUE) is offered to + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Client">Approver</tp:dbus-ref>s + by the channel dispatcher, it also offers the Approvers a list of all + the running or activatable ChannelHandlers whose + <tp:member-ref>HandlerChannelFilter</tp:member-ref> property + (possibly as cached in the .client file) indicates that they + are able to handle the channel. The Approvers can choose one of + those channel handlers to handle the channel.</p> + + <p>When a new outgoing channel (one with + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.FUTURE">Requested</tp:dbus-ref> + = FALSE) appears, the channel dispatcher passes it to an appropriate + channel handler automatically. + </p> + + </tp:docstring> + + <property name="HandlerChannelFilter" + tp:name-for-bindings="Handler_Channel_Filter" + type="aa{sv}" access="read" tp:type="Channel_Class[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A specification of the channels that this channel handler can + deal with. It will be offered to approvers as a potential + channel handler for bundles that contain only suitable channels, + or for suitable channels that must be handled separately.</p> + + <p>This property works in exactly the same way as the + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Client.Observer.DRAFT.ObserverChannelFilter</tp:dbus-ref> + property. In the .client file, it is represented in the + same way as ObserverChannelFilter, but the group has the same + name as this interface and the keys start with + HandlerChannelFilter instead of ObserverChannelFilter.</p> + </tp:docstring> + </property> + + <property name="BypassApproval" tp:name-for-bindings="Bypass_Approval" + type="b" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If true, channels destined for this handler are automatically + handled, without invoking approvers.</p> + + <tp:rationale> + <p>The intended usage is to allow a client handling one channel to + pick up closely related channels. Suppose a client capable of + handling both Text and StreamedMedia, + <code>org.freedesktop.Telepathy.Client.Empathy</code>, is + handling a StreamedMedia channel. That client can take a second + well-known bus name, say + <code>org.freedesktop.Telepathy.Client.Empathy._1._42.Bundle1</code>, + and configure an object at + <code>/org/freedesktop/Telepathy/Client/Empathy/_1/_42/Bundle1</code> + with BypassApproval = TRUE, + whose <tp:member-ref>HandlerChannelFilter</tp:member-ref> + matches closely related Text channels by their Bundle property. + (This is use-case dis5)</p> + </tp:rationale> + </tp:docstring> + </property> + + <method name="HandleChannels" tp:name-for-bindings="Handle_Channels"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Called by the channel dispatcher when this client should handle these + channels, or when this client should present channels that it is already + handling to the user (e.g. bring them into the foreground).</p> + + <tp:rationale> + <p>Clients are expected to know what channels they're already handling, + and which channel object path corresponds to which window or tab. + This can easily be done using a hash table keyed by channels' object + paths.</p> + </tp:rationale> + + <p>This method can raise any D-Bus error. If it does, or if the + handler loses its bus name before all the channels have closed, the + handler is assumed to have failed or crashed, and the channel + dispatcher MUST recover in an implementation-specific way.</p> + + <p>It is RECOMMENDED that the channel dispatcher attempts to + close the channels using + <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Channel.Close</tp:dbus-ref>, + but resorts to calling + <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Channel.Interface.Destroyable.DRAFT.Destroy</tp:dbus-ref> + (if available) or ignoring the channel (if not) if the same handler + repeatedly fails to handle channels.</p> + </tp:docstring> + + <arg name="Account" type="o" direction="in"> + <tp:docstring> + The + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref> + with which the channels are associated. The + well-known bus name to use is that of the + <tp:dbus-ref namespace="org.freedesktop.Telepathy">AccountManager</tp:dbus-ref>. + </tp:docstring> + </arg> + + <arg name="Connection" type="o" direction="in"> + <tp:docstring> + The Connection with which the channels are associated. The + well-known bus name to use can be derived from this object + path by removing the leading '/' and replacing all subsequent + '/' by '.'. + </tp:docstring> + </arg> + + <arg name="Channels" type="a(oa{sv})" direction="in"> + <tp:docstring> + The channels and their immutable properties. Their well-known + bus name is the same as that of the Connection. + </tp:docstring> + </arg> + + <arg name="Requests_Satisfied" type="ao" direction="in"> + <tp:docstring> + The requests satisfied by these channels. + + <tp:rationale> + There can be more than one, if they were EnsureChannel + requests. + </tp:rationale> + </tp:docstring> + </arg> + + <arg name="User_Action_Time" type="t" direction="in"> + <tp:docstring> + The time at which user action occurred, or 0 if this channel + is to be handled for some reason not involving user action. + Handlers SHOULD use this for focus-stealing prevention, + if applicable. + </tp:docstring> + </arg> + + <!-- FIXME: invent a way to say "any error is possible" in spec markup --> + </method> + + <method name="AddRequest" tp:name-for-bindings="Add_Request"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Called by the ChannelDispatcher to indicate that channels have been + requested, and that if the request is successful, they will be + handled by this Handler.</p> + + <tp:rationale> + <p>This allows the UI to start preparing to handle the channels + in advance (e.g. render a window with an "in progress" message), + improving perceived responsiveness.</p> + </tp:rationale> + + <p>(FIXME: how do we know the returned channels will be handled by + this handler? Do we just assume that they'll match the + HandlerChannelFilter iff the request does?)</p> + </tp:docstring> + + <arg name="Request" type="o" direction="in"> + <tp:docstring> + The <tp:dbus-ref + namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref> + object. + </tp:docstring> + </arg> + + <arg name="Properties" type="a{sv}" + tp:type="Qualified_Property_Value_Map" direction="in"> + <tp:docstring> + <p>Some of the properties of the ChannelRequest. To avoid race + conditions, this dictionary MUST NOT include properties whose + values could subsequently change. It SHOULD include as many + properties as possible, given that constraint.</p> + + <p>In particular, the properties Requests and UserActionTimestamp + MUST be included.</p> + </tp:docstring> + </arg> + </method> + + <method name="RemoveFailedRequest" + tp:name-for-bindings="Remove_Failed_Request"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Called by the ChannelDispatcher to indicate that a request + previously passed to <tp:member-ref>AddRequest</tp:member-ref> + has failed and should be disregarded.</p> + </tp:docstring> + + <arg name="Request" type="o" direction="in"> + <tp:docstring> + The request that failed. + </tp:docstring> + </arg> + + <arg name="Error" type="s" tp:type="DBus_Error_Name" direction="in"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The name of the D-Bus error with which the request failed.</p> + + <p>If this is <code>org.freedesktop.Telepathy.Errors.NotYours</code>, + this indicates that the request succeeded, but all the resulting + channels were given to some other handler.</p> + </tp:docstring> + </arg> + + <arg name="Message" type="s" direction="in"> + <tp:docstring> + Any message supplied with the D-Bus error. + </tp:docstring> + </arg> + </method> + + <property name="HandledChannels" tp:name-for-bindings="Handled_Channels" + type="ao" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A list of the channels that this Handler is currently handling. + </p> + + <p>There is no change notification.</p> + + <tp:rationale> + <p>This property exists for state recovery - it makes it possible + for channel handling to survive a ChannelDispatcher crash.</p> + + <p>If the channel dispatcher is automatically replaced, the + replacement can discover all Handlers by looking for the Client + well-known bus names, and discover which channels they are + currently handling. Once this has been done, all unhandled + channels can be re-dispatched, and the only issue visible to + the user is that unhandled channels that they have already + approved might be sent back to Approvers.</p> + </tp:rationale> + </tp:docstring> + </property> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Client_Observer.xml b/spec/Client_Observer.xml new file mode 100644 index 000000000..eccbefdcc --- /dev/null +++ b/spec/Client_Observer.xml @@ -0,0 +1,230 @@ +<?xml version="1.0" ?> +<node name="/Client_Observer" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright (C) 2008 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright (C) 2008 Nokia Corporation</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="org.freedesktop.Telepathy.Client.Observer.DRAFT" + tp:causes-havoc="experimental"> + <tp:added version="0.17.UNRELEASED"/> + + <tp:requires interface="org.freedesktop.Telepathy.Client.DRAFT"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Observers monitor the creation of new channels. This + functionality can be used for things like message logging. + All observers are notified simultaneously.</p> + + <p>Observers SHOULD NOT modify the state of a channel except + via user interaction.</p> + + <tp:rationale> + <p>We want Observer UIs for file transfer channels (a progress + bar for the transfer) to be able to have a Cancel button.</p> + </tp:rationale> + + <p>Observers MUST NOT carry out actions that exactly one process + must take responsibility for (e.g. acknowledging Text + messages, or carrying out the actual transfer in a file transfer + channel).</p> + + <tp:rationale> + <p>Since arbitrarily many observers can be activated for + each channel, it would not make sense for observers to do things + that can only be done by one process (acknowledging + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type">Text</tp:dbus-ref> + messages, carrying out streaming for + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref> + channels, doing the actual data transfer for file transfers, + setting up the out-of-band connection for Tubes). The + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client">Handler</tp:dbus-ref> + is responsible for such tasks.</p> + + <p>Handlers MAY, of course, delegate responsibility for these + tasks to other processes (including those run as observers), + but this MUST be done explicitly via a request from the Handler + to the Observer.</p> + </tp:rationale> + + <p>Whenever new channels are signalled, the channel dispatcher + will notify all running or activatable observers whose + <tp:member-ref>ObserverChannelFilter</tp:member-ref> property + (possibly as cached in the .client file) indicates that they are + interested in the channel.</p> + + <p>Observers are activated for all channels in which they have + registered an interest - incoming, outgoing or automatically created - + although of course the ObserverChannelFilter property can be set + to filter on the + <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Channel.FUTURE.Requested</tp:dbus-ref> + property.</p> + </tp:docstring> + + <property name="ObserverChannelFilter" + tp:name-for-bindings="Observer_Channel_Filter" + type="aa{sv}" access="read" tp:type="Channel_Class[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A specification of the channels in which this observer is + interested. The <tp:member-ref>ObserveChannels</tp:member-ref> method + should be called by the channel dispatcher whenever any of the new + channels in a NewChannels signal match this description.</p> + + <p>(FIXME: open issue: do we want this, and the corresponding + Approver and Handler properties, to be able to change at + runtime?)</p> + + <p>Only certain D-Bus types have useful semantics for matching like this, + so only certain types are allowed:</p> + + <dl> + <dt>Integers of all sizes, including byte (y, n, q, i, u, x, t)</dt> + <dd>Matched by numeric value, regardless of type (e.g. 42 as a + 16-bit signed integer 'n' is considered equal to 42 as a 32-bit + unsigned integer 'u')</dd> + + <dt>Booleans (b)</dt> + <dd>Matched by equality in the obvious way; not considered equal to any + other type</dd> + + <dt>Strings (s)</dt> + <dd>Matched by equality in the obvious way; not considered equal to any + other type</dd> + + <dt>Object paths (o)</dt> + <dd>Matched by equality in the obvious way; not considered equal to any + other type</dd> + + </dl> + + <p>This property never changes while the observer process is + running. For activatable processes, the filter can change due to an + upgrade - the channel dispatcher SHOULD observe changes to .client files + using a mechanism like inotify.</p> + + <p>For observers that have a .client file, the channel dispatcher + may discover this property from keys of the form + <code><em>propertyname</em>/<em>type</em></code>, + in groups in the .client file whose name is the name of this + interface followed by <code>.ObserverChannelFilter</code>, + a space and an ASCII decimal number starting from 0.</p> + + <p>Integers in the .client file are encoded in ASCII decimal, booleans + are encoded as "true" or "false", and strings are encoded in the usual + way for desktop files (including the C-style backslash escapes + documented in the Desktop Entry specification).</p> + + <p>For instance, a .client file for an observer that is only interested + in Text channels, with CONTACT or ROOM handles, that were requested by + a local client:</p> + +<pre> +[org.freedesktop.Telepathy.Client.DRAFT] +Interfaces=org.freedesktop.Telepathy.Client.Observer.DRAFT; + +[org.freedesktop.Telepathy.Client.Observer.DRAFT.ObserverChannelFilter 0] +org.freedesktop.Telepathy.Channel.Type s=org.freedesktop.Telepathy.Channel.Type.Text +org.freedesktop.Telepathy.Channel.TargetHandleType u=1 +org.freedesktop.Telepathy.Channel.FUTURE.Requested b=true + +[org.freedesktop.Telepathy.Client.Observer.DRAFT.ObserverChannelFilter 1] +org.freedesktop.Telepathy.Channel.Type s=org.freedesktop.Telepathy.Channel.Type.Text +org.freedesktop.Telepathy.Channel.TargetHandleType u=2 +org.freedesktop.Telepathy.Channel.FUTURE.Requested b=true +</pre> + + </tp:docstring> + </property> + + <method name="ObserveChannels" tp:name-for-bindings="Observe_Channels"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Called by the channel dispatcher when channels in which the + observer has registered an interest are created.</p> + + <p>The observer MUST NOT return from this method call until it is ready + for a handler for the channel to run (which may change the channel's + state).</p> + + <tp:rationale> + <p>The channel dispatcher must wait for observers to start up, + to avoid the following race: text channel logger (observer) gets + ObserveChannel, text channel handler gets + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client.Handler.DRAFT">HandleChannels</tp:dbus-ref> + channel handler starts up faster and acknowledges messages, + logger never sees those messages.</p> + </tp:rationale> + </tp:docstring> + + <arg name="Account" type="o" direction="in"> + <tp:docstring> + The + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref> + with which the channels are associated. The + well-known bus name to use is that of the + <tp:dbus-ref namespace="org.freedesktop.Telepathy">AccountManager</tp:dbus-ref>. + </tp:docstring> + </arg> + + <arg name="Connection" type="o" direction="in"> + <tp:docstring> + The + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref> + with which the channels are associated. The + well-known bus name to use can be derived from this object + path by removing the leading '/' and replacing all subsequent + '/' by '.'. + </tp:docstring> + </arg> + + <arg name="Channels" type="a(oa{sv})" tp:type="Channel_Details[]" + direction="in"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The + <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Channel</tp:dbus-ref>s + and their properties. Their well-known bus names are all the same + as that of the Connection.</p> + + <tp:rationale> + <p>The ChannelDispatchOperation is <em>not</em> supplied: for + requests, there isn't one, and for incoming channels, it hasn't + been created yet.</p> + </tp:rationale> + </tp:docstring> + </arg> + + <arg name="Observer_Info" type="a{sv}" direction="in"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Additional information about these channels. No keys are + currently defined.</p> + + <p>If keys are defined for this dictionary, all will be optional; + observers MAY safely ignore any entry in this dictionary.</p> + </tp:docstring> + </arg> + + </method> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Makefile.am b/spec/Makefile.am index ea5282522..83c57ef1b 100644 --- a/spec/Makefile.am +++ b/spec/Makefile.am @@ -3,12 +3,16 @@ EXTRA_DIST = \ Account_Manager.xml \ Account.xml \ all.xml \ + Channel_Dispatch_Operation.xml \ + Channel_Dispatcher.xml \ + Channel_Dispatcher_Interface_Operation_List.xml \ Channel_Future.xml \ Channel_Handler.xml \ Channel_Interface_Call_Merging.xml \ Channel_Interface_Call_State.xml \ Channel_Interface_Chat_State.xml \ Channel_Interface_Delivery_Reporting.xml \ + Channel_Interface_Destroyable.xml \ Channel_Interface_DTMF.xml \ Channel_Interface_Group.xml \ Channel_Interface_Hold.xml \ @@ -17,6 +21,7 @@ EXTRA_DIST = \ Channel_Interface_Messages.xml \ Channel_Interface_Password.xml \ Channel_Interface_Transfer.xml \ + Channel_Request.xml \ Channel_Type_Contact_List.xml \ Channel_Type_Contact_Search.xml \ Channel_Type_Room_List.xml \ @@ -24,6 +29,10 @@ EXTRA_DIST = \ Channel_Type_Text.xml \ Channel_Type_Tubes.xml \ Channel.xml \ + Client.xml \ + Client_Approver.xml \ + Client_Handler.xml \ + Client_Observer.xml \ Connection_Interface_Aliasing.xml \ Connection_Interface_Avatars.xml \ Connection_Interface_Capabilities.xml \ diff --git a/spec/all.xml b/spec/all.xml index d60f9e398..a9c58c113 100644 --- a/spec/all.xml +++ b/spec/all.xml @@ -3,7 +3,7 @@ xmlns:xi="http://www.w3.org/2001/XInclude"> <tp:title>Telepathy D-Bus Interface Specification</tp:title> -<tp:version>0.17.11</tp:version> +<tp:version>0.17.12</tp:version> <tp:copyright>Copyright (C) 2005-2008 Collabora Limited</tp:copyright> <tp:copyright>Copyright (C) 2005-2008 Nokia Corporation</tp:copyright> @@ -31,14 +31,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <xi:include href="Connection_Interface_Avatars.xml"/> <xi:include href="Connection_Interface_Capabilities.xml"/> <xi:include href="Connection_Interface_Contacts.xml"/> -<!-- Never implemented, is a terrible API -<xi:include href="Connection_Interface_Contact_Info.xml"/> --> -<!-- Never implemented, insufficient (needs conditions) -<xi:include href="Connection_Interface_Forwarding.xml"/> --> <xi:include href="Connection_Interface_Simple_Presence.xml"/> <xi:include href="Connection_Interface_Presence.xml"/> -<!-- Never implemented, vague -<xi:include href="Connection_Interface_Privacy.xml"/> --> <xi:include href="Connection_Interface_Renaming.xml"/> <xi:include href="Connection_Interface_Requests.xml"/> @@ -47,8 +41,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <xi:include href="Channel.xml"/> <xi:include href="Channel_Future.xml"/> <xi:include href="Channel_Type_Contact_List.xml"/> -<!-- Never implemented, can't be implemented with current dbus-glib, vague -<xi:include href="Channel_Type_Contact_Search.xml"/> --> <xi:include href="Channel_Type_Streamed_Media.xml"/> <xi:include href="Channel_Type_Room_List.xml"/> <xi:include href="Channel_Type_Text.xml"/> @@ -58,13 +50,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <xi:include href="Channel_Interface_Call_State.xml"/> <xi:include href="Channel_Interface_Chat_State.xml"/> <xi:include href="Channel_Interface_Delivery_Reporting.xml"/> +<xi:include href="Channel_Interface_Destroyable.xml"/> <xi:include href="Channel_Interface_DTMF.xml"/> <xi:include href="Channel_Interface_Group.xml"/> <xi:include href="Channel_Interface_Hold.xml"/> <xi:include href="Channel_Interface_HTML.xml"/> <xi:include href="Channel_Interface_Password.xml"/> -<!-- Causes havoc, never implemented, unclear requirements -<xi:include href="Channel_Interface_Transfer.xml"/> --> <xi:include href="Channel_Interface_Media_Signalling.xml"/> <xi:include href="Channel_Interface_Messages.xml"/> @@ -77,9 +68,30 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <xi:include href="Account.xml"/> <xi:include href="Account_Interface_Avatar.xml"/> +<xi:include href="Channel_Dispatcher.xml"/> +<xi:include href="Channel_Dispatcher_Interface_Operation_List.xml"/> +<xi:include href="Channel_Dispatch_Operation.xml"/> +<xi:include href="Channel_Request.xml"/> + +<xi:include href="Client.xml"/> +<xi:include href="Client_Observer.xml"/> +<xi:include href="Client_Approver.xml"/> +<xi:include href="Client_Handler.xml"/> + <xi:include href="Channel_Handler.xml"/> <xi:include href="errors.xml"/> <xi:include href="generic-types.xml"/> +<!-- Never implemented, is a terrible API +<xi:include href="Connection_Interface_Contact_Info.xml"/> --> +<!-- Never implemented, insufficient (needs conditions) +<xi:include href="Connection_Interface_Forwarding.xml"/> --> +<!-- Never implemented, vague +<xi:include href="Connection_Interface_Privacy.xml"/> --> +<!-- Never implemented, can't be implemented with current dbus-glib, vague +<xi:include href="Channel_Type_Contact_Search.xml"/> --> +<!-- Causes havoc, never implemented, unclear requirements +<xi:include href="Channel_Interface_Transfer.xml"/> --> + </tp:spec> diff --git a/spec/errors.xml b/spec/errors.xml index 81ab440e7..679e3f4e2 100644 --- a/spec/errors.xml +++ b/spec/errors.xml @@ -1,5 +1,8 @@ <?xml version="1.0" ?> <tp:errors xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0" namespace="org.freedesktop.Telepathy.Error"> + <!-- Don't re-order these errors until fd.o #17588 is fixed, or you will + break telepathy-glib's ABI. + --> <tp:error name="Network Error"> <tp:docstring> Raised when there is an error reading from or writing to the network. @@ -60,8 +63,22 @@ </tp:docstring> </tp:error> - <tp:copyright>Copyright (C) 2005, 2006, 2007 Collabora Limited</tp:copyright> - <tp:copyright>Copyright (C) 2005, 2006, 2007 Nokia Corporation</tp:copyright> + <tp:error name="Not Yours"> + <tp:docstring> + The requested channel or other resource already exists, and another + client is responsible for it + </tp:docstring> + </tp:error> + + <tp:error name="Cancelled"> + <tp:docstring> + Raised by an ongoing request if it is cancelled by user request before + it has completed. + </tp:docstring> + </tp:error> + + <tp:copyright>Copyright (C) 2005-2008 Collabora Limited</tp:copyright> + <tp:copyright>Copyright (C) 2005-2008 Nokia Corporation</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 diff --git a/spec/generic-types.xml b/spec/generic-types.xml index 480b2c958..9d8501de9 100644 --- a/spec/generic-types.xml +++ b/spec/generic-types.xml @@ -67,7 +67,8 @@ "org.freedesktop.DBus.Peer.Ping".</tp:docstring> </tp:simple-type> - <tp:mapping name="Qualified_Property_Value_Map"> + <tp:mapping name="Qualified_Property_Value_Map" + array-name="Qualified_Property_Value_Map_List"> <tp:docstring>A mapping from strings representing D-Bus properties (by their namespaced names) to their values.</tp:docstring> <tp:member type="s" name="Key" tp:type="DBus_Qualified_Member"> diff --git a/telepathy-glib/Makefile.am b/telepathy-glib/Makefile.am index ae2993e50..741290bef 100644 --- a/telepathy-glib/Makefile.am +++ b/telepathy-glib/Makefile.am @@ -18,7 +18,8 @@ ABI_LISTS = \ versions/0.7.12.abi \ versions/0.7.13.abi \ versions/0.7.14.abi \ - versions/0.7.15.abi + versions/0.7.15.abi \ + versions/0.7.16.abi EXTRA_DIST = \ $(ABI_LISTS) \ diff --git a/telepathy-glib/channel-manager.c b/telepathy-glib/channel-manager.c index f6b6d71ef..e134fa044 100644 --- a/telepathy-glib/channel-manager.c +++ b/telepathy-glib/channel-manager.c @@ -154,12 +154,14 @@ * @ensure_channel: Respond to a request for a (new or existing) channel made * with the Connection.Interface.Requests.EnsureChannel method. See * #TpChannelManagerRequestFunc for details. - * Since: 0.7.UNRELEASED+1 + * Since: 0.7.16 * * The vtable for a channel manager implementation. * * In addition to the fields documented here there are several GCallback * fields which must currently be %NULL. + * + * Since: 0.7.15 */ @@ -639,7 +641,7 @@ tp_channel_manager_request_channel (TpChannelManager *manager, * * Returns: %TRUE if this request will be handled by @manager; else %FALSE. * - * Since: 0.7.UNRELEASED+1 + * Since: 0.7.16 */ gboolean tp_channel_manager_ensure_channel (TpChannelManager *manager, diff --git a/telepathy-glib/connection.c b/telepathy-glib/connection.c index 54c723726..6785bbb5c 100644 --- a/telepathy-glib/connection.c +++ b/telepathy-glib/connection.c @@ -1066,7 +1066,7 @@ get_presence_type_availability (TpConnectionPresenceType type) * * Returns: -1, 0 or 1, if @p1 is <, == or > than @p2. * - * Since: 0.7.UNRELEASED + * Since: 0.7.16 */ gint tp_connection_presence_type_cmp_availability (TpConnectionPresenceType p1, diff --git a/telepathy-glib/versions/0.7.16.abi b/telepathy-glib/versions/0.7.16.abi new file mode 100644 index 000000000..7d2ec51de --- /dev/null +++ b/telepathy-glib/versions/0.7.16.abi @@ -0,0 +1,9 @@ +Version: TELEPATHY_GLIB_0.7.16 +Extends: TELEPATHY_GLIB_0.7.15 +Release: 0.7.16 + +tp_channel_manager_ensure_channel +tp_cli_connection_interface_requests_call_ensure_channel +tp_cli_connection_interface_requests_run_ensure_channel +tp_connection_presence_type_cmp_availability +tp_svc_connection_interface_requests_implement_ensure_channel |