path: root/spec/Channel_Interface_SMS1.xml

<?xml version="1.0" ?>
<node name="/Channel_Interface_SMS1"
  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="im.telepathy.v1.Channel.Interface.SMS1">
    <tp:requires interface="im.telepathy.v1.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="imt1.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='imt1.Channel'>ChannelType</tp:dbus-ref>:
      ...<tp:dbus-ref namespace='imt1.Channel.Type'>Text</tp:dbus-ref>,<br/>
  ...<tp:dbus-ref namespace='imt1.Channel'>TargetHandleType</tp:dbus-ref>:
      <tp:value-ref type="Handle_Type">Contact</tp:value-ref>,<br/>
  ...<tp:dbus-ref namespace='imt1.Channel.Interface'>SMS1.Flash</tp:dbus-ref>:
      True,<br/>
}</code></blockquote>

      <p>It should also set its <tp:dbus-ref
        namespace='imt1.Client.Handler'>BypassApproval</tp:dbus-ref> property
        to <code>True</code>, so that it is invoked immediately for new
        channels.</p>

      <h4>Contact Capabilities</h4>

      <p>Contacts to whom SMSes can be sent SHOULD indicate this via a
        requestable channel class with
        <tp:member-ref>SMSChannel</tp:member-ref> = True as a fixed
        property.</p>

      <p>For instance, a contact that can accept both text and SMS channels:</p>

      <blockquote><code>
[<br/>
 ({ ...<tp:dbus-ref namespace='imt1.Channel'>ChannelType</tp:dbus-ref>:
     ...<tp:dbus-ref namespace='imt1.Channel.Type'>Text</tp:dbus-ref>,<br/>
    ...<tp:dbus-ref namespace='imt1.Channel'>TargetHandleType</tp:dbus-ref>:
       <tp:value-ref type="Handle_Type">Contact</tp:value-ref>,<br/>
  },<br/>
  [ ...<tp:dbus-ref namespace='imt1.Channel'>TargetHandle</tp:dbus-ref>,
    ...<tp:dbus-ref namespace='imt1.Channel'>TargetID</tp:dbus-ref> ]),<br/>
<br/>
 ({ ...<tp:dbus-ref namespace='imt1.Channel'>ChannelType</tp:dbus-ref>:
       ...<tp:dbus-ref namespace='imt1.Channel.Type'>Text</tp:dbus-ref>,<br/>
    ...<tp:dbus-ref namespace='imt1.Channel'>TargetHandleType</tp:dbus-ref>:
       <tp:value-ref type="Handle_Type">Contact</tp:value-ref>,<br/>
    ...<tp:member-ref>SMSChannel</tp:member-ref>: True,<br/>
  },<br/>
  [ ...<tp:dbus-ref namespace='imt1.Channel'>TargetHandle</tp:dbus-ref>,
    ...<tp:dbus-ref namespace='imt1.Channel'>TargetID</tp:dbus-ref> ]),<br/>
]
      </code></blockquote>
    </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='imt1.Channel.Type.Text'>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="imt1.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='imt1.Client'>Handler</tp:dbus-ref>—which
            would include this property in its <tp:dbus-ref
            namespace='imt1.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>

    <method name="GetSMSLength"
            tp:name-for-bindings="Get_SMS_Length">
      <tp:added version="0.23.1"/>

      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Returns the number of 140 octet chunks required to send a message
          via SMS, as well as the number of remaining characters available in
          the final chunk and, if possible, an estimate of the cost.</p>

        <tp:rationale>
          <p>There are a number of different SMS encoding mechanisms, and the
            client doesn't know which mechanisms an individual CM might support.
            This method allows the client, without any knowledge of the
            encoding mechanism, to provide length details to the user.</p>
        </tp:rationale>

        <p>Clients SHOULD limit the frequency with which this method is called
        and SHOULD NOT call it for every keystroke. Clients MAY estimate the
        remaining size between single keystrokes.</p>
      </tp:docstring>

      <arg name="Message" type="aa{sv}" tp:type="Message_Part[]" direction="in">
        <tp:docstring>
          The message the user wishes to send.
        </tp:docstring>
      </arg>

      <arg name="Chunks_Required" type="u" direction="out">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>The number of 140 octet chunks required to send this message.</p>

          <p>For example, in the GSM standard 7-bit encoding, a 162 character
            message would require 2 chunks.</p>
        </tp:docstring>
      </arg>

      <arg name="Remaining_Characters" type="i" direction="out">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>The number of further characters that can be fit in the final
            chunk. A negative value indicates that the message will be
            truncated by <code>abs(Remaining_Characters)</code>. The value
            <code>MIN_INT32</code> (<code>-2<sup>31</sup></code>)
            indicates the message will be truncated by an unknown amount.</p>

          <p>For example, in the GSM standard 7-bit encoding, a 162 character
            message would return 144 remaining characters (because of the
            space required for the multipart SMS header).</p>
        </tp:docstring>
      </arg>

      <arg name="Estimated_Cost" type="i" direction="out">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>The estimated cost of sending this message. The currency and
            scale of this value are the same as the
            <tp:dbus-ref namespace="imt1.Connection.Interface">Balance1.AccountBalance</tp:dbus-ref>
            property.</p>

          <p>A value of <code>-1</code> indicates the cost could not be
            estimated.</p>

        </tp:docstring>
      </arg>

      <tp:possible-errors>
        <tp:error name="im.telepathy.v1.Error.NotImplemented">
          <tp:docstring>
            Raised when the method is not available on this channel.
            Clients MAY choose to make their own estimation.
          </tp:docstring>
        </tp:error>
        <tp:error name="im.telepathy.v1.Error.InvalidArgument">
          <tp:docstring>
            Raised when the content cannot be encoded into a valid SMS.
          </tp:docstring>
        </tp:error>
      </tp:possible-errors>
    </method>
  </interface>
</node>