path: root/spec/Account.xml

<?xml version="1.0" ?>
<node name="/Account"
  xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
  <tp:copyright>Copyright © 2008-2009 Collabora Ltd.</tp:copyright>
  <tp:copyright>Copyright © 2008-2009 Nokia Corporation</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="im.telepathy.Account">
    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
      <p>An Account object encapsulates the necessary details to make a
        Telepathy connection.</p>

      <p>Accounts are uniquely identified by object path. The object path
        of an Account MUST take the form
        <code>/im/telepathy/Account/<em>cm</em>/<em>proto</em>/<em>acct</em></code>, where:</p>

      <ul>
        <li><em>cm</em> is the same <tp:type>Connection_Manager_Name</tp:type>
          that appears in the connection manager's well-known bus name and
          object path</li>
        <li><em>proto</em> is the <tp:type>Protocol</tp:type> name as seen in
          <tp:dbus-ref
          namespace="im.telepathy">ConnectionManager.ListProtocols</tp:dbus-ref>,
          but with "-" replaced with "_"
          (i.e. the same as in the object-path of a <tp:dbus-ref
          namespace="im.telepathy">Connection</tp:dbus-ref>)</li>
        <li><em>acct</em> is an arbitrary string of ASCII letters, digits
          and underscores, starting with a letter or underscore, which
          uniquely identifies this account</li>
        <li>Clients SHOULD parse the object path to discover the
          connection manager and protocol</li>
        <li>Clients MUST NOT attempt to parse <em>acct</em></li>
        <li>Clients MUST NOT assume that <em>acct</em> matches
          the connection-specific part of a Connection's object-path and
          bus name</li>
        <li>The account manager SHOULD choose <em>acct</em> such that if
          an account is deleted, its object path will be re-used if and only
          if the new account is in some sense "the same"
          (incorporating the 'account' parameter in some way is
          recommended)</li>
      </ul>

      <tp:rationale>
        <p>This API avoids specifying the "profiles" used in Mission Control
          4.x or the "presets" that have been proposed to replace them. An
          optional interface will be provided for AM implementations
          that want to provide presets.</p>

        <p>There is deliberately no functionality here for opening channels;
          we intend to provide that in the channel dispatcher.</p>

        <p>Other missing features which would be better in their own
          interfaces:</p>

        <ul>
          <li>dynamic parameter-providing (aka provisioning)</li>
          <li>saved server capabilities</li>
          <li>account conditions</li>
          <li>account grouping</li>
        </ul>
      </tp:rationale>

    </tp:docstring>
    <tp:added version="0.17.2"/>
    <tp:changed version="0.17.6">moved the Avatar property to a separate
      interface</tp:changed>

    <!-- Missing functionality compared with NMC 4.x account + profile,
    apart from as listed above:

    * vCard field, + default profile for each vCard field
      (vCard field is per protocol and should be chosen by the
      Telepathy <-> address-book bridge?; default profile is now
      meaningless)

    * "normalized name" (normalized handle?)

    * branding icon (what's this and how does it differ from the icon?)

    * configuration UI (not our problem - perhaps the UI could special-case
      by cm,protocol,preset tuples?)

    * default account domain (somewhat meaningless in general; specialized
      account config UI can hard-code this)

    * SPLIT_ACCOUNT (pseudo-capability - this is a property of the protocol,
      not the profile, and in any case only the account config UI cares)

    Missing functionality compared with Decibel accounts:

    * we don't really know, they take arbitrary key/value pairs...
      but display name, protocol, presence/message, current, autoreconnect
      are the ones given special status by the source, and we have all of them
    -->

    <property name="Interfaces" tp:name-for-bindings="Interfaces"
      type="as" tp:type="DBus_Interface[]" access="read">
      <tp:docstring>
        A list of the extra interfaces provided by this account.
      </tp:docstring>
    </property>

    <method name="Remove" tp:name-for-bindings="Remove">
      <tp:docstring>Delete the account.</tp:docstring>
      <tp:possible-errors>
        <tp:error name="im.telepathy.Error.PermissionDenied"/>
      </tp:possible-errors>
    </method>

    <signal name="Removed" tp:name-for-bindings="Removed">
      <tp:docstring>
        This account has been removed.

        <tp:rationale>
          This is redundant with <tp:dbus-ref
          namespace="im.telepathy.AccountManager">AccountRemoved</tp:dbus-ref>,
          but it's still worth having,
          to avoid having to bind to AccountManager.AccountRemoved to tell
          you whether your Account is valid — ideally, an account-editing UI
          should only care about a single Account.
        </tp:rationale>
      </tp:docstring>
    </signal>

    <signal name="AccountPropertyChanged"
      tp:name-for-bindings="Account_Property_Changed">
      <tp:docstring>
        The values of one or more properties on this interface (that do not
        specify that this signal does not apply to them) may have changed.
        This does not cover properties of other interfaces, which must
        provide their own change notification if appropriate.
      </tp:docstring>

      <arg name="Properties" type="a{sv}">
        <tp:docstring>
          A map from property names in this namespace (e.g.
          <tp:member-ref>Nickname</tp:member-ref>) to
          values. Properties whose values have not changed SHOULD be
          omitted, but this need not be done.
        </tp:docstring>
      </arg>
    </signal>

    <property name="DisplayName" type="s" access="readwrite"
      tp:name-for-bindings="Display_Name">
      <tp:docstring>
        The user-visible name of this account. This SHOULD be chosen by the
        user at account creation time. The account creation user interface
        is responsible for setting a reasonable default value in the user's
        locale; something like "Jabber (bob@example.com)" would be sensible.
      </tp:docstring>
    </property>

    <property name="Icon" tp:name-for-bindings="Icon"
      type="s" access="readwrite">
      <tp:docstring>
        The name of an icon in the system's icon theme, such as "im-msn",
        or the empty string to not specify an icon. If the icon is set to
        an empty string, the account manager or any client MAY derive a
        default icon, for instance from the protocol.
      </tp:docstring>
    </property>

    <property name="Valid" tp:name-for-bindings="Valid"
      type="b" access="read">
      <tp:docstring>
        If true, this account is considered by the account manager to be
        complete and usable. If false, user action is required to make it
        usable, and it will never attempt to connect (for instance, this
        might be caused by the absence of a required parameter).

        <tp:rationale>
          For connection managers with a plugin architecture, like
          telepathy-haze, we have little or no control over the parameters
          offered; for platforms with package management, we have little or
          no control over the CMs offered. NMC 4.x would just pretend the
          account didn't exist in these circumstances, but silent data loss
          is bad, and UIs with CM-specific knowledge (or a user filling in
          newly-required parameters) might be able to rescue a broken account.
        </tp:rationale>
      </tp:docstring>
    </property>

    <property name="Enabled" tp:name-for-bindings="Enabled"
      type="b" access="readwrite">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>This property gives the users the possibility to prevent an account
          from being used. This flag does not change the validity of the
          account.</p>

        <p>A disabled account can never be put online.</p>

        <tp:rationale>
          <p>Use cases:</p>

          <ul>
            <li>user has two or more accounts capable of calling contact X, but
              he doesn't want the UI to prompt him everytime about which one he
              wants to use for the call. He can then disable all the equivalent
              accounts but one.</li>

            <li>There is some temporary server error and the user doesn't want
              to be be bother by error messages, or change the account
              configuration: temporarily disabling the account is quicker.</li>
          </ul>
        </tp:rationale>

        <p>The AccountManager SHOULD allow this property to be set on invalid
          accounts, but MUST NOT attempt to put invalid accounts online
          even if they become Enabled.</p>

        <tp:rationale>
          <p>There doesn't seem to be any good reason not to allow this.</p>
        </tp:rationale>
      </tp:docstring>
    </property>

    <property name="Nickname" tp:name-for-bindings="Nickname"
      type="s" access="readwrite">
      <tp:docstring>
        The nickname to set on this account for display to other contacts,
        as set by the user. When the account becomes connected, the
        account manager SHOULD set this as the user's alias using <tp:dbus-ref
        namespace="im.telepathy.Connection.Interface.Aliasing">SetAliases</tp:dbus-ref>
        if appropriate.

        <tp:rationale>
          In a later specification revision, we plan to separate the concepts
          of a contact's nickname as set by themselves, and the local
          name for them in our contact list (a "handle" or "pet name" as
          described in XEP-0165 and its references). The terminology change
          from alias to nickname here is a step in that direction.
        </tp:rationale>
      </tp:docstring>
    </property>

    <property name="Service" tp:name-for-bindings="Service" type="s"
        access="readwrite">
      <tp:added version="0.19.8"/>
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Some protocols, like XMPP and SIP, are used by various different
          user-recognised brands, such as <i>Google Talk</i> and <i>Ovi by
          Nokia</i>. On accounts for such services, this property SHOULD be
          set to a string describing the service, which MUST consist only of
          ASCII letters, numbers and hyphen/minus signs, and start with a
          letter (matching the requirements for <tp:type>Protocol</tp:type>).
          For the <tt>jabber</tt> protocol, one of the following service names
          should be used if possible:</p>

        <ul>
          <li><tt>google-talk</tt> (for <a
            href="http://www.google.com/talk/">Google's IM service</a>)</li>
          <li><tt>ovi-chat</tt> (for <a href="http://www.ovi.com/">Ovi</a>'s IM
            service)</li>
          <li><tt>facebook</tt> (for <a
            href="http://www.facebook.com/sitetour/chat.php">Facebook's IM
            service</a>)</li>
          <li><tt>lj-talk</tt> (for <a
            href="http://www.livejournal.com/chat/">LiveJournal's IM
            service</a>)</li>
          <li><tt>windows-live</tt> (for <a
            href="http://live.com">Windows Live Messenger IM service</a>)</li>

        </ul>

        <p>The <tp:member-ref>Icon</tp:member-ref> property SHOULD be set to a
          corresponding brand-specific icon name, if possible. In the future,
          this property may be used as an index into additional
          service-specific customizations. If this property is the empty string
          (or missing), the service is determined by the protocol name (either
          because this is a single-service protocol like <tt>msn</tt>, or
          because this is just a generic <tt>jabber</tt> or <tt>sip</tt>
          account without specific branding).</p>

        <p>This property MAY be set, if appropriate, when calling
          <tp:dbus-ref
            namespace="im.telepathy.AccountManager"
            >CreateAccount</tp:dbus-ref>. Updating this property will fail on
          externally-stored accounts whose <tp:dbus-ref
            namespace="im.telepathy.Account.Interface.Storage"
            >StorageRestrictions</tp:dbus-ref> include
          <code>Cannot_Set_Service</code>.</p>
      </tp:docstring>
    </property>

    <property name="Parameters" tp:name-for-bindings="Parameters"
      type="a{sv}" access="read">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>A map from connection manager parameter names (as in the
          <tp:dbus-ref
          namespace="im.telepathy">ConnectionManager</tp:dbus-ref>
          interface) to their values. This property includes
          only those parameters that are stored for this account, and SHOULD
          only include those parameters that the user has explicitly set.
        </p>
        <p>This property cannot be altered using
          <code>org.freedesktop.DBus.Properties.Set()</code>; use
          <tp:member-ref>UpdateParameters</tp:member-ref> instead.</p>
      </tp:docstring>
    </property>

    <method name="UpdateParameters" tp:name-for-bindings="Update_Parameters">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Change the value of the <tp:member-ref>Parameters</tp:member-ref>
          property.</p>

        <p>If any of the <var>Set</var> parameters’
          <tp:type>Conn_Mgr_Param_Flags</tp:type> include
          <code>DBus_Property</code>, the change will be applied immediately to
          the corresponding D-Bus Property on the active
          <tp:member-ref>Connection</tp:member-ref>, if there is one. If any of
          the <var>Unset</var> parameters’
          <tp:type>Conn_Mgr_Param_Flags</tp:type> include both
          <code>DBus_Property</code> and <code>Has_Default</code>, the
          corresponding D-Bus Property on the connection will be set to the
          default value.  Changes to other parameters will not take effect
          until the next time the account is disconnected and reconnected. (If
          parameters are explicitly set to their default value, or are unset
          when previously set to their default value, the account manager MAY
          decide that no reconnection is necessary to make the change take
          effect.)</p>

        <tp:rationale>
          <p>In general, reconnecting is a destructive operation that shouldn't
            happen as a side-effect. In particular, migration tools that
            twiddle the settings of all accounts shouldn't cause an automatic
            disconnect and reconnect.</p>
        </tp:rationale>
      </tp:docstring>

      <tp:changed version="0.17.16">
        parameters which are also D-Bus properties can and should be updated on
        existing Connections
      </tp:changed>

      <tp:changed version="0.17.24">
        return an array of the parameters that won't change until the account
        is reconnected
      </tp:changed>

      <arg name="Set" type="a{sv}" direction="in">
        <tp:docstring>
          A mapping from parameter names to their values. These parameters
          should be stored for future use.
        </tp:docstring>
      </arg>

      <arg name="Unset" type="as" direction="in">
        <tp:docstring>
          A list of the names of parameters to be removed from the set of
          stored values, allowing the default values to be used.
          If the given parameters were not, in fact, stored, or even if they
          do not exist at all, the account manager MUST accept this without
          error.
        </tp:docstring>
      </arg>

      <arg name="Reconnect_Required" type="as" direction="out">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>If all of the updates could be applied to the active
            <tp:member-ref>Connection</tp:member-ref> (if any),
            the empty list, signifying that no reconnection is required for the
            new parameters to take effect. For example, if the only parameter
            updated is <tt>...Cellular.<tp:dbus-ref
              namespace="im.telepathy.Connection.Interface.Cellular">MessageValidityPeriod</tp:dbus-ref></tt>,
            the new value can be applied immediately to the connection.</p>

          <p>Otherwise, a list of the names of parameters with changes that
            will not take effect until the account is reconnected. User
            interfaces that require "instant apply" semantics MAY call
            <tp:member-ref>Reconnect</tp:member-ref> in response to receiving a
            non-empty list. For example, if the caller updates both
            <tt>...Anonymity.<tp:dbus-ref
              namespace="im.telepathy.Connection.Interface.Anonymity">AnonymityMandatory</tp:dbus-ref></tt>
            and <tt>require-encryption</tt>, the former can be applied to the
            current connection, but the latter needs a reconnect to take
            effect, so this method should return
            <code>["require-encryption"]</code>.</p>
        </tp:docstring>
      </arg>

      <tp:possible-errors>
        <tp:error name="im.telepathy.Error.PermissionDenied"/>
        <tp:error name="im.telepathy.Error.InvalidArgument"/>
      </tp:possible-errors>
    </method>

    <property name="AutomaticPresence" type="(uss)" access="readwrite"
      tp:type="Simple_Presence" tp:name-for-bindings="Automatic_Presence">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>The presence status that this account should have if it is brought
          online.</p>

        <tp:rationale>
          In ITOS2007 and ITOS2008 this is a global preference, not visible
          on D-Bus (the "default presence"). "Automatic presence" better
          describes when it is used.
        </tp:rationale>

        <p>Setting this property MUST NOT actually change the account's
          status until the next time it is (re)connected for some reason.</p>

        <p>The value of this property MUST be one that would be acceptable
          for <tp:member-ref>RequestedPresence</tp:member-ref>,
          with the additional restriction that the
          <tp:type>Connection_Presence_Type</tp:type> MUST NOT be Offline.</p>

        <tp:rationale>
          <p>Otherwise, it would not be possible to use this presence to bring
            the account online for a channel request.</p>
        </tp:rationale>
      </tp:docstring>
    </property>

    <property name="ConnectAutomatically" type="b" access="readwrite"
      tp:name-for-bindings="Connect_Automatically">
      <tp:docstring>
        If true, the account manager SHOULD attempt to put this account
        online with the <tp:member-ref>AutomaticPresence</tp:member-ref>
        whenever possible (in the base
        Account interface this is deliberately left vague). If false,
        it MUST NOT put the account online automatically in response to,
        for instance, connectivity changes, but SHOULD still put the account
        online with the <tp:member-ref>AutomaticPresence</tp:member-ref> if
        requested by the user (for
        instance, if the user tries to start a conversation using this
        account).
      </tp:docstring>
    </property>

    <property name="Connection" tp:name-for-bindings="Connection"
      type="o" access="read">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Either the object path of the <tp:dbus-ref
          namespace="im.telepathy">Connection</tp:dbus-ref> to
        this account, or the special value <code>'/'</code> if there is no
        connection.</p>

        <p>If this object path is not '/', the Connection's well-known bus
          name can be derived from this object path by removing the first '/'
          and replacing subsequent '/' characters with '.'.</p>

        <tp:rationale>
          Object paths aren't nullable, so we can't use an empty string.
        </tp:rationale>
      </tp:docstring>
    </property>

    <property name="ConnectionStatus" type="u" tp:type="Connection_Status"
      access="read" tp:name-for-bindings="Connection_Status">
      <tp:docstring>
        If the <tp:member-ref>Connection</tp:member-ref> property is non-empty,
        the status of that connection.
        If the Connection property is the empty string, this property may
        either be Disconnected (indicating that the account manager is not
        attempting to bring it online), or Connecting (indicating that the
        account manager is attempting to connect).
        The account manager is expected to set this by observing signals
        from the Connection.

        <tp:rationale>
          If the AM is doing some sort of backoff/delay on reconnection
          attempts, the account's status is conceptually "Connecting" even
          though there is no Connection.
        </tp:rationale>
      </tp:docstring>
    </property>

    <property name="ConnectionStatusReason" type="u"
      tp:type="Connection_Status_Reason" access="read"
      tp:name-for-bindings="Connection_Status_Reason">
      <tp:docstring>
        The reason for the last change to
        <tp:member-ref>ConnectionStatus</tp:member-ref>.
        The account manager is expected to set this by observing signals
        from the Connection.

        <tp:rationale>
          If you weren't watching the Connection at the time it failed,
          you can't tell why - unless the AM can tell you.
        </tp:rationale>
      </tp:docstring>
    </property>

    <property name="ConnectionError" tp:name-for-bindings="Connection_Error"
      access="read" type="s" tp:type="DBus_Error_Name">
      <tp:added version="0.19.7"/>
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>If the last connection to this account failed with an error,
          the D-Bus error name of that error; otherwise, the empty string.
          The account manager is expected to set this by observing the
          <tp:dbus-ref namespace="im.telepathy"
            >Connection.ConnectionError</tp:dbus-ref> and
          <tp:dbus-ref namespace="im.telepathy"
            >Connection.StatusChanged</tp:dbus-ref>
          signals.</p>

        <p>If ConnectionError is received before the connection disconnects,
          its first argument should be used to set this property;
          otherwise, the Reason argument of StatusChanged should be converted
          to a suitable D-Bus error name.</p>

        <p>Whenever the Connection connects successfully, this property should
          be reset to the empty string.</p>

        <tp:rationale>
          <p>This combines the state-recoverability of
            <tp:member-ref>ConnectionStatusReason</tp:member-ref> with the
            extensibility of Connection.ConnectionError.</p>
        </tp:rationale>
      </tp:docstring>
    </property>

    <property name="ConnectionErrorDetails"
      tp:name-for-bindings="Connection_Error_Details"
      access="read" type="a{sv}" tp:type="String_Variant_Map">
      <tp:added version="0.19.7"/>
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>If the last connection to this account failed with an error,
          a mapping representing any additional information about the last
          disconnection; otherwise, the empty map. The keys and values are
          the same as for the second argument of
          <tp:dbus-ref namespace="im.telepathy"
            >Connection.ConnectionError</tp:dbus-ref>.</p>

        <p>Whenever the Connection connects successfully, this property should
          be reset to the empty map.</p>

        <tp:rationale>
          <p>This combines the state-recoverability of
            <tp:member-ref>ConnectionStatusReason</tp:member-ref> with the
            extensibility of Connection.ConnectionError.</p>
        </tp:rationale>
      </tp:docstring>
    </property>

    <property name="CurrentPresence" type="(uss)" access="read"
      tp:type="Simple_Presence" tp:name-for-bindings="Current_Presence">
      <tp:docstring>
        The actual presence. If the connection is not online, the
        <tp:type>Connection_Presence_Type</tp:type> SHOULD be
        Connection_Presence_Type_Offline.
        If the connection is online but does not support the <tp:dbus-ref
        namespace="im.telepathy.Connection.Interface">SimplePresence</tp:dbus-ref>
        interface, the type SHOULD be Connection_Presence_Type_Unset.
        The account manager is expected to set this by observing signals
        from the Connection.
      </tp:docstring>
    </property>

    <property name="RequestedPresence" type="(uss)" access="readwrite"
      tp:type="Simple_Presence" tp:name-for-bindings="Requested_Presence">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>The requested presence for this account. When this is changed, the
        account manager should attempt to manipulate the connection manager to
        make <tp:member-ref>CurrentPresence</tp:member-ref> match
        <tp:member-ref>RequestedPresence</tp:member-ref> as closely as
          possible. It should not be saved to any sort of persistent
          storage.</p>

        <p>When the account manager automatically connects an account,
          it must signal this by setting the RequestedPresence to the same
          thing as the <tp:member-ref>AutomaticPresence</tp:member-ref>.</p>

        <p>The <tp:type>Connection_Presence_Type</tp:type> in this property
          MUST NOT be Unset, Unknown or Error.</p>

        <tp:rationale>
          <p>Requesting those presence types doesn't make sense.</p>
        </tp:rationale>
      </tp:docstring>
    </property>

    <property name="ChangingPresence" tp:name-for-bindings="Changing_Presence"
      type="b" access="read">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>If true, a change to the presence of this account is
        in progress.</p>

        <p>Whenever <tp:member-ref>RequestedPresence</tp:member-ref> is set on
        an account that could go online, or whenever an account with a
        non-offline <tp:member-ref>RequestedPresence</tp:member-ref> becomes
        able to go online (for instance because
        <tp:member-ref>Enabled</tp:member-ref> or
        <tp:member-ref>Valid</tp:member-ref> changes to True),
        ChangingPresence MUST change to True, and the two property changes MUST
        be emitted in the same
        <tp:member-ref>AccountPropertyChanged</tp:member-ref> signal, before the
        Set method returns.</p>

        <p>When the account manager succeeds or fails in changing the presence,
        or the connection disconnects due to an error, ChangingPresence MUST
        change to False as part of the same
        <tp:member-ref>AccountPropertyChanged</tp:member-ref> signal.</p>

        <tp:rationale>
          <p>This allows UIs to indicate that a presence change is in progress
          or has finished, even if the change was initiated by a different
          UI.</p>

          <p>For instance, Maemo 5 and Empathy indicate a presence change by
          having the presence indicator alternate between the
          <tp:member-ref>RequestedPresence</tp:member-ref>
          and the <tp:member-ref>CurrentPresence</tp:member-ref>; they should
          start blinking when ChangingPresence becomes true, and stop when it
          becomes false.</p>
        </tp:rationale>

      </tp:docstring>
    </property>

    <method name="Reconnect" tp:name-for-bindings="Reconnect">
      <tp:added version="0.17.24"/>
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Re-connect this account. If the account is currently disconnected
          and the requested presence is offline, or if the account
          is not <tp:member-ref>Enabled</tp:member-ref> or not
          <tp:member-ref>Valid</tp:member-ref>, this does nothing.</p>

        <p>If the account is disconnected and the requested presence is not
          offline, this forces an attempt to connect with the requested
          presence immediately.</p>

        <p>If the account is connecting or connected, this is equivalent to
          remembering the current value of
          <tp:member-ref>RequestedPresence</tp:member-ref>, setting its value
          to (OFFLINE, "offline", ""), waiting for the change to take effect,
          then setting its value to the value that was previously
          remembered.</p>

        <tp:rationale>
          <p>Clients desiring "instant apply" semantics for CM parameters MAY
            call this method to achieve that.</p>
        </tp:rationale>

        <p>In particular, if the account's
          <tp:member-ref>Connection</tp:member-ref> is in the Connecting
          state, calling this method causes the attempt to connect to be
          aborted and re-tried.</p>

        <tp:rationale>
          <p>This is necessary to ensure that the new parameters are
            picked up.</p>
        </tp:rationale>
      </tp:docstring>
    </method>

    <property name="NormalizedName" type="s" access="read"
      tp:name-for-bindings="Normalized_Name">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>The normalized user ID of the local user on this account (i.e. the
          string returned when the <tp:dbus-ref
          namespace="im.telepathy.Connection">InspectHandles</tp:dbus-ref>
          method is called on the value of the <tp:dbus-ref
          namespace="im.telepathy.Connection">SelfHandle</tp:dbus-ref>
          property for an active connection).</p>

        <p>It is unspecified whether this user ID is globally unique.</p>

        <tp:rationale>
          <p>As currently implemented, IRC user IDs are only unique within
            the same IRCnet. On some saner protocols, the user ID includes a
            DNS name which provides global uniqueness.</p>
        </tp:rationale>

        <p>If this value is not known yet (which will always be the case for
          accounts that have never been online), it will be an empty
          string.</p>

        <p>It is possible that this value will change if the connection
          manager's normalization algorithm changes, although this SHOULD
          be avoided.</p>

        <tp:rationale>
          <p>It's not always completely clear what normalization algorithm
            should be used; for instance, in Gabble, we currently use JIDs,
            but it would also have been reasonable to use xmpp URIs.</p>
        </tp:rationale>
      </tp:docstring>
    </property>

    <property name="HasBeenOnline" tp:name-for-bindings="Has_Been_Online"
      type="b" access="read">
      <tp:docstring>
        If true, this account has successfully been put online at some point
        in the past.

        <tp:rationale>
          UIs could apply a policy that the 'account' parameter can only be
          edited in accounts that have never been online, or that
          ConnectAutomatically cannot be set on such accounts. The account
          manager should not enforce such policies, but it can expose enough
          information to UIs that the UI can decide what to do.
        </tp:rationale>
      </tp:docstring>
    </property>

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