## InfError InfError — Common error codes |

## Stability Level

Unstable, unless otherwise indicated

## Synopsis

    #include <libinfinity/common/inf-error.h>

    enum                InfRequestError;
    enum                InfUserError;
    enum                InfDirectoryError;
    enum                InfAuthenticationDetailError;
    GQuark              inf_request_error_quark             (void);
    const gchar *       inf_request_strerror                (InfRequestError code);
    GQuark              inf_user_error_quark                (void);
    const gchar *       inf_user_strerror                   (InfUserError code);
    GQuark              inf_directory_error_quark           (void);
    const gchar *       inf_directory_strerror              (InfDirectoryError code);
    GQuark              inf_authentication_detail_error_quark
                                                            (void);
    const gchar *       inf_authentication_detail_strerror  (InfAuthenticationDetailError code);
    GQuark              inf_gnutls_error_quark              (void);
    void                inf_gnutls_set_error                (GError **error,
                                                             int error_code);
    GQuark              inf_gsasl_error_quark               (void);
    void                inf_gsasl_set_error                 (GError **error,
                                                             int error_code);

## Description

This section defines some common error codes that are used on both client and server side in infinote, and maps these to GErrors.

## Details

### enum InfRequestError

    typedef enum {
      INF_REQUEST_ERROR_UNKNOWN_DOMAIN,
      INF_REQUEST_ERROR_REPLY_UNPROCESSED,
      INF_REQUEST_ERROR_INVALID_SEQ,
      INF_REQUEST_ERROR_NO_SUCH_ATTRIBUTE,
      INF_REQUEST_ERROR_INVALID_NUMBER,

      INF_REQUEST_ERROR_FAILED
    } InfRequestError;

These are general request errors that all InfcRequests can fail with. Specific requests may also fail with more errors, such as InfDirectoryError.

`INF_REQUEST_ERROR_UNKNOWN_DOMAIN` | The server sent <request-failed/> with an unknown error domain.
`INF_REQUEST_ERROR_REPLY_UNPROCESSED` | An error occured while processing the server reply for a request.
`INF_REQUEST_ERROR_INVALID_SEQ` | The server sent an invalid sequence number in a reply to a request.
`INF_REQUEST_ERROR_NO_SUCH_ATTRIBUTE` | A request did not contain a XML attribute that is required to complete the request.
`INF_REQUEST_ERROR_INVALID_NUMBER` | A number in a request was invalid. Either it was not numerical, or it produced an underflow or an overflow.
`INF_REQUEST_ERROR_FAILED` | Generic error code when no further reason of failure is known.

### enum InfUserError

    typedef enum {
      INF_USER_ERROR_NAME_IN_USE,
      INF_USER_ERROR_ID_PROVIDED,
      INF_USER_ERROR_NO_SUCH_USER,
      INF_USER_ERROR_STATUS_UNAVAILABLE,
      INF_USER_ERROR_NOT_JOINED,
      INF_USER_ERROR_INVALID_STATUS,

      INF_USER_ERROR_FAILED
    } InfUserError;

These are errors related to users. They may occur during user join or during processing a user-related message, such as a user status change message in an InfSession.

`INF_USER_ERROR_NAME_IN_USE` | The requested name is already in use by another user.
`INF_USER_ERROR_ID_PROVIDED` | The client provided a user ID field in a user join request, but it's the server's job to find an ID.
`INF_USER_ERROR_NO_SUCH_USER` | A request referred to a user ID that no user is associated with.
`INF_USER_ERROR_STATUS_UNAVAILABLE` | The initial user status was given as unavailable during user join or rejoin.
`INF_USER_ERROR_NOT_JOINED` | The user did not join from the connection the request comes from. For example, a user status change can only be requested from the same connection that joined the user.
`INF_USER_ERROR_INVALID_STATUS` | An invalid status was used in a XML request. Allowed status values are "unavailable", "inactive" or "active".
`INF_USER_ERROR_FAILED` | Generic error code when no further reason of failure is known.

### enum InfDirectoryError

    typedef enum {
      INF_DIRECTORY_ERROR_NO_WELCOME_MESSAGE,
      INF_DIRECTORY_ERROR_VERSION_MISMATCH,
      INF_DIRECTORY_ERROR_NODE_EXISTS,
      INF_DIRECTORY_ERROR_INVALID_NAME,
      INF_DIRECTORY_ERROR_NO_SUCH_NODE,
      INF_DIRECTORY_ERROR_NO_SUCH_SUBSCRIPTION_REQUEST,
      INF_DIRECTORY_ERROR_CHAT_DISABLED,
      INF_DIRECTORY_ERROR_NOT_A_SUBDIRECTORY,
      INF_DIRECTORY_ERROR_NOT_A_NOTE,
      INF_DIRECTORY_ERROR_ROOT_NODE_REMOVE_ATTEMPT,
      INF_DIRECTORY_ERROR_ALREADY_EXPLORED,
      INF_DIRECTORY_ERROR_TOO_MUCH_CHILDREN,
      INF_DIRECTORY_ERROR_TOO_FEW_CHILDREN,
      INF_DIRECTORY_ERROR_TYPE_UNKNOWN,
      INF_DIRECTORY_ERROR_ALREADY_SUBSCRIBED,
      INF_DIRECTORY_ERROR_UNSUBSCRIBED,
      INF_DIRECTORY_ERROR_NETWORK_UNSUPPORTED,
      INF_DIRECTORY_ERROR_METHOD_UNSUPPORTED,
      INF_DIRECTORY_ERROR_UNEXPECTED_SYNC_IN,
      INF_DIRECTORY_ERROR_UNEXPECTED_MESSAGE,
      INF_DIRECTORY_ERROR_NO_STORAGE,

      INF_DIRECTORY_ERROR_FAILED
    } InfDirectoryError;

These are errors related to the directory of documents. These errors can be reason why requests created by InfcBrowser fail.

`INF_DIRECTORY_ERROR_NO_WELCOME_MESSAGE` | A client did not receive the directory's initial welcome message.
`INF_DIRECTORY_ERROR_VERSION_MISMATCH` | The server and client use different versions of the protocol.
`INF_DIRECTORY_ERROR_NODE_EXISTS` | A node with the given name exists already in that subdirectory (in response to node creation requests).
`INF_DIRECTORY_ERROR_INVALID_NAME` | A node with an invalid name was attempted to be created.
`INF_DIRECTORY_ERROR_NO_SUCH_NODE` | The node refered to in a request does not exist in the directory (anymore).
`INF_DIRECTORY_ERROR_NO_SUCH_SUBSCRIPTION_REQUEST` | A <subscribe-ack> or <subscribe-nack> has been received without a previous request.
`INF_DIRECTORY_ERROR_CHAT_DISABLED` | A client attempted to subscribe to a server's chat, but the chat is disabled on the server side.
`INF_DIRECTORY_ERROR_NOT_A_SUBDIRECTORY` | The node refered to in a request is not a subdirectory node, but the requested operation requires one.
`INF_DIRECTORY_ERROR_NOT_A_NOTE` | The node refered to in a request is not a note (non-subdirectory) node, but the requested operations requires one.
`INF_DIRECTORY_ERROR_ROOT_NODE_REMOVE_ATTEMPT` | A <remove-node> request attempted to remove a directory's root node, which is not allowed.
`INF_DIRECTORY_ERROR_ALREADY_EXPLORED` | The node given in an exploration request has already been explored earlier.
`INF_DIRECTORY_ERROR_TOO_MUCH_CHILDREN` | Exploration yields more children than announced at the beginning of the exploration.
`INF_DIRECTORY_ERROR_TOO_FEW_CHILDREN` | Exploration yields less children than announced at the beginning of the exploration.
`INF_DIRECTORY_ERROR_TYPE_UNKNOWN` | The type of a note is not known.
`INF_DIRECTORY_ERROR_ALREADY_SUBSCRIBED` | The connection already subscribed to the node refered to, but the requested operation requires it to be unsubscribed.
`INF_DIRECTORY_ERROR_UNSUBSCRIBED` | The connection is not subscribed to the node refered to, but the requested operation requires it to be subscribed.
`INF_DIRECTORY_ERROR_NETWORK_UNSUPPORTED` | The server does not support the network of the incoming connection for the requested operation. For example, subscribing to a session might require a network that has a peer-to-peer communication method, but there is no implementation of that method for the connection's network.
`INF_DIRECTORY_ERROR_METHOD_UNSUPPORTED` | The server requested a communaction method for subscription or synchronization that is not supported by the client.
`INF_DIRECTORY_ERROR_UNEXPECTED_SYNC_IN` | A client received a <sync-in/> without having requested one. The client has no data to sync to the server.
`INF_DIRECTORY_ERROR_UNEXPECTED_MESSAGE` | A message that is not understood was received.
`INF_DIRECTORY_ERROR_NO_STORAGE` | A node cannot be stored permanently on the server since it has no storage backend attached.
`INF_DIRECTORY_ERROR_FAILED` | Generic error code when no further reason of failure is known.

### enum InfAuthenticationDetailError

    typedef enum {
      INF_AUTHENTICATION_DETAIL_ERROR_AUTHENTICATION_FAILED,
      INF_AUTHENTICATION_DETAIL_ERROR_USER_NOT_AUTHORIZED,
      INF_AUTHENTICATION_DETAIL_ERROR_TRY_AGAIN,
      INF_AUTHENTICATION_DETAIL_ERROR_SERVER_ERROR
    } InfAuthenticationDetailError;

`INF_AUTHENTICATION_DETAIL_ERROR_AUTHENTICATION_FAILED` | User did not provide valid credentials.
`INF_AUTHENTICATION_DETAIL_ERROR_USER_NOT_AUTHORIZED` | User is not permitted to connect to this server.
`INF_AUTHENTICATION_DETAIL_ERROR_TRY_AGAIN` | Authentication was temporarily interrupted on the server side.
`INF_AUTHENTICATION_DETAIL_ERROR_SERVER_ERROR` | An error occured while checking user permissions.

### inf_request_error_quark ()

    GQuark              inf_request_error_quark             (void);

Error domain for request errors. Errors in this domain will be from the InfRequestError enumeration. See GError for information on error domains.

Returns : | A GQuark.

### inf_request_strerror ()

    const gchar *       inf_request_strerror                (InfRequestError code);

Returns a human-readable string for the given error code.

`code` : | An error code from the InfRequestError enumeration.
Returns : | A static string that must not be freed.

### inf_user_error_quark ()

    GQuark              inf_user_error_quark                (void);

Error domain for user-related errors. Errors in this domain will be from the InfUserError enumeration. See GError for information on error domains.

Returns : | A GQuark.

### inf_user_strerror ()

    const gchar *       inf_user_strerror                   (InfUserError code);

Returns a human-readable string for the given error code.

`code` : | An error code from the InfUserError enumeration.
Returns : | A static string that must not be freed.

### inf_directory_error_quark ()

    GQuark              inf_directory_error_quark           (void);

Error domain for directory errors. Errors in this domain will be from the InfDirectoryError enumeration. See GError for information on error domains.

Returns : | A GQuark.

### inf_directory_strerror ()

    const gchar *       inf_directory_strerror              (InfDirectoryError code);

Returns a human-readable string for the given error code.

`code` : | An error code from the InfDirectoryError enumeration.
Returns : | A static string that must not be freed.

### inf_authentication_detail_error_quark ()

    GQuark              inf_authentication_detail_error_quark
                                                            (void);

Error domain for further information on authentication errors. Errors in this domain will be from the InfAuthenticationDetailError enumeration. See GError for information on error domains.

Returns : | A GQuark.

### inf_authentication_detail_strerror ()

    const gchar *       inf_authentication_detail_strerror  (InfAuthenticationDetailError code);

Returns a human-readable string for the given error code.

`code` : | An error code from the InfAuthenticationDetailError enumeration.
Returns : | A static string that must not be freed.

### inf_gnutls_error_quark ()

    GQuark              inf_gnutls_error_quark              (void);

Error domain for GnuTLS errors. Errors in this domain will be GnuTLS error codes. See GError for information on error domains.

Returns : | A GQuark.

### inf_gnutls_set_error ()

    void                inf_gnutls_set_error                (GError **error,
                                                             int error_code);

Sets a GError from a GnuTLS error code. If `error` is `NULL`, does nothing.

`error` : | Location to store the error, or `NULL`.
`error_code` : | A GnuTLS error code.

### inf_gsasl_error_quark ()

    GQuark              inf_gsasl_error_quark               (void);

Error domain for GNU SASL errors. Errors in this domain will be GNU SASL error codes. See GError for information on error domains.

Returns : | A GQuark.

### inf_gsasl_set_error ()

    void                inf_gsasl_set_error                 (GError **error,
                                                             int error_code);

Sets a GError from a GNU SASL error code. If `error` is `NULL`, does nothing.

`error` : | Location to store the error, or `NULL`.
`error_code` : | A GNU SASL error code.