NetSurf
fetch.h
Go to the documentation of this file.
1/*
2 * Copyright 2003 James Bursa <bursa@users.sourceforge.net>
3 *
4 * This file is part of NetSurf, http://www.netsurf-browser.org/
5 *
6 * NetSurf is free software; you can redistribute it and/or modify
7 * it under the terms of the GNU General Public License as published by
8 * the Free Software Foundation; version 2 of the License.
9 *
10 * NetSurf is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
14 *
15 * You should have received a copy of the GNU General Public License
16 * along with this program. If not, see <http://www.gnu.org/licenses/>.
17 */
18
19/** \file
20 * Fetching of data from a URL (interface).
21 */
22
23#ifndef _NETSURF_DESKTOP_FETCH_H_
24#define _NETSURF_DESKTOP_FETCH_H_
25
26#include <stdbool.h>
27
28#include "utils/config.h"
29#include "utils/nsurl.h"
30#include "utils/inet.h"
31#include "netsurf/ssl_certs.h"
32
33struct content;
34struct fetch;
35struct ssl_cert_info;
36
37/**
38 * Fetcher message types
39 */
40typedef enum {
45 /* Anything after here is a completed fetch of some kind. */
55
56/** Minimum finished message type.
57 *
58 * If a fetch does not progress this far, it's an error and the fetch machinery
59 * will send FETCH_ERROR to the llcache on fetch_free()
60 */
61#define FETCH_MIN_FINISHED_MSG FETCH_FINISHED
62
63/**
64 * This message is actually an internal message used to indicate
65 * that a fetch was aborted. Do not send this, nor expect it.
66 */
67#define FETCH__INTERNAL_ABORTED FETCH_ERROR
68
69/**
70 * Fetcher message data
71 */
72typedef struct fetch_msg {
74
75 union {
76 const char *progress;
77
78 struct {
79 const uint8_t *buf;
80 size_t len;
82
83 const char *error;
84
85 /** \todo Use nsurl */
86 const char *redirect;
87
88 struct {
89 const char *realm;
91
92 const struct cert_chain *chain;
95
96/**
97 * Fetcher post data types
98 */
99typedef enum {
104
105
106/**
107 * Fetch POST multipart data
108 */
110 struct fetch_multipart_data *next; /**< Next in linked list */
111
112 char *name; /**< Name of item */
113 char *value; /**< Item value */
114
115 char *rawfile; /**< Raw filename if file is true */
116 bool file; /**< Item is a file */
117};
118
119/**
120 * fetch POST data
121 */
124 union {
125 /** Url encoded POST string if type is FETCH_POSTDATA_URLENC */
126 char *urlenc;
127 /** Multipart post data if type is FETCH_POSTDATA_MULTIPART */
130};
131
132
133typedef void (*fetch_callback)(const fetch_msg *msg, void *p);
134
135/**
136 * Start fetching data for the given URL.
137 *
138 * The function returns immediately. The fetch may be queued for later
139 * processing.
140 *
141 * A pointer to an opaque struct fetch is returned, which can be passed to
142 * fetch_abort() to abort the fetch at any time. Returns NULL if memory is
143 * exhausted (or some other fatal error occurred).
144 *
145 * The caller must supply a callback function which is called when anything
146 * interesting happens. The callback function is first called with msg
147 * FETCH_HEADER, with the header in data, then one or more times
148 * with FETCH_DATA with some data for the url, and finally with
149 * FETCH_FINISHED. Alternatively, FETCH_ERROR indicates an error occurred:
150 * data contains an error message. FETCH_REDIRECT may replace the FETCH_HEADER,
151 * FETCH_DATA, FETCH_FINISHED sequence if the server sends a replacement URL.
152 *
153 * \param url URL to fetch
154 * \param referer
155 * \param callback
156 * \param p
157 * \param only_2xx
158 * \param post_urlenc
159 * \param post_multipart
160 * \param verifiable
161 * \param downgrade_tls
162 * \param headers
163 * \param fetch_out ponter to recive new fetch object.
164 * \return NSERROR_OK and fetch_out updated else appropriate error code
165 */
166nserror fetch_start(nsurl *url, nsurl *referer, fetch_callback callback,
167 void *p, bool only_2xx, const char *post_urlenc,
168 const struct fetch_multipart_data *post_multipart,
169 bool verifiable, bool downgrade_tls,
170 const char *headers[], struct fetch **fetch_out);
171
172/**
173 * Abort a fetch.
174 */
175void fetch_abort(struct fetch *f);
176
177
178/**
179 * Check if a URL's scheme can be fetched.
180 *
181 * \param url URL to check
182 * \return true if the scheme is supported
183 */
184bool fetch_can_fetch(const nsurl *url);
185
186/**
187 * Change the callback function for a fetch.
188 */
189void fetch_change_callback(struct fetch *fetch, fetch_callback callback, void *p);
190
191/**
192 * Get the HTTP response code.
193 */
194long fetch_http_code(struct fetch *fetch);
195
196
197/**
198 * Free a linked list of fetch_multipart_data.
199 *
200 * \param list Pointer to head of list to free
201 */
203
204/**
205 * Clone a linked list of fetch_multipart_data.
206 *
207 * \param list List to clone
208 * \return Pointer to head of cloned list, or NULL on failure
209 */
211
212/**
213 * Find an entry in a fetch_multipart_data
214 *
215 * \param list Pointer to the multipart list
216 * \param name The name to look for in the list
217 * \return The value found, or NULL if not present
218 */
219const char *fetch_multipart_data_find(const struct fetch_multipart_data *list,
220 const char *name);
221
222/**
223 * Create an entry for a fetch_multipart_data
224 *
225 * If an entry exists of the same name, it will *NOT* be overwritten
226 *
227 * \param list Pointer to the pointer to the current multipart list
228 * \param name The name of the entry to create
229 * \param value The value of the entry to create
230 * \return The result of the attempt
231 */
233 const char *name,
234 const char *value);
235
236/**
237 * send message to fetch
238 */
239void fetch_send_callback(const fetch_msg *msg, struct fetch *fetch);
240
241/**
242 * remove a queued fetch
243 */
245
246/**
247 * Free a fetch structure and associated resources.
248 */
249void fetch_free(struct fetch *f);
250
251/**
252 * set the http code of a fetch
253 */
254void fetch_set_http_code(struct fetch *fetch, long http_code);
255
256/**
257 * set cookie data on a fetch
258 */
259void fetch_set_cookie(struct fetch *fetch, const char *data);
260
261/**
262 * Get the set of file descriptors the fetchers are currently using.
263 *
264 * This obtains the file descriptors the fetch system is using to
265 * obtain data. It will cause the fetchers to make progress, if
266 * possible, potentially completing fetches before requiring activity
267 * on file descriptors.
268 *
269 * If a set of descriptors is returned (maxfd is not -1) The caller is
270 * expected to wait on them (with select etc.) and continue to obtain
271 * the fdset with this call. This will switch the fetchers from polled
272 * mode to waiting for network activity which is much more efficient.
273 *
274 * \note If the caller does not subsequently obtain the fdset again
275 * the fetchers will fall back to the less efficient polled
276 * operation. The fallback to polled operation will only occour after
277 * a timeout which introduces additional delay.
278 *
279 * \param[out] read_fd_set The fd set for read.
280 * \param[out] write_fd_set The fd set for write.
281 * \param[out] except_fd_set The fd set for exceptions.
282 * \param[out] maxfd The highest fd number in the set or -1 if no fd available.
283 * \return NSERROR_OK on success or appropriate error code.
284 */
285nserror fetch_fdset(fd_set *read_fd_set, fd_set *write_fd_set, fd_set *except_fd_set, int *maxfd);
286
287#endif
struct fetch_msg fetch_msg
Fetcher message data.
nserror fetch_multipart_data_new_kv(struct fetch_multipart_data **list, const char *name, const char *value)
Create an entry for a fetch_multipart_data.
Definition: fetch.c:721
void fetch_set_http_code(struct fetch *fetch, long http_code)
set the http code of a fetch
Definition: fetch.c:794
fetch_postdata_type
Fetcher post data types.
Definition: fetch.h:99
@ FETCH_POSTDATA_URLENC
Definition: fetch.h:101
@ FETCH_POSTDATA_NONE
Definition: fetch.h:100
@ FETCH_POSTDATA_MULTIPART
Definition: fetch.h:102
bool fetch_can_fetch(const nsurl *url)
Check if a URL's scheme can be fetched.
Definition: fetch.c:586
void fetch_set_cookie(struct fetch *fetch, const char *data)
set cookie data on a fetch
Definition: fetch.c:803
const char * fetch_multipart_data_find(const struct fetch_multipart_data *list, const char *name)
Find an entry in a fetch_multipart_data.
Definition: fetch.c:686
long fetch_http_code(struct fetch *fetch)
Get the HTTP response code.
Definition: fetch.c:612
nserror fetch_start(nsurl *url, nsurl *referer, fetch_callback callback, void *p, bool only_2xx, const char *post_urlenc, const struct fetch_multipart_data *post_multipart, bool verifiable, bool downgrade_tls, const char *headers[], struct fetch **fetch_out)
Start fetching data for the given URL.
Definition: fetch.c:449
void fetch_abort(struct fetch *f)
Abort a fetch.
Definition: fetch.c:537
void fetch_send_callback(const fetch_msg *msg, struct fetch *fetch)
send message to fetch
Definition: fetch.c:757
void fetch_free(struct fetch *f)
Free a fetch structure and associated resources.
Definition: fetch.c:548
void(* fetch_callback)(const fetch_msg *msg, void *p)
Definition: fetch.h:133
fetch_msg_type
Fetcher message types.
Definition: fetch.h:40
@ FETCH_REDIRECT
Definition: fetch.h:49
@ FETCH_DATA
Definition: fetch.h:44
@ FETCH_AUTH
Definition: fetch.h:51
@ FETCH_CERTS
Definition: fetch.h:42
@ FETCH_HEADER
Definition: fetch.h:43
@ FETCH_PROGRESS
Definition: fetch.h:41
@ FETCH_NOTMODIFIED
Definition: fetch.h:50
@ FETCH_FINISHED
Definition: fetch.h:46
@ FETCH_SSL_ERR
Definition: fetch.h:53
@ FETCH_ERROR
Definition: fetch.h:48
@ FETCH_TIMEDOUT
Definition: fetch.h:47
@ FETCH_CERT_ERR
Definition: fetch.h:52
struct fetch_multipart_data * fetch_multipart_data_clone(const struct fetch_multipart_data *list)
Clone a linked list of fetch_multipart_data.
Definition: fetch.c:620
void fetch_remove_from_queues(struct fetch *fetch)
remove a queued fetch
Definition: fetch.c:767
void fetch_change_callback(struct fetch *fetch, fetch_callback callback, void *p)
Change the callback function for a fetch.
Definition: fetch.c:602
void fetch_multipart_data_destroy(struct fetch_multipart_data *list)
Free a linked list of fetch_multipart_data.
Definition: fetch.c:701
nserror fetch_fdset(fd_set *read_fd_set, fd_set *write_fd_set, fd_set *except_fd_set, int *maxfd)
Get the set of file descriptors the fetchers are currently using.
Definition: fetch.c:385
nserror
Enumeration of error codes.
Definition: errors.h:29
internet structures and defines
NetSurf URL handling (interface).
struct nsurl nsurl
NetSurf URL object.
Definition: nsurl.h:31
SSL related types and values.
X509 certificate chain.
Definition: ssl_certs.h:59
Content which corresponds to a single URL.
Fetcher message data.
Definition: fetch.h:72
const uint8_t * buf
Definition: fetch.h:79
fetch_msg_type type
Definition: fetch.h:73
struct fetch_msg::@118::@119 header_or_data
const char * realm
Definition: fetch.h:89
const struct cert_chain * chain
Definition: fetch.h:92
size_t len
Definition: fetch.h:80
struct fetch_msg::@118::@120 auth
union fetch_msg::@118 data
const char * progress
Definition: fetch.h:76
const char * redirect
Definition: fetch.h:86
const char * error
Definition: fetch.h:83
Fetch POST multipart data.
Definition: fetch.h:109
char * rawfile
Raw filename if file is true.
Definition: fetch.h:115
char * value
Item value.
Definition: fetch.h:113
struct fetch_multipart_data * next
Next in linked list.
Definition: fetch.h:110
char * name
Name of item.
Definition: fetch.h:112
bool file
Item is a file.
Definition: fetch.h:116
fetch POST data
Definition: fetch.h:122
struct fetch_multipart_data * multipart
Multipart post data if type is FETCH_POSTDATA_MULTIPART.
Definition: fetch.h:128
union fetch_postdata::@121 data
char * urlenc
Url encoded POST string if type is FETCH_POSTDATA_URLENC.
Definition: fetch.h:126
fetch_postdata_type type
Definition: fetch.h:123
Information for a single fetch.
Definition: fetch.c:89