Attachment 87467 Details for Bug 37380 – [spec master] Complete CD.I.Messages1

[patch] [spec master] Complete CD.I.Messages1

0003-Complete-CD.I.Messages1.patch (text/plain), 8.30 KB, created by Simon McVittie on 2013-10-11 16:02:14 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Simon McVittie

Created: 2013-10-11 16:02:14 UTC

Size: 8.30 KB

patch

obsolete

>From 2e3793484f5086df0767407cb8ef464c77ab83f5 Mon Sep 17 00:00:00 2001
>From: Simon McVittie <simon.mcvittie@collabora.co.uk>
>Date: Thu, 10 Oct 2013 19:15:33 +0100
>Subject: [PATCH 3/7] Complete CD.I.Messages1
>
>---
> spec/Channel_Dispatcher_Interface_Messages1.xml | 138 ++++++++++++++++++++++--
> spec/all.xml | 1 +
> 2 files changed, 129 insertions(+), 10 deletions(-)
>
>diff --git a/spec/Channel_Dispatcher_Interface_Messages1.xml b/spec/Channel_Dispatcher_Interface_Messages1.xml
>index 61a398b..e768b55 100644
>--- a/spec/Channel_Dispatcher_Interface_Messages1.xml
>+++ b/spec/Channel_Dispatcher_Interface_Messages1.xml
>@@ -1,8 +1,8 @@
> <?xml version="1.0" ?>
>-<node name="/Channel_Dispatcher_Interface_Messages_Draft"
>+<node name="/Channel_Dispatcher_Interface_Messages1"
> xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
> 
>- <tp:copyright>Copyright (C) 2011 Collabora Ltd.</tp:copyright>
>+ <tp:copyright>Copyright (C) 2011-2013 Collabora Ltd.</tp:copyright>
> <tp:copyright>Copyright (C) 2011 Nokia Corporation</tp:copyright>
> <tp:license xmlns="http://www.w3.org/1999/xhtml">
> This library is free software; you can redistribute it and/or
>@@ -22,9 +22,7 @@
> </tp:license>
> 
> <interface
>- name="org.freedesktop.Telepathy.ChannelDispatcher.Interface.Messages.DRAFT"
>- tp:causes-havoc="not yet final">
>-
>+ name="org.freedesktop.Telepathy.ChannelDispatcher.Interface.Messages1">
> <tp:requires interface="org.freedesktop.Telepathy.ChannelDispatcher"/>
> 
> <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
>@@ -44,12 +42,132 @@
> </tp:docstring>
> 
> <method name="SendMessage" tp:name-for-bindings="Send_Message">
>- <arg direction="in" name="Account" type="o"/>
>- <arg direction="in" name="TargetID" type="s"/>
>+ <arg direction="in" name="Account" type="o">
>+ <tp:docstring>
>+ The <tp:dbus-ref namespace="ofdT">Account</tp:dbus-ref>
>+ through which to communicate.
>+ </tp:docstring>
>+ </arg>
>+ <arg direction="in" name="Target_ID" type="s">
>+ <tp:docstring>
>+ The contact to send the message to.
>+ </tp:docstring>
>+ </arg>
> <arg direction="in" name="Message" type="aa{sv}"
>- tp:type="Message_Part[]"/>
>- <arg direction="in" name="Flags" type="u"/>
>- <arg direction="out" name="Token" type="s"/>
>+ tp:type="Message_Part[]">
>+ <tp:docstring>
>+ The parts of the message, the same as for <tp:dbus-ref
>+ namespace="ofdT.Channel.Interface">Messages.SendMessage</tp:dbus-ref>.
>+ </tp:docstring>
>+ </arg>
>+ <arg direction="in" name="Flags" type="u">
>+ <tp:docstring>
>+ Flags influencing how to send the message, the same as for <tp:dbus-ref
>+ namespace="ofdT.Channel.Interface">Messages.SendMessage</tp:dbus-ref>.
>+ </tp:docstring>
>+ </arg>
>+ <arg direction="out" name="Token" type="s">
>+ <tp:docstring>
>+ An opaque token equivalent to the one returned by <tp:dbus-ref
>+ namespace="ofdT.Channel.Interface">Messages.SendMessage</tp:dbus-ref>.
>+ </tp:docstring>
>+ </arg>
>+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
>+ Submit a message to the server for sending, like the
>+ <tp:dbus-ref namespace="ofdT.Channel.Interface">Messages.SendMessage</tp:dbus-ref>
>+ method.
>+
>+ If the <var>Account</var> is connected and a Text channel to the
>+ <var>Target_ID</var> already exists, this method is equivalent to
>+ sending the same message via that channel.
>+
>+ Otherwise, this method creates a channel (connecting the
>+ Account if appropriate), sends the desired message, and
>+ closes the channel as if via <tp:dbus-ref
>+ namespace="ofdT">Channel.Close</tp:dbus-ref>, without
>+ acknowledging any messages received on that channel
>+ during that time.
>+
>+ If any messages are received on that channel before it is
>+ closed, a correct connection manager implementation will reopen
>+ the channel when it is closed, resulting in those "rescued" messages
>+ being processed by the system's normal <tp:dbus-ref
>+ namespace="ofdT.Client">Handler</tp:dbus-ref> for text
>+ channels. In particular, this deals with the situation where
>+ a successful or failed delivery report is received
>+ before the channel is closed.
>+
>+ <tp:rationale>
>+ Expecting a trivial client (perhaps a send-only IRC bot,
>+ or a simple SMS-sending API) to go through all those steps to
>+ send a message seems somewhat unreasonable. Having this as a
>+ method in the ChannelDispatcher lets it take some short-cuts if
>+ required, and centralizes the implementation to reduce the risk of
>+ mistakes that cause message loss.
>+ </tp:rationale>
>+
>+ The ChannelDispatcher SHOULD support this method for any
>+ connection manager that would accept channel requests of this
>+ form:
>+
>+ <pre> {
>+ â¦<tp:dbus-ref namespace="ofdT">Channel.ChannelType</tp:dbus-ref>:
>+ â¦<tp:dbus-ref namespace="ofdT">Channel.Type.Text</tp:dbus-ref>,
>+ â¦<tp:dbus-ref namespace="ofdT">Channel.TargetHandleType</tp:dbus-ref>:
>+ <tp:value-ref type="Handle_Type">Contact</tp:value-ref>,
>+ â¦<tp:dbus-ref namespace="ofdT">Channel.TargetID</tp:dbus-ref>:
>+ <var>Target_ID</var>
>+ }</pre>
>+
>+ However, if the connection manager provides additional APIs
>+ (such as a way to open "send-only" channels), the
>+ ChannelDispatcher MAY use those: it is not required to use
>+ those exact request parameters.
>+
>+ This method may raise any error that would be raised by the
>+ <tp:dbus-ref
>+ namespace="ofdT.Connection.Interface">Requests.EnsureChannel</tp:dbus-ref>
>+ or <tp:dbus-ref
>+ namespace="ofdT.Channel.Interface">Messages.SendMessage</tp:dbus-ref>
>+ methods, or signalled by the <tp:dbus-ref
>+ namespace="ofdT.ChannelRequest">Failed</tp:dbus-ref>
>+ signal.
>+ </tp:docstring>
>+
>+ <tp:possible-errors>
>+ <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
>+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
>+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
>+ <tp:docstring>
>+ The connection manager does not implement Text channels
>+ that communicate with a named contact.
>+ </tp:docstring>
>+ </tp:error>
>+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle">
>+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
>+ The <var>Target_ID</var> was not syntactically valid for the
>+ <var>Account</var>'s protocol.
>+ </tp:docstring>
>+ </tp:error>
>+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle">
>+ <tp:docstring>
>+ The requested message is malformed and cannot be sent.
>+ </tp:docstring>
>+ </tp:error>
>+ <tp:error name="org.freedesktop.Telepathy.Error.Offline">
>+ <tp:docstring>
>+ The requested channel cannot be created because the target is
>+ offline.
>+ </tp:docstring>
>+ </tp:error>
>+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
>+ <tp:docstring>
>+ The requested channel cannot be created, but in
>+ principle, a similar request might succeed in future.
>+ </tp:docstring>
>+ </tp:error>
>+ <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
>+ </tp:possible-errors>
> </method>
> 
> </interface>
>diff --git a/spec/all.xml b/spec/all.xml
>index f41a700..616b880 100644
>--- a/spec/all.xml
>+++ b/spec/all.xml
>@@ -300,6 +300,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
> 
> </tp:docstring>
> <xi:include href="Channel_Dispatcher.xml"/>
>+ <xi:include href="Channel_Dispatcher_Interface_Messages1.xml"/>
> <xi:include href="Channel_Dispatcher_Interface_Operation_List.xml"/>
> <xi:include href="Channel_Dispatch_Operation.xml"/>
> <xi:include href="Channel_Request.xml"/>
>-- 
>1.8.4.rc3
>

Actions: View | Splinter Review

Attachments on bug 37380: 87466 | 87467 | 87468 | 87469 | 87470

Use of freedesktop.org services, including Bugzilla, is subject to our Code of Conduct. How we collect and use information is described in our Privacy Policy.