diff options
Diffstat (limited to 'qt4/spec/Channel_Interface_SMS.xml')
| -rw-r--r-- | qt4/spec/Channel_Interface_SMS.xml | 179 |
1 files changed, 179 insertions, 0 deletions
diff --git a/qt4/spec/Channel_Interface_SMS.xml b/qt4/spec/Channel_Interface_SMS.xml new file mode 100644 index 000000000..4cfe3f2f8 --- /dev/null +++ b/qt4/spec/Channel_Interface_SMS.xml @@ -0,0 +1,179 @@ +<?xml version="1.0" ?> +<node name="/Channel_Interface_SMS" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright © 2008–2010 Nokia Corporation</tp:copyright> + <tp:copyright>Copyright © 2010 Collabora Ltd.</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> +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. + +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 +Library General Public License for more details. + +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. + </tp:license> + + <interface + name="org.freedesktop.Telepathy.Channel.Interface.SMS"> + <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.Text"/> + <tp:added version='0.19.12'>Imported from + rtcom-telepathy-glib, with the unused properties removed and the + documentation tidied up.</tp:added> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>This interface contains SMS-specific properties for text + channels.</p> + + <p>The presence of this interface on a channel does not imply that + messages will be delivered via SMS.</p> + + <p>This interface MAY appear in the + <tp:dbus-ref namespace="ofdT.Channel">Interfaces</tp:dbus-ref> property + of channels where <tp:member-ref>SMSChannel</tp:member-ref> would be + immutable and false. It SHOULD appear on channels where + <tp:member-ref>SMSChannel</tp:member-ref> is immutable and true, and + also on channels where <tp:member-ref>SMSChannel</tp:member-ref> is + mutable (i.e. channels that might fall back to sending SMS at any + time, such as on MSN).</p> + + <h4>Handler filters</h4> + + <p>A handler for class 0 SMSes should advertise the following filter:</p> + + <blockquote><code> +{ ...<tp:dbus-ref namespace='ofdT.Channel'>ChannelType</tp:dbus-ref>: + ...<tp:dbus-ref namespace='ofdT.Channel.Type'>Text</tp:dbus-ref>,<br/> + ...<tp:dbus-ref namespace='ofdT.Channel'>TargetHandleType</tp:dbus-ref>: + <tp:type>Handle_Type</tp:type>_Contact,<br/> + ...<tp:dbus-ref namespace='ofdT.Channel.Interface'>SMS.Flash</tp:dbus-ref>: + True,<br/> +}</code></blockquote> + + <p>It should also set its <tp:dbus-ref + namespace='ofdT.Client.Handler'>BypassApproval</tp:dbus-ref> property + to <code>True</code>, so that it is invoked immediately for new + channels.</p> + </tp:docstring> + + <property name="Flash" tp:name-for-bindings="Flash" + type="b" access="read" tp:immutable="yes"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If <code>True</code>, then this channel is exclusively for + receiving class 0 SMSes (and no SMSes can be sent using <tp:dbus-ref + namespace='ofdT.Channel.Interface.Messages'>SendMessage</tp:dbus-ref> + on this channel). If <code>False</code>, no incoming class 0 SMSes + will appear on this channel.</p> + + <p>This property is immutable (cannot change), and therefore SHOULD + appear wherever immutable properties are reported, e.g. <tp:dbus-ref + namespace="ofdT.Connection.Interface.Requests" + >NewChannels</tp:dbus-ref> signals.</p> + + <tp:rationale> + <p>Class 0 SMSes should be displayed immediately to the user, and + need not be saved to the device memory unless the user explicitly + chooses to do so. This is unlike “normal”, class 1 SMSes, which + must be stored, but need not be shown immediately in their entirity + to the user.</p> + + <p>Separating class 0 SMSes into their own channel with this + immutable property allows them to be dispatched to a different + <tp:dbus-ref namespace='ofdT.Client'>Handler</tp:dbus-ref>—which + would include this property in its <tp:dbus-ref + namespace='ofdT.Client.Handler' + >HandlerChannelFilter</tp:dbus-ref>—avoiding the normal Text + channel handler having to decide for each message whether it should + be displayed to the user immediately or handled normally.</p> + + <p>Currently, no mechanism is defined for <em>sending</em> class 0 + SMSes. It seems reasonable to support specifying the class of an + outgoing SMS in its header <tp:type>Message_Part</tp:type>, rather + than requiring the UI to request a special channel for such SMSes; + hence, we define here that channels with Flash set to + <code>True</code> are read-only.</p> + </tp:rationale> + </tp:docstring> + </property> + + <property name="SMSChannel" + tp:name-for-bindings="SMS_Channel" + type="b" + access="read" tp:requestable="yes" tp:immutable="sometimes"> + <tp:added version="0.21.7"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If TRUE, messages sent and received on this channel are transmitted + via SMS.</p> + + <p>If this property is included in the channel request, the + Connection Manager MUST return an appropriate channel (i.e. if TRUE + the channel must be for SMSes, if FALSE it must not), or else fail + to provide the requested channel with the + <tp:error-ref>NotCapable</tp:error-ref> + error.</p> + + <p>For example, to explicitly request an SMS channel to a contact. + You might construct a channel request like:</p> + + <blockquote><pre>{ + Channel.Type: Channel.Type.Text, + Channel.TargetHandleType: Handle_Type_Contact, + Channel.TargetID: escher.cat, + Channel.Interface.SMS.SMSChannel: True, +}</pre></blockquote> + + <tp:rationale> + Some protocols allow us to send SMSes to a remote contact, without + knowing the phone number to which those SMSes will be sent. This + provides a mechanism to request such channels. + </tp:rationale> + + <p>If this property is not included in the channel request, the + Connection Manager MAY return an SMS channel if that is the most + appropriate medium (i.e. if the channel target is a phone + number).</p> + + <tp:rationale> + To some types of identifiers (i.e. phone numbers) it only makes + sense to return an SMS channel, this is what happens currently with + telepathy-ring. We don't want to break this behaviour when we are + not explicit about the type of channel we want. Alternatively, for + protocols where there is an SMS fallback for IM messages, it's + possible that we don't care what sort of channel we get, and simply + want notification of the transport. + </tp:rationale> + + <p>Some protocols have a fallback to deliver IM messages via SMS. + On these protocols, the Connection Manager SHOULD set the property + value as appropriate, and notify its change with + <tp:member-ref>SMSChannelChanged</tp:member-ref>.</p> + + <tp:rationale> + Protocols such as MSN can fall back to delivering IM messages via + SMS. Where possible we want clients to be able to inform the user + that their messages are going to be redirected to the remote + contact's phone. + </tp:rationale> + </tp:docstring> + </property> + + <signal name="SMSChannelChanged" + tp:name-for-bindings="SMS_Channel_Changed"> + <tp:added version="0.21.7"/> + <arg name="SMSChannel" type="b"> + <tp:docstring> + The new value for <tp:member-ref>SMSChannel</tp:member-ref>. + </tp:docstring> + </arg> + <tp:docstring> + This signal indicates a change in the + <tp:member-ref>SMSChannel</tp:member-ref> property. + </tp:docstring> + </signal> + </interface> +</node> |