documented name_identifier_mapping.c; removed its unused dump functions; fixed

a few docstrings

4 files changed, 119 insertions, 64 deletions

diff --git a/lasso/id-ff/defederation.c b/lasso/id-ff/defederation.c
index d1aadc52..926806fb 100644
--- a/lasso/id-ff/defederation.c
+++ b/lasso/id-ff/defederation.c
@@ -34,24 +34,28 @@
 
 /**
  * lasso_defederation_build_notification_msg:
- * @defederation: the federation termination object
+ * @defederation: a #LassoDefederation
  * 
- * This method builds the federation termination notification message.
+ * Builds the federation termination notification message.
  * 
  * It gets the federation termination notification protocol profile and:
- * 
- * - if it is a SOAP method, then it builds the federation termination
+ * <itemizedlist>
+ * <listitem><para>
+ *   if it is a SOAP method, then it builds the federation termination
  *   notification SOAP message, optionaly signs the notification node, set the
  *   msg_body attribute, gets the SoapEndpoint url and set the msg_url
  *   attribute of the federation termination object.
- *
- * - if it is a HTTP-Redirect method, then it builds the federation termination
+ * </para></listitem>
+ * <listitem><para>
+ *   if it is a HTTP-Redirect method, then it builds the federation termination
  *   notification QUERY message (optionaly signs the notification message),
  *   builds the federation termination notification url with federation
  *   termination service url, set the msg_url attribute of the federation
  *   termination object, set the msg_body to NULL
+ * </para></listitem>
+ * </itemizedlist>
  * 
- * Return value: O of OK else < 0
+ * Return value: 0 on success; or a negative value otherwise.
  **/
 gint
 lasso_defederation_build_notification_msg(LassoDefederation *defederation)
@@ -116,10 +120,9 @@ lasso_defederation_build_notification_msg(LassoDefederation *defederation)
 
 /**
  * lasso_defederation_destroy:
- * @defederation: the federation termination object
+ * @defederation: a #LassoDefederation
  * 
- * This method destroys the federation termination object
- *
+ * Destroys a #LassoDefederation object.
  **/
 void
 lasso_defederation_destroy(LassoDefederation *defederation)
@@ -244,21 +247,14 @@ lasso_defederation_init_notification(LassoDefederation *defederation, gchar *rem
  * @defederation: the federation termination object
  * @notification_msg: the federation termination notification message
  * 
- * Process the federation termination notification.
- * 
- * - if it is a SOAP notification method then it builds the federation
- *   termination object from the SOAP message and optionaly verify the
- *   signature.
- *
- * - if it is a HTTP-Redirect notification method then it builds the
- *   federation termination notication object from the QUERY message and
- *   optionaly verify the signature.
+ * Processes a lib:FederationTerminationNotification message.  Rebuilds a
+ * request object from the message and optionally verifies its signature.
  * 
  * Set the msg_nameIdentifier attribute with the NameIdentifier content of the
  * notification object and optionaly set the msg_relayState attribute with the
- * RelayState content of the notification object
+ * RelayState content of the notification object.
  *
- * Return value: 0 on success or a negative value otherwise.
+ * Return value: 0 on success; or a negative value otherwise.
  **/
 gint
 lasso_defederation_process_notification_msg(LassoDefederation *defederation, char *request_msg)
@@ -311,16 +307,12 @@ lasso_defederation_process_notification_msg(LassoDefederation *defederation, cha
 
 /**
  * lasso_defederation_validate_notification:
- * @defederation: the federation termination object
+ * @defederation: a #LassoDefederation
  * 
- * Validate the federation termination notification :
- * -  verifies the ProviderID
- * -  if HTTP-Redirect method, set msg_url with the federation termination
- *    service return url
- * -  verifies the federation
- * -  verifies the authentication
+ * Checks notification with regards to message status and principal
+ * federations; update them accordingly.
  * 
- * Return value: O if OK else < 0
+ * Return value: 0 on success; or a negative value otherwise.
  **/
 gint
 lasso_defederation_validate_notification(LassoDefederation *defederation)
@@ -434,22 +426,12 @@ lasso_defederation_get_type()
 
 /**
  * lasso_defederation_new:
- * @server: the server object of the provider
+ * @server: the #LassoServer
  * 
- * This function build a new federation termination object to build
- * a notification message or to process a notification.
- *
- * If building a federation termination notification message then call :
- *    lasso_defederation_init_notification()
- *    lasso_defederation_build_notification_msg()
- * and get msg_url or msg_body.
+ * Creates a new #LassoDefederation.
  *
- * If processing a federation termination notification message then call :
- *   lasso_defederation_process_notification_msg()
- *   lasso_defederation_validate_notification()
- * and process the returned code.
- *
- * Return value: a new instance of federation termination object or NULL
+ * Return value: a newly created #LassoDefederation object; or NULL if an error
+ *     occured
  **/
 LassoDefederation*
 lasso_defederation_new(LassoServer *server)
@@ -463,4 +445,3 @@ lasso_defederation_new(LassoServer *server)
 
 	return defederation;
 }
-
diff --git a/lasso/id-ff/name_identifier_mapping.c b/lasso/id-ff/name_identifier_mapping.c
index 963db112..4973d3ee 100644
--- a/lasso/id-ff/name_identifier_mapping.c
+++ b/lasso/id-ff/name_identifier_mapping.c
@@ -32,6 +32,26 @@
 /* public methods                                                            */
 /*****************************************************************************/
 
+/**
+ * lasso_name_identifier_mapping_build_request_msg:
+ * @mapping: a #LassoNameIdentifierMapping
+ * 
+ * Builds a name identifier mapping request message.
+ * 
+ * <itemizedlist>
+ * <listitem><para>
+ *   If it is a SOAP method, then it builds the request as a SOAP message,
+ *   optionally signs his node, sets @msg_body with that message and sets
+ *   @msg_url with the SOAP Endpoint URL
+ * </para></listitem>
+ * <listitem><para>
+ *   If it is a HTTP-Redirect method, then it builds the request as a query
+ *   string message, optionally signs it and sets @msg_url to that URL.
+ * </para></listitem>
+ * </itemizedlist>
+ * 
+ * Return value: 0 on success; or a negative value otherwise.
+ **/
 gint
 lasso_name_identifier_mapping_build_request_msg(LassoNameIdentifierMapping *mapping)
 {
@@ -70,6 +90,31 @@ lasso_name_identifier_mapping_build_request_msg(LassoNameIdentifierMapping *mapp
 	return 0;
 }
 
+
+/**
+ * lasso_name_identifier_mapping_build_response_msg:
+ * @mapping: a #LassoNameIdentifierMapping
+ * 
+ * Builds a name identifier mapping response message.
+ *
+ * <itemizedlist>
+ * <listitem><para>
+ *   If it is a SOAP method, then it builds the response as a SOAP message,
+ *   optionally signs his node, sets @msg_body with that message and sets
+ *   @msg_url with the register name identifier service return URL.
+ * </para></listitem>
+ * <listitem><para>
+ *   If it is a HTTP-Redirect method, then it builds the response as a query
+ *   string message, optionally signs it and sets @msg_url to that URL.
+ * </para></listitem>
+ * </itemizedlist>
+ *
+ * If private key and certificate are set in server object it will also signs
+ * the message (either with X509 if SOAP or with a simple signature for query
+ * strings).
+ * 
+ * Return value: 0 on success; or a negative value otherwise.
+ **/
 gint
 lasso_name_identifier_mapping_build_response_msg(LassoNameIdentifierMapping *mapping)
 {
@@ -119,6 +164,17 @@ lasso_name_identifier_mapping_destroy(LassoNameIdentifierMapping *mapping)
 	lasso_node_destroy(LASSO_NODE(mapping));
 }
 
+
+/**
+ * lasso_name_identifier_mapping_init_request:
+ * @mapping: a #LassoNameIdentifierMapping
+ * @targetNamespace: the request targetNamespace
+ * @remote_providerID: the providerID of the identity provider.
+ *
+ * Initializes a new lib:NameIdentifierMappingRequest request.
+ * 
+ * Return value: 0 on success; or a negative value otherwise.
+ **/
 gint
 lasso_name_identifier_mapping_init_request(LassoNameIdentifierMapping *mapping,
 		char *targetNamespace, char *remote_providerID)
@@ -194,6 +250,17 @@ lasso_name_identifier_mapping_init_request(LassoNameIdentifierMapping *mapping,
 	return 0;
 }
 
+
+/**
+ * lasso_name_identifier_mapping_process_request_msg:
+ * @mapping: a #LassoNameIdentifierMapping
+ * @request_msg: the name identifier mapping request message
+ * 
+ * Processes a lib:NameIdentifierMappingRequest message.  Rebuilds a request
+ * object from the message and optionally verifies its signature.
+ *
+ * Return value: 0 on success; or a negative value otherwise.
+ **/
 gint
 lasso_name_identifier_mapping_process_request_msg(LassoNameIdentifierMapping *mapping,
 		char *request_msg)
@@ -244,6 +311,19 @@ lasso_name_identifier_mapping_process_request_msg(LassoNameIdentifierMapping *ma
 	return profile->signature_status;
 }
 
+
+/**
+ * lasso_name_identifier_mapping_process_response_msg:
+ * @mapping: a #LassoNameIdentifierMapping
+ * @response_msg: the name identifier mapping response message
+ * 
+ * Processes a lib:NameIdentifierMappingResponse message.  Rebuilds a response
+ * object from the message and optionally verifies its signature.
+ *
+ * If the response depicts Success it will also sets @targetNameIdentifier.
+ *
+ * Return value: 0 on success; or a negative value otherwise.
+ **/
 gint
 lasso_name_identifier_mapping_process_response_msg(LassoNameIdentifierMapping *mapping,
 		char *response_msg)
@@ -290,6 +370,17 @@ lasso_name_identifier_mapping_process_response_msg(LassoNameIdentifierMapping *m
 	return rc;
 }
 
+
+/**
+ * lasso_name_identifier_mapping_validate_request:
+ * @mapping: a #LassoNameIdentifierMapping
+ *
+ * Checks profile request with regards to message status and principal
+ * federations, update them accordingly and prepares a 
+ * lib:NameIdentifierMappingResponse accordingly.
+ * 
+ * Return value: 0 on success; or a negative value otherwise.
+ **/
 gint
 lasso_name_identifier_mapping_validate_request(LassoNameIdentifierMapping *mapping)
 {
@@ -406,7 +497,6 @@ lasso_name_identifier_mapping_validate_request(LassoNameIdentifierMapping *mappi
 }
 
 
-
 /*****************************************************************************/
 /* instance and class init functions                                         */
 /*****************************************************************************/
@@ -466,17 +556,3 @@ lasso_name_identifier_mapping_new(LassoServer *server)
 
 	return mapping;
 }
-
-LassoNameIdentifierMapping*
-lasso_name_identifier_mapping_new_from_dump(LassoServer *server, const char *dump)
-{
-	g_assert_not_reached();
-	return NULL;
-}
-
-char*
-lasso_name_identifier_mapping_dump(LassoNameIdentifierMapping *mapping)
-{
-	g_assert_not_reached();
-	return lasso_node_dump(LASSO_NODE(mapping));
-}
diff --git a/lasso/id-ff/name_identifier_mapping.h b/lasso/id-ff/name_identifier_mapping.h
index eb8a64d8..611fc6ef 100644
--- a/lasso/id-ff/name_identifier_mapping.h
+++ b/lasso/id-ff/name_identifier_mapping.h
@@ -70,9 +70,6 @@ struct _LassoNameIdentifierMappingClass {
 LASSO_EXPORT GType lasso_name_identifier_mapping_get_type(void);
 
 LASSO_EXPORT LassoNameIdentifierMapping* lasso_name_identifier_mapping_new(LassoServer *server);
-LASSO_EXPORT gchar* lasso_name_identifier_mapping_dump(LassoNameIdentifierMapping*);
-LASSO_EXPORT LassoNameIdentifierMapping* lasso_name_identifier_mapping_new_from_dump(
-		LassoServer *server, const char *dump);
 
 LASSO_EXPORT gint lasso_name_identifier_mapping_build_request_msg(
 		LassoNameIdentifierMapping *mapping);
diff --git a/lasso/id-ff/name_registration.c b/lasso/id-ff/name_registration.c
index 144f2e42..35cc47bf 100644
--- a/lasso/id-ff/name_registration.c
+++ b/lasso/id-ff/name_registration.c
@@ -206,7 +206,7 @@ lasso_name_registration_destroy(LassoNameRegistration *name_registration)
  * @http_method: if set, then it get the protocol profile in metadata
  *     corresponding of this HTTP request method.
  *
- * Initializes a new lib:RegisterNameIdentifier request.
+ * Initializes a new lib:RegisterNameIdentifierRequest request.
  * 
  * Return value: 0 on success; or a negative value otherwise.
  **/
@@ -518,7 +518,8 @@ lasso_name_registration_process_response_msg(LassoNameRegistration *name_registr
  * lasso_name_registration_validate_request:
  * @name_registration: a #LassoNameRegistration
  *
- * Checks profile request with regards to principal federations and prepares a
+ * Checks profile request with regards to message status and principal
+ * federations, update them accordingly and prepares a 
  * lib:RegisterNameIdentifierResponse accordingly.
  * 
  * Return value: 0 on success; or a negative value otherwise.