WockyAuthRegistry

## WockyAuthRegistry WockyAuthRegistry |

## Synopsis

    #define             WOCKY_AUTH_ERROR
    #define             WOCKY_AUTH_MECH_JABBER_DIGEST
    #define             WOCKY_AUTH_MECH_JABBER_PASSWORD
    #define             WOCKY_AUTH_MECH_SASL_DIGEST_MD5
    #define             WOCKY_AUTH_MECH_SASL_PLAIN
    enum                WockyAuthError;
    struct              WockyAuthRegistry;
    void                (*WockyAuthRegistryChallengeAsyncFunc)
                                                            (WockyAuthRegistry *self,
                                                             const GString *challenge_data,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            (*WockyAuthRegistryChallengeFinishFunc)
                                                            (WockyAuthRegistry *self,
                                                             GAsyncResult *result,
                                                             GString **response,
                                                             GError **error);
    struct              WockyAuthRegistryClass;
    void                (*WockyAuthRegistryFailureFunc)     (WockyAuthRegistry *self,
                                                             GError *error);
    void                (*WockyAuthRegistryStartAuthAsyncFunc)
                                                            (WockyAuthRegistry *self,
                                                             const GSList *mechanisms,
                                                             gboolean allow_plain,
                                                             gboolean is_secure_channel,
                                                             const gchar *username,
                                                             const gchar *password,
                                                             const gchar *server,
                                                             const gchar *session_id,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            (*WockyAuthRegistryStartAuthFinishFunc)
                                                            (WockyAuthRegistry *self,
                                                             GAsyncResult *result,
                                                             WockyAuthRegistryStartData **start_data,
                                                             GError **error);
                        WockyAuthRegistryStartData;
    void                (*WockyAuthRegistrySuccessAsyncFunc)
                                                            (WockyAuthRegistry *self,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            (*WockyAuthRegistrySuccessFinishFunc)
                                                            (WockyAuthRegistry *self,
                                                             GAsyncResult *result,
                                                             GError **error);
    GQuark              wocky_auth_error_quark              (void);
    void                wocky_auth_registry_add_handler     (WockyAuthRegistry *self,
                                                             WockyAuthHandler *handler);
    void                wocky_auth_registry_challenge_async (WockyAuthRegistry *self,
                                                             const GString *challenge_data,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            wocky_auth_registry_challenge_finish
                                                            (WockyAuthRegistry *self,
                                                             GAsyncResult *res,
                                                             GString **response,
                                                             GError **error);
    void                wocky_auth_registry_failure         (WockyAuthRegistry *self,
                                                             GError *error);
    WockyAuthRegistry * wocky_auth_registry_new             (void);
    void                wocky_auth_registry_start_auth_async
                                                            (WockyAuthRegistry *self,
                                                             const GSList *mechanisms,
                                                             gboolean allow_plain,
                                                             gboolean is_secure_channel,
                                                             const gchar *username,
                                                             const gchar *password,
                                                             const gchar *server,
                                                             const gchar *session_id,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            wocky_auth_registry_start_auth_finish
                                                            (WockyAuthRegistry *self,
                                                             GAsyncResult *result,
                                                             WockyAuthRegistryStartData **start_data,
                                                             GError **error);
    WockyAuthRegistryStartData * wocky_auth_registry_start_data_dup
                                                            (WockyAuthRegistryStartData *start_data);
    void                wocky_auth_registry_start_data_free (WockyAuthRegistryStartData *start_data);
    WockyAuthRegistryStartData * wocky_auth_registry_start_data_new
                                                            (const gchar *mechanism,
                                                             const GString *initial_response);
    void                wocky_auth_registry_success_async   (WockyAuthRegistry *self,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            wocky_auth_registry_success_finish  (WockyAuthRegistry *self,
                                                             GAsyncResult *res,
                                                             GError **error);

## Object Hierarchy

      GEnum
       +----WockyAuthError

      GObject
       +----WockyAuthRegistry

## Description

## Details

### WOCKY_AUTH_ERROR

    #define             WOCKY_AUTH_ERROR

### WOCKY_AUTH_MECH_JABBER_DIGEST

    #define WOCKY_AUTH_MECH_JABBER_DIGEST "X-WOCKY-JABBER-DIGEST"

### WOCKY_AUTH_MECH_JABBER_PASSWORD

    #define WOCKY_AUTH_MECH_JABBER_PASSWORD "X-WOCKY-JABBER-PASSWORD"

### WOCKY_AUTH_MECH_SASL_DIGEST_MD5

    #define WOCKY_AUTH_MECH_SASL_DIGEST_MD5 "DIGEST-MD5"

### WOCKY_AUTH_MECH_SASL_PLAIN

    #define WOCKY_AUTH_MECH_SASL_PLAIN "PLAIN"

### enum WockyAuthError

    typedef enum
    {
      WOCKY_AUTH_ERROR_INIT_FAILED,
      WOCKY_AUTH_ERROR_NOT_SUPPORTED,
      WOCKY_AUTH_ERROR_NO_SUPPORTED_MECHANISMS,
      WOCKY_AUTH_ERROR_NETWORK,
      WOCKY_AUTH_ERROR_INVALID_REPLY,
      WOCKY_AUTH_ERROR_NO_CREDENTIALS,
      WOCKY_AUTH_ERROR_FAILURE,
      WOCKY_AUTH_ERROR_CONNRESET,
      WOCKY_AUTH_ERROR_STREAM,
      WOCKY_AUTH_ERROR_RESOURCE_CONFLICT,
      WOCKY_AUTH_ERROR_NOT_AUTHORIZED,
    } WockyAuthError;

WockyAuthRegistry specific errors.

`WOCKY_AUTH_ERROR_INIT_FAILED` | Failed to initialize our auth support
`WOCKY_AUTH_ERROR_NOT_SUPPORTED` | Server doesn't support this authentication method
`WOCKY_AUTH_ERROR_NO_SUPPORTED_MECHANISMS` | Server doesn't support any mechanisms that we support
`WOCKY_AUTH_ERROR_NETWORK` | Couldn't send our stanzas to the server
`WOCKY_AUTH_ERROR_INVALID_REPLY` | Server sent an invalid reply
`WOCKY_AUTH_ERROR_NO_CREDENTIALS` | Failure to provide user credentials
`WOCKY_AUTH_ERROR_FAILURE` | Server sent a failure
`WOCKY_AUTH_ERROR_CONNRESET` | disconnected
`WOCKY_AUTH_ERROR_STREAM` | XMPP stream error while authing
`WOCKY_AUTH_ERROR_RESOURCE_CONFLICT` | Resource conflict (relevant in in jabber auth)
`WOCKY_AUTH_ERROR_NOT_AUTHORIZED` | Provided credentials are not valid

### struct WockyAuthRegistry

    struct WockyAuthRegistry;

### WockyAuthRegistryChallengeAsyncFunc ()

    void                (*WockyAuthRegistryChallengeAsyncFunc)
                                                            (WockyAuthRegistry *self,
                                                             const GString *challenge_data,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Recieves a challenge and asynchronously provides a reply. By default the challenge is passed on to the chosen WockyAuthHandler.

`self` : | a WockyAuthRegistry object
`challenge_data` : | the challenge data string
`callback` : | a callback to call when finished
`user_data` : | data to pass to `callback`

### WockyAuthRegistryChallengeFinishFunc ()

    gboolean            (*WockyAuthRegistryChallengeFinishFunc)
                                                            (WockyAuthRegistry *self,
                                                             GAsyncResult *result,
                                                             GString **response,
                                                             GError **error);

Finishes a GAsyncResult from WockyAuthRegistryChallengeAsyncFunc. By default it extracts a GString response from the given GSimpleAsyncResult and copies it to the out param.

`self` : | a WockyAuthRegistry object
`result` : | a GAsyncResult object
`response` : | a location to be filled with the response string
`error` : | a location to fill with a GError if an error is hit, or `NULL`
Returns : | `TRUE` on success, otherwise `FALSE`

### struct WockyAuthRegistryClass

    struct WockyAuthRegistryClass {
      WockyAuthRegistryStartAuthAsyncFunc start_auth_async_func;
      WockyAuthRegistryStartAuthFinishFunc start_auth_finish_func;

      WockyAuthRegistryChallengeAsyncFunc challenge_async_func;
      WockyAuthRegistryChallengeFinishFunc challenge_finish_func;

      WockyAuthRegistrySuccessAsyncFunc success_async_func;
      WockyAuthRegistrySuccessFinishFunc success_finish_func;

      WockyAuthRegistryFailureFunc failure_func;
    };

The class of a WockyAuthRegistry.

WockyAuthRegistryStartAuthAsyncFunc `start_auth_async_func`; | a function to call to start an asynchronous start auth operation; see `wocky_auth_registry_start_auth_async()` for more details.
WockyAuthRegistryStartAuthFinishFunc `start_auth_finish_func`; | a function to call to finish an asynchronous start auth operation; see `wocky_auth_registry_start_auth_finish()` for more details.
WockyAuthRegistryChallengeAsyncFunc `challenge_async_func`; | a function to call to start an asynchronous challenge operation; see `wocky_auth_registry_challenge_async()` for more details.
WockyAuthRegistryChallengeFinishFunc `challenge_finish_func`; | a function to call to finish an asynchronous challenge operation; see `wocky_auth_registry_challenge_finish()` for more details.
WockyAuthRegistrySuccessAsyncFunc `success_async_func`; | a function to call to start an asynchronous success operation; see `wocky_auth_registry_success_async()` for more details.
WockyAuthRegistrySuccessFinishFunc `success_finish_func`; | a function to call to finish an asynchronous success operation; see `wocky_auth_registry_success_finish()` for more details.
WockyAuthRegistryFailureFunc `failure_func`; | a function to call on failure; see `wocky_auth_registry_failure()` for more details.

### WockyAuthRegistryFailureFunc ()

    void                (*WockyAuthRegistryFailureFunc)     (WockyAuthRegistry *self,
                                                             GError *error);

Notifies the client of a server-side error. By default this is not implemented.

`self` : | a WockyAuthRegistry object
`error` : | a GError describing the failure

### WockyAuthRegistryStartAuthAsyncFunc ()

    void                (*WockyAuthRegistryStartAuthAsyncFunc)
                                                            (WockyAuthRegistry *self,
                                                             const GSList *mechanisms,
                                                             gboolean allow_plain,
                                                             gboolean is_secure_channel,
                                                             const gchar *username,
                                                             const gchar *password,
                                                             const gchar *server,
                                                             const gchar *session_id,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Starts a async authentication: chooses mechanism and gets initial data. The default function chooses a WockyAuthHandler by which mechanism it supports and gets the initial data from the chosen handler.

`self` : | a WockyAuthRegistry object
`mechanisms` : | a list of avahilable mechanisms
`allow_plain` : | `TRUE` if PLAIN is allowed, otherwise `FALSE`
`is_secure_channel` : | `TRUE` if channel is secure, otherwise `FALSE`
`username` : | the username
`password` : | the password
`server` : | the server
`session_id` : | the session ID
`callback` : | a callback to be called when finished
`user_data` : | data to pass to `callback`

### WockyAuthRegistryStartAuthFinishFunc ()

    gboolean            (*WockyAuthRegistryStartAuthFinishFunc)
                                                            (WockyAuthRegistry *self,
                                                             GAsyncResult *result,
                                                             WockyAuthRegistryStartData **start_data,
                                                             GError **error);

Called to finish the GAsyncResult task for authentication start. By default, it extracts a WockyAuthRegistryStartData pointer from a given GSimpleAsyncResult and copies it to the out param.

`self` : | a WockyAuthRegistry object
`result` : | a GAsyncResult object
`start_data` : | a location to fill with a WockyAuthRegistryStartData structure
`error` : | a location to fill with a GError if an error is hit, or `NULL`
Returns : | `TRUE` on success, otherwise `FALSE`

### WockyAuthRegistryStartData

    typedef struct {
      gchar *mechanism;
      GString *initial_response;
    } WockyAuthRegistryStartData;

A structure to hold the mechanism and response data.

gchar *`mechanism`; | the name of the mechanism
GString *`initial_response`; | the data in the response

### WockyAuthRegistrySuccessAsyncFunc ()

    void                (*WockyAuthRegistrySuccessAsyncFunc)
                                                            (WockyAuthRegistry *self,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Notifies the registry of authentication success, and allows a last ditch attempt at aborting the authentication at the client's discretion.

`self` : | a WockyAuthRegistry object
`callback` : | a callback to be called when finished
`user_data` : | data to pass to `callback`

### WockyAuthRegistrySuccessFinishFunc ()

    gboolean            (*WockyAuthRegistrySuccessFinishFunc)
                                                            (WockyAuthRegistry *self,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes a GAsyncResult from WockyAuthRegistrySuccessAsyncFunc. It checks for any errors set on the given GSimpleAsyncResult, copies the GError to an out param and returns `FALSE` if there was an error.

`self` : | a WockyAuthRegistry object
`result` : | a GAsyncResult object
`error` : | a location to fill with a GError if an error is hit, or `NULL`
Returns : | `TRUE` on success, otherwise `FALSE`

### wocky_auth_error_quark ()

    GQuark              wocky_auth_error_quark              (void);

### wocky_auth_registry_add_handler ()

    void                wocky_auth_registry_add_handler     (WockyAuthRegistry *self,
                                                             WockyAuthHandler *handler);

### wocky_auth_registry_challenge_async ()

    void                wocky_auth_registry_challenge_async (WockyAuthRegistry *self,
                                                             const GString *challenge_data,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

### wocky_auth_registry_challenge_finish ()

    gboolean            wocky_auth_registry_challenge_finish
                                                            (WockyAuthRegistry *self,
                                                             GAsyncResult *res,
                                                             GString **response,
                                                             GError **error);

### wocky_auth_registry_failure ()

    void                wocky_auth_registry_failure         (WockyAuthRegistry *self,
                                                             GError *error);

### wocky_auth_registry_new ()

    WockyAuthRegistry * wocky_auth_registry_new             (void);

### wocky_auth_registry_start_auth_async ()

    void                wocky_auth_registry_start_auth_async
                                                            (WockyAuthRegistry *self,
                                                             const GSList *mechanisms,
                                                             gboolean allow_plain,
                                                             gboolean is_secure_channel,
                                                             const gchar *username,
                                                             const gchar *password,
                                                             const gchar *server,
                                                             const gchar *session_id,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

### wocky_auth_registry_start_auth_finish ()

    gboolean            wocky_auth_registry_start_auth_finish
                                                            (WockyAuthRegistry *self,
                                                             GAsyncResult *result,
                                                             WockyAuthRegistryStartData **start_data,
                                                             GError **error);

### wocky_auth_registry_start_data_dup ()

    WockyAuthRegistryStartData * wocky_auth_registry_start_data_dup
                                                            (WockyAuthRegistryStartData *start_data);

### wocky_auth_registry_start_data_free ()

    void                wocky_auth_registry_start_data_free (WockyAuthRegistryStartData *start_data);

### wocky_auth_registry_start_data_new ()

    WockyAuthRegistryStartData * wocky_auth_registry_start_data_new
                                                            (const gchar *mechanism,
                                                             const GString *initial_response);

### wocky_auth_registry_success_async ()

    void                wocky_auth_registry_success_async   (WockyAuthRegistry *self,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

### wocky_auth_registry_success_finish ()

    gboolean            wocky_auth_registry_success_finish  (WockyAuthRegistry *self,
                                                             GAsyncResult *res,
                                                             GError **error);