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

[netsurf at semichrome.net]

Author: jmb
Date: Tue Oct  6 13:17:07 2009
New Revision: 9608

URL: http://source.netsurf-browser.org?rev=9608&view=rev
Log:
Something approximating a low-level cache API

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

Added: branches/jmb/new-cache/content/llcache.h
URL: http://source.netsurf-browser.org/branches/jmb/new-cache/content/llcache.h?rev=9608&view=auto
==============================================================================
--- branches/jmb/new-cache/content/llcache.h (added)
+++ branches/jmb/new-cache/content/llcache.h Tue Oct  6 13:17:07 2009
@@ -1,0 +1,129 @@
+/*
+ * Copyright 2009 John-Mark Bell <jmb at netsurf-browser.org>
+ *
+ * This file is part of NetSurf, http://www.netsurf-browser.org/
+ *
+ * NetSurf is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; version 2 of the License.
+ *
+ * NetSurf is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+/** \file
+ * Low-level resource cache (interface)
+ */
+
+#ifndef NETSURF_CONTENT_LLCACHE_H_
+#define NETSURF_CONTENT_LLCACHE_H_
+
+#include <stddef.h>
+#include <stdint.h>
+
+struct form_successful_control;
+
+/** Type of low-level cache object */
+typedef struct llcache_object llcache_object;
+
+/** POST data object for low-level cache requests */
+typedef struct {
+	enum {
+		LLCACHE_POST_URL_ENCODED,
+		LLCACHE_POST_MULTIPART
+	} type;				/**< Type of POST data */
+	union {
+		const char *urlenc;	/**< URL encoded data */
+		/** \todo Need to abstract this away from HTML forms. */
+		struct form_successful_control *multipart; /**< Multipart data */
+	} data;				/**< POST data content */
+} llcache_post_data;
+
+/** Low-level cache event types */
+typedef enum {
+	LLCACHE_EVENT_HAD_HEADERS,	/**< Received all headers */
+	LLCACHE_EVENT_HAD_DATA,		/**< Received some data */
+	LLCACHE_EVENT_DONE		/**< Finished fetching data */
+} llcache_event_type;
+
+/** Low-level cache events */
+typedef struct {
+	llcache_event_type type;	/**< Type of event */
+	struct {
+		const uint8_t *buf;	/**< Buffer of data */
+		size_t len;		/**< Length of buffer, in bytes */
+	} data;				/**< Received data */
+} llcache_event;
+
+/** Client callback for low-level cache events
+ *
+ * \param object  Object for which event is issued
+ * \param event   Event data
+ * \param pw      Pointer to client-specific data
+ */
+/** \todo Need to return an error code */
+typedef void (*llcache_client_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 */
+
+/**
+ * Retrieve a low-level cache object
+ *
+ * \param url      URL of the object to fetch
+ * \param flags    Object retrieval flags
+ * \param referer  Referring URL, or NULL if none
+ * \param post     POST data, or NULL for a GET request
+ * \param cb       Client callback for events
+ * \param pw       Pointer to client-specific data
+ * \return Pointer to cache object, or NULL on failure
+ *
+ * \todo Would it be better to have an error code here?
+ */
+llcache_object *llcache_object_retrieve(const char *url, uint32_t flags,
+		const char *referer, llcache_post_data *post,
+		llcache_client_callback cb, void *pw);
+
+/**
+ * Remove a callback from a low-level cache object
+ *
+ * \param object  Object to remove callback from
+ * \param cb      Callback to remove
+ * \param pw      Pointer to client-specific data
+ * 
+ * \todo Return an error code?
+ */
+void llcache_object_remove_callback(llcache_object *object,
+		llcache_client_callback cb, void *pw);
+
+/**
+ * Retrieve the post-redirect URL of a low-level cache object
+ *
+ * \param object  Object to retrieve URL from
+ * \return Post-redirect URL of cache object
+ */
+const char *llcache_object_get_url(llcache_object *object);
+
+/**
+ * Retrieve a header value associated with a low-level cache object
+ *
+ * \param object  Object to retrieve header from
+ * \param key     Header name
+ * \return Header value, or NULL if header does not exist
+ *
+ * \todo Make the key an enumeration, to avoid needless string comparisons
+ * \todo Forcing the client to parse the header value seems wrong. 
+ *       Better would be to return the actual value part and an array of 
+ *       key-value pairs for any additional parameters.
+ */
+const char *llcache_object_get_header(llcache_object *object, const char *key);
+
+#endif