[Telepathy-commits] [telepathy-spec/master] ChannelDispatchOperation: rename from ChannelDispatch to reduce confusion with ChannelDispatcher
Simon McVittie
simon.mcvittie at collabora.co.uk
Fri Sep 26 08:21:09 PDT 2008
20080623180908-53eee-e755af7d16c946bcd8f986553d7ed97643367b71.gz
---
spec/Channel_Dispatch.xml | 119 -----------------------------------
spec/Channel_Dispatch_Operation.xml | 119 +++++++++++++++++++++++++++++++++++
spec/Channel_Dispatcher.xml | 26 ++++++--
spec/all.xml | 2 +-
4 files changed, 139 insertions(+), 127 deletions(-)
delete mode 100644 spec/Channel_Dispatch.xml
create mode 100644 spec/Channel_Dispatch_Operation.xml
diff --git a/spec/Channel_Dispatch.xml b/spec/Channel_Dispatch.xml
deleted file mode 100644
index 8b4684e..0000000
--- a/spec/Channel_Dispatch.xml
+++ /dev/null
@@ -1,119 +0,0 @@
-<?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.ChannelDispatch.DRAFT"
- tp:causes-havoc="experimental">
- <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>A channel dispatch is an object in the Channel Dispatcher
- representing a bundle of channels being announced to client
- processes.</p>
-
- <p>These objects can result from new incoming channels, requests for
- outgoing channels, or channels which are automatically created
- for some reason.</p>
-
- <p>The creation of a channel dispatch operation is indicated
- by the NewDispatchOperation signal on the ChannelDispatcher
- interface.</p>
- </tp:docstring>
-
- <property name="Interfaces" type="as" access="read"
- tp:type="DBus_Interface[]">
- <tp:docstring>
- A list of the extra interfaces provided by this channel dispatch
- operation.
- </tp:docstring>
- </property>
-
- <method name="HandleWith">
- <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 Closed, and also cause the
- ChannelDispatcher to emit DispatchOperationClosed.</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 handle the channels itself in this case.</p>
-
- <p>Approvers which are also channel handlers SHOULD use HandleWith
- to request that they can handle a channel bundle themselves, but
- MUST NOT actually start to handle the channel until the
- ChannelHandler.HandleChannels method is called on them.</p>
- </tp:docstring>
-
- <arg direction="in" type="s" tp:type="DBus_Bus_Name" name="Handler">
- </arg>
-
- <tp:possible-errors>
- <!-- FIXME -->
- </tp:possible-errors>
- </method>
-
- <method name="Reject">
- <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>Called by an approver to reject a channel bundle. The channel
- dispatcher should close the channels.</p>
-
- <p>If successful, this method will cause the ChannelDispatchOperation
- object to disappear. See HandleWith for more details.</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 close the channels itself in this case.</p>
- </tp:docstring>
-
- <tp:possible-errors>
- <!-- FIXME -->
- </tp:possible-errors>
- </method>
-
- <signal name="Closed">
- <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>
-
- <tp:rationale>
- <p>Strictly speaking this is redundant with
- ChannelDispatcher.DispatchOperationClosed, but having it here
- makes the ChannelDispatchOperation self-contained.</p>
- </tp:rationale>
-
- <p>Its object path MAY be reused for a subsequent dispatch
- operation, but the ChannelDispatcher SHOULD choose object paths
- in a way that avoids immediate re-use.</p>
-
- <tp:rationale>
- <p>Otherwise, clients might accidentally call Claim, HandleWith
- or Reject 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_Dispatch_Operation.xml b/spec/Channel_Dispatch_Operation.xml
new file mode 100644
index 0000000..880a88b
--- /dev/null
+++ b/spec/Channel_Dispatch_Operation.xml
@@ -0,0 +1,119 @@
+<?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 channels being announced to client
+ processes.</p>
+
+ <p>These objects can result from new incoming channels, requests for
+ outgoing channels, or channels which are automatically created
+ for some reason.</p>
+
+ <p>The creation of a channel dispatch operation is indicated
+ by the NewDispatchOperation signal on the ChannelDispatcher
+ interface.</p>
+ </tp:docstring>
+
+ <property name="Interfaces" type="as" access="read"
+ tp:type="DBus_Interface[]">
+ <tp:docstring>
+ A list of the extra interfaces provided by this channel dispatch
+ operation.
+ </tp:docstring>
+ </property>
+
+ <method name="HandleWith">
+ <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 Closed, and also cause the
+ ChannelDispatcher to emit DispatchOperationClosed.</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 handle the channels itself in this case.</p>
+
+ <p>Approvers which are also channel handlers SHOULD use HandleWith
+ to request that they can handle a channel bundle themselves, but
+ MUST NOT actually start to handle the channel until the
+ ChannelHandler.HandleChannels method is called on them.</p>
+ </tp:docstring>
+
+ <arg direction="in" type="s" tp:type="DBus_Bus_Name" name="Handler">
+ </arg>
+
+ <tp:possible-errors>
+ <!-- FIXME -->
+ </tp:possible-errors>
+ </method>
+
+ <method name="Reject">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Called by an approver to reject a channel bundle. The channel
+ dispatcher should close the channels.</p>
+
+ <p>If successful, this method will cause the ChannelDispatchOperation
+ object to disappear. See HandleWith for more details.</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 close the channels itself in this case.</p>
+ </tp:docstring>
+
+ <tp:possible-errors>
+ <!-- FIXME -->
+ </tp:possible-errors>
+ </method>
+
+ <signal name="Closed">
+ <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>
+
+ <tp:rationale>
+ <p>Strictly speaking this is redundant with
+ ChannelDispatcher.DispatchOperationClosed, but having it here
+ makes the ChannelDispatchOperation self-contained.</p>
+ </tp:rationale>
+
+ <p>Its object path MAY be reused for a subsequent dispatch
+ operation, but the ChannelDispatcher SHOULD choose object paths
+ in a way that avoids immediate re-use.</p>
+
+ <tp:rationale>
+ <p>Otherwise, clients might accidentally call Claim, HandleWith
+ or Reject 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
index a654f26..66efd49 100644
--- a/spec/Channel_Dispatcher.xml
+++ b/spec/Channel_Dispatcher.xml
@@ -62,14 +62,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
<property name="Dispatch_Operations" type="ao" access="read">
<tp:docstring>
- The list of ChannelDispatch objects currently being processed.
- Change notification is via the NewDispatch and DispatchFinished
- signals.
+ The list of ChannelDispatchOperation objects currently being
+ processed. Change notification is via the NewDispatch and
+ DispatchFinished signals.
</tp:docstring>
</property>
- <signal name="NewDispatch">
- <arg name="Dispatch" type="o">
+ <signal name="NewDispatchOperation">
+ <arg name="Dispatch_Operation" type="o">
</arg>
<!-- FIXME: copy the Channel_Announcement_Flags from
@@ -79,8 +79,20 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
</arg>
</signal>
- <signal name="DispatchFinished">
- <arg name="Dispatch" type="o">
+ <signal name="DispatchOperationClosed">
+ <tp:docstring>
+ Emitted when a dispatch operation finishes (i.e. exactly once per
+ emission of ChannelDispatchOperation.Close).
+
+ <tp:rationale>
+ Strictly speaking this is redundant with
+ ChannelDispatchOperation.Closed, but it provides full
+ change-notification for the DispatchOperations property.
+ </tp:rationale>
+ </tp:docstring>
+
+ <arg name="Dispatch_Operation" type="o">
+ The dispatch operation that was closed.
</arg>
</signal>
diff --git a/spec/all.xml b/spec/all.xml
index f6fb0dd..20730a1 100644
--- a/spec/all.xml
+++ b/spec/all.xml
@@ -77,7 +77,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<xi:include href="Account.xml"/>
<xi:include href="Channel_Dispatcher.xml"/>
-<xi:include href="Channel_Dispatch.xml"/>
+<xi:include href="Channel_Dispatch_Operation.xml"/>
<xi:include href="Channel_Handler.xml"/>
--
1.5.6.5
More information about the Telepathy-commits
mailing list