summaryrefslogtreecommitdiff
path: root/content/llcache.h
diff options
context:
space:
mode:
Diffstat (limited to 'content/llcache.h')
-rw-r--r--content/llcache.h238
1 files changed, 238 insertions, 0 deletions
diff --git a/content/llcache.h b/content/llcache.h
new file mode 100644
index 000000000..b2c856f3b
--- /dev/null
+++ b/content/llcache.h
@@ -0,0 +1,238 @@
+/*
+ * Copyright 2009 John-Mark Bell <jmb@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 <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+
+#include "utils/errors.h"
+
+struct ssl_cert_info;
+struct fetch_multipart_data;
+
+/** Handle for low-level cache object */
+typedef struct llcache_handle llcache_handle;
+
+/** POST data object for low-level cache requests */
+typedef struct {
+ enum {
+ LLCACHE_POST_URL_ENCODED,
+ LLCACHE_POST_MULTIPART
+ } type; /**< Type of POST data */
+ union {
+ char *urlenc; /**< URL encoded data */
+ struct fetch_multipart_data *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_ERROR, /**< An error occurred during fetch */
+ LLCACHE_EVENT_PROGRESS, /**< Fetch progress update */
+} llcache_event_type;
+
+/** Low-level cache events */
+typedef struct {
+ llcache_event_type type; /**< Type of event */
+ union {
+ struct {
+ const uint8_t *buf; /**< Buffer of data */
+ size_t len; /**< Length of buffer, in bytes */
+ } data; /**< Received data */
+ const char *msg; /**< Error or progress message */
+ } data; /**< Event data */
+} llcache_event;
+
+/**
+ * Client callback for low-level cache events
+ *
+ * \param handle Handle for which event is issued
+ * \param event Event data
+ * \param pw Pointer to client-specific data
+ * \return NSERROR_OK on success, appropriate error otherwise.
+ */
+typedef nserror (*llcache_handle_callback)(llcache_handle *handle,
+ const 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 */
+#define LLCACHE_RETRIEVE_NO_ERROR_PAGES (1 << 3) /* No error pages */
+
+/** 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)(const 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);
+
+/**
+ * Poll the low-level cache
+ *
+ * \return NSERROR_OK on success, appropriate error otherwise.
+ */
+nserror llcache_poll(void);
+
+/**
+ * Retrieve a handle for 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
+ * \param result Pointer to location to recieve cache handle
+ * \return NSERROR_OK on success, appropriate error otherwise
+ */
+nserror llcache_handle_retrieve(const char *url, uint32_t flags,
+ const char *referer, const llcache_post_data *post,
+ llcache_handle_callback cb, void *pw,
+ llcache_handle **result);
+
+/**
+ * Change the callback associated with a low-level cache handle
+ *
+ * \param handle Handle to change callback of
+ * \param cb New callback
+ * \param pw Client data for new callback
+ * \return NSERROR_OK on success, appropriate error otherwise
+ */
+nserror llcache_handle_change_callback(llcache_handle *handle,
+ llcache_handle_callback cb, void *pw);
+
+/**
+ * Release a low-level cache handle
+ *
+ * \param handle Handle to release
+ * \return NSERROR_OK on success, appropriate error otherwise
+ */
+nserror llcache_handle_release(llcache_handle *handle);
+
+/**
+ * Retrieve the post-redirect URL of a low-level cache object
+ *
+ * \param handle Handle to retrieve URL from
+ * \return Post-redirect URL of cache object
+ */
+const char *llcache_handle_get_url(const llcache_handle *handle);
+
+/**
+ * Retrieve source data of a low-level cache object
+ *
+ * \param handle Handle to retrieve source data from
+ * \param size Pointer to location to receive byte length of data
+ * \return Pointer to source data
+ */
+const uint8_t *llcache_handle_get_source_data(const llcache_handle *handle,
+ size_t *size);
+
+/**
+ * Retrieve a header value associated with a low-level cache object
+ *
+ * \param handle Handle 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_handle_get_header(const llcache_handle *handle,
+ const char *key);
+
+/**
+ * Determine if the same underlying object is referenced by the given handles
+ *
+ * \param a First handle
+ * \param b Second handle
+ * \return True if handles reference the same object, false otherwise
+ */
+bool llcache_handle_references_same_object(const llcache_handle *a,
+ const llcache_handle *b);
+
+#endif