diff options
author | Bart Polot <bart@net.in.tum.de> | 2014-05-07 12:07:34 +0000 |
---|---|---|
committer | Bart Polot <bart@net.in.tum.de> | 2014-05-07 12:07:34 +0000 |
commit | d675b12cbb54900e6ac6e63ced5e06795996cb97 (patch) | |
tree | a1f655acc9b5ef90365eb7f14814605c8d805bcb /src/include/gnunet_cadet_service.h | |
parent | 2551c86b4aa52e1cb80ebfa7e9763f2fc9c55083 (diff) | |
download | gnunet-d675b12cbb54900e6ac6e63ced5e06795996cb97.tar.gz gnunet-d675b12cbb54900e6ac6e63ced5e06795996cb97.zip |
- move include file
Diffstat (limited to 'src/include/gnunet_cadet_service.h')
-rw-r--r-- | src/include/gnunet_cadet_service.h | 619 |
1 files changed, 619 insertions, 0 deletions
diff --git a/src/include/gnunet_cadet_service.h b/src/include/gnunet_cadet_service.h new file mode 100644 index 000000000..e69c9eaa7 --- /dev/null +++ b/src/include/gnunet_cadet_service.h | |||
@@ -0,0 +1,619 @@ | |||
1 | /* | ||
2 | This file is part of GNUnet. | ||
3 | (C) 2009 - 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 3, 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_cadet_service.h | ||
23 | * @brief cadet service; establish channels to distant peers | ||
24 | * @author Christian Grothoff | ||
25 | */ | ||
26 | |||
27 | #ifndef GNUNET_CADET_SERVICE_H | ||
28 | #define GNUNET_CADET_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 "gnunet_util_lib.h" | ||
39 | #include "gnunet_transport_service.h" | ||
40 | |||
41 | /** | ||
42 | * Version number of GNUnet-cadet API. | ||
43 | */ | ||
44 | #define GNUNET_CADET_VERSION 0x00000003 | ||
45 | |||
46 | |||
47 | /** | ||
48 | * Opaque handle to the service. | ||
49 | */ | ||
50 | struct GNUNET_CADET_Handle; | ||
51 | |||
52 | /** | ||
53 | * Opaque handle to a channel. | ||
54 | */ | ||
55 | struct GNUNET_CADET_Channel; | ||
56 | |||
57 | /** | ||
58 | * Hash to be used in Cadet communication. Only 256 bits needed, | ||
59 | * instead of the 512 from @c GNUNET_HashCode. | ||
60 | * | ||
61 | */ | ||
62 | struct GNUNET_CADET_Hash | ||
63 | { | ||
64 | unsigned char bits[256 / 8]; | ||
65 | }; | ||
66 | |||
67 | /** | ||
68 | * Channel options. | ||
69 | * Second line indicates filed in the CadetChannelInfo union carrying the answer. | ||
70 | */ | ||
71 | enum GNUNET_CADET_ChannelOption | ||
72 | { | ||
73 | /** | ||
74 | * Default options: unreliable, default buffering, not out of order. | ||
75 | */ | ||
76 | GNUNET_CADET_OPTION_DEFAULT = 0x0, | ||
77 | |||
78 | /** | ||
79 | * Disable buffering on intermediate nodes (for minimum latency). | ||
80 | * Yes/No. | ||
81 | */ | ||
82 | GNUNET_CADET_OPTION_NOBUFFER = 0x1, | ||
83 | |||
84 | /** | ||
85 | * Enable channel reliability, lost messages will be retransmitted. | ||
86 | * Yes/No. | ||
87 | */ | ||
88 | GNUNET_CADET_OPTION_RELIABLE = 0x2, | ||
89 | |||
90 | /** | ||
91 | * Enable out of order delivery of messages. | ||
92 | * Yes/No. | ||
93 | */ | ||
94 | GNUNET_CADET_OPTION_OOORDER = 0x4, | ||
95 | |||
96 | /** | ||
97 | * Who is the peer at the other end of the channel. | ||
98 | * Only for use in @c GNUNET_CADET_channel_get_info | ||
99 | * struct GNUNET_PeerIdentity *peer | ||
100 | */ | ||
101 | GNUNET_CADET_OPTION_PEER = 0x8 | ||
102 | |||
103 | }; | ||
104 | |||
105 | |||
106 | /** | ||
107 | * Functions with this signature are called whenever a message is | ||
108 | * received. | ||
109 | * | ||
110 | * Each time the function must call #GNUNET_CADET_receive_done on the channel | ||
111 | * in order to receive the next message. This doesn't need to be immediate: | ||
112 | * can be delayed if some processing is done on the message. | ||
113 | * | ||
114 | * @param cls Closure (set from #GNUNET_CADET_connect). | ||
115 | * @param channel Connection to the other end. | ||
116 | * @param channel_ctx Place to store local state associated with the channel. | ||
117 | * @param message The actual message. | ||
118 | * @return #GNUNET_OK to keep the channel open, | ||
119 | * #GNUNET_SYSERR to close it (signal serious error). | ||
120 | */ | ||
121 | typedef int (*GNUNET_CADET_MessageCallback) (void *cls, | ||
122 | struct GNUNET_CADET_Channel *channel, | ||
123 | void **channel_ctx, | ||
124 | const struct GNUNET_MessageHeader *message); | ||
125 | |||
126 | |||
127 | /** | ||
128 | * Message handler. Each struct specifies how to handle on particular | ||
129 | * type of message received. | ||
130 | */ | ||
131 | struct GNUNET_CADET_MessageHandler | ||
132 | { | ||
133 | /** | ||
134 | * Function to call for messages of "type". | ||
135 | */ | ||
136 | GNUNET_CADET_MessageCallback callback; | ||
137 | |||
138 | /** | ||
139 | * Type of the message this handler covers. | ||
140 | */ | ||
141 | uint16_t type; | ||
142 | |||
143 | /** | ||
144 | * Expected size of messages of this type. Use 0 for variable-size. | ||
145 | * If non-zero, messages of the given type will be discarded if they | ||
146 | * do not have the right size. | ||
147 | */ | ||
148 | uint16_t expected_size; | ||
149 | }; | ||
150 | |||
151 | |||
152 | /** | ||
153 | * Method called whenever another peer has added us to a channel | ||
154 | * the other peer initiated. | ||
155 | * Only called (once) upon reception of data with a message type which was | ||
156 | * subscribed to in #GNUNET_CADET_connect. | ||
157 | * | ||
158 | * A call to #GNUNET_CADET_channel_destroy causes te channel to be ignored. In | ||
159 | * this case the handler MUST return NULL. | ||
160 | * | ||
161 | * @param cls closure | ||
162 | * @param channel new handle to the channel | ||
163 | * @param initiator peer that started the channel | ||
164 | * @param port Port this channel is for. | ||
165 | * @param options CadetOption flag field, with all active option bits set to 1. | ||
166 | * | ||
167 | * @return initial channel context for the channel | ||
168 | * (can be NULL -- that's not an error) | ||
169 | */ | ||
170 | typedef void *(GNUNET_CADET_InboundChannelNotificationHandler) (void *cls, | ||
171 | struct | ||
172 | GNUNET_CADET_Channel | ||
173 | * channel, | ||
174 | const struct | ||
175 | GNUNET_PeerIdentity | ||
176 | * initiator, | ||
177 | uint32_t port, | ||
178 | enum GNUNET_CADET_ChannelOption | ||
179 | options); | ||
180 | |||
181 | |||
182 | /** | ||
183 | * Function called whenever a channel is destroyed. Should clean up | ||
184 | * any associated state. | ||
185 | * | ||
186 | * It must NOT call #GNUNET_CADET_channel_destroy on the channel. | ||
187 | * | ||
188 | * @param cls closure (set from #GNUNET_CADET_connect) | ||
189 | * @param channel connection to the other end (henceforth invalid) | ||
190 | * @param channel_ctx place where local state associated | ||
191 | * with the channel is stored | ||
192 | */ | ||
193 | typedef void (GNUNET_CADET_ChannelEndHandler) (void *cls, | ||
194 | const struct GNUNET_CADET_Channel * | ||
195 | channel, | ||
196 | void *channel_ctx); | ||
197 | |||
198 | |||
199 | /** | ||
200 | * Connect to the cadet service. | ||
201 | * | ||
202 | * @param cfg Configuration to use. | ||
203 | * @param cls Closure for the various callbacks that follow (including | ||
204 | * handlers in the handlers array). | ||
205 | * @param new_channel Function called when an *incoming* channel is created. | ||
206 | * Can be NULL if no inbound channels are desired. | ||
207 | * See @a ports. | ||
208 | * @param cleaner Function called when a channel is destroyed by the remote peer. | ||
209 | * It is NOT called if #GNUNET_CADET_channel_destroy is called on | ||
210 | * the channel. | ||
211 | * @param handlers Callbacks for messages we care about, NULL-terminated. Each | ||
212 | * one must call #GNUNET_CADET_receive_done on the channel to | ||
213 | * receive the next message. Messages of a type that is not | ||
214 | * in the handlers array are ignored if received. | ||
215 | * @param ports NULL or 0-terminated array of port numbers for incoming channels. | ||
216 | * See @a new_channel. | ||
217 | * | ||
218 | * @return handle to the cadet service NULL on error | ||
219 | * (in this case, init is never called) | ||
220 | */ | ||
221 | struct GNUNET_CADET_Handle * | ||
222 | GNUNET_CADET_connect (const struct GNUNET_CONFIGURATION_Handle *cfg, void *cls, | ||
223 | GNUNET_CADET_InboundChannelNotificationHandler new_channel, | ||
224 | GNUNET_CADET_ChannelEndHandler cleaner, | ||
225 | const struct GNUNET_CADET_MessageHandler *handlers, | ||
226 | const uint32_t *ports); | ||
227 | |||
228 | |||
229 | /** | ||
230 | * Disconnect from the cadet service. All channels will be destroyed. All channel | ||
231 | * disconnect callbacks will be called on any still connected peers, notifying | ||
232 | * about their disconnection. The registered inbound channel cleaner will be | ||
233 | * called should any inbound channels still exist. | ||
234 | * | ||
235 | * @param handle connection to cadet to disconnect | ||
236 | */ | ||
237 | void | ||
238 | GNUNET_CADET_disconnect (struct GNUNET_CADET_Handle *handle); | ||
239 | |||
240 | |||
241 | /** | ||
242 | * Create a new channel towards a remote peer. | ||
243 | * | ||
244 | * If the destination port is not open by any peer or the destination peer | ||
245 | * does not accept the channel, #GNUNET_CADET_ChannelEndHandler will be called | ||
246 | * for this channel. | ||
247 | * | ||
248 | * @param h cadet handle | ||
249 | * @param channel_ctx client's channel context to associate with the channel | ||
250 | * @param peer peer identity the channel should go to | ||
251 | * @param port Port number. | ||
252 | * @param options CadetOption flag field, with all desired option bits set to 1. | ||
253 | * | ||
254 | * @return handle to the channel | ||
255 | */ | ||
256 | struct GNUNET_CADET_Channel * | ||
257 | GNUNET_CADET_channel_create (struct GNUNET_CADET_Handle *h, | ||
258 | void *channel_ctx, | ||
259 | const struct GNUNET_PeerIdentity *peer, | ||
260 | uint32_t port, | ||
261 | enum GNUNET_CADET_ChannelOption options); | ||
262 | |||
263 | |||
264 | /** | ||
265 | * Destroy an existing channel. | ||
266 | * | ||
267 | * The existing end callback for the channel will be called immediately. | ||
268 | * Any pending outgoing messages will be sent but no incoming messages will be | ||
269 | * accepted and no data callbacks will be called. | ||
270 | * | ||
271 | * @param channel Channel handle, becomes invalid after this call. | ||
272 | */ | ||
273 | void | ||
274 | GNUNET_CADET_channel_destroy (struct GNUNET_CADET_Channel *channel); | ||
275 | |||
276 | |||
277 | /** | ||
278 | * Struct to retrieve info about a channel. | ||
279 | */ | ||
280 | union GNUNET_CADET_ChannelInfo | ||
281 | { | ||
282 | |||
283 | /** | ||
284 | * #GNUNET_YES / #GNUNET_NO, for binary flags. | ||
285 | */ | ||
286 | int yes_no; | ||
287 | |||
288 | /** | ||
289 | * Peer on the other side of the channel | ||
290 | */ | ||
291 | const struct GNUNET_PeerIdentity peer; | ||
292 | }; | ||
293 | |||
294 | |||
295 | /** | ||
296 | * Get information about a channel. | ||
297 | * | ||
298 | * @param channel Channel handle. | ||
299 | * @param option Query type GNUNET_CADET_OPTION_* | ||
300 | * @param ... dependant on option, currently not used | ||
301 | * @return Union with an answer to the query. | ||
302 | */ | ||
303 | const union GNUNET_CADET_ChannelInfo * | ||
304 | GNUNET_CADET_channel_get_info (struct GNUNET_CADET_Channel *channel, | ||
305 | enum GNUNET_CADET_ChannelOption option, ...); | ||
306 | |||
307 | |||
308 | /** | ||
309 | * Handle for a transmission request. | ||
310 | */ | ||
311 | struct GNUNET_CADET_TransmitHandle; | ||
312 | |||
313 | |||
314 | /** | ||
315 | * Ask the cadet to call @a notify once it is ready to transmit the | ||
316 | * given number of bytes to the specified channel. | ||
317 | * Only one call can be active at any time, to issue another request, | ||
318 | * wait for the callback or cancel the current request. | ||
319 | * | ||
320 | * @param channel channel to use for transmission | ||
321 | * @param cork is corking allowed for this transmission? | ||
322 | * @param maxdelay how long can the message wait? | ||
323 | * @param notify_size how many bytes of buffer space does notify want? | ||
324 | * @param notify function to call when buffer space is available; | ||
325 | * will be called with NULL on timeout or if the overall queue | ||
326 | * for this peer is larger than queue_size and this is currently | ||
327 | * the message with the lowest priority | ||
328 | * @param notify_cls closure for @a notify | ||
329 | * @return non-NULL if the notify callback was queued, | ||
330 | * NULL if we can not even queue the request (insufficient | ||
331 | * memory); if NULL is returned, @a notify will NOT be called. | ||
332 | */ | ||
333 | struct GNUNET_CADET_TransmitHandle * | ||
334 | GNUNET_CADET_notify_transmit_ready (struct GNUNET_CADET_Channel *channel, | ||
335 | int cork, | ||
336 | struct GNUNET_TIME_Relative maxdelay, | ||
337 | size_t notify_size, | ||
338 | GNUNET_CONNECTION_TransmitReadyNotify notify, | ||
339 | void *notify_cls); | ||
340 | |||
341 | |||
342 | /** | ||
343 | * Cancel the specified transmission-ready notification. | ||
344 | * | ||
345 | * @param th handle that was returned by "notify_transmit_ready". | ||
346 | */ | ||
347 | void | ||
348 | GNUNET_CADET_notify_transmit_ready_cancel (struct GNUNET_CADET_TransmitHandle | ||
349 | *th); | ||
350 | |||
351 | |||
352 | /** | ||
353 | * Indicate readiness to receive the next message on a channel. | ||
354 | * | ||
355 | * Should only be called once per handler called. | ||
356 | * | ||
357 | * @param channel Channel that will be allowed to call another handler. | ||
358 | */ | ||
359 | void | ||
360 | GNUNET_CADET_receive_done (struct GNUNET_CADET_Channel *channel); | ||
361 | |||
362 | |||
363 | |||
364 | /******************************************************************************/ | ||
365 | /******************** MONITORING /DEBUG API *************************/ | ||
366 | /******************************************************************************/ | ||
367 | /* The following calls are not useful for normal CADET operation, but for */ | ||
368 | /* debug and monitoring of the cadet state. They can be safely ignored. */ | ||
369 | /* The API can change at any point without notice. */ | ||
370 | /* Please contact the developer if you consider any of this calls useful for */ | ||
371 | /* normal cadet applications. */ | ||
372 | /******************************************************************************/ | ||
373 | |||
374 | |||
375 | /** | ||
376 | * Method called to retrieve information about a specific channel the cadet peer | ||
377 | * is aware of, including all transit nodes. | ||
378 | * | ||
379 | * @param cls Closure. | ||
380 | * @param root Root of the channel. | ||
381 | * @param dest Destination of the channel. | ||
382 | * @param port Destination port of the channel. | ||
383 | * @param root_channel_number Local number for root, if known. | ||
384 | * @param dest_channel_number Local number for dest, if known. | ||
385 | * @param public_channel_numbe Number for P2P, always known. | ||
386 | */ | ||
387 | typedef void (*GNUNET_CADET_ChannelCB) (void *cls, | ||
388 | const struct GNUNET_PeerIdentity *root, | ||
389 | const struct GNUNET_PeerIdentity *dest, | ||
390 | uint32_t port, | ||
391 | uint32_t root_channel_number, | ||
392 | uint32_t dest_channel_number, | ||
393 | uint32_t public_channel_number); | ||
394 | |||
395 | /** | ||
396 | * Method called to retrieve information about all peers in CADET, called | ||
397 | * once per peer. | ||
398 | * | ||
399 | * After last peer has been reported, an additional call with NULL is done. | ||
400 | * | ||
401 | * @param cls Closure. | ||
402 | * @param peer Peer, or NULL on "EOF". | ||
403 | * @param tunnel Do we have a tunnel towards this peer? | ||
404 | * @param n_paths Number of known paths towards this peer. | ||
405 | * @param best_path How long is the best path? | ||
406 | * (0 = unknown, 1 = ourselves, 2 = neighbor) | ||
407 | */ | ||
408 | typedef void (*GNUNET_CADET_PeersCB) (void *cls, | ||
409 | const struct GNUNET_PeerIdentity *peer, | ||
410 | int tunnel, unsigned int n_paths, | ||
411 | unsigned int best_path); | ||
412 | |||
413 | /** | ||
414 | * Method called to retrieve information about a specific peer | ||
415 | * known to the service. | ||
416 | * | ||
417 | * @param cls Closure. | ||
418 | * @param peer Peer ID. | ||
419 | * @param tunnel Do we have a tunnel towards this peer? #GNUNET_YES/#GNUNET_NO | ||
420 | * @param neighbor Is this a direct neighbor? #GNUNET_YES/#GNUNET_NO | ||
421 | * @param n_paths Number of paths known towards peer. | ||
422 | * @param paths Array of PEER_IDs representing all paths to reach the peer. | ||
423 | * Each path starts with the local peer. | ||
424 | * Each path ends with the destination peer (given in @c peer). | ||
425 | */ | ||
426 | typedef void (*GNUNET_CADET_PeerCB) (void *cls, | ||
427 | const struct GNUNET_PeerIdentity *peer, | ||
428 | int tunnel, | ||
429 | int neighbor, | ||
430 | unsigned int n_paths, | ||
431 | struct GNUNET_PeerIdentity *paths); | ||
432 | |||
433 | |||
434 | /** | ||
435 | * Method called to retrieve information about all tunnels in CADET, called | ||
436 | * once per tunnel. | ||
437 | * | ||
438 | * After last tunnel has been reported, an additional call with NULL is done. | ||
439 | * | ||
440 | * @param cls Closure. | ||
441 | * @param peer Destination peer, or NULL on "EOF". | ||
442 | * @param channels Number of channels. | ||
443 | * @param connections Number of connections. | ||
444 | * @param estate Encryption state. | ||
445 | * @param cstate Connectivity state. | ||
446 | */ | ||
447 | typedef void (*GNUNET_CADET_TunnelsCB) (void *cls, | ||
448 | const struct GNUNET_PeerIdentity *peer, | ||
449 | unsigned int channels, | ||
450 | unsigned int connections, | ||
451 | uint16_t estate, | ||
452 | uint16_t cstate); | ||
453 | |||
454 | |||
455 | |||
456 | /** | ||
457 | * Method called to retrieve information about a specific tunnel the cadet peer | ||
458 | * has established, o`r is trying to establish. | ||
459 | * | ||
460 | * @param cls Closure. | ||
461 | * @param peer Peer towards whom the tunnel is directed. | ||
462 | * @param n_channels Number of channels. | ||
463 | * @param n_connections Number of connections. | ||
464 | * @param channels Channels. | ||
465 | * @param connections Connections. | ||
466 | * @param estate Encryption state. | ||
467 | * @param cstate Connectivity state. | ||
468 | */ | ||
469 | typedef void (*GNUNET_CADET_TunnelCB) (void *cls, | ||
470 | const struct GNUNET_PeerIdentity *peer, | ||
471 | unsigned int n_channels, | ||
472 | unsigned int n_connections, | ||
473 | uint32_t *channels, | ||
474 | struct GNUNET_CADET_Hash *connections, | ||
475 | unsigned int estate, | ||
476 | unsigned int cstate); | ||
477 | |||
478 | /** | ||
479 | * Request information about a specific channel of the running cadet peer. | ||
480 | * | ||
481 | * WARNING: unstable API, likely to change in the future! | ||
482 | * | ||
483 | * @param h Handle to the cadet peer. | ||
484 | * @param peer ID of the other end of the channel. | ||
485 | * @param channel_number Channel number. | ||
486 | * @param callback Function to call with the requested data. | ||
487 | * @param callback_cls Closure for @c callback. | ||
488 | */ | ||
489 | void | ||
490 | GNUNET_CADET_get_channel (struct GNUNET_CADET_Handle *h, | ||
491 | struct GNUNET_PeerIdentity *peer, | ||
492 | uint32_t channel_number, | ||
493 | GNUNET_CADET_ChannelCB callback, | ||
494 | void *callback_cls); | ||
495 | |||
496 | |||
497 | /** | ||
498 | * Request information about peers known to the running cadet service. | ||
499 | * The callback will be called for every peer known to the service. | ||
500 | * Only one info request (of any kind) can be active at once. | ||
501 | * | ||
502 | * | ||
503 | * WARNING: unstable API, likely to change in the future! | ||
504 | * | ||
505 | * @param h Handle to the cadet peer. | ||
506 | * @param callback Function to call with the requested data. | ||
507 | * @param callback_cls Closure for @c callback. | ||
508 | * | ||
509 | * @return #GNUNET_OK / #GNUNET_SYSERR | ||
510 | */ | ||
511 | int | ||
512 | GNUNET_CADET_get_peers (struct GNUNET_CADET_Handle *h, | ||
513 | GNUNET_CADET_PeersCB callback, | ||
514 | void *callback_cls); | ||
515 | |||
516 | /** | ||
517 | * Cancel a peer info request. The callback will not be called (anymore). | ||
518 | * | ||
519 | * WARNING: unstable API, likely to change in the future! | ||
520 | * | ||
521 | * @param h Cadet handle. | ||
522 | * | ||
523 | * @return Closure given to GNUNET_CADET_get_peers. | ||
524 | */ | ||
525 | void * | ||
526 | GNUNET_CADET_get_peers_cancel (struct GNUNET_CADET_Handle *h); | ||
527 | |||
528 | |||
529 | /** | ||
530 | * Request information about a peer known to the running cadet peer. | ||
531 | * The callback will be called for the tunnel once. | ||
532 | * Only one info request (of any kind) can be active at once. | ||
533 | * | ||
534 | * WARNING: unstable API, likely to change in the future! | ||
535 | * | ||
536 | * @param h Handle to the cadet peer. | ||
537 | * @param id Peer whose tunnel to examine. | ||
538 | * @param callback Function to call with the requested data. | ||
539 | * @param callback_cls Closure for @c callback. | ||
540 | * | ||
541 | * @return #GNUNET_OK / #GNUNET_SYSERR | ||
542 | */ | ||
543 | int | ||
544 | GNUNET_CADET_get_peer (struct GNUNET_CADET_Handle *h, | ||
545 | const struct GNUNET_PeerIdentity *id, | ||
546 | GNUNET_CADET_PeerCB callback, | ||
547 | void *callback_cls); | ||
548 | |||
549 | /** | ||
550 | * Request information about tunnels of the running cadet peer. | ||
551 | * The callback will be called for every tunnel of the service. | ||
552 | * Only one info request (of any kind) can be active at once. | ||
553 | * | ||
554 | * WARNING: unstable API, likely to change in the future! | ||
555 | * | ||
556 | * @param h Handle to the cadet peer. | ||
557 | * @param callback Function to call with the requested data. | ||
558 | * @param callback_cls Closure for @c callback. | ||
559 | * | ||
560 | * @return #GNUNET_OK / #GNUNET_SYSERR | ||
561 | */ | ||
562 | int | ||
563 | GNUNET_CADET_get_tunnels (struct GNUNET_CADET_Handle *h, | ||
564 | GNUNET_CADET_TunnelsCB callback, | ||
565 | void *callback_cls); | ||
566 | |||
567 | /** | ||
568 | * Cancel a monitor request. The monitor callback will not be called. | ||
569 | * | ||
570 | * @param h Cadet handle. | ||
571 | * | ||
572 | * @return Closure given to GNUNET_CADET_monitor, if any. | ||
573 | */ | ||
574 | void * | ||
575 | GNUNET_CADET_get_tunnels_cancel (struct GNUNET_CADET_Handle *h); | ||
576 | |||
577 | |||
578 | /** | ||
579 | * Request information about a tunnel of the running cadet peer. | ||
580 | * The callback will be called for the tunnel once. | ||
581 | * Only one info request (of any kind) can be active at once. | ||
582 | * | ||
583 | * WARNING: unstable API, likely to change in the future! | ||
584 | * | ||
585 | * @param h Handle to the cadet peer. | ||
586 | * @param id Peer whose tunnel to examine. | ||
587 | * @param callback Function to call with the requested data. | ||
588 | * @param callback_cls Closure for @c callback. | ||
589 | * | ||
590 | * @return #GNUNET_OK / #GNUNET_SYSERR | ||
591 | */ | ||
592 | int | ||
593 | GNUNET_CADET_get_tunnel (struct GNUNET_CADET_Handle *h, | ||
594 | const struct GNUNET_PeerIdentity *id, | ||
595 | GNUNET_CADET_TunnelCB callback, | ||
596 | void *callback_cls); | ||
597 | |||
598 | /** | ||
599 | * Create a message queue for a cadet channel. | ||
600 | * The message queue can only be used to transmit messages, | ||
601 | * not to receive them. | ||
602 | * | ||
603 | * @param channel the channel to create the message qeue for | ||
604 | * @return a message queue to messages over the channel | ||
605 | */ | ||
606 | struct GNUNET_MQ_Handle * | ||
607 | GNUNET_CADET_mq_create (struct GNUNET_CADET_Channel *channel); | ||
608 | |||
609 | |||
610 | #if 0 /* keep Emacsens' auto-indent happy */ | ||
611 | { | ||
612 | #endif | ||
613 | #ifdef __cplusplus | ||
614 | } | ||
615 | #endif | ||
616 | |||
617 | /* ifndef GNUNET_CADET_SERVICE_H */ | ||
618 | #endif | ||
619 | /* end of gnunet_cadet_service.h */ | ||