Started organizing Lasso Reference Manual; documenting LassoProvider.

9 files changed, 342 insertions, 79 deletions

diff --git a/configure.ac b/configure.ac
index bf18fe5c..881f5861 100644
--- a/configure.ac
+++ b/configure.ac
@@ -652,6 +652,7 @@ csharp/lasso-sharp.pc
 docs/Makefile
 docs/lasso-book/Makefile
 docs/reference/Makefile
+docs/reference/version.xml
 java/Makefile
 lasso/Makefile
 lasso/id-ff/Makefile
diff --git a/docs/reference/Makefile.am b/docs/reference/Makefile.am
index 4cc87582..c78cd5ea 100644
--- a/docs/reference/Makefile.am
+++ b/docs/reference/Makefile.am
@@ -1,7 +1,8 @@
 EXTRA_DIST = \
 	lasso-sections.txt \
 	lasso.sgml \
-	lasso.types 
+	lasso.types \
+	version.xml.in
 
 # We need to pre-process original source files
 # because gtkdoc does not understand some C features
@@ -36,7 +37,7 @@ sgml: templates
 		    --tmpl-dir=../tmpl/ \
 		    --source-dir=../$(DOC_SOURCE_DIR)/lasso \
 		    --output-dir=../sgml/
-	cp $(srcdir)/lasso.sgml build/
+	cp $(srcdir)/*.sgml $(srcdir)/version.xml build/
 	(for i in `find sgml -name "*.sgml" -print` ; do \
 	    cat $$i | \
 		sed 's!\(&lt;dsig:\)\([^/]*\)\(\/&gt;\)!<ulink URL=\"http://www.w3.org/TR/xmldsig-core/#sec-\2\">\1\2\3</ulink>!g' | \
diff --git a/docs/reference/lasso-sections.txt b/docs/reference/lasso-sections.txt
index 75c819b1..1e0c8bd7 100644
--- a/docs/reference/lasso-sections.txt
+++ b/docs/reference/lasso-sections.txt
@@ -1,3 +1,34 @@
+<INCLUDE>lasso/lasso.h</INCLUDE>
+
+<SECTION>
+<FILE>provider</FILE>
+<TITLE>LassoProvider</TITLE>
+LassoProvider
+LassoProviderRole
+lassoHttpMethod
+lassoMdProtocolType
+lasso_provider_new
+lasso_provider_get_metadata_one
+lasso_provider_get_metadata_list
+lasso_provider_load_metadata
+lasso_provider_new_from_dump
+lasso_provider_verify_signature
+lasso_provider_get_first_http_method
+lasso_provider_accept_http_method
+lasso_provider_has_protocol_profile
+lasso_provider_get_base64_succint_id
+<SUBSECTION Standard>
+LASSO_PROVIDER
+LASSO_IS_PROVIDER
+LASSO_TYPE_PROVIDER
+lasso_provider_get_type
+LASSO_PROVIDER_CLASS
+LASSO_IS_PROVIDER_CLASS
+LASSO_PROVIDER_GET_CLASS
+</SECTION>
+
+
+
 <SECTION>
 <FILE>lib_assertion</FILE>
 <TITLE>LassoLibAssertion</TITLE>
@@ -1187,49 +1218,6 @@ LASSO_NAME_IDENTIFIER_MAPPING_RESPONSE_GET_CLASS
 </SECTION>
 
 <SECTION>
-<FILE>provider</FILE>
-LASSO_PROVIDER_NODE
-LASSO_PROVIDER_PUBLIC_KEY_NODE
-LASSO_PROVIDER_CA_CERTIFICATE_NODE
-LassoProviderPrivate
-<TITLE>LassoProvider</TITLE>
-LassoProvider
-LassoProviderClass
-lasso_provider_new
-lasso_provider_new_from_metadata_node
-lasso_provider_new_metadata_filename
-lasso_provider_copy
-lasso_provider_destroy
-lasso_provider_dump
-lasso_provider_get_assertionConsumerServiceURL
-lasso_provider_get_authnRequestsSigned
-lasso_provider_get_federationTerminationNotificationProtocolProfile
-lasso_provider_get_federationTerminationServiceReturnURL
-lasso_provider_get_federationTerminationServiceURL
-lasso_provider_get_nameIdentifierMappingProtocolProfile
-lasso_provider_get_providerID
-lasso_provider_get_registerNameIdentifierProtocolProfile
-lasso_provider_get_registerNameIdentifierServiceURL
-lasso_provider_get_registerNameIdentifierServiceReturnURL
-lasso_provider_get_singleSignOnProtocolProfile
-lasso_provider_get_singleSignOnServiceURL
-lasso_provider_get_singleLogoutProtocolProfile
-lasso_provider_get_singleLogoutServiceURL
-lasso_provider_get_singleLogoutServiceReturnURL
-lasso_provider_get_soapEndpoint
-lasso_provider_set_public_key
-lasso_provider_set_ca_certificate
-<SUBSECTION Standard>
-LASSO_PROVIDER
-LASSO_IS_PROVIDER
-LASSO_TYPE_PROVIDER
-lasso_provider_get_type
-LASSO_PROVIDER_CLASS
-LASSO_IS_PROVIDER_CLASS
-LASSO_PROVIDER_GET_CLASS
-</SECTION>
-
-<SECTION>
 <FILE>register_name_identifier_request</FILE>
 <TITLE>LassoRegisterNameIdentifierRequest</TITLE>
 LassoRegisterNameIdentifierRequest
@@ -1407,7 +1395,6 @@ LASSO_LOGOUT_GET_CLASS
 <SECTION>
 <FILE>profile</FILE>
 LassoProfilePrivate
-lassoHttpMethod
 lassoProviderType
 lassoMessageType
 lasso_profile_get_request_type_from_soap_msg
diff --git a/docs/reference/lasso.sgml b/docs/reference/lasso.sgml
index 6e8569ef..042189a2 100644
--- a/docs/reference/lasso.sgml
+++ b/docs/reference/lasso.sgml
@@ -53,15 +53,58 @@
 <!ENTITY LassoProfile SYSTEM "sgml/profile.sgml">
 <!ENTITY LassoServer SYSTEM "sgml/server.sgml">
 <!ENTITY LassoSession SYSTEM "sgml/session.sgml">
-<!ENTITY lasso-tools SYSTEM "sgml/tools.sgml">
+
+<!ENTITY lasso-Liberty-Alliance "liberty-alliance.sgml">
+<!ENTITY version SYSTEM "version.xml">
 ]>
 <book id="index">
   <bookinfo>
-    <title>Lasso API Reference</title>
+    <title>Lasso Reference Manual</title>
+    <releaseinfo>for Lasso &version;</releaseinfo>
   </bookinfo>
 
-  <chapter>
-    <title>Lasso</title>
+  <chapter id="lasso">
+    <title>Lasso Overview</title>
+    <para>
+Lasso is a library which provides all the necessary functions for sites to
+implement Liberty Alliance specifications.
+    </para>
+
+  </chapter>
+
+  
+  <chapter id="architecture">
+    <title>Lasso Architecture</title>
+    &LassoProvider;
+    &LassoServer;
+    &LassoIdentity;
+    &LassoSession;
+  </chapter>
+    
+  <chapter id="idff">
+    <title>Identity Federation Framework</title>
+
+    &LassoProfile;
+    &LassoLogin;
+    &LassoFederation;
+    &LassoLecp;
+    &LassoLogout;
+    &LassoDefederation;
+
+  </chapter>
+
+  <chapter id="idwsf">
+    <title>Identity Web Services Framework</title>
+
+    <para>
+    </para>
+
+  </chapter>
+
+  <chapter id="xml">
+    <title>Schemas</title>
+
+    &LassoNode;
     &LassoLibAssertion;
     &LassoLibAuthnRequest;
     &lasso-LassoLibAuthnRequestEnvelope;
@@ -90,7 +133,6 @@
     &LassoSamlpResponseAbstract;
     &LassoSamlpStatus;
     &LassoSamlpStatusCode;
-    &LassoNode;
     &LassoLibLogoutRequest;
     &LassoLibFederationTerminationNotification;
     &LassoLibLogoutResponse;
@@ -106,16 +148,5 @@
     &lasso-export;
     &lasso-lasso;
     &lasso-version;
-    &LassoFederation;
-    &LassoLecp;
-    &LassoProvider;
-    &LassoDefederation;
-    &LassoIdentity;
-    &LassoLogin;
-    &LassoLogout;
-    &LassoProfile;
-    &LassoServer;
-    &LassoSession;
-    &lasso-tools;
   </chapter>
 </book>
diff --git a/docs/reference/tmpl/provider.sgml b/docs/reference/tmpl/provider.sgml
new file mode 100644
index 00000000..647442ec
--- /dev/null
+++ b/docs/reference/tmpl/provider.sgml
@@ -0,0 +1,170 @@
+<!-- ##### SECTION Title ##### -->
+LassoProvider
+
+<!-- ##### SECTION Short_Description ##### -->
+Representation of a provider
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+
+<!-- ##### STRUCT LassoProvider ##### -->
+<para>
+
+</para>
+
+@ProviderID: 
+@role: 
+@public_key: 
+@ca_cert_chain: 
+
+<!-- ##### ENUM LassoProviderRole ##### -->
+<para>
+
+</para>
+
+@LASSO_PROVIDER_ROLE_NONE: 
+@LASSO_PROVIDER_ROLE_SP: Acts as service provider
+@LASSO_PROVIDER_ROLE_IDP: Acts as identity provider
+
+<!-- ##### ENUM lassoHttpMethod ##### -->
+<para>
+
+</para>
+
+@LASSO_HTTP_METHOD_NONE: 
+@LASSO_HTTP_METHOD_ANY: Any method will do, select one automatically
+@LASSO_HTTP_METHOD_IDP_INITIATED: 
+@LASSO_HTTP_METHOD_GET: HTTP-GET implementation (for image tags in Single Logout)
+@LASSO_HTTP_METHOD_POST: use an HTML form to post message between service and
+  identity providers
+@LASSO_HTTP_METHOD_REDIRECT: use HTTP 302 redirects to post message between
+  service and identity providers
+@LASSO_HTTP_METHOD_SOAP: use a SOAP call to post message between service and
+  identity providers
+
+<!-- ##### ENUM lassoMdProtocolType ##### -->
+<para>
+
+</para>
+
+@LASSO_MD_PROTOCOL_TYPE_FEDERATION_TERMINATION: Federation Termination
+  Notification
+@LASSO_MD_PROTOCOL_TYPE_NAME_IDENTIFIER_MAPPING: Name Identifier Mapping
+@LASSO_MD_PROTOCOL_TYPE_REGISTER_NAME_IDENTIFIER: Name Registration
+@LASSO_MD_PROTOCOL_TYPE_SINGLE_LOGOUT: Single Logout
+@LASSO_MD_PROTOCOL_TYPE_SINGLE_SIGN_ON: Single Sign-On and Federation
+
+<!-- ##### FUNCTION lasso_provider_new ##### -->
+<para>
+
+</para>
+
+@role: 
+@metadata: 
+@public_key: 
+@ca_cert_chain: 
+@Returns: 
+
+
+<!-- ##### FUNCTION lasso_provider_get_metadata_one ##### -->
+<para>
+
+</para>
+
+@provider: 
+@name: 
+@Returns: 
+
+
+<!-- ##### FUNCTION lasso_provider_get_metadata_list ##### -->
+<para>
+
+</para>
+
+@provider: 
+@name: 
+@Returns: 
+
+
+<!-- ##### FUNCTION lasso_provider_load_metadata ##### -->
+<para>
+
+</para>
+
+@provider: 
+@metadata: 
+@Returns: 
+
+
+<!-- ##### FUNCTION lasso_provider_new_from_dump ##### -->
+<para>
+
+</para>
+
+@dump: 
+@Returns: 
+
+
+<!-- ##### FUNCTION lasso_provider_verify_signature ##### -->
+<para>
+
+</para>
+
+@provider: 
+@message: 
+@id_attr_name: 
+@format: 
+@Returns: 
+
+
+<!-- ##### FUNCTION lasso_provider_get_first_http_method ##### -->
+<para>
+
+</para>
+
+@provider: 
+@remote_provider: 
+@protocol_type: 
+@Returns: 
+
+
+<!-- ##### FUNCTION lasso_provider_accept_http_method ##### -->
+<para>
+
+</para>
+
+@provider: 
+@remote_provider: 
+@protocol_type: 
+@http_method: 
+@initiate_profile: 
+@Returns: 
+
+
+<!-- ##### FUNCTION lasso_provider_has_protocol_profile ##### -->
+<para>
+
+</para>
+
+@provider: 
+@protocol_type: 
+@protocol_profile: 
+@Returns: 
+
+
+<!-- ##### FUNCTION lasso_provider_get_base64_succint_id ##### -->
+<para>
+
+</para>
+
+@provider: 
+@Returns: 
+
+
diff --git a/docs/reference/version.xml.in b/docs/reference/version.xml.in
new file mode 100644
index 00000000..d78bda93
--- /dev/null
+++ b/docs/reference/version.xml.in
@@ -0,0 +1 @@
+@VERSION@
diff --git a/lasso.pc.in b/lasso.pc.in
index 7e2347b1..0efed0f2 100644
--- a/lasso.pc.in
+++ b/lasso.pc.in
@@ -7,5 +7,5 @@ Name: lasso
 Version: @VERSION@
 Description: A free implementation of the Liberty Alliance specifications
 Requires: libxml-2.0 libxslt xmlsec1 glib-2.0 gobject-2.0
-Cflags: @LASSO_CORE_CFLAGS@
+Cflags: @LASSO_PUB_CFLAGS@
 Libs: -L${libdir} @LASSO_CORE_LIBS@
diff --git a/lasso/id-ff/provider.c b/lasso/id-ff/provider.c
index 9f6c9290..27abb9d6 100644
--- a/lasso/id-ff/provider.c
+++ b/lasso/id-ff/provider.c
@@ -62,6 +62,16 @@ char *protocol_methods[] = {"", "", "", "", "", "-http", "-soap"};
 /* public methods */
 /*****************************************************************************/
 
+/**
+ * lasso_provider_get_metadata_one:
+ * @provider: a #LassoProvider
+ * @name: the element name
+ *
+ * Extracts the element @name from the provider metadata descriptor.
+ *
+ * Return value: the element value, NULL if the element was not found.  This
+ *      string must be freed by the caller.
+ **/
 gchar*
 lasso_provider_get_metadata_one(LassoProvider *provider, const char *name)
 {
@@ -79,6 +89,18 @@ lasso_provider_get_metadata_one(LassoProvider *provider, const char *name)
 	return NULL;
 }
 
+
+/**
+ * lasso_provider_get_metadata_list:
+ * @provider: a #LassoProvider
+ * @name: the element name
+ *
+ * Extracts zero to many elements from the provider metadata descriptor.
+ *
+ * Return value: a #GList with the elements.  This GList is internally
+ *      allocated and points to internally allocated strings.  It must
+ *      not be freed, modified or stored.
+ **/
 GList*
 lasso_provider_get_metadata_list(LassoProvider *provider, const char *name)
 {
@@ -92,6 +114,17 @@ lasso_provider_get_metadata_list(LassoProvider *provider, const char *name)
 }
 
 
+/**
+ * lasso_provider_get_first_http_method:
+ * @provider: a #LassoProvider
+ * @remote_provider: a #LassoProvider depicting the remote provider
+ * @protocol_type: a Liberty profile
+ *
+ * Looks up and returns a #lassoHttpMethod appropriate for performing the
+ * @protocol_type between @provider and @remote_provider.
+ *
+ * Return value: the #lassoHttpMethod
+ **/
 lassoHttpMethod lasso_provider_get_first_http_method(LassoProvider *provider,
 		LassoProvider *remote_provider, lassoMdProtocolType protocol_type)
 {
@@ -142,6 +175,19 @@ lassoHttpMethod lasso_provider_get_first_http_method(LassoProvider *provider,
 	return LASSO_HTTP_METHOD_NONE;
 }
 
+/**
+ * lasso_provider_accept_http_method:
+ * @provider: a #LassoProvider
+ * @remote_provider: a #LassoProvider depicting the remote provider
+ * @protocol_type: a Liberty profile type
+ * @http_method: an HTTP method
+ * @initiate_profile: whether @provider initiates the profile
+ *
+ * Gets if @http_method is an appropriate method for the @protocol_type profile
+ * between @provider and @remote_provider.
+ *
+ * Return value: %TRUE if it is appropriate
+ **/
 gboolean
 lasso_provider_accept_http_method(LassoProvider *provider, LassoProvider *remote_provider,
 		lassoMdProtocolType protocol_type, lassoHttpMethod http_method,
@@ -176,6 +222,16 @@ lasso_provider_accept_http_method(LassoProvider *provider, LassoProvider *remote
 	return TRUE;
 }
 
+/**
+ * lasso_provider_has_protocol_profile:
+ * @provider: a #LassoProvider
+ * @protocol_type: a Liberty profile type
+ * @protocol_profile: a fully-qualified Liberty profile
+ *
+ * Gets if @provider supports @protocol_profile.
+ *
+ * Return value: %TRUE if it is supported
+ **/
 gboolean
 lasso_provider_has_protocol_profile(LassoProvider *provider,
 		lassoMdProtocolType protocol_type, const char *protocol_profile)
@@ -191,11 +247,14 @@ lasso_provider_has_protocol_profile(LassoProvider *provider,
 }
 
 /**
- * lasso_provider_get_base64_succint_id
- * @provider: #LassoProvider
+ * lasso_provider_get_base64_succint_id:
+ * @provider: a #LassoProvider
  *
  * Computes and returns the base64-encoded provider succint ID.
- */
+ *
+ * Return value: the provider succint ID.  This string must be freed by the
+ *      caller.
+ **/
 char*
 lasso_provider_get_base64_succint_id(LassoProvider *provider)
 {
@@ -487,6 +546,17 @@ lasso_provider_load_metadata(LassoProvider *provider, const gchar *metadata)
 	return TRUE;
 }
 
+/**
+ * lasso_provider_new:
+ * @role: provider role, identity provider or service provider
+ * @metadata: path to metadata file for the provider
+ * @public_key: 
+ * @ca_cert_chain:
+ *
+ * Creates a new #LassoProvider
+ *
+ * Return value: a newly created #LassoProvider
+ */
 LassoProvider*
 lasso_provider_new(LassoProviderRole role, char *metadata, char *public_key, char *ca_cert_chain)
 {
diff --git a/lasso/id-ff/provider.h b/lasso/id-ff/provider.h
index 1884061a..80554a03 100644
--- a/lasso/id-ff/provider.h
+++ b/lasso/id-ff/provider.h
@@ -48,37 +48,39 @@ typedef struct _LassoProviderPrivate LassoProviderPrivate;
 
 typedef enum {
 	LASSO_HTTP_METHOD_NONE = -1,
-	LASSO_HTTP_METHOD_ANY,
-	LASSO_HTTP_METHOD_IDP_INITIATED,
-	LASSO_HTTP_METHOD_GET,
-	LASSO_HTTP_METHOD_POST,
-	LASSO_HTTP_METHOD_REDIRECT,
-	LASSO_HTTP_METHOD_SOAP
+	LASSO_HTTP_METHOD_ANY,           /* any method will do */
+	LASSO_HTTP_METHOD_IDP_INITIATED, /* no method, IdP initiated profile */
+	LASSO_HTTP_METHOD_GET,           /* HTTP GET */
+	LASSO_HTTP_METHOD_POST,          /* Browser POST */
+	LASSO_HTTP_METHOD_REDIRECT,      /* HTTP-Redirect based */
+	LASSO_HTTP_METHOD_SOAP           /* SOAP/HTTP based */
 } lassoHttpMethod;
 
 typedef enum {
-	LASSO_MD_PROTOCOL_TYPE_FEDERATION_TERMINATION = 0,
-	LASSO_MD_PROTOCOL_TYPE_NAME_IDENTIFIER_MAPPING,
-	LASSO_MD_PROTOCOL_TYPE_REGISTER_NAME_IDENTIFIER,
-	LASSO_MD_PROTOCOL_TYPE_SINGLE_LOGOUT,
-	LASSO_MD_PROTOCOL_TYPE_SINGLE_SIGN_ON
+	LASSO_MD_PROTOCOL_TYPE_FEDERATION_TERMINATION = 0, /* Federation Termination Notification */
+	LASSO_MD_PROTOCOL_TYPE_NAME_IDENTIFIER_MAPPING,    /* Name Identifier Mapping */
+	LASSO_MD_PROTOCOL_TYPE_REGISTER_NAME_IDENTIFIER,   /* Name Registration */
+	LASSO_MD_PROTOCOL_TYPE_SINGLE_LOGOUT,              /* Single Logout */
+	LASSO_MD_PROTOCOL_TYPE_SINGLE_SIGN_ON              /* Single Sign-On and Federation */
 } lassoMdProtocolType;
 
 typedef enum {
 	LASSO_PROVIDER_ROLE_NONE = 0,
-	LASSO_PROVIDER_ROLE_SP,
-	LASSO_PROVIDER_ROLE_IDP
+	LASSO_PROVIDER_ROLE_SP,       /* Service Provider */
+	LASSO_PROVIDER_ROLE_IDP       /* Identity Provider */
 } LassoProviderRole;
 
 struct _LassoProvider {
 	LassoNode parent;
 
+	/*< public >*/
 	gchar *ProviderID;
 	LassoProviderRole role;
 
 	gchar *public_key;
 	gchar *ca_cert_chain;
 
+	/*< private >*/
 	LassoProviderPrivate *private_data;
 };