path: root/spec/Connection_Interface_Presence.xml

<?xml version="1.0" ?>
<node name="/Connection_Interface_Presence" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
  <tp:copyright>
    Copyright (C) 2005, 2006 Collabora Limited
  </tp:copyright>
  <tp:copyright>
Copyright (C) 2005, 2006 Nokia Corporation
  </tp:copyright>
  <tp:copyright>
Copyright (C) 2006 INdT
  </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.Connection.Interface.Presence">
    <tp:requires interface="org.freedesktop.Telepathy.Connection"/>
    <tp:requires interface="org.freedesktop.Telepathy.Connection.Interface.SimplePresence"/>

    <tp:mapping name="Multiple_Status_Map">
      <tp:docstring>Mapping used in
        <tp:type>Last_Activity_And_Statuses</tp:type> and passed to
        <tp:member-ref>SetStatus</tp:member-ref>, representing a collection of
        statuses. Use of this mapping with more than one member is
        deprecated.</tp:docstring>
      <tp:member type="s" name="Status"/>
      <tp:member type="a{sv}" tp:type="String_Variant_Map" name="Parameters"/>
    </tp:mapping>
    <tp:struct name="Last_Activity_And_Statuses" array-name="">
      <tp:docstring>Structure representing a contact's presence, containing
        a last-activity time (deprecated) and a Multiple_Status_Map.
      </tp:docstring>
      <tp:member type="u" tp:type="Unix_Timestamp" name="Last_Activity"/>
      <tp:member type="a{sa{sv}}" tp:type="Multiple_Status_Map"
        name="Statuses"/>
    </tp:struct>
    <tp:mapping name="Contact_Presences">
      <tp:docstring>Mapping returned by
        <tp:member-ref>GetPresence</tp:member-ref> and signalled by
        <tp:member-ref>PresenceUpdate</tp:member-ref>, where the keys are
        contacts and the values represent their presences.</tp:docstring>
      <tp:member type="u" tp:type="Contact_Handle" name="Contact"/>
      <tp:member type="(ua{sa{sv}})" tp:type="Last_Activity_And_Statuses"
        name="Presence"/>
    </tp:mapping>
    <tp:struct name="Status_Spec" array-name="">
      <tp:member type="u" tp:type="Connection_Presence_Type" name="Type"/>
      <tp:member type="b" name="May_Set_On_Self"/>
      <tp:member type="b" name="Exclusive"/>
      <tp:member type="a{ss}" tp:type="String_String_Map"
        name="Parameter_Types"/>
    </tp:struct>
    <tp:mapping name="Status_Spec_Map">
      <tp:member type="s" name="Identifier"/>
      <tp:member type="(ubba{ss})" tp:type="Status_Spec" name="Spec"/>
    </tp:mapping>

    <method name="AddStatus" tp:name-for-bindings="Add_Status">
      <arg direction="in" name="Status" type="s">
        <tp:docstring>
          The string identifier of the desired status
        </tp:docstring>
      </arg>
      <arg direction="in" name="Parameters" type="a{sv}" tp:type="String_Variant_Map">
        <tp:docstring>
          A dictionary of optional parameter names mapped to their variant-boxed values
        </tp:docstring>
      </arg>
      <tp:docstring>
        Request that a single presence status is published for the user, along
        with any desired parameters. Changes will be indicated by
        <tp:member-ref>PresenceUpdate</tp:member-ref> signals being emitted.
      </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.InvalidArgument"/>
        <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/>
        <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
      </tp:possible-errors>
    </method>
    <method name="ClearStatus" tp:name-for-bindings="Clear_Status">
      <tp:docstring>
        Request that all of a user's presence statuses be removed. Be aware
        that this request may simply result in the statuses being replaced by a
        default available status. Changes will be indicated by
        <tp:member-ref>PresenceUpdate</tp:member-ref> signals being emitted.
      </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.PermissionDenied"/>
      </tp:possible-errors>
    </method>
    <method name="GetPresence" tp:name-for-bindings="Get_Presence">
      <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]">
        <tp:docstring>
          An array of the contacts whose presence should be obtained
        </tp:docstring>
      </arg>
      <arg direction="out" name="Presence" type="a{u(ua{sa{sv}})}"
        tp:type="Contact_Presences">
        <tp:docstring>
          Presence information in the same format as for the
          <tp:member-ref>PresenceUpdate</tp:member-ref> signal
        </tp:docstring>
      </arg>
      <tp:docstring>
        Get presence previously emitted by
        <tp:member-ref>PresenceUpdate</tp:member-ref> for the given contacts.
        Data is returned in the same structure as the PresenceUpdate signal.
        Using this method in favour of
        <tp:member-ref>RequestPresence</tp:member-ref> has the advantage that
        it will not wake up each client connected to the PresenceUpdate signal.
      </tp:docstring>
      <tp:possible-errors>
        <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
        <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
        <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/>
      </tp:possible-errors>
    </method>
    <method name="GetStatuses" tp:name-for-bindings="Get_Statuses">
      <arg direction="out" type="a{s(ubba{ss})}" tp:type="Status_Spec_Map"
        name="Available_Statuses">
        <tp:docstring>
        A dictionary of string identifiers mapped to a struct for each status, containing:
        <ul>
          <li>a type value from one of the values above</li>
          <li>a boolean to indicate if this status may be set on yourself</li>
          <li>a boolean to indicate if this is an exclusive status which you
            may not set alongside any other</li>
          <li>a dictionary of valid optional string argument names mapped to
            their types</li>
        </ul>
        </tp:docstring>
      </arg>
      <tp:docstring>
        Get a dictionary of the valid presence statuses for this connection.
        This is only available when online because only some statuses will
        be available on some servers.
      </tp:docstring>
      <tp:possible-errors>
        <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
        <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
      </tp:possible-errors>
    </method>
    <signal name="PresenceUpdate" tp:name-for-bindings="Presence_Update">
      <arg name="Presence" type="a{u(ua{sa{sv}})}" tp:type="Contact_Presences">
        <tp:docstring>
        A dictionary of contact handles mapped to a struct containing
        a UNIX timestamp of the last activity time (in UTC), and
        a dictionary mapping the contact's current status identifiers to
          a dictionary of optional parameter names mapped to their
          variant-boxed values
        </tp:docstring>
      </arg>
      <tp:docstring>
        This signal should be emitted when your own presence has been changed,
        or the presence of the member of any of the connection's channels has
        been changed, or when the presence requested by
        <tp:member-ref>RequestPresence</tp:member-ref> is available.
      </tp:docstring>
    </signal>
    <method name="RemoveStatus" tp:name-for-bindings="Remove_Status">
      <arg direction="in" name="Status" type="s">
        <tp:docstring>
          The string identifier of the status not to publish anymore for the user
        </tp:docstring>
      </arg>
      <tp:docstring>
        Request that the given presence status is no longer published for the
        user. Changes will be indicated by
        <tp:member-ref>PresenceUpdate</tp:member-ref> signals being emitted. As
        with <tp:member-ref>ClearStatus</tp:member-ref>, removing a status may
        actually result in it being replaced by a default available status.
      </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.PermissionDenied"/>
        <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
          <tp:docstring>The status requested is not currently set</tp:docstring>
        </tp:error>
      </tp:possible-errors>
    </method>
    <method name="RequestPresence" tp:name-for-bindings="Request_Presence">
      <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]">
        <tp:docstring>
          An array of the contacts whose presence should be obtained
        </tp:docstring>
      </arg>
      <tp:docstring>
        Request the presence for contacts on this connection. A <tp:member-ref>PresenceUpdate</tp:member-ref>
        signal will be emitted when they are received. This is not the same as
        subscribing to the presence of a contact, which must be done using the
        'subscription' <tp:dbus-ref
        namespace="org.freedesktop.Telepathy.Channel.Type">ContactList</tp:dbus-ref>,
        and on some protocols presence information may not be available unless
        a subscription exists.
      </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.InvalidHandle"/>
        <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
        <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
          <tp:docstring>
            The presence of the requested contacts is not reported to this connection
          </tp:docstring>
        </tp:error>
      </tp:possible-errors>
    </method>
    <method name="SetLastActivityTime"
      tp:name-for-bindings="Set_Last_Activity_Time">
      <arg direction="in" name="Time" type="u" tp:type="Unix_Timestamp">
        <tp:docstring>
          A UNIX timestamp of the user's last activity time (in UTC)
        </tp:docstring>
      </arg>
      <tp:docstring>
        Request that the recorded last activity time for the user be updated on
        the server.
      </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>
            This protocol has no concept of idle time
          </tp:docstring>
        </tp:error>
      </tp:possible-errors>
    </method>
    <method name="SetStatus" tp:name-for-bindings="Set_Status">
      <arg direction="in" name="Statuses" type="a{sa{sv}}" tp:type="Multiple_Status_Map">
        <tp:docstring>
          A dictionary mapping status identifiers to dictionaries, which
          map optional parameter names to their variant-boxed values
        </tp:docstring>
      </arg>
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Request that the user's presence be changed to the given statuses
          and desired parameters. Changes will be reflected by
          <tp:member-ref>PresenceUpdate</tp:member-ref>
          signals being emitted.</p>

        <p>Statuses whose <tp:type>Connection_Presence_Type</tp:type>
          is Offline, Error or Unknown MUST NOT be passed to this
          function. Connection managers SHOULD reject these statuses.</p>

        <tp:rationale>
          <p>The same rationale as for <tp:dbus-ref
              namespace="org.freedesktop.Telepathy.Connection.Interface">SimplePresence.SetPresence</tp:dbus-ref>
            applies.</p>
        </tp:rationale>

        <p>On certain protocols, this method may be
          called on a newly-created connection which is still in the
          DISCONNECTED state, and will sign on with the requested status.
          If the requested status is not available after signing on,
          NotAvailable will be returned and the connection will remain
          offline, or if the protocol does not support signing on with
          a certain status, Disconnected will be returned.</p>
      </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.NotAvailable"/>
        <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/>
        <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
      </tp:possible-errors>
    </method>

    <tp:deprecated version="0.17.21">Client implementations
      SHOULD use <tp:dbus-ref
        namespace="org.freedesktop.Telepathy.Connection.Interface">SimplePresence</tp:dbus-ref>
      instead.</tp:deprecated>
    <tp:changed version="0.17.23">Connection managers implementing
      Presence MUST implement SimplePresence too.</tp:changed>

    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">

      <p>This interface is for services which have a concept of presence which
        can be published for yourself and monitored on your contacts.
        Telepathy's definition of presence is based on that used by
        <a href="http://www.galago-project.org/">the Galago project</a>.</p>

    <p>Presence on an individual (yourself or one of your contacts) is modelled as
    a last activity time along with a set of zero or more statuses, each of
    which may have arbitrary key/value parameters. Valid statuses are defined
    per connection, and a list of them can be obtained with the
    <tp:member-ref>GetStatuses</tp:member-ref> method.</p>

    <p>(The SimplePresence interface which replaces this one restricts
      presences to one status per contact, with an optional message, which is
      in practice all that was implemented on this interface.)</p>

    <p>Each status has an arbitrary string identifier which should have an agreed
    meaning between the connection manager and any client which is expected to
    make use of it. The well-known values defined by the <tp:dbus-ref
        namespace="org.freedesktop.Telepathy.Connection.Interface">SimplePresence</tp:dbus-ref>
      interface SHOULD be used where possible</p>

    <p>As well as these well-known status identifiers, every status also has a
    numerical type value chosen from
    <tp:type>Connection_Presence_Type</tp:type> which can be used by the client
    to classify even unknown statuses into different fundamental types.</p>

    <p>These numerical types exist so that even if a client does not understand
    the string identifier being used, and hence cannot present the presence to
    the user to set on themselves, it may display an approximation of the
    presence if it is set on a contact.</p>

    <p>The dictionary of variant types allows the connection manager to exchange
    further protocol-specific information with the client. It is recommended
    that the string (s) argument 'message' be interpreted as an optional
    message which can be associated with a presence status.</p>

    <p>If the connection has a 'subscribe' contact list,
    <tp:member-ref>PresenceUpdate</tp:member-ref> signals should be emitted to
    indicate changes of contacts on this list, and should also be emitted for
    changes in your own presence. Depending on the protocol, the signal may
    also be emitted for others such as people with whom you are communicating,
    and any user interface should be updated accordingly.</p>

    <p>On some protocols, <tp:member-ref>RequestPresence</tp:member-ref> may
    only succeed on contacts on your 'subscribe' list, and other contacts will
    cause a PermissionDenied error.  On protocols where there is no 'subscribe'
    list, and RequestPresence succeeds, a client may poll the server
    intermittently to update any display of presence information.</p>
    </tp:docstring>

  </interface>
</node>
<!-- vim:set sw=2 sts=2 et ft=xml: -->