summaryrefslogtreecommitdiff
path: root/content/hlcache.h
blob: 9f03052fa3e31f794b174c9d096559fa5207ce8a (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
/*
 * 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
 * High-level resource cache (interface)
 */

#ifndef NETSURF_CONTENT_HLCACHE_H_
#define NETSURF_CONTENT_HLCACHE_H_

#include "content/content.h"
#include "content/llcache.h"
#include "utils/errors.h"

/** High-level cache handle */
typedef struct hlcache_handle hlcache_handle;

/** Context for retrieving a child object */
typedef struct hlcache_child_context {
 	const char *charset;		/**< Charset of parent */
 	bool quirks;			/**< Whether parent is quirky */
} hlcache_child_context;

/** High-level cache event */
typedef struct {
	content_msg type;		/**< Event type */
	union content_msg_data data;	/**< Event data */
} hlcache_event;

/**
 * Client callback for high-level cache events
 *
 * \param handle  Handle to object generating event
 * \param event   Event data
 * \param pw      Pointer to client-specific data
 * \return NSERROR_OK on success, appropriate error otherwise.
 */
typedef nserror (*hlcache_handle_callback)(hlcache_handle *handle,
		const hlcache_event *event, void *pw); 

/** Flags for high-level cache object retrieval */
enum hlcache_retrieve_flag {
	/* Note: low-level cache retrieval flags occupy the bottom 16 bits of 
	 * the flags word. High-level cache flags occupy the top 16 bits. 
	 * To avoid confusion, high-level flags are allocated from bit 31 down. 
	 */
	/** It's permitted to convert this request into a download */
	HLCACHE_RETRIEVE_MAY_DOWNLOAD = (1 << 31)
};

/**
 * Retrieve a high-level cache handle for an object
 *
 * \param url             URL of the object to retrieve handle for
 * \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              Callback to handle object events
 * \param pw              Pointer to client-specific data for callback
 * \param child           Child retrieval context, or NULL for top-level content
 * \param accepted_types  Array of acceptable content types, or NULL for any
 * \param result          Pointer to location to recieve cache handle
 * \return NSERROR_OK on success, appropriate error otherwise
 *
 * Child contents are keyed on the tuple < URL, quirks >.
 * The quirks field is ignored for child contents whose behaviour is not
 * affected by quirks mode.
 *
 * The \a accepted_types array must be terminated with CONTENT_UNKNOWN
 *
 * \todo The above rules should be encoded in the handler_map.
 *
 * \todo Is there any way to sensibly reduce the number of parameters here?
 */
nserror hlcache_handle_retrieve(const char *url, uint32_t flags,
		const char *referer, llcache_post_data *post,
		hlcache_handle_callback cb, void *pw,
		hlcache_child_context *child, 
		const content_type *accepted_types, hlcache_handle **result);

/**
 * Release a high-level cache handle
 *
 * \param handle  Handle to release
 * \return NSERROR_OK on success, appropriate error otherwise
 */
nserror hlcache_handle_release(hlcache_handle *handle);

/**
 * Abort a high-level cache fetch
 *
 * \param handle  Handle to abort
 * \return NSERROR_OK on success, appropriate error otherwise
 */
nserror hlcache_handle_abort(hlcache_handle *handle);

/**
 * Retrieve a content object from a cache handle
 *
 * \param handle  Cache handle to dereference
 * \return Pointer to content object, or NULL if there is none
 *
 * \todo This may not be correct. Ideally, the client should never need to 
 * directly access a content object. It may, therefore, be better to provide a 
 * bunch of veneers here that take a hlcache_handle and invoke the 
 * corresponding content_ API. If there's no content object associated with the
 * hlcache_handle (e.g. because the source data is still being fetched, so it 
 * doesn't exist yet), then these veneers would behave as a NOP. The important 
 * thing being that the client need not care about this possibility and can 
 * just call the functions with impugnity.
 */
struct content *hlcache_handle_get_content(const hlcache_handle *handle);

#endif