WockyAuthHandler

## WockyAuthHandler WockyAuthHandler |

## Synopsis

    gboolean            (*WockyAuthAuthDataFunc)            (WockyAuthHandler *handler,
                                                             const GString *data,
                                                             GString **response,
                                                             GError **error);
    struct              WockyAuthHandlerIface;
    gboolean            (*WockyAuthInitialResponseFunc)     (WockyAuthHandler *handler,
                                                             GString **initial_data,
                                                             GError **error);
    gboolean            (*WockyAuthSuccessFunc)             (WockyAuthHandler *handler,
                                                             GError **error);
    void                wocky_auth_handler_free             (WockyAuthHandler *handler);
    gboolean            wocky_auth_handler_get_initial_response
                                                            (WockyAuthHandler *handler,
                                                             GString **initial_data,
                                                             GError **error);
    const gchar *       wocky_auth_handler_get_mechanism    (WockyAuthHandler *handler);
    gboolean            wocky_auth_handler_handle_auth_data (WockyAuthHandler *handler,
                                                             const GString *data,
                                                             GString **response,
                                                             GError **error);
    gboolean            wocky_auth_handler_handle_success   (WockyAuthHandler *handler,
                                                             GError **error);
    gboolean            wocky_auth_handler_is_plain         (WockyAuthHandler *handler);

## Description

## Details

### WockyAuthAuthDataFunc ()

    gboolean            (*WockyAuthAuthDataFunc)            (WockyAuthHandler *handler,
                                                             const GString *data,
                                                             GString **response,
                                                             GError **error);

### struct WockyAuthHandlerIface

    struct WockyAuthHandlerIface {
        GTypeInterface parent;
        gchar *mechanism;
        gboolean plain;
        WockyAuthInitialResponseFunc initial_response_func;
        WockyAuthAuthDataFunc auth_data_func;
        WockyAuthSuccessFunc success_func;
    };

GTypeInterface `parent`; | The parent interface.
gchar *`mechanism`; | The AUTH mechanism which this handler responds to challenges for.
gboolean `plain`; | Whether the mechanism this handler handles sends secrets in plaintext.
WockyAuthInitialResponseFunc `initial_response_func`; | Called when the initial `<auth />` stanza is generated
WockyAuthAuthDataFunc `auth_data_func`; | Called when any authentication data from the server is received
WockyAuthSuccessFunc `success_func`; | Called when a `<success/>` stanza is received.

### WockyAuthInitialResponseFunc ()

    gboolean            (*WockyAuthInitialResponseFunc)     (WockyAuthHandler *handler,
                                                             GString **initial_data,
                                                             GError **error);

Called when authentication begins, if the mechanism allows a response to an implicit challenge during AUTH initiation (which, in XMPP, corresponds to sending the `<auth/>` stanza to the server).

The function should return `TRUE` on success and optionally set the `initial_data` to a string (allocated using `g_malloc()`) if there is initial data to send. On error it should return `FALSE` and set the error

`handler` : | a WockyAuthHandler object
`initial_data` : | a GString location to fill with the initial data, or `NULL` to ignre
`error` : | an optional location for a GError to fill, or `NULL`
Returns : | `TRUE` on success, otherwise `FALSE`

### WockyAuthSuccessFunc ()

    gboolean            (*WockyAuthSuccessFunc)             (WockyAuthHandler *handler,
                                                             GError **error);

Called when a `<success/>` stanza is received during authentication. If no error is returned, then authentication is considered finished. (Typically, an error is only raised if the `<success/>` stanza was received earlier than expected)

`handler` : | a WockyAuthHandler object
`error` : | an optional location for a GError to fill, or `NULL`
Returns : | `TRUE` on success, otherwise `FALSE`

### wocky_auth_handler_free ()

    void                wocky_auth_handler_free             (WockyAuthHandler *handler);

### wocky_auth_handler_get_initial_response ()

    gboolean            wocky_auth_handler_get_initial_response
                                                            (WockyAuthHandler *handler,
                                                             GString **initial_data,
                                                             GError **error);

### wocky_auth_handler_get_mechanism ()

    const gchar *       wocky_auth_handler_get_mechanism    (WockyAuthHandler *handler);

### wocky_auth_handler_handle_auth_data ()

    gboolean            wocky_auth_handler_handle_auth_data (WockyAuthHandler *handler,
                                                             const GString *data,
                                                             GString **response,
                                                             GError **error);

### wocky_auth_handler_handle_success ()

    gboolean            wocky_auth_handler_handle_success   (WockyAuthHandler *handler,
                                                             GError **error);

### wocky_auth_handler_is_plain ()

    gboolean            wocky_auth_handler_is_plain         (WockyAuthHandler *handler);