wocky-xmpp-error

wocky-xmpp-error

Synopsis

enum                WockyXmppErrorType;
enum                WockyXmppError;
GQuark              wocky_xmpp_error_quark              (void);
#define             WOCKY_XMPP_ERROR
                    WockyXmppErrorSpecialization;
                    WockyXmppErrorDomain;
void                wocky_xmpp_error_register_domain    (WockyXmppErrorDomain *domain);
enum                WockyJingleError;
GQuark              wocky_jingle_error_quark            (void);
#define             WOCKY_JINGLE_ERROR
enum                WockySIError;
GQuark              wocky_si_error_quark                (void);
#define             WOCKY_SI_ERROR
enum                WockyXmppStreamError;
GQuark              wocky_xmpp_stream_error_quark       (void);
#define             WOCKY_XMPP_STREAM_ERROR
const gchar *       wocky_xmpp_error_string             (WockyXmppError error);
const gchar *       wocky_xmpp_error_description        (WockyXmppError error);
GError *            wocky_xmpp_stream_error_from_node   (WockyNode *error);
WockyNode *         wocky_stanza_error_to_node          (const GError *error,
                                                         WockyNode *parent_node);
const gchar *       wocky_xmpp_stanza_error_to_string   (GError *error);
void                wocky_xmpp_error_extract            (WockyNode *error,
                                                         WockyXmppErrorType *type,
                                                         GError **core,
                                                         GError **specialized,
                                                         WockyNode **specialized_node);
void                wocky_xmpp_error_init               (void);
void                wocky_xmpp_error_deinit             (void);

Description

Details

enum WockyXmppErrorType

typedef enum
{
  WOCKY_XMPP_ERROR_TYPE_CANCEL,
  WOCKY_XMPP_ERROR_TYPE_CONTINUE,
  WOCKY_XMPP_ERROR_TYPE_MODIFY,
  WOCKY_XMPP_ERROR_TYPE_AUTH,
  WOCKY_XMPP_ERROR_TYPE_WAIT
} WockyXmppErrorType;

XMPP error types as described in RFC 3920 §9.3.2.

WOCKY_XMPP_ERROR_TYPE_CANCEL

do not retry (the error is unrecoverable)

WOCKY_XMPP_ERROR_TYPE_CONTINUE

proceed (the condition was only a warning)

WOCKY_XMPP_ERROR_TYPE_MODIFY

retry after changing the data sent

WOCKY_XMPP_ERROR_TYPE_AUTH

retry after providing credentials

WOCKY_XMPP_ERROR_TYPE_WAIT

retry after waiting (the error is temporary)

enum WockyXmppError

typedef enum {
    WOCKY_XMPP_ERROR_UNDEFINED_CONDITION = 0, /* 500 */

    WOCKY_XMPP_ERROR_REDIRECT,                /* 302 */
    WOCKY_XMPP_ERROR_GONE,                    /* 302 */

    WOCKY_XMPP_ERROR_BAD_REQUEST,             /* 400 */
    WOCKY_XMPP_ERROR_UNEXPECTED_REQUEST,      /* 400 */
    WOCKY_XMPP_ERROR_JID_MALFORMED,           /* 400 */

    WOCKY_XMPP_ERROR_NOT_AUTHORIZED,          /* 401 */

    WOCKY_XMPP_ERROR_PAYMENT_REQUIRED,        /* 402 */

    WOCKY_XMPP_ERROR_FORBIDDEN,               /* 403 */

    WOCKY_XMPP_ERROR_ITEM_NOT_FOUND,          /* 404 */
    WOCKY_XMPP_ERROR_RECIPIENT_UNAVAILABLE,   /* 404 */
    WOCKY_XMPP_ERROR_REMOTE_SERVER_NOT_FOUND, /* 404 */

    WOCKY_XMPP_ERROR_NOT_ALLOWED,             /* 405 */

    WOCKY_XMPP_ERROR_NOT_ACCEPTABLE,          /* 406 */

    WOCKY_XMPP_ERROR_REGISTRATION_REQUIRED,   /* 407 */
    WOCKY_XMPP_ERROR_SUBSCRIPTION_REQUIRED,   /* 407 */

    WOCKY_XMPP_ERROR_REMOTE_SERVER_TIMEOUT,   /* 408, 504 */

    WOCKY_XMPP_ERROR_CONFLICT,                /* 409 */

    WOCKY_XMPP_ERROR_INTERNAL_SERVER_ERROR,   /* 500 */
    WOCKY_XMPP_ERROR_RESOURCE_CONSTRAINT,     /* 500 */

    WOCKY_XMPP_ERROR_FEATURE_NOT_IMPLEMENTED, /* 501 */

    WOCKY_XMPP_ERROR_SERVICE_UNAVAILABLE,     /* 502, 503, 510 */

    /*< private >*/
    NUM_WOCKY_XMPP_ERRORS /*< skip >*/ /* don't want this in the GEnum */
} WockyXmppError;

Possible XMPP stream errors, as defined by RFC 3920 §9.3.3.

WOCKY_XMPP_ERROR_UNDEFINED_CONDITION

he error condition is not one of those defined by the other conditions in this list

WOCKY_XMPP_ERROR_REDIRECT

the recipient or server is redirecting requests for this information to another entity

WOCKY_XMPP_ERROR_GONE

the recipient or server can no longer be contacted at this address

WOCKY_XMPP_ERROR_BAD_REQUEST

the sender has sent XML that is malformed or that cannot be processed

WOCKY_XMPP_ERROR_UNEXPECTED_REQUEST

the recipient or server understood the request but was not expecting it at this time

WOCKY_XMPP_ERROR_JID_MALFORMED

the sending entity has provided or communicated an XMPP address

WOCKY_XMPP_ERROR_NOT_AUTHORIZED

the sender must provide proper credentials before being allowed to perform the action, or has provided improper credentials

WOCKY_XMPP_ERROR_PAYMENT_REQUIRED

the requesting entity is not authorized to access the requested service because payment is required

WOCKY_XMPP_ERROR_FORBIDDEN

the requesting entity does not possess the required permissions to perform the action

WOCKY_XMPP_ERROR_ITEM_NOT_FOUND

he addressed JID or item requested cannot be found

WOCKY_XMPP_ERROR_RECIPIENT_UNAVAILABLE

the intended recipient is temporarily unavailable

WOCKY_XMPP_ERROR_REMOTE_SERVER_NOT_FOUND

a remote server or service specified as part or all of the JID of the intended recipient does not exist

WOCKY_XMPP_ERROR_NOT_ALLOWED

the recipient or server does not allow any entity to perform the action

WOCKY_XMPP_ERROR_NOT_ACCEPTABLE

the recipient or server understands the request but is refusing to process it because it does not meet criteria defined by the recipient or server

WOCKY_XMPP_ERROR_REGISTRATION_REQUIRED

the requesting entity is not authorized to access the requested service because registration is required

WOCKY_XMPP_ERROR_SUBSCRIPTION_REQUIRED

the requesting entity is not authorized to access the requested service because a subscription is required

WOCKY_XMPP_ERROR_REMOTE_SERVER_TIMEOUT

a remote server or service specified as part or all of the JID of the intended recipient (or required to fulfill a request) could not be contacted within a reasonable amount of time

WOCKY_XMPP_ERROR_CONFLICT

access cannot be granted because an existing resource or session exists with the same name or address

WOCKY_XMPP_ERROR_INTERNAL_SERVER_ERROR

the server could not process the stanza because of a misconfiguration or an otherwise-undefined internal server error

WOCKY_XMPP_ERROR_RESOURCE_CONSTRAINT

the server or recipient lacks the system resources necessary to service the request

WOCKY_XMPP_ERROR_FEATURE_NOT_IMPLEMENTED

the feature requested is not implemented by the recipient or server and therefore cannot be processed

WOCKY_XMPP_ERROR_SERVICE_UNAVAILABLE

the server or recipient does not currently provide the requested service

wocky_xmpp_error_quark ()

GQuark              wocky_xmpp_error_quark              (void);

Returns :


WOCKY_XMPP_ERROR

#define WOCKY_XMPP_ERROR (wocky_xmpp_error_quark ())


WockyXmppErrorSpecialization

typedef struct {
  const gchar *description;
  WockyXmppError specializes;
  gboolean override_type;
  WockyXmppErrorType type;
} WockyXmppErrorSpecialization;

A struct to represent a specialization of an existing WockyXmppError member.

const gchar *description;

description of the error

WockyXmppError specializes;

which WockyXmppError this error specializes

gboolean override_type;

TRUE if type should be used, or FALSE if the default error type for specializes should be used

WockyXmppErrorType type;

the XMPP error type

WockyXmppErrorDomain

typedef struct {
  GQuark domain;
  GType enum_type;
  WockyXmppErrorSpecialization *codes;
} WockyXmppErrorDomain;

A struct to represent extra XMPP error domains added.

GQuark domain;

a GQuark of the error domain

GType enum_type;

the GType of the error enum

WockyXmppErrorSpecialization *codes;

a NULL-terminated array of of WockyXmppErrorSpecializations

wocky_xmpp_error_register_domain ()

void                wocky_xmpp_error_register_domain    (WockyXmppErrorDomain *domain);

Registers a new set of application-specific stanza errors. This allows GErrors in that domain to be passed to wocky_stanza_error_to_node(), and to be recognized and returned by wocky_xmpp_error_extract() (and wocky_stanza_extract_errors(), by extension).

domain :

a description of the error domain

enum WockyJingleError

typedef enum {
    WOCKY_JINGLE_ERROR_OUT_OF_ORDER,
    WOCKY_JINGLE_ERROR_TIE_BREAK,
    WOCKY_JINGLE_ERROR_UNKNOWN_SESSION,
    WOCKY_JINGLE_ERROR_UNSUPPORTED_INFO
} WockyJingleError;

Jingle specific errors.

WOCKY_JINGLE_ERROR_OUT_OF_ORDER

the request cannot occur at this point in the state machine

WOCKY_JINGLE_ERROR_TIE_BREAK

the request is rejected because it was sent while the initiator was awaiting a reply on a similar request

WOCKY_JINGLE_ERROR_UNKNOWN_SESSION

the 'sid' attribute specifies a session that is unknown to the recipient

WOCKY_JINGLE_ERROR_UNSUPPORTED_INFO

the recipient does not support the informational payload of a session-info action.

wocky_jingle_error_quark ()

GQuark              wocky_jingle_error_quark            (void);

Returns :


WOCKY_JINGLE_ERROR

#define WOCKY_JINGLE_ERROR (wocky_jingle_error_quark ())


enum WockySIError

typedef enum {
    WOCKY_SI_ERROR_NO_VALID_STREAMS,
    WOCKY_SI_ERROR_BAD_PROFILE
} WockySIError;

SI specific errors.

WOCKY_SI_ERROR_NO_VALID_STREAMS

none of the available streams are acceptable

WOCKY_SI_ERROR_BAD_PROFILE

the profile is not understood or invalid

wocky_si_error_quark ()

GQuark              wocky_si_error_quark                (void);

Returns :


WOCKY_SI_ERROR

#define WOCKY_SI_ERROR (wocky_si_error_quark ())


enum WockyXmppStreamError

typedef enum {
  WOCKY_XMPP_STREAM_ERROR_BAD_FORMAT,
  WOCKY_XMPP_STREAM_ERROR_BAD_NAMESPACE_PREFIX,
  WOCKY_XMPP_STREAM_ERROR_CONFLICT,
  WOCKY_XMPP_STREAM_ERROR_CONNECTION_TIMEOUT,
  WOCKY_XMPP_STREAM_ERROR_HOST_GONE,
  WOCKY_XMPP_STREAM_ERROR_HOST_UNKNOWN,
  WOCKY_XMPP_STREAM_ERROR_IMPROPER_ADDRESSING,
  WOCKY_XMPP_STREAM_ERROR_INTERNAL_SERVER_ERROR,
  WOCKY_XMPP_STREAM_ERROR_INVALID_FROM,
  WOCKY_XMPP_STREAM_ERROR_INVALID_ID,
  WOCKY_XMPP_STREAM_ERROR_INVALID_NAMESPACE,
  WOCKY_XMPP_STREAM_ERROR_INVALID_XML,
  WOCKY_XMPP_STREAM_ERROR_NOT_AUTHORIZED,
  WOCKY_XMPP_STREAM_ERROR_POLICY_VIOLATION,
  WOCKY_XMPP_STREAM_ERROR_REMOTE_CONNECTION_FAILED,
  WOCKY_XMPP_STREAM_ERROR_RESOURCE_CONSTRAINT,
  WOCKY_XMPP_STREAM_ERROR_RESTRICTED_XML,
  WOCKY_XMPP_STREAM_ERROR_SEE_OTHER_HOST,
  WOCKY_XMPP_STREAM_ERROR_SYSTEM_SHUTDOWN,
  WOCKY_XMPP_STREAM_ERROR_UNDEFINED_CONDITION,
  WOCKY_XMPP_STREAM_ERROR_UNSUPPORTED_ENCODING,
  WOCKY_XMPP_STREAM_ERROR_UNSUPPORTED_STANZA_TYPE,
  WOCKY_XMPP_STREAM_ERROR_UNSUPPORTED_VERSION,
  WOCKY_XMPP_STREAM_ERROR_XML_NOT_WELL_FORMED,
  WOCKY_XMPP_STREAM_ERROR_UNKNOWN,
} WockyXmppStreamError;

Stream-level error conditions as described in RFC 3920 §4.7.3.

WOCKY_XMPP_STREAM_ERROR_BAD_FORMAT

the entity has sent XML that cannot be processed

WOCKY_XMPP_STREAM_ERROR_BAD_NAMESPACE_PREFIX

the entity has sent a namespace prefix that is unsupported, or has sent no namespace prefix on an element that requires such a prefix

WOCKY_XMPP_STREAM_ERROR_CONFLICT

the server is closing the active stream for this entity because a new stream has been initiated that conflicts with the existing stream

WOCKY_XMPP_STREAM_ERROR_CONNECTION_TIMEOUT

the entity has not generated any traffic over the stream for some period of time

WOCKY_XMPP_STREAM_ERROR_HOST_GONE

the value of the 'to' attribute provided by the initiating entity in the stream header corresponds to a hostname that is no longer hosted by the server

WOCKY_XMPP_STREAM_ERROR_HOST_UNKNOWN

the value of the 'to' attribute provided by the initiating entity in the stream header does not correspond to a hostname that is hosted by the server

WOCKY_XMPP_STREAM_ERROR_IMPROPER_ADDRESSING

a stanza sent between two servers lacks a 'to' or 'from' attribute (or the attribute has no value)

WOCKY_XMPP_STREAM_ERROR_INTERNAL_SERVER_ERROR

the server has experienced a misconfiguration or an otherwise-undefined internal error that prevents it from servicing the stream

WOCKY_XMPP_STREAM_ERROR_INVALID_FROM

the JID or hostname provided in a 'from' address does not match an authorized JID or validated domain negotiated between servers via SASL or dialback, or between a client and a server via authentication and resource binding

WOCKY_XMPP_STREAM_ERROR_INVALID_ID

the stream ID or dialback ID is invalid or does not match an ID previously provided

WOCKY_XMPP_STREAM_ERROR_INVALID_NAMESPACE

the streams namespace name is something other than "http://etherx.jabber.org/streams" or the dialback namespace name is something other than "jabber:server:dialback"

WOCKY_XMPP_STREAM_ERROR_INVALID_XML

the entity has sent invalid XML over the stream to a server that performs validation

WOCKY_XMPP_STREAM_ERROR_NOT_AUTHORIZED

the entity has attempted to send data before the stream has been authenticated, or otherwise is not authorized to perform an action related to stream negotiation

WOCKY_XMPP_STREAM_ERROR_POLICY_VIOLATION

the entity has violated some local service policy

WOCKY_XMPP_STREAM_ERROR_REMOTE_CONNECTION_FAILED

the server is unable to properly connect to a remote entity that is required for authentication or authorization

WOCKY_XMPP_STREAM_ERROR_RESOURCE_CONSTRAINT

the server lacks the system resources necessary to service the stream

WOCKY_XMPP_STREAM_ERROR_RESTRICTED_XML

the entity has attempted to send restricted XML features such as a comment, processing instruction, DTD, entity reference, or unescaped character

WOCKY_XMPP_STREAM_ERROR_SEE_OTHER_HOST

the server will not provide service to the initiating entity but is redirecting traffic to another host

WOCKY_XMPP_STREAM_ERROR_SYSTEM_SHUTDOWN

the server is being shut down and all active streams are being closed

WOCKY_XMPP_STREAM_ERROR_UNDEFINED_CONDITION

the error condition is not one of those defined by the other conditions in this list

WOCKY_XMPP_STREAM_ERROR_UNSUPPORTED_ENCODING

the initiating entity has encoded the stream in an encoding that is not supported by the server

WOCKY_XMPP_STREAM_ERROR_UNSUPPORTED_STANZA_TYPE

the initiating entity has sent a first-level child of the stream that is not supported by the server

WOCKY_XMPP_STREAM_ERROR_UNSUPPORTED_VERSION

the value of the 'version' attribute provided by the initiating entity in the stream header specifies a version of XMPP that is not supported by the server

WOCKY_XMPP_STREAM_ERROR_XML_NOT_WELL_FORMED

the initiating entity has sent XML that is not well-formed

WOCKY_XMPP_STREAM_ERROR_UNKNOWN

an unknown stream error

wocky_xmpp_stream_error_quark ()

GQuark              wocky_xmpp_stream_error_quark       (void);

Get the error quark used for stream errors

Returns :

the quark for stream errors.

WOCKY_XMPP_STREAM_ERROR

#define WOCKY_XMPP_STREAM_ERROR (wocky_xmpp_stream_error_quark ())

Get access to the error quark of the xmpp stream errors.


wocky_xmpp_error_string ()

const gchar *       wocky_xmpp_error_string             (WockyXmppError error);

error :

a core stanza error

Returns :

the name of the tag corresponding to error

wocky_xmpp_error_description ()

const gchar *       wocky_xmpp_error_description        (WockyXmppError error);

error :

a core stanza error

Returns :

a description of the error, in English, as specified in XMPP Core

wocky_xmpp_stream_error_from_node ()

GError *            wocky_xmpp_stream_error_from_node   (WockyNode *error);

error :

the root node of a WOCKY_STANZA_TYPE_STREAM_ERROR stanza

Returns :

a GError in the WOCKY_XMPP_STREAM_ERROR domain.

wocky_stanza_error_to_node ()

WockyNode *         wocky_stanza_error_to_node          (const GError *error,
                                                         WockyNode *parent_node);

error :

parent_node :

Returns :


wocky_xmpp_stanza_error_to_string ()

const gchar *       wocky_xmpp_stanza_error_to_string   (GError *error);

Returns the name of the XMPP stanza error element represented by error. This is intended for use in debugging messages, with GErrors returned by wocky_stanza_extract_errors().

error :

an error in the domain WOCKY_XMPP_ERROR, or another domain registered with wocky_xmpp_error_register_domain() (such as WOCKY_JINGLE_ERROR).

Returns :

the error code as a string, or NULL if error->domain is not known to Wocky.

wocky_xmpp_error_extract ()

void                wocky_xmpp_error_extract            (WockyNode *error,
                                                         WockyXmppErrorType *type,
                                                         GError **core,
                                                         GError **specialized,
                                                         WockyNode **specialized_node);

Given an <error/> node, breaks it down into values describing the error. type and core are guaranteed to be set; specialized and specialized_node will be set if a recognised application-specific error is found, and the latter will be set to NULL if no application-specific error is found.

Any or all of the out parameters may be NULL to ignore the value. The value stored in specialized_node is borrowed from stanza, and is only valid as long as the latter is alive.

error :

the <error/> child of a stanza with type='error'

type :

location at which to store the error type

core :

location at which to store an error in the domain WOCKY_XMPP_ERROR

specialized :

location at which to store an error in an application-specific domain, if one is found

specialized_node :

location at which to store the node representing an application-specific error, if one is found

wocky_xmpp_error_init ()

void                wocky_xmpp_error_init               (void);


wocky_xmpp_error_deinit ()

void                wocky_xmpp_error_deinit             (void);