Added a new FETCH_CALLBACK option to fetch data without allocation
[strongswan.git] / src / libstrongswan / fetcher / fetcher.h
1 /*
2 * Copyright (C) 2008-2011 Martin Willi
3 * Hochschule fuer Technik Rapperswil
4 * Copyright (C) 2011 revosec AG
5 *
6 * This program is free software; you can redistribute it and/or modify it
7 * under the terms of the GNU General Public License as published by the
8 * Free Software Foundation; either version 2 of the License, or (at your
9 * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>.
10 *
11 * This program is distributed in the hope that it will be useful, but
12 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
13 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * for more details.
15 */
16
17 /**
18 * @defgroup fetcheri fetcher
19 * @{ @ingroup fetcher
20 */
21
22 #ifndef FETCHER_H_
23 #define FETCHER_H_
24
25 typedef struct fetcher_t fetcher_t;
26 typedef enum fetcher_option_t fetcher_option_t;
27
28 #include <stdarg.h>
29 #include <chunk.h>
30
31 /**
32 * Constructor function which creates fetcher instances.
33 *
34 * @return fetcher instance
35 */
36 typedef fetcher_t* (*fetcher_constructor_t)();
37
38 /**
39 * Callback function used with FETCH_CALLBACK.
40 *
41 * @param userdata userdata passed to fetcher_t.fetch()
42 * @param chunk chunk with next chunk of data
43 * @return TRUE to continue with transfer, FALSE to abort
44 */
45 typedef bool (*fetcher_callback_t)(void *userdata, chunk_t chunk);
46
47 #include <library.h>
48
49 /**
50 * Fetching options to use for fetcher_t.fetch() call.
51 */
52 enum fetcher_option_t {
53
54 /**
55 * Data to include in fetch request, e.g. on a HTTP post.
56 * Additional argument is a chunk_t
57 */
58 FETCH_REQUEST_DATA,
59
60 /**
61 * Mime-Type of data included in FETCH_REQUEST_DATA.
62 * Additional argument is a char*.
63 */
64 FETCH_REQUEST_TYPE,
65
66 /**
67 * HTTP header to be sent with with the fetch request.
68 * Additional argument is a char*.
69 */
70 FETCH_REQUEST_HEADER,
71
72 /**
73 * Use HTTP Version 1.0 instead of 1.1.
74 * No additional argument is needed.
75 */
76 FETCH_HTTP_VERSION_1_0,
77
78 /**
79 * Timeout to use for fetch, in seconds.
80 * Additional argument is u_int
81 */
82 FETCH_TIMEOUT,
83
84 /**
85 * Callback to invoke with each chunk of data.
86 * Additional argument fetch_callback_t.
87 * If this option is not given, the fetcher_default_callback is used,
88 * which accumulates the data into an allocated chunk.
89 */
90 FETCH_CALLBACK,
91
92 /**
93 * end of fetching options
94 */
95 FETCH_END,
96 };
97
98 /**
99 * Fetcher interface, an implementation fetches data from an URL.
100 */
101 struct fetcher_t {
102
103 /**
104 * Fetch data from URI into chunk.
105 *
106 * The fetcher returns NOT_SUPPORTED to indicate that it is uncappable
107 * to handle such URLs. Other return values indicate a failure, and
108 * fetching of that URL gets cancelled.
109 * If no FETCH_CALLBACK function is set as option, userdata must be
110 * a chunk_t*. This chunk gets allocated, accumulated data using the
111 * fetcher_default_callback() function.
112 *
113 * @param uri URI to fetch from
114 * @param userdata userdata to pass to callback function.
115 * @return
116 * - SUCCESS if fetch was successful
117 * - NOT_SUPPORTED if fetcher does not support such URLs
118 * - FAILED, NOT_FOUND, PARSE_ERROR on failure
119 */
120 status_t (*fetch)(fetcher_t *this, char *uri, void *userdata);
121
122 /**
123 * Set a fetcher option, as defined in fetcher_option_t.
124 *
125 * Arguments passed to options must stay in memory until fetch() returns.
126 *
127 * @param option option to set
128 * @param ... variable argument(s) to option
129 * @return TRUE if option supported, FALSE otherwise
130 */
131 bool (*set_option)(fetcher_t *this, fetcher_option_t option, ...);
132
133 /**
134 * Destroy the fetcher instance.
135 */
136 void (*destroy)(fetcher_t *this);
137 };
138
139 /**
140 * Default fetcher callback function, accumulates data to a chunk.
141 *
142 * @param userdata chunk for allocated data, empty on first invocation
143 * @param chunk current chunk of data
144 * @return FALSE if chunk too large to allocate
145 */
146 bool fetcher_default_callback(void *userdata, chunk_t chunk);
147
148 #endif /** FETCHER_H_ @}*/