<?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>