From 270ef59a98d34fef418fb6cd27e46f3edc912948 Mon Sep 17 00:00:00 2001 From: Daniel Silverstone Date: Sun, 28 Mar 2010 12:56:39 +0000 Subject: Merge jmb/new-cache; r=dsilvers,rs=vince svn path=/trunk/netsurf/; revision=10180 --- content/llcache.h | 238 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 238 insertions(+) create mode 100644 content/llcache.h (limited to 'content/llcache.h') 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 + * + * 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 . + */ + +/** \file + * Low-level resource cache (interface) + */ + +#ifndef NETSURF_CONTENT_LLCACHE_H_ +#define NETSURF_CONTENT_LLCACHE_H_ + +#include +#include +#include + +#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 -- cgit v1.2.3