diff options
| -rw-r--r-- | wocky/wocky-auth-handler.c | 59 | ||||
| -rw-r--r-- | wocky/wocky-auth-handler.h | 19 |
2 files changed, 69 insertions, 9 deletions
diff --git a/wocky/wocky-auth-handler.c b/wocky/wocky-auth-handler.c index 37e0b38..d1d3daf 100644 --- a/wocky/wocky-auth-handler.c +++ b/wocky/wocky-auth-handler.c @@ -32,18 +32,50 @@ wocky_auth_handler_get_type (void) return g_define_type_id__volatile; } +/** + * wocky_auth_handler_get_mechanism: + * @handler: a handler for a SASL mechanism. + * + * Returns the name of the SASL mechanism @handler implements. + * + * Returns: the name of the SASL mechanism @handler implements. + */ const gchar * wocky_auth_handler_get_mechanism (WockyAuthHandler *handler) { return WOCKY_AUTH_HANDLER_GET_IFACE (handler)->mechanism; } +/** + * wocky_auth_handler_is_plain: + * @handler: a handler for a SASL mechanism. + * + * Checks whether @handler sends secrets in plaintext. This may be used to + * decide whether to use @handler on an insecure XMPP connection. + * + * Returns: %TRUE if @handler sends secrets in plaintext. + */ gboolean wocky_auth_handler_is_plain (WockyAuthHandler *handler) { return WOCKY_AUTH_HANDLER_GET_IFACE (handler)->plain; } +/** + * wocky_auth_handler_get_initial_response: + * @handler: a handler for a SASL mechanism + * @initial_data: (out) (transfer full): initial data to send to the server, if + * any + * @error: an optional location for a #GError to fill, or %NULL + * + * Called when authentication begins to fetch the initial data to send to the + * server in the <code><auth/></code> stanza. + * + * If this function returns %TRUE, @initial_data will be non-%NULL if @handler + * provides an initial response, and %NULL otherwise. + * + * Returns: %TRUE on success; %FALSE otherwise. + */ gboolean wocky_auth_handler_get_initial_response (WockyAuthHandler *handler, GString **initial_data, @@ -61,6 +93,20 @@ wocky_auth_handler_get_initial_response (WockyAuthHandler *handler, return func (handler, initial_data, error); } +/** + * wocky_auth_handler_handle_auth_data: + * @handler: a #WockyAuthHandler object + * @data: the challenge string + * @response: (out) (transfer full): a location to fill with a challenge + * response in a #GString + * @error: an optional location for a #GError to fill, or %NULL + * + * Asks @handler to respond to a <code><challenge/></code> stanza or a + * <code><success/></code> with data. On success, @handler will put + * response data into @response, Base64-encoding it if appropriate. + * + * Returns: %TRUE on success, otherwise %FALSE + */ gboolean wocky_auth_handler_handle_auth_data ( WockyAuthHandler *handler, @@ -85,6 +131,19 @@ wocky_auth_handler_handle_auth_data ( return func (handler, data, response, error); } +/** + * wocky_auth_handler_handle_success: + * @handler: a #WockyAuthHandler object + * @error: an optional location for a #GError to fill, or %NULL + * + * Called when a <code><success/></code> stanza is received + * during authentication. If no error is returned, then authentication + * is considered finished. (Typically, an error is only raised if the + * <code><success/></code> stanza was received earlier than + * expected) + * + * Returns: %TRUE on success, otherwise %FALSE + */ gboolean wocky_auth_handler_handle_success ( WockyAuthHandler *handler, diff --git a/wocky/wocky-auth-handler.h b/wocky/wocky-auth-handler.h index 448558c..dfef4f9 100644 --- a/wocky/wocky-auth-handler.h +++ b/wocky/wocky-auth-handler.h @@ -21,7 +21,7 @@ typedef struct _WockyAuthHandler WockyAuthHandler; /** * WockyAuthInitialResponseFunc: * @handler: a #WockyAuthHandler object - * @initial_data: a #GString location to fill with the initial data, or %NULL to ignre + * @initial_data: (out): a #GString location to fill with the initial data * @error: an optional location for a #GError to fill, or %NULL * * Called when authentication begins, if the mechanism allows a @@ -29,10 +29,10 @@ typedef struct _WockyAuthHandler WockyAuthHandler; * XMPP, corresponds to sending the <code><auth/></code> 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 + * The function should return %TRUE on success, and optionally set the + * @initial_data to a string if there is + * initial data to send. On error, it should return %FALSE and set + * @error. * * Returns: %TRUE on success, otherwise %FALSE **/ @@ -43,14 +43,15 @@ typedef gboolean (*WockyAuthInitialResponseFunc) (WockyAuthHandler *handler, /** * WockyAuthChallengeFunc: * @handler: a #WockyAuthHandler object - * @data: the challange string - * @response: a location to fill with a challenge response in a #GString + * @data: the challenge string + * @response: (out) (transfer full): a location to fill with a challenge + * response in a #GString * @error: an optional location for a #GError to fill, or %NULL * - * Called During authentication, when a + * Called during authentication when a * <code><challenge/></code> stanza or a * <code><success/></code> with data is received. The handler - * should put response data in response (allocate using g_malloc()) if + * should put response data into @response if * appropriate. The handler is responsible for Base64-encoding * responses if appropriate. * |