Telepathy protocol errors

## 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,
    } 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.
`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_g_set_error_invalid_handle_type ()

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

Set the error InvalidArgument corresponding to an invalid handle type, with an appropriate message.

`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 InvalidArgument for a handle type which is valid but is not supported by this connection manager, with an appropriate message.

FIXME: Shouldn't the error be NotImplemented? The spec doesn't always allow us to return that, though.

`type` : | An unsupported handle type
`error` : | Either `NULL`, or used to return an error (as for g_set_error)