r9610 jmb - /branches/jmb/new-cache/content/llcache.h

[netsurf at semichrome.net]

Author: jmb
Date: Wed Oct  7 11:43:49 2009
New Revision: 9610

URL: http://source.netsurf-browser.org?rev=9610&view=rev
Log:
When the low-level cache is informed that authentication details are required, or detects a redirect that requires user permission to follow, or is informed that the TLS certificate chain cannot be verified, it needs some mechanism to ask the user.
These kinds of queries are orthogonal to where the resource being fetched will be used. Therefore, it seems crazy to force users of a resource to have to care about these resource-fetching details.
Instead, what we do is to handle these kinds of out-of-band queries in a central place by registering a query handler with the low-level cache. This handler is called whenever such a fetch-related query is generated. Immediately before calling this handler, the low-level cache will mark the object being fetched as pending a user response. The handler (which is provided by the frontend code) will open a non-modal dialogue requesting the relevant permissions from the user. Once the user has dealt with the request, the frontend calls the provided response handler to inform the low-level cache whether it should continue with the fetching process or abort.

Modified:
    branches/jmb/new-cache/content/llcache.h

Modified: branches/jmb/new-cache/content/llcache.h
URL: http://source.netsurf-browser.org/branches/jmb/new-cache/content/llcache.h?rev=9610&r1=9609&r2=9610&view=diff
==============================================================================
--- branches/jmb/new-cache/content/llcache.h (original)
+++ branches/jmb/new-cache/content/llcache.h Wed Oct  7 11:43:49 2009
@@ -23,11 +23,13 @@
 #ifndef NETSURF_CONTENT_LLCACHE_H_
 #define NETSURF_CONTENT_LLCACHE_H_
 
+#include <stdbool.h>
 #include <stddef.h>
 #include <stdint.h>
 
 #include "utils/errors.h"
 
+struct ssl_cert_info;
 struct form_successful_control;
 
 /** Type of low-level cache object */
@@ -70,13 +72,76 @@
  * \param pw      Pointer to client-specific data
  * \return NSERROR_OK on success, appropriate error otherwise.
  */
-typedef nserror (*llcache_client_callback)(llcache_object *object, 
+typedef nserror (*llcache_object_callback)(llcache_object *object, 
 		llcache_event *event, void *pw);
 
 /** Flags for low-level cache object retrieval */
 #define LLCACHE_RETRIEVE_FORCE_FETCH (1 << 0) /* Force a new fetch */
 #define LLCACHE_RETRIEVE_VERIFIABLE  (1 << 1) /* Requested URL was verified */
 #define LLCACHE_RETRIEVE_SNIFF_TYPE  (1 << 2) /* Permit content-type sniffing */
+
+/** Low-level cache query types */
+typedef enum {
+	LLCACHE_QUERY_AUTH,		/**< Need authentication details */
+	LLCACHE_QUERY_REDIRECT,		/**< Need permission to redirect */
+	LLCACHE_QUERY_SSL		/**< SSL chain needs inspection */
+} llcache_query_type;
+
+/** Low-level cache query */
+typedef struct {
+	llcache_query_type type;	/**< Type of query */
+
+	const char *url;		/**< URL being fetched */
+
+	union {
+		struct {
+			const char *realm;	/**< Authentication realm */
+		} auth;
+
+		struct {
+			const char *target;	/**< Redirect target */
+		} redirect;
+
+		struct {
+			const struct ssl_cert_info *certs;
+			size_t num;		/**< Number of certs in chain */
+		} ssl;
+	} data;
+} llcache_query;
+
+/**
+ * Response handler for fetch-related queries
+ *
+ * \param proceed  Whether to proceed with the fetch or not
+ * \param cbpw     Opaque value provided to llcache_query_callback
+ * \return NSERROR_OK on success, appropriate error otherwise
+ */
+typedef nserror (*llcache_query_response)(bool proceed, void *cbpw);
+
+/**
+ * Callback to handle fetch-related queries
+ *
+ * \param query  Object containing details of query
+ * \param pw     Pointer to callback-specific data
+ * \param cb     Callback that client should call once query is satisfied
+ * \param cbpw   Opaque value to pass into \a cb
+ * \return NSERROR_OK on success, appropriate error otherwise
+ *
+ * \note This callback should return immediately. Once a suitable answer to 
+ *       the query has been obtained, the provided response callback should be 
+ *       called. This is intended to be an entirely asynchronous process.
+ */
+typedef nserror (*llcache_query_callback)(llcache_query *query, void *pw,
+		llcache_query_response cb, void *cbpw);
+
+/**
+ * Initialise the low-level cache
+ *
+ * \param cb  Query handler
+ * \param pw  Pointer to query handler data
+ * \return NSERROR_OK on success, appropriate error otherwise.
+ */
+nserror llcache_initialise(llcache_query_callback cb, void *pw);
 
 /**
  * Retrieve a low-level cache object
@@ -92,7 +157,7 @@
  */
 nserror llcache_object_retrieve(const char *url, uint32_t flags,
 		const char *referer, llcache_post_data *post,
-		llcache_client_callback cb, void *pw,
+		llcache_object_callback cb, void *pw,
 		llcache_object **result);
 
 /**
@@ -104,7 +169,7 @@
  * \return NSERROR_OK on success, appropriate error otherwise
  */
 nserror llcache_object_remove_callback(llcache_object *object,
-		llcache_client_callback cb, void *pw);
+		llcache_object_callback cb, void *pw);
 
 /**
  * Retrieve the post-redirect URL of a low-level cache object