Telepathy protocol errors

Telepathy protocol errors — The errors from the Telepathy D-Bus spec, as a GLib error domain

Synopsis


#include <telepathy-glib/errors.h>

#define             TP_ERROR_PREFIX
#define             TP_ERRORS
#define             TP_TYPE_ERROR
enum                TpError;
void                tp_g_set_error_invalid_handle_type  (guint type,
                                                         GError **error);
void                tp_g_set_error_unsupported_handle_type
                                                        (guint type,
                                                         GError **error);

Description

This header provides the Telepathy D-Bus errors, in the form of a GLib error domain. For D-Bus methods which fail with one of these errors, dbus-glib will generate a reply message with the appropriate error.

It also provides utility functions used by functions which return an error.

Details

TP_ERROR_PREFIX

#define TP_ERROR_PREFIX "org.freedesktop.Telepathy.Errors"

The common prefix of Telepathy errors, as a string constant, without the trailing '.' character.

Since 0.7.1


TP_ERRORS

#define TP_ERRORS tp_errors_quark ()

The error domain for the D-Bus errors described in the Telepathy specification.


TP_TYPE_ERROR

#define             TP_TYPE_ERROR

The GType of the Telepathy error enumeration.


enum TpError

typedef enum {
    TP_ERROR_NETWORK_ERROR,
    TP_ERROR_NOT_IMPLEMENTED,
    TP_ERROR_INVALID_ARGUMENT,
    TP_ERROR_NOT_AVAILABLE,
    TP_ERROR_PERMISSION_DENIED,
    TP_ERROR_DISCONNECTED,
    TP_ERROR_INVALID_HANDLE,
    TP_ERROR_CHANNEL_BANNED,
    TP_ERROR_CHANNEL_FULL,
    TP_ERROR_CHANNEL_INVITE_ONLY,
    TP_ERROR_NOT_YOURS,
    TP_ERROR_CANCELLED,
    TP_ERROR_AUTHENTICATION_FAILED,
    TP_ERROR_ENCRYPTION_NOT_AVAILABLE,
    TP_ERROR_ENCRYPTION_ERROR,
    TP_ERROR_CERT_NOT_PROVIDED,
    TP_ERROR_CERT_UNTRUSTED,
    TP_ERROR_CERT_EXPIRED,
    TP_ERROR_CERT_NOT_ACTIVATED,
    TP_ERROR_CERT_FINGERPRINT_MISMATCH,
    TP_ERROR_CERT_HOSTNAME_MISMATCH,
    TP_ERROR_CERT_SELF_SIGNED,
    TP_ERROR_CERT_INVALID,
    TP_ERROR_NOT_CAPABLE,
    TP_ERROR_OFFLINE,
    TP_ERROR_CHANNEL_KICKED,
    TP_ERROR_BUSY,
    TP_ERROR_NO_ANSWER,
    TP_ERROR_DOES_NOT_EXIST,
} TpError;

Enumerated type representing the Telepathy D-Bus errors.

TP_ERROR_NETWORK_ERROR

org.freedesktop.Telepathy.Error.NetworkError: Raised when there is an error reading from or writing to the network.

TP_ERROR_NOT_IMPLEMENTED

org.freedesktop.Telepathy.Error.NotImplemented: Raised when the requested method, channel, etc is not available on this connection.

TP_ERROR_INVALID_ARGUMENT

org.freedesktop.Telepathy.Error.InvalidArgument: Raised when one of the provided arguments is invalid.

TP_ERROR_NOT_AVAILABLE

org.freedesktop.Telepathy.Error.NotAvailable: Raised when the requested functionality is temporarily unavailable.

TP_ERROR_PERMISSION_DENIED

org.freedesktop.Telepathy.Error.PermissionDenied: The user is not permitted to perform the requested operation.

TP_ERROR_DISCONNECTED

org.freedesktop.Telepathy.Error.Disconnected: 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 <dbus-ref>StatusChanged</dbus-ref> has signalled status Disconnected for reason None. <rationale> The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead. </rationale>

TP_ERROR_INVALID_HANDLE

org.freedesktop.Telepathy.Error.InvalidHandle: The contact name specified is unknown on this channel or connection.

TP_ERROR_CHANNEL_BANNED

org.freedesktop.Telepathy.Error.Channel.Banned: You are banned from the channel.

TP_ERROR_CHANNEL_FULL

org.freedesktop.Telepathy.Error.Channel.Full: The channel is full.

TP_ERROR_CHANNEL_INVITE_ONLY

org.freedesktop.Telepathy.Error.Channel.InviteOnly: The requested channel is invite-only.

TP_ERROR_NOT_YOURS

org.freedesktop.Telepathy.Error.NotYours: The requested channel or other resource already exists, and another client is responsible for it

TP_ERROR_CANCELLED

org.freedesktop.Telepathy.Error.Cancelled: 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). <rationale> The second form can be used to correspond to the Requested member in the Connection_Status_Reason 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. </rationale>

TP_ERROR_AUTHENTICATION_FAILED

org.freedesktop.Telepathy.Error.AuthenticationFailed: Raised when authentication with a service was unsuccessful. <rationale> This corresponds to Authentication_Failed in the Connection_Status_Reason enum. </rationale>

TP_ERROR_ENCRYPTION_NOT_AVAILABLE

org.freedesktop.Telepathy.Error.EncryptionNotAvailable: Raised if a user request insisted that encryption should be used, but encryption was not actually available. <rationale> This corresponds to part of Encryption_Error in the Connection_Status_Reason 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. </rationale>

TP_ERROR_ENCRYPTION_ERROR

org.freedesktop.Telepathy.Error.EncryptionError: Raised if encryption appears to be available, but could not actually be used (for instance if SSL/TLS negotiation fails). <rationale> This corresponds to part of Encryption_Error in the Connection_Status_Reason enum. </rationale>

TP_ERROR_CERT_NOT_PROVIDED

org.freedesktop.Telepathy.Error.Cert.NotProvided: 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. <rationale> This corresponds to Cert_Not_Provided in the Connection_Status_Reason 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. </rationale>

TP_ERROR_CERT_UNTRUSTED

org.freedesktop.Telepathy.Error.Cert.Untrusted: 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. <rationale> This corresponds to Cert_Untrusted in the Connection_Status_Reason enum, with a clarification to avoid ambiguity. </rationale>

TP_ERROR_CERT_EXPIRED

org.freedesktop.Telepathy.Error.Cert.Expired: Raised if the server provided an expired SSL/TLS certificate. <rationale> This corresponds to Cert_Expired in the Connection_Status_Reason enum. </rationale>

TP_ERROR_CERT_NOT_ACTIVATED

org.freedesktop.Telepathy.Error.Cert.NotActivated: Raised if the server provided an SSL/TLS certificate that will become valid at some point in the future. <rationale> This corresponds to Cert_Not_Activated in the Connection_Status_Reason enum. </rationale>

TP_ERROR_CERT_FINGERPRINT_MISMATCH

org.freedesktop.Telepathy.Error.Cert.FingerprintMismatch: Raised if the server provided an SSL/TLS certificate that did not have the expected fingerprint. <rationale> This corresponds to Cert_Fingerprint_Mismatch in the Connection_Status_Reason enum. </rationale>

TP_ERROR_CERT_HOSTNAME_MISMATCH

org.freedesktop.Telepathy.Error.Cert.HostnameMismatch: Raised if the server provided an SSL/TLS certificate that did not match its hostname. <rationale> This corresponds to Cert_Hostname_Mismatch in the Connection_Status_Reason enum. </rationale>

TP_ERROR_CERT_SELF_SIGNED

org.freedesktop.Telepathy.Error.Cert.SelfSigned: Raised if the server provided an SSL/TLS certificate that is self-signed and untrusted. <rationale> This corresponds to Cert_Hostname_Mismatch in the Connection_Status_Reason enum. </rationale>

TP_ERROR_CERT_INVALID

org.freedesktop.Telepathy.Error.Cert.Invalid: Raised if the server provided an SSL/TLS certificate that is unacceptable in some way that does not have a more specific error. <rationale> This corresponds to Cert_Other_Error in the Connection_Status_Reason enum. </rationale>

TP_ERROR_NOT_CAPABLE

org.freedesktop.Telepathy.Error.NotCapable: Raised when requested functionality is unavailable due to contact not having required capabilities.

TP_ERROR_OFFLINE

org.freedesktop.Telepathy.Error.Offline: Raised when requested functionality is unavailable because a contact is offline. <rationale> This corresponds to Offline in the Channel_Group_Change_Reason enum. </rationale>

TP_ERROR_CHANNEL_KICKED

org.freedesktop.Telepathy.Error.Channel.Kicked: Used to represent a user being ejected from a channel by another user, for instance being kicked from a chatroom. <rationale> This corresponds to Kicked in the Channel_Group_Change_Reason enum. </rationale>

TP_ERROR_BUSY

org.freedesktop.Telepathy.Error.Busy: Used to represent a user being removed from a channel because of a "busy" indication. <rationale> This corresponds to Busy in the Channel_Group_Change_Reason enum. </rationale>

TP_ERROR_NO_ANSWER

org.freedesktop.Telepathy.Error.NoAnswer: Used to represent a user being removed from a channel because they did not respond, e.g. to a StreamedMedia call. <rationale> This corresponds to No_Answer in the Channel_Group_Change_Reason enum. </rationale>

TP_ERROR_DOES_NOT_EXIST

org.freedesktop.Telepathy.Error.DoesNotExist: Raised when the requested user does not, in fact, exist. <rationale> This corresponds to Invalid_Contact in the Channel_Group_Change_Reason enum, but can also be used to represent other things not existing (like chatrooms, perhaps). </rationale>

tp_g_set_error_invalid_handle_type ()

void                tp_g_set_error_invalid_handle_type  (guint type,
                                                         GError **error);

Set the error NotImplemented for an invalid handle type, with an appropriate message.

Changed in version 0.7.23: previously, the error was InvalidArgument.

type :

An invalid handle type

error :

Either NULL, or used to return an error (as for g_set_error)

tp_g_set_error_unsupported_handle_type ()

void                tp_g_set_error_unsupported_handle_type
                                                        (guint type,
                                                         GError **error);

Set the error NotImplemented for a handle type which is valid but is not supported by this connection manager, with an appropriate message.

Changed in version 0.7.23: previously, the error was InvalidArgument.

type :

An unsupported handle type

error :

Either NULL, or used to return an error (as for g_set_error)