summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorWill Thompson <will@willthompson.co.uk>2012-01-31 14:39:56 (GMT)
committerWill Thompson <will.thompson@collabora.co.uk>2012-02-06 13:26:16 (GMT)
commitfe9b08f15f346676c67c798f6f626839a0f5f71b (patch)
tree59ccb5f7da77ccacc5368a2b25ead03728de9ac8
parentfcf4ab9b107a3a3d25a129dc86fd2edcd5188a38 (diff)
downloadwocky-fe9b08f15f346676c67c798f6f626839a0f5f71b.tar.gz
wocky-fe9b08f15f346676c67c798f6f626839a0f5f71b.tar.xz
AuthHandler: add a bit of documentation.
-rw-r--r--wocky/wocky-auth-handler.c59
-rw-r--r--wocky/wocky-auth-handler.h19
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>&lt;auth/&gt;</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>&lt;challenge/&gt;</code> stanza or a
+ * <code>&lt;success/&gt;</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>&lt;success/&gt;</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>&lt;success/&gt;</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>&lt;auth/&gt;</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>&lt;challenge/&gt;</code> stanza or a
* <code>&lt;success/&gt;</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.
*