diff options
author | Florian Dold <florian.dold@gmail.com> | 2013-04-17 00:44:29 +0000 |
---|---|---|
committer | Florian Dold <florian.dold@gmail.com> | 2013-04-17 00:44:29 +0000 |
commit | 0555e4e107db9c0c1f0caa6c947881c32bf426f4 (patch) | |
tree | d9bbd740ad0f73c07cf56aad0650e6ded7d05229 /src/include/gnunet_set_service.h | |
parent | e77e2db24ef3681f207521e539a2c1ca3584efda (diff) | |
download | gnunet-0555e4e107db9c0c1f0caa6c947881c32bf426f4.tar.gz gnunet-0555e4e107db9c0c1f0caa6c947881c32bf426f4.zip |
started implementing set api, draft for mq
Diffstat (limited to 'src/include/gnunet_set_service.h')
-rw-r--r-- | src/include/gnunet_set_service.h | 257 |
1 files changed, 200 insertions, 57 deletions
diff --git a/src/include/gnunet_set_service.h b/src/include/gnunet_set_service.h index 78dc7b7d0..cf782c841 100644 --- a/src/include/gnunet_set_service.h +++ b/src/include/gnunet_set_service.h | |||
@@ -1,9 +1,76 @@ | |||
1 | // FIXME: copyright, etc. | 1 | /* |
2 | This file is part of GNUnet | ||
3 | (C) 2013 Christian Grothoff (and other contributing authors) | ||
4 | |||
5 | GNUnet is free software; you can redistribute it and/or modify | ||
6 | it under the terms of the GNU General Public License as published | ||
7 | by the Free Software Foundation; either version 2, or (at your | ||
8 | option) any later version. | ||
9 | |||
10 | GNUnet is distributed in the hope that it will be useful, but | ||
11 | WITHOUT ANY WARRANTY; without even the implied warranty of | ||
12 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | ||
13 | General Public License for more details. | ||
14 | |||
15 | You should have received a copy of the GNU General Public License | ||
16 | along with GNUnet; see the file COPYING. If not, write to the | ||
17 | Free Software Foundation, Inc., 59 Temple Place - Suite 330, | ||
18 | Boston, MA 02111-1307, USA. | ||
19 | */ | ||
20 | |||
21 | /** | ||
22 | * @file include/gnunet_set_service.h | ||
23 | * @brief two-peer set operations | ||
24 | * @author Florian Dold | ||
25 | */ | ||
26 | |||
27 | #ifndef GNUNET_SET_SERVICE_H | ||
28 | #define GNUNET_SET_SERVICE_H | ||
29 | |||
30 | #ifdef __cplusplus | ||
31 | extern "C" | ||
32 | { | ||
33 | #if 0 /* keep Emacsens' auto-indent happy */ | ||
34 | } | ||
35 | #endif | ||
36 | #endif | ||
37 | |||
38 | #include "platform.h" | ||
39 | #include "gnunet_common.h" | ||
40 | #include "gnunet_time_lib.h" | ||
41 | #include "gnunet_configuration_lib.h" | ||
42 | |||
43 | |||
44 | /** | ||
45 | * Opaque handle to a set. | ||
46 | */ | ||
47 | struct GNUNET_SET_Handle; | ||
48 | |||
49 | /** | ||
50 | * Opaque handle to a set operation request from another peer. | ||
51 | */ | ||
52 | struct GNUNET_SET_Request; | ||
53 | |||
54 | /** | ||
55 | * Opaque handle to a listen operation. | ||
56 | */ | ||
57 | struct GNUNET_SET_ListenHandle; | ||
58 | |||
59 | /** | ||
60 | * Opaque handle to a set operation. | ||
61 | */ | ||
62 | struct GNUNET_SET_OperationHandle; | ||
63 | |||
64 | |||
65 | /** | ||
66 | * Opaque handle to a listen operation. | ||
67 | */ | ||
68 | struct GNUNET_SET_ListenHandle; | ||
2 | 69 | ||
3 | /** | 70 | /** |
4 | * The operation that a set set supports. | 71 | * The operation that a set set supports. |
5 | */ | 72 | */ |
6 | enum GNUNET_SET_Operation | 73 | enum GNUNET_SET_OperationType |
7 | { | 74 | { |
8 | /** | 75 | /** |
9 | * Set intersection, only return elements that are in both sets. | 76 | * Set intersection, only return elements that are in both sets. |
@@ -31,10 +98,37 @@ enum GNUNET_SET_Status | |||
31 | /* | 98 | /* |
32 | * The other peer refused to to the operation with us | 99 | * The other peer refused to to the operation with us |
33 | */ | 100 | */ |
34 | GNUNET_SET_STATUS_REFUSED | 101 | GNUNET_SET_STATUS_REFUSED, |
102 | /* | ||
103 | * Success, all elements have been sent. | ||
104 | */ | ||
105 | GNUNET_SET_STATUS_DONE | ||
35 | }; | 106 | }; |
36 | 107 | ||
37 | // FIXME: comment | 108 | /** |
109 | * The way results are given to the client. | ||
110 | */ | ||
111 | enum GNUNET_SET_ResultMode | ||
112 | { | ||
113 | /** | ||
114 | * Client gets every element in the resulting set. | ||
115 | */ | ||
116 | GNUNET_SET_RESULT_FULL, | ||
117 | /** | ||
118 | * Client gets only elements that have been added to the set. | ||
119 | * Only works with set union. | ||
120 | */ | ||
121 | GNUNET_SET_RESULT_ADDED, | ||
122 | /** | ||
123 | * Client gets only elements that have been removed from the set. | ||
124 | * Only works with set intersection. | ||
125 | */ | ||
126 | GNUNET_SET_RESULT_REMOVED | ||
127 | }; | ||
128 | |||
129 | /** | ||
130 | * Element stored in a set. | ||
131 | */ | ||
38 | struct GNUNET_SET_Element | 132 | struct GNUNET_SET_Element |
39 | { | 133 | { |
40 | /** | 134 | /** |
@@ -53,8 +147,53 @@ struct GNUNET_SET_Element | |||
53 | 147 | ||
54 | 148 | ||
55 | /** | 149 | /** |
150 | * Continuation used for some of the set operations | ||
151 | * | ||
152 | * @cls closure | ||
153 | */ | ||
154 | typedef void (*GNUNET_SET_Continuation) (void *cls); | ||
155 | |||
156 | /** | ||
157 | * Callback for set operation results. Called for each element | ||
158 | * in the result set. | ||
159 | * | ||
160 | * @param cls closure | ||
161 | * @param element a result element, only valid if status is GNUNET_SET_STATUS_OK | ||
162 | * @param status see enum GNUNET_SET_Status | ||
163 | */ | ||
164 | typedef void | ||
165 | (*GNUNET_SET_ResultIterator) (void *cls, | ||
166 | struct GNUNET_SET_Element *element, | ||
167 | enum GNUNET_SET_Status status); | ||
168 | |||
169 | |||
170 | /** | ||
171 | * Called when another peer wants to do a set operation with the | ||
172 | * local peer | ||
173 | * | ||
174 | * @param other_peer the other peer | ||
175 | * @param context_msg message with application specific information from | ||
176 | * the other peer | ||
177 | * @param request request from the other peer, use GNUNET_SET_accept | ||
178 | * to accept it, otherwise the request will be refused | ||
179 | * Note that we don't use a return value here, as it is also | ||
180 | * necessary to specify the set we want to do the operation with, | ||
181 | * whith sometimes can be derived from the context message. | ||
182 | * Also necessary to specify the timeout. | ||
183 | */ | ||
184 | typedef void | ||
185 | (*GNUNET_SET_ListenCallback) (void *cls, | ||
186 | const struct GNUNET_PeerIdentity *other_peer, | ||
187 | const struct GNUNET_MessageHeader *context_msg, | ||
188 | struct GNUNET_SET_Request *request); | ||
189 | |||
190 | |||
191 | |||
192 | /** | ||
56 | * Create an empty set, supporting the specified operation. | 193 | * Create an empty set, supporting the specified operation. |
57 | * | 194 | * |
195 | * @param cfg configuration to use for connecting to the | ||
196 | * set service | ||
58 | * @param op operation supported by the set | 197 | * @param op operation supported by the set |
59 | * Note that the operation has to be specified | 198 | * Note that the operation has to be specified |
60 | * beforehand, as certain set operations need to maintain | 199 | * beforehand, as certain set operations need to maintain |
@@ -62,10 +201,21 @@ struct GNUNET_SET_Element | |||
62 | * @return a handle to the set | 201 | * @return a handle to the set |
63 | */ | 202 | */ |
64 | struct GNUNET_SET_Handle * | 203 | struct GNUNET_SET_Handle * |
65 | GNUNET_SET_create (enum GNUNET_SET_Operation op); | 204 | GNUNET_SET_create (struct GNUNET_CONFIGURATION_Handle *cfg, |
205 | enum GNUNET_SET_OperationType op); | ||
66 | 206 | ||
67 | 207 | ||
68 | // FIXME: comment | 208 | /** |
209 | * Add an element to the given set. | ||
210 | * After the element has been added (in the sense of being | ||
211 | * transmitted to the set service), cont will be called. | ||
212 | * Calls to add_element can be queued | ||
213 | * | ||
214 | * @param set set to add element to | ||
215 | * @param element element to add to the set | ||
216 | * @param cont continuation called after the element has been added | ||
217 | * @param cont_cls closure for cont | ||
218 | */ | ||
69 | void | 219 | void |
70 | GNUNET_SET_add_element (struct GNUNET_SET_Handle *set, | 220 | GNUNET_SET_add_element (struct GNUNET_SET_Handle *set, |
71 | const struct GNUNET_SET_Element *element, | 221 | const struct GNUNET_SET_Element *element, |
@@ -73,7 +223,17 @@ GNUNET_SET_add_element (struct GNUNET_SET_Handle *set, | |||
73 | void *cont_cls); | 223 | void *cont_cls); |
74 | 224 | ||
75 | 225 | ||
76 | // FIXME: comment | 226 | /** |
227 | * Remove an element to the given set. | ||
228 | * After the element has been removed (in the sense of the | ||
229 | * request being transmitted to the set service), cont will be called. | ||
230 | * Calls to remove_element can be queued | ||
231 | * | ||
232 | * @param set set to remove element from | ||
233 | * @param element element to remove from the set | ||
234 | * @param cont continuation called after the element has been removed | ||
235 | * @param cont_cls closure for cont | ||
236 | */ | ||
77 | void | 237 | void |
78 | GNUNET_SET_remove_element (struct GNUNET_SET_Handle *set, | 238 | GNUNET_SET_remove_element (struct GNUNET_SET_Handle *set, |
79 | const struct GNUNET_SET_Element *element, | 239 | const struct GNUNET_SET_Element *element, |
@@ -81,37 +241,17 @@ GNUNET_SET_remove_element (struct GNUNET_SET_Handle *set, | |||
81 | void *cont_cls); | 241 | void *cont_cls); |
82 | 242 | ||
83 | 243 | ||
84 | // FIXME: comment | ||
85 | struct GNUNET_SET_Handle * | ||
86 | GNUNET_SET_clone (struct GNUNET_SET_Handle *set); | ||
87 | |||
88 | |||
89 | // FIXME: comment | ||
90 | void | ||
91 | GNUNET_SET_destroy (struct GNUNET_SET_Handle *set); | ||
92 | |||
93 | |||
94 | |||
95 | /** | 244 | /** |
96 | * Callback for set operation results. Called for each element | 245 | * Destroy the set handle, and free all associated resources. |
97 | * in the result set. | ||
98 | // FIXME: might want a way to just get the 'additional/removd' elements | ||
99 | * | ||
100 | * @param cls closure | ||
101 | * @param element element, or NULL to indicate that all elements | ||
102 | * have been passed to the callback | ||
103 | * Only valid if (status==GNUNET_SET_STATUS_OK) holds. | ||
104 | * @param status see enum GNUNET_SET_Status | ||
105 | */ | 246 | */ |
106 | typedef void | 247 | void |
107 | (*GNUNET_SET_ResultIterator) (void *cls, | 248 | GNUNET_SET_destroy (struct GNUNET_SET_Handle *set); |
108 | struct GNUNET_SET_Element *element, | ||
109 | enum GNUNET_SET_ResultStatus status); | ||
110 | 249 | ||
111 | 250 | ||
112 | /** | 251 | /** |
113 | * Evaluate a set operation with our set and the set of another peer. | 252 | * Evaluate a set operation with our set and the set of another peer. |
114 | * | 253 | * |
254 | * @param set set to use | ||
115 | * @param other_peer peer with the other set | 255 | * @param other_peer peer with the other set |
116 | * @param app_id hash for the application using the set | 256 | * @param app_id hash for the application using the set |
117 | * @param context_msg additional information for the request | 257 | * @param context_msg additional information for the request |
@@ -120,38 +260,23 @@ typedef void | |||
120 | * @return a handle to cancel the operation | 260 | * @return a handle to cancel the operation |
121 | */ | 261 | */ |
122 | struct GNUNET_SET_OperationHandle * | 262 | struct GNUNET_SET_OperationHandle * |
123 | GNUNET_SET_evaluate (const struct GNUNET_PeerIdentity *other_peer, | 263 | GNUNET_SET_evaluate (struct GNUNET_SET_Handle *set, |
264 | const struct GNUNET_PeerIdentity *other_peer, | ||
124 | const struct GNUNET_HashCode *app_id, | 265 | const struct GNUNET_HashCode *app_id, |
125 | const struct GNUNET_MessageHeader *context_msg, | 266 | const struct GNUNET_MessageHeader *context_msg, |
126 | struct GNUNET_TIME_Relative timeout, | 267 | struct GNUNET_TIME_Relative timeout, |
268 | enum GNUNET_SET_ResultMode result_mode, | ||
127 | GNUNET_SET_ResultIterator result_cb, | 269 | GNUNET_SET_ResultIterator result_cb, |
128 | void *result_cls); | 270 | void *result_cls); |
129 | 271 | ||
130 | 272 | ||
131 | /** | ||
132 | * Called when another peer wants to do a set operation with the | ||
133 | * local peer | ||
134 | * | ||
135 | * @param other_peer the other peer | ||
136 | * @param context_msg message with application specific information from | ||
137 | * the other peer | ||
138 | * @param request request from the other peer, use GNUNET_SET_accept | ||
139 | * to accept it, otherwise the request will be refused | ||
140 | * Note that we don't use a return value here, as it is also | ||
141 | * necessary to specify the set we want to do the operation with, | ||
142 | * whith sometimes can be derived from the context message. | ||
143 | * Also necessary to specify the timeout. | ||
144 | */ | ||
145 | typedef void | ||
146 | (*GNUNET_SET_ListenCallback) (void *cls, | ||
147 | const struct GNUNET_PeerIdentity *other_peer, | ||
148 | const struct GNUNET_MessageHeader *context_msg, | ||
149 | struct GNUNET_SET_Request *request); | ||
150 | 273 | ||
151 | 274 | ||
152 | /** | 275 | /** |
153 | * Wait for set operation requests for the given application id | 276 | * Wait for set operation requests for the given application id |
154 | * | 277 | * |
278 | * @param cfg configuration to use for connecting to | ||
279 | * the set service | ||
155 | * @param operation operation we want to listen for | 280 | * @param operation operation we want to listen for |
156 | * @param app_id id of the application that handles set operation requests | 281 | * @param app_id id of the application that handles set operation requests |
157 | * @param listen_cb called for each incoming request matching the operation | 282 | * @param listen_cb called for each incoming request matching the operation |
@@ -160,14 +285,19 @@ typedef void | |||
160 | * @return a handle that can be used to cancel the listen operation | 285 | * @return a handle that can be used to cancel the listen operation |
161 | */ | 286 | */ |
162 | struct GNUNET_SET_ListenHandle * | 287 | struct GNUNET_SET_ListenHandle * |
163 | GNUNET_SET_listen (enum GNUNET_SET_Operation operation, | 288 | GNUNET_SET_listen (struct GNUNET_CONFIGURATION_Handle *cfg, |
289 | enum GNUNET_SET_OperationType op_type, | ||
164 | const struct GNUNET_HashCode *app_id, | 290 | const struct GNUNET_HashCode *app_id, |
165 | GNUNET_SET_ListenCallback listen_cb, | 291 | GNUNET_SET_ListenCallback listen_cb, |
166 | void *listen_cls); | 292 | void *listen_cls); |
167 | 293 | ||
168 | 294 | ||
169 | 295 | ||
170 | // FIXME: comment | 296 | /** |
297 | * Cancel the given listen operation. | ||
298 | * | ||
299 | * @param lh handle for the listen operation | ||
300 | */ | ||
171 | void | 301 | void |
172 | GNUNET_SET_listen_cancel (struct GNUNET_SET_ListenHandle *lh); | 302 | GNUNET_SET_listen_cancel (struct GNUNET_SET_ListenHandle *lh); |
173 | 303 | ||
@@ -185,12 +315,25 @@ struct GNUNET_SET_OperationHandle * | |||
185 | GNUNET_SET_accept (struct GNUNET_SET_Request *request, | 315 | GNUNET_SET_accept (struct GNUNET_SET_Request *request, |
186 | struct GNUNET_SET_Handle *set, | 316 | struct GNUNET_SET_Handle *set, |
187 | struct GNUNET_TIME_Relative timeout, | 317 | struct GNUNET_TIME_Relative timeout, |
318 | enum GNUNET_SET_ResultMode result_mode, | ||
188 | GNUNET_SET_ResultIterator result_cb, | 319 | GNUNET_SET_ResultIterator result_cb, |
189 | void *cls) | 320 | void *cls); |
190 | 321 | ||
191 | 322 | ||
192 | // FIXME: comment | 323 | /** |
324 | * Cancel the given set operation. | ||
325 | * | ||
326 | * @param op set operation to cancel | ||
327 | */ | ||
193 | void | 328 | void |
194 | GNUNET_SET_operation_cancel (struct GNUNET_SET_OperationHandle *op); | 329 | GNUNET_SET_operation_cancel (struct GNUNET_SET_OperationHandle *oh); |
195 | 330 | ||
331 | |||
332 | #if 0 /* keep Emacsens' auto-indent happy */ | ||
333 | { | ||
334 | #endif | ||
335 | #ifdef __cplusplus | ||
336 | } | ||
337 | #endif | ||
196 | 338 | ||
339 | #endif | ||