path: root/spec/errors.xml

<?xml version="1.0" ?>
<tp:errors xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0" namespace="org.freedesktop.Telepathy.Error">

  <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
    <p>The D-Bus errors used in Telepathy all start with
      <code>org.freedesktop.Telepathy.Error.</code>. They are used in
      D-Bus messages of type ERROR, and also as plain strings annotated with
      the <tp:type>DBus_Error_Name</tp:type> type.</p>

    <p>In principle, any method can raise any error (this is a general fact
      of IPC). For instance, generic D-Bus errors starting with
      <code>org.freedesktop.DBus.Error.</code> will occur in some
      situations.</p>

    <p>Telepathy methods can also raise implementation-specific errors to
      indicate specialized failure conditions. For better interoperability,
      if a suitable Telepathy error exists, it should be preferred.</p>

    <p>The namespace <code>org.freedesktop.Telepathy.Qt4.Error.</code>
      is reserved for use by the D-Bus client implementation in telepathy-qt4,
      which uses it to represent certain error situations that did not involve
      a D-Bus ERROR message. These errors are defined and documented as part of
      telepathy-qt4's C++ API, and should not be used on D-Bus.</p>
  </tp:docstring>

  <tp:error name="Network Error">
    <tp:docstring>
    Raised when there is an error reading from or writing to the network.
    </tp:docstring>
  </tp:error>

  <tp:error name="Not Implemented">
    <tp:docstring>
    Raised when the requested method, channel, etc is not available on this connection.
    </tp:docstring>
  </tp:error>

  <tp:error name="Invalid Argument">
    <tp:docstring>
    Raised when one of the provided arguments is invalid.
    </tp:docstring>
  </tp:error>

  <tp:error name="Not Available">
    <tp:docstring>
    Raised when the requested functionality is temporarily unavailable.
    </tp:docstring>
  </tp:error>

  <tp:error name="Permission Denied">
    <tp:docstring>
    The user is not permitted to perform the requested operation.
    </tp:docstring>
  </tp:error>

  <tp:error name="Disconnected">
    <tp:docstring>
      The connection is not currently connected and cannot be used.
      This error may also be raised when operations are performed on a
      Connection for which
      <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection">StatusChanged</tp:dbus-ref>
      has signalled status Disconnected for reason None.

      <tp:rationale>
        The second usage corresponds to None in the
        <tp:type>Connection_Status_Reason</tp:type> enum; if a better reason
        is available, the corresponding error should be used instead.
      </tp:rationale>
    </tp:docstring>
  </tp:error>

  <tp:error name="Invalid Handle">
    <tp:docstring>
    The handle specified is unknown on this channel or connection.
    </tp:docstring>
  </tp:error>

  <tp:error name="Channel.Banned">
    <tp:docstring>
    You are banned from the channel.
    </tp:docstring>
  </tp:error>

  <tp:error name="Channel.Full">
    <tp:docstring>
    The channel is full.
    </tp:docstring>
  </tp:error>

  <tp:error name="Channel.Invite Only">
    <tp:docstring>
    The requested channel is invite-only.
    </tp:docstring>
  </tp:error>

  <tp:error name="Not Yours">
    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
      <p>The requested channel or other resource already exists, and another
        user interface in this session is responsible for it.</p>

      <p>User interfaces SHOULD handle this error unobtrusively, since it
        indicates that some other user interface is already processing the
        channel.</p>
    </tp:docstring>
  </tp:error>

  <tp:error name="Cancelled">
    <tp:docstring>
      Raised by an ongoing request if it is cancelled by user request before
      it has completed, or when operations are performed on an object which
      the user has asked to close (for instance, a Connection where the user
      has called Disconnect, or a Channel where the user has called Close).

      <tp:rationale>
        The second form can be used to correspond to the Requested member in
        the <tp:type>Connection_Status_Reason</tp:type> enum, or to
        to represent the situation where disconnecting a Connection,
        closing a Channel, etc. has been requested by the user but this
        request has not yet been acted on, for instance because the
        service will only act on the request when it has finished processing
        an event queue.
      </tp:rationale>
    </tp:docstring>
  </tp:error>

  <tp:error name="Authentication Failed">
    <tp:docstring>
      Raised when authentication with a service was unsuccessful.
      <tp:rationale>
        This corresponds to Authentication_Failed in the
        <tp:type>Connection_Status_Reason</tp:type> enum.
      </tp:rationale>
    </tp:docstring>
  </tp:error>

  <tp:error name="Encryption Not Available">
    <tp:docstring>
      Raised if a user request insisted that encryption should be used,
      but encryption was not actually available.

      <tp:rationale>
        This corresponds to part of Encryption_Error in the
        <tp:type>Connection_Status_Reason</tp:type> enum. It's been separated
        into a distinct error here because the two concepts that were part
        of EncryptionError seem to be things that could reasonably appear
        differently in the UI.
      </tp:rationale>
    </tp:docstring>
  </tp:error>

  <tp:error name="Encryption Error">
    <tp:docstring>
      Raised if encryption appears to be available, but could not actually be
      used (for instance if SSL/TLS negotiation fails).
      <tp:rationale>
        This corresponds to part of Encryption_Error in the
        <tp:type>Connection_Status_Reason</tp:type> enum.
      </tp:rationale>
    </tp:docstring>
  </tp:error>

  <tp:error name="Cert.Not Provided">
    <tp:docstring>
      Raised if the server did not provide a SSL/TLS certificate. This error
      MUST NOT be used to represent the absence of a client certificate
      provided by the Telepathy connection manager.
      <tp:rationale>
        This corresponds to Cert_Not_Provided in the
        <tp:type>Connection_Status_Reason</tp:type> enum. That error
        explicitly applied only to server SSL certificates, so this one
        is similarly limited; having the CM present a client certificate
        is a possible future feature, but it should have its own error
        handling.
      </tp:rationale>
    </tp:docstring>
  </tp:error>

  <tp:error name="Cert.Untrusted">
    <tp:docstring>
      Raised if the server provided a SSL/TLS certificate signed by an
      untrusted certifying authority. This error SHOULD NOT be used to
      represent a self-signed certificate: see the Self Signed error for that.
      <tp:rationale>
        This corresponds to Cert_Untrusted in the
        <tp:type>Connection_Status_Reason</tp:type> enum and to Untrusted in the
        <tp:type>TLS_Certificate_Reject_Reason</tp:type> enum, with a clarification
        to avoid ambiguity.
      </tp:rationale>
    </tp:docstring>
  </tp:error>

  <tp:error name="Cert.Expired">
    <tp:docstring>
      Raised if the server provided an expired SSL/TLS certificate.
      <tp:rationale>
        This corresponds to Cert_Expired in the
        <tp:type>Connection_Status_Reason</tp:type> enum and to Expired in
        the <tp:type>TLS_Certificate_Reject_Reason</tp:type> enum.
      </tp:rationale>
    </tp:docstring>
  </tp:error>

  <tp:error name="Cert.Not Activated">
    <tp:docstring>
      Raised if the server provided an SSL/TLS certificate that will become
      valid at some point in the future.
      <tp:rationale>
        This corresponds to Cert_Not_Activated in the
        <tp:type>Connection_Status_Reason</tp:type> enum and to
        Not_Activated in the <tp:type>TLS_Certificate_Reject_Reason</tp:type> enum.
      </tp:rationale>
    </tp:docstring>
  </tp:error>

  <tp:error name="Cert.Fingerprint Mismatch">
    <tp:docstring>
      Raised if the server provided an SSL/TLS certificate that did not have
      the expected fingerprint.
      <tp:rationale>
        This corresponds to Cert_Fingerprint_Mismatch in the
        <tp:type>Connection_Status_Reason</tp:type> enum and to
        Fingerprint_Mismatch in the <tp:type>TLS_Certificate_Reject_Reason</tp:type> enum.
      </tp:rationale>
    </tp:docstring>
  </tp:error>

  <tp:error name="Cert.Hostname Mismatch">
    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
      <p>Raised if the server provided an SSL/TLS certificate that did not match
      its hostname.</p>
      <p>You MAY be able to get more details about the expected and certified
      hostnames by looking up the 'expected-hostname' and 'certificate-hostname'
      keys in the details map that came together with this error.</p>
      <tp:rationale>
        This corresponds to Cert_Hostname_Mismatch in the
        <tp:type>Connection_Status_Reason</tp:type> enum and to Hostname_Mismatch
        in the <tp:type>TLS_Certificate_Reject_Reason</tp:type> enum.
      </tp:rationale>
    </tp:docstring>
  </tp:error>

  <tp:error name="Cert.Self Signed">
    <tp:docstring>
      Raised if the server provided an SSL/TLS certificate that is self-signed
      and untrusted.
      <tp:rationale>
        This corresponds to Cert_Self_Signed in the
        <tp:type>Connection_Status_Reason</tp:type> enum and to Self_Signed
        in the <tp:type>TLS_Certificate_Reject_Reason</tp:type> enum.
      </tp:rationale>
    </tp:docstring>
  </tp:error>

  <tp:error name="Cert.Revoked">
    <tp:docstring>
      Raised if the server provided an SSL/TLS certificate that has been
      revoked.
      <tp:rationale>
        This corresponds to Cert_Revoked in the
        <tp:type>Connection_Status_Reason</tp:type> enum and to Revoked
        in the <tp:type>TLS_Certificate_Reject_Reason</tp:type> enum.
      </tp:rationale>
    </tp:docstring>
  </tp:error>

  <tp:error name="Cert.Insecure">
    <tp:added version="0.19.11"/>
    <tp:docstring>
      Raised if the server provided an SSL/TLS certificate that uses an
      insecure cipher algorithm or is cryptographically weak.
      <tp:rationale>
        This corresponds to Cert_Insecure in the
        <tp:type>Connection_Status_Reason</tp:type> enum and to Insecure
        in the <tp:type>TLS_Certificate_Reject_Reason</tp:type> enum.
      </tp:rationale>
    </tp:docstring>
  </tp:error>

  <tp:error name="Cert.Invalid">
    <tp:added version="0.19.11"/>
    <tp:docstring>
      Raised if the server provided an SSL/TLS certificate that is
      unacceptable in some way that does not have a more specific error.
      <tp:rationale>
        This corresponds to Cert_Other_Error in the
        <tp:type>Connection_Status_Reason</tp:type> enum and to Unknown
        in the <tp:type>TLS_Certificate_Reject_Reason</tp:type> enum.
      </tp:rationale>
    </tp:docstring>
  </tp:error>

  <tp:error name="Cert.Limit Exceeded">
    <tp:added version="0.19.11"/>
    <tp:docstring>
      Raised if the length in bytes of the server certificate, or the depth of the
      server certificate chain exceeds the limits imposed by the crypto
      library.
      <tp:rationale>
        This corresponds to Cert_Limit_Exceeded in the
        <tp:type>Connection_Status_Reason</tp:type> enum and to Limit_Exceeded
        in the <tp:type>TLS_Certificate_Reject_Reason</tp:type> enum.
      </tp:rationale>
    </tp:docstring>
  </tp:error>

  <tp:error name="Not Capable">
    <tp:docstring>
    Raised when requested functionality is unavailable due to contact
    not having required capabilities.
    </tp:docstring>
  </tp:error>

  <tp:error name="Offline">
    <tp:docstring>
      Raised when requested functionality is unavailable because a contact is
      offline.

      <tp:rationale>
        This corresponds to Offline in the
        <tp:type>Channel_Group_Change_Reason</tp:type> enum.
      </tp:rationale>
    </tp:docstring>
  </tp:error>

  <tp:error name="Channel.Kicked">
    <tp:docstring>
      Used to represent a user being ejected from a channel by another user,
      for instance being kicked from a chatroom.

      <tp:rationale>
        This corresponds to Kicked in the
        <tp:type>Channel_Group_Change_Reason</tp:type> enum.
      </tp:rationale>
    </tp:docstring>
  </tp:error>

  <tp:error name="Busy">
    <tp:docstring>
      Used to represent a user being removed from a channel because of a
      "busy" indication. This error SHOULD NOT be used to represent a server
      or other infrastructure being too busy to process a request - for that,
      see ServerBusy.

      <tp:rationale>
        This corresponds to Busy in the
        <tp:type>Channel_Group_Change_Reason</tp:type> enum.
      </tp:rationale>
    </tp:docstring>
  </tp:error>

  <tp:error name="No Answer">
    <tp:docstring>
      Used to represent a user being removed from a channel because they did
      not respond, e.g. to a StreamedMedia call.

      <tp:rationale>
        This corresponds to No_Answer in the
        <tp:type>Channel_Group_Change_Reason</tp:type> enum.
      </tp:rationale>
    </tp:docstring>
  </tp:error>

  <tp:error name="Does Not Exist">
    <tp:docstring>
      Raised when the requested user does not, in fact, exist.

      <tp:rationale>
        This corresponds to Invalid_Contact in the
        <tp:type>Channel_Group_Change_Reason</tp:type> enum, but can also be
        used to represent other things not existing (like chatrooms, perhaps).
      </tp:rationale>
    </tp:docstring>
  </tp:error>

  <tp:error name="Terminated">
    <tp:docstring>
      Raised when a channel is terminated for an unspecified reason. In
      particular, this error SHOULD be used whenever normal termination of
      a 1-1 StreamedMedia call by the remote user is represented as a D-Bus
      error name.

      <tp:rationale>
        This corresponds to None in the
        <tp:type>Channel_Group_Change_Reason</tp:type> enum.
      </tp:rationale>
    </tp:docstring>
  </tp:error>

  <tp:error name="Media.Codecs Incompatible">
    <tp:added version="0.23.4"/>
    <tp:docstring>
      Raised when the local streaming implementation has no codecs in common
      with the remote side.

      <tp:rationale>
        This corresponds to
        <tp:value-ref type="Call_State_Change_Reason">Media_Error</tp:value-ref>.
      </tp:rationale>
    </tp:docstring>
  </tp:error>

  <tp:error name="Media.Unsupported Type">
    <tp:added version="0.23.4"/>
    <tp:docstring>
      The media stream type requested is not supported by either the
      local or remote side.

      <tp:rationale>
        This corresponds to
        <tp:value-ref type="Call_State_Change_Reason">Media_Error</tp:value-ref>.
      </tp:rationale>
    </tp:docstring>
  </tp:error>

  <tp:error name="Media.Streaming Error">
    <tp:added version="0.23.4"/>
    <tp:docstring>
      Raised when the call's streaming implementation has some kind of internal
      error.

      <tp:rationale>
        This corresponds to
        <tp:value-ref type="Call_State_Change_Reason">Internal_Error</tp:value-ref>.
      </tp:rationale>
    </tp:docstring>
  </tp:error>

  <tp:error name="Connection Refused">
    <tp:docstring>
      Raised when a connection is refused.
    </tp:docstring>
  </tp:error>

  <tp:error name="Connection Failed">
    <tp:docstring>
      Raised when a connection can't be established.
    </tp:docstring>
  </tp:error>

  <tp:error name="Connection Lost">
    <tp:docstring>
      Raised when a connection is broken.
    </tp:docstring>
  </tp:error>

  <tp:error name="Already Connected">
    <tp:docstring>
      Raised when the user attempts to connect to an account but they are
      already connected (perhaps from another client or computer), and the
      protocol or account settings do not allow this.

      <tp:rationale>
        XMPP can have this behaviour if the user chooses the same resource
        in both clients (it is server-dependent whether the result is
        AlreadyConnected on the new connection, ConnectionReplaced on the
        old connection, or two successful connections).
      </tp:rationale>
    </tp:docstring>
  </tp:error>

  <tp:error name="Connection Replaced">
    <tp:docstring>
      Raised by an existing connection to an account if it is replaced by
      a new connection (perhaps from another client or computer).

      <tp:rationale>
        In MSNP, when connecting twice with the same Passport, the new
        connection "wins" and the old one is automatically disconnected.
        XMPP can also have this behaviour if the user chooses the same
        resource in two clients (it is server-dependent whether the result is
        AlreadyConnected on the new connection, ConnectionReplaced on the
        old connection, or two successful connections).
      </tp:rationale>
    </tp:docstring>
  </tp:error>

  <tp:error name="Registration Exists">
    <tp:docstring>
      Raised during in-band registration if the server indicates that the
      requested account already exists.
    </tp:docstring>
  </tp:error>

  <tp:error name="Service Busy">
    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
      Raised if a server or some other piece of infrastructure cannot process
      the request, e.g. due to resource limitations. Clients MAY try again
      later.

      <tp:rationale>
        This is not the same error as Busy, which indicates that a
        <em>user</em> is busy.
      </tp:rationale>
    </tp:docstring>
  </tp:error>

  <tp:error name="Resource Unavailable">
    <tp:docstring>
      Raised if a request cannot be satisfied because a process local to the
      user has insufficient resources. Clients MAY try again
      later.

      <tp:rationale>
        For instance, the <tp:dbus-ref
          namespace="org.freedesktop.Telepathy">ChannelDispatcher</tp:dbus-ref>
        might raise this error for some or all channel requests if it has
        detected that there is not enough free memory.
      </tp:rationale>
    </tp:docstring>
  </tp:error>

  <tp:error name="Would Break Anonymity">
    <tp:added version="0.19.7"/>
    <tp:docstring>
      Raised if a request cannot be satisfied without violating an earlier
      request for anonymity, and the earlier request specified that raising
      an error is preferable to disclosing the user's identity (for instance
      via <tp:dbus-ref namespace="org.freedesktop.Telepathy"
        >Connection.Interface.Anonymity.AnonymityMandatory</tp:dbus-ref> or
      <tp:dbus-ref namespace="org.freedesktop.Telepathy"
        >Channel.Interface.Anonymity.AnonymityMandatory</tp:dbus-ref>).
    </tp:docstring>
  </tp:error>

  <tp:error name="Not Yet">
    <tp:added version="0.19.12"/>
    <tp:docstring>
      Raised when the requested functionality is not yet available, but is
      likely to become available after some time has passed.
    </tp:docstring>
  </tp:error>

  <tp:error name="Rejected">
    <tp:added version="0.21.2"/>
    <tp:docstring>
      Raised when an incoming or outgoing <tp:dbus-ref
      namespace="ofdT.Channel.Type">Call1</tp:dbus-ref> is
      rejected by the the receiver.
    </tp:docstring>
  </tp:error>

  <tp:error name="Picked Up Elsewhere">
    <tp:added version="0.21.3"/>
    <tp:docstring>
      Raised when a call was terminated as a result of the local user
      picking up the call on a different resource.
    </tp:docstring>
  </tp:error>

  <tp:error name="Service Confused">
    <tp:added version="0.21.5"/>
    <tp:docstring>
      Raised when a server or other piece of infrastructure indicates an
      internal error, or when a message that makes no sense is received from
      a server or other piece of infrastructure.

      <tp:rationale>
        For instance, this is appropriate for XMPP's
        <code>internal-server-error</code>, and is also appropriate if
        you receive sufficiently inconsistent information from a server that
        you cannot continue.
      </tp:rationale>
    </tp:docstring>
  </tp:error>

  <tp:error name="Confused">
    <tp:added version="0.21.5"/>
    <tp:docstring>
      Raised if a server rejects protocol messages from a connection manager
      claiming that they do not make sense, two local processes fail to
      understand each other, or an apparently impossible situation is
      reached.

      <tp:rationale>
        For instance, this would be an appropriate mapping for XMPP's
        errors bad-format, invalid-xml, etc., which can't happen unless
        the local (or remote) XMPP implementation is faulty. This is
        also analogous to
        <tp:value-ref type="Media_Stream_Error">Invalid_CM_Behavior</tp:value-ref>,
        <code>TP_DBUS_ERROR_INCONSISTENT</code> in telepathy-glib, and
        <code>TELEPATHY_QT4_ERROR_INCONSISTENT</code> in telepathy-qt4.
      </tp:rationale>
    </tp:docstring>
  </tp:error>

  <tp:error name="Software Upgrade Required">
    <tp:added version="0.21.12"/>
    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
      <p>Raised as a
        <tp:dbus-ref namespace="ofdT.Connection">ConnectionError</tp:dbus-ref>
        when a Connection cannot be established because either the Connection
        Manager or its support library (e.g. wocky, papyon, sofiasip) requires
        upgrading to support a newer protocol version.</p>

      <p>This error corresponds to the
        <tp:type>Connection_Status_Reason</tp:type> of Network_Error.</p>

      <tp:rationale>
        Some protocols transmit a protocol or library version number to the
        server, which will disconnect them if the version isn't appropriate.
        This way we can report the error to the user, and if appropriate, the
        user's client can check for updates.
      </tp:rationale>
    </tp:docstring>
  </tp:error>

  <tp:error name="Emergency Calls Not Supported">
    <tp:added version="0.21.12"/>
    <tp:docstring>
      Raised if a client attempts to dial a number that is recognized as an
      emergency number (e.g. '911' in the USA), but the Connection Manager or
      provider does not support dialling emergency numbers.

      <tp:rationale>
        Many VOIP providers have the ability to dial traditional (PSTN)
        telephone numbers, but do not provide the ability to dial emergency
        numbers (for instance, Google Voice).  This error provides additional
        information about why such a call was unsuccessful.
      </tp:rationale>
    </tp:docstring>
  </tp:error>

  <tp:error name="Insufficient Balance">
    <tp:added version="0.22.1"/>
    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
      <p>Raised if the user has insufficient
        <tp:dbus-ref namespace="ofdT.Connection.Interface">Balance</tp:dbus-ref>
        to place a call or send a message.</p>

      <p>The key 'balance-required' MAY be included in
        <tp:dbus-ref namespace="ofdT.Channel.Type.Call1">CallStateDetails</tp:dbus-ref>
        or a delivery report's <tp:type>Message_Part</tp:type>
        (with the same units and scale as
        <tp:dbus-ref namespace="ofdT.Connection.Interface.Balance">AccountBalance</tp:dbus-ref>)
        to indicate how much credit is required to make this call or send
        this message.</p>
    </tp:docstring>
  </tp:error>

  <tp:copyright>Copyright © 2005-2010 Collabora Limited</tp:copyright>
  <tp:copyright>Copyright © 2005-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>
</tp:errors>