diff options
author | Christian Grothoff <christian@grothoff.org> | 2017-03-13 01:33:06 +0100 |
---|---|---|
committer | Christian Grothoff <christian@grothoff.org> | 2017-03-13 01:33:15 +0100 |
commit | ba32b87dd8c99a85ffe5d620d9ad20b43abf7345 (patch) | |
tree | e4bf6b703359f04f855274bb5640d33201a58156 /src/include | |
parent | 01523e0c445460302a71077dfaa735d4c52e9a45 (diff) | |
download | gnunet-ba32b87dd8c99a85ffe5d620d9ad20b43abf7345.tar.gz gnunet-ba32b87dd8c99a85ffe5d620d9ad20b43abf7345.zip |
getting rid of the old cadet client library (pre-MQ)
Diffstat (limited to 'src/include')
-rw-r--r-- | src/include/gnunet_cadet_service.h | 525 |
1 files changed, 153 insertions, 372 deletions
diff --git a/src/include/gnunet_cadet_service.h b/src/include/gnunet_cadet_service.h index fd838df8d..8d3d4326b 100644 --- a/src/include/gnunet_cadet_service.h +++ b/src/include/gnunet_cadet_service.h | |||
@@ -49,7 +49,7 @@ extern "C" | |||
49 | /** | 49 | /** |
50 | * Version number of GNUnet-cadet API. | 50 | * Version number of GNUnet-cadet API. |
51 | */ | 51 | */ |
52 | #define GNUNET_CADET_VERSION 0x00000004 | 52 | #define GNUNET_CADET_VERSION 0x00000005 |
53 | 53 | ||
54 | 54 | ||
55 | /** | 55 | /** |
@@ -69,6 +69,33 @@ struct GNUNET_CADET_Port; | |||
69 | 69 | ||
70 | 70 | ||
71 | /** | 71 | /** |
72 | * Hash uniquely identifying a connection below a tunnel. | ||
73 | */ | ||
74 | struct GNUNET_CADET_ConnectionTunnelIdentifier | ||
75 | { | ||
76 | struct GNUNET_ShortHashCode connection_of_tunnel; | ||
77 | }; | ||
78 | |||
79 | |||
80 | /** | ||
81 | * Number identifying a CADET channel within a tunnel. | ||
82 | */ | ||
83 | struct GNUNET_CADET_ChannelTunnelNumber | ||
84 | { | ||
85 | /** | ||
86 | * Which number does this channel have that uniquely identfies | ||
87 | * it within its tunnel, in network byte order. | ||
88 | * | ||
89 | * Given two peers, both may initiate channels over the same tunnel. | ||
90 | * The @e cn must be greater or equal to 0x80000000 (high-bit set) | ||
91 | * for tunnels initiated with the peer that has the larger peer | ||
92 | * identity as compared using #GNUNET_CRYPTO_cmp_peer_identity(). | ||
93 | */ | ||
94 | uint32_t cn GNUNET_PACKED; | ||
95 | }; | ||
96 | |||
97 | |||
98 | /** | ||
72 | * Channel options. Second line indicates filed in the | 99 | * Channel options. Second line indicates filed in the |
73 | * CadetChannelInfo union carrying the answer. | 100 | * CadetChannelInfo union carrying the answer. |
74 | */ | 101 | */ |
@@ -108,118 +135,67 @@ enum GNUNET_CADET_ChannelOption | |||
108 | 135 | ||
109 | 136 | ||
110 | /** | 137 | /** |
111 | * Functions with this signature are called whenever a message is | 138 | * Method called whenever a peer connects to a port in MQ-based CADET. |
112 | * received. | ||
113 | * | ||
114 | * Each time the function must call #GNUNET_CADET_receive_done on the channel | ||
115 | * in order to receive the next message. This doesn't need to be immediate: | ||
116 | * can be delayed if some processing is done on the message. | ||
117 | * | 139 | * |
118 | * @param cls Closure (set from #GNUNET_CADET_connect). | 140 | * @param cls Closure from #GNUNET_CADET_open_porT. |
119 | * @param channel Connection to the other end. | 141 | * @param channel New handle to the channel. |
120 | * @param channel_ctx Place to store local state associated with the channel. | 142 | * @param source Peer that started this channel. |
121 | * @param message The actual message. | 143 | * @return Closure for the incoming @a channel. It's given to: |
122 | * @return #GNUNET_OK to keep the channel open, | 144 | * - The #GNUNET_CADET_DisconnectEventHandler (given to |
123 | * #GNUNET_SYSERR to close it (signal serious error). | 145 | * #GNUNET_CADET_open_porT) when the channel dies. |
124 | */ | 146 | * - Each the #GNUNET_MQ_MessageCallback handlers for each message |
125 | typedef int | 147 | * received on the @a channel. |
126 | (*GNUNET_CADET_MessageCallback) (void *cls, | ||
127 | struct GNUNET_CADET_Channel *channel, | ||
128 | void **channel_ctx, | ||
129 | const struct GNUNET_MessageHeader *message); | ||
130 | |||
131 | |||
132 | /** | ||
133 | * Message handler. Each struct specifies how to handle on particular | ||
134 | * type of message received. | ||
135 | */ | 148 | */ |
136 | struct GNUNET_CADET_MessageHandler | 149 | typedef void * |
137 | { | 150 | (*GNUNET_CADET_ConnectEventHandler) (void *cls, |
138 | /** | 151 | struct GNUNET_CADET_Channel *channel, |
139 | * Function to call for messages of type @e type. | 152 | const struct GNUNET_PeerIdentity *source); |
140 | */ | ||
141 | GNUNET_CADET_MessageCallback callback; | ||
142 | |||
143 | /** | ||
144 | * Type of the message this handler covers. | ||
145 | */ | ||
146 | uint16_t type; | ||
147 | |||
148 | /** | ||
149 | * Expected size of messages of this type. Use 0 for variable-size. | ||
150 | * If non-zero, messages of the given type will be discarded if they | ||
151 | * do not have the right size. | ||
152 | */ | ||
153 | uint16_t expected_size; | ||
154 | }; | ||
155 | 153 | ||
156 | 154 | ||
157 | /** | 155 | /** |
158 | * Method called whenever another peer has added us to a channel | 156 | * Function called whenever an MQ-channel is destroyed, even if the destruction |
159 | * the other peer initiated. | 157 | * was requested by #GNUNET_CADET_channel_destroy. |
160 | * Only called (once) upon reception of data with a message type which was | 158 | * It must NOT call #GNUNET_CADET_channel_destroy on the channel. |
161 | * subscribed to in #GNUNET_CADET_connect. | ||
162 | * | ||
163 | * A call to #GNUNET_CADET_channel_destroy causes te channel to be ignored. In | ||
164 | * this case the handler MUST return NULL. | ||
165 | * | 159 | * |
166 | * @param cls closure | 160 | * It should clean up any associated state, including cancelling any pending |
167 | * @param channel new handle to the channel | 161 | * transmission on this channel. |
168 | * @param initiator peer that started the channel | ||
169 | * @param port Port this channel is for. | ||
170 | * @param options CadetOption flag field, with all active option bits set to 1. | ||
171 | * | 162 | * |
172 | * @return initial channel context for the channel | 163 | * @param cls Channel closure. |
173 | * (can be NULL -- that's not an error) | 164 | * @param channel Connection to the other end (henceforth invalid). |
174 | */ | 165 | */ |
175 | typedef void * | 166 | typedef void |
176 | (GNUNET_CADET_InboundChannelNotificationHandler) (void *cls, | 167 | (*GNUNET_CADET_DisconnectEventHandler) (void *cls, |
177 | struct GNUNET_CADET_Channel *channel, | 168 | const struct GNUNET_CADET_Channel *channel); |
178 | const struct GNUNET_PeerIdentity *initiator, | ||
179 | const struct GNUNET_HashCode *port, | ||
180 | enum GNUNET_CADET_ChannelOption options); | ||
181 | 169 | ||
182 | 170 | ||
183 | /** | 171 | /** |
184 | * Function called whenever a channel is destroyed. Should clean up | 172 | * Function called whenever an MQ-channel's transmission window size changes. |
185 | * any associated state, including cancelling any pending transmission on this | ||
186 | * channel. | ||
187 | * | 173 | * |
188 | * It must NOT call #GNUNET_CADET_channel_destroy on the channel. | 174 | * The first callback in an outgoing channel will be with a non-zero value |
175 | * and will mean the channel is connected to the destination. | ||
176 | * | ||
177 | * For an incoming channel it will be called immediately after the | ||
178 | * #GNUNET_CADET_ConnectEventHandler, also with a non-zero value. | ||
189 | * | 179 | * |
190 | * @param cls closure (set from #GNUNET_CADET_connect) | 180 | * @param cls Channel closure. |
191 | * @param channel connection to the other end (henceforth invalid) | 181 | * @param channel Connection to the other end --- FIXME: drop? |
192 | * @param channel_ctx place where local state associated | 182 | * @param window_size New window size. If the is more messages than buffer size |
193 | * with the channel is stored | 183 | * this value will be negative. -- FIXME: make unsigned, we never call negative? |
194 | */ | 184 | */ |
195 | typedef void | 185 | typedef void |
196 | (GNUNET_CADET_ChannelEndHandler) (void *cls, | 186 | (*GNUNET_CADET_WindowSizeEventHandler) (void *cls, |
197 | const struct GNUNET_CADET_Channel *channel, | 187 | const struct GNUNET_CADET_Channel *channel, |
198 | void *channel_ctx); | 188 | int window_size); |
199 | 189 | ||
200 | 190 | ||
201 | /** | 191 | /** |
202 | * Connect to the cadet service. | 192 | * Connect to the MQ-based cadet service. |
203 | * | 193 | * |
204 | * @param cfg Configuration to use. | 194 | * @param cfg Configuration to use. |
205 | * @param cls Closure for the various callbacks that follow (including | 195 | * @return Handle to the cadet service NULL on error. |
206 | * handlers in the handlers array). | ||
207 | * @param cleaner Function called when a channel is destroyed. | ||
208 | * It is called immediately if #GNUNET_CADET_channel_destroy | ||
209 | * is called on the channel. | ||
210 | * @param handlers Callbacks for messages we care about, NULL-terminated. Each | ||
211 | * one must call #GNUNET_CADET_receive_done on the channel to | ||
212 | * receive the next message. Messages of a type that is not | ||
213 | * in the handlers array are ignored if received. | ||
214 | * | ||
215 | * @return handle to the cadet service NULL on error | ||
216 | * (in this case, init is never called) | ||
217 | */ | 196 | */ |
218 | struct GNUNET_CADET_Handle * | 197 | struct GNUNET_CADET_Handle * |
219 | GNUNET_CADET_connect (const struct GNUNET_CONFIGURATION_Handle *cfg, | 198 | GNUNET_CADET_connecT (const struct GNUNET_CONFIGURATION_Handle *cfg); |
220 | void *cls, | ||
221 | GNUNET_CADET_ChannelEndHandler cleaner, | ||
222 | const struct GNUNET_CADET_MessageHandler *handlers); | ||
223 | 199 | ||
224 | 200 | ||
225 | /** | 201 | /** |
@@ -233,21 +209,29 @@ GNUNET_CADET_connect (const struct GNUNET_CONFIGURATION_Handle *cfg, | |||
233 | void | 209 | void |
234 | GNUNET_CADET_disconnect (struct GNUNET_CADET_Handle *handle); | 210 | GNUNET_CADET_disconnect (struct GNUNET_CADET_Handle *handle); |
235 | 211 | ||
212 | |||
236 | /** | 213 | /** |
237 | * Open a port to receive incomming channels. | 214 | * Open a port to receive incomming MQ-based channels. |
238 | * | 215 | * |
239 | * @param h CADET handle. | 216 | * @param h CADET handle. |
240 | * @param port Hash representing the port number. | 217 | * @param port Hash identifying the port. |
241 | * @param new_channel Function called when an channel is received. | 218 | * @param connects Function called when an incoming channel is connected. |
242 | * @param new_channel_cls Closure for @a new_channel. | 219 | * @param connects_cls Closure for the @a connects handler. |
243 | * | 220 | * @param window_changes Function called when the transmit window size changes. |
221 | * Can be NULL. | ||
222 | * @param disconnects Function called when a channel is disconnected. | ||
223 | * @param handlers Callbacks for messages we care about, NULL-terminated. | ||
244 | * @return Port handle. | 224 | * @return Port handle. |
245 | */ | 225 | */ |
246 | struct GNUNET_CADET_Port * | 226 | struct GNUNET_CADET_Port * |
247 | GNUNET_CADET_open_port (struct GNUNET_CADET_Handle *h, | 227 | GNUNET_CADET_open_porT (struct GNUNET_CADET_Handle *h, |
248 | const struct GNUNET_HashCode *port, | 228 | const struct GNUNET_HashCode *port, |
249 | GNUNET_CADET_InboundChannelNotificationHandler new_channel, | 229 | GNUNET_CADET_ConnectEventHandler connects, |
250 | void *new_channel_cls); | 230 | void *connects_cls, |
231 | GNUNET_CADET_WindowSizeEventHandler window_changes, | ||
232 | GNUNET_CADET_DisconnectEventHandler disconnects, | ||
233 | const struct GNUNET_MQ_MessageHandler *handlers); | ||
234 | |||
251 | 235 | ||
252 | /** | 236 | /** |
253 | * Close a port opened with @a GNUNET_CADET_open_port. | 237 | * Close a port opened with @a GNUNET_CADET_open_port. |
@@ -258,27 +242,38 @@ GNUNET_CADET_open_port (struct GNUNET_CADET_Handle *h, | |||
258 | void | 242 | void |
259 | GNUNET_CADET_close_port (struct GNUNET_CADET_Port *p); | 243 | GNUNET_CADET_close_port (struct GNUNET_CADET_Port *p); |
260 | 244 | ||
245 | |||
261 | /** | 246 | /** |
262 | * Create a new channel towards a remote peer. | 247 | * Create a new channel towards a remote peer. |
263 | * | 248 | * |
264 | * If the destination port is not open by any peer or the destination peer | 249 | * If the destination port is not open by any peer or the destination peer |
265 | * does not accept the channel, #GNUNET_CADET_ChannelEndHandler will be called | 250 | * does not accept the channel, @a disconnects will be called |
266 | * for this channel. | 251 | * for this channel. |
267 | * | 252 | * |
268 | * @param h cadet handle | 253 | * @param h CADET handle. |
269 | * @param channel_ctx client's channel context to associate with the channel | 254 | * @param channel_cls Closure for the channel. It's given to: |
270 | * @param peer peer identity the channel should go to | 255 | * - The management handler @a window_changes. |
271 | * @param port Port hash (port number). | 256 | * - The disconnect handler @a disconnects |
257 | * - Each message type callback in @a handlers | ||
258 | * @param destination Peer identity the channel should go to. | ||
259 | * @param port Identification of the destination port. | ||
272 | * @param options CadetOption flag field, with all desired option bits set to 1. | 260 | * @param options CadetOption flag field, with all desired option bits set to 1. |
273 | * | 261 | * @param window_changes Function called when the transmit window size changes. |
274 | * @return handle to the channel | 262 | * Can be NULL if this data is of no interest. |
263 | * TODO Not yet implemented. | ||
264 | * @param disconnects Function called when the channel is disconnected. | ||
265 | * @param handlers Callbacks for messages we care about, NULL-terminated. | ||
266 | * @return Handle to the channel. | ||
275 | */ | 267 | */ |
276 | struct GNUNET_CADET_Channel * | 268 | struct GNUNET_CADET_Channel * |
277 | GNUNET_CADET_channel_create (struct GNUNET_CADET_Handle *h, | 269 | GNUNET_CADET_channel_creatE (struct GNUNET_CADET_Handle *h, |
278 | void *channel_ctx, | 270 | void *channel_cls, |
279 | const struct GNUNET_PeerIdentity *peer, | 271 | const struct GNUNET_PeerIdentity *destination, |
280 | const struct GNUNET_HashCode *port, | 272 | const struct GNUNET_HashCode *port, |
281 | enum GNUNET_CADET_ChannelOption options); | 273 | enum GNUNET_CADET_ChannelOption options, |
274 | GNUNET_CADET_WindowSizeEventHandler window_changes, | ||
275 | GNUNET_CADET_DisconnectEventHandler disconnects, | ||
276 | const struct GNUNET_MQ_MessageHandler *handlers); | ||
282 | 277 | ||
283 | 278 | ||
284 | /** | 279 | /** |
@@ -295,6 +290,52 @@ GNUNET_CADET_channel_destroy (struct GNUNET_CADET_Channel *channel); | |||
295 | 290 | ||
296 | 291 | ||
297 | /** | 292 | /** |
293 | * Obtain the message queue for a connected channel. | ||
294 | * | ||
295 | * @param channel The channel handle from which to get the MQ. | ||
296 | * @return The message queue of the channel. | ||
297 | */ | ||
298 | struct GNUNET_MQ_Handle * | ||
299 | GNUNET_CADET_get_mq (const struct GNUNET_CADET_Channel *channel); | ||
300 | |||
301 | |||
302 | /** | ||
303 | * Indicate readiness to receive the next message on a channel. | ||
304 | * | ||
305 | * Should only be called once per handler called. | ||
306 | * | ||
307 | * @param channel Channel that will be allowed to call another handler. | ||
308 | */ | ||
309 | void | ||
310 | GNUNET_CADET_receive_done (struct GNUNET_CADET_Channel *channel); | ||
311 | |||
312 | |||
313 | /******************************************************************************/ | ||
314 | /******************** MONITORING /DEBUG API *************************/ | ||
315 | /******************************************************************************/ | ||
316 | /* The following calls are not useful for normal CADET operation, but for */ | ||
317 | /* debug and monitoring of the cadet state. They can be safely ignored. */ | ||
318 | /* The API can change at any point without notice. */ | ||
319 | /* Please contact the developer if you consider any of this calls useful for */ | ||
320 | /* normal cadet applications. */ | ||
321 | /******************************************************************************/ | ||
322 | |||
323 | |||
324 | /** | ||
325 | * Transitional function to convert an unsigned int port to a hash value. | ||
326 | * WARNING: local static value returned, NOT reentrant! | ||
327 | * WARNING: do not use this function for new code! | ||
328 | * | ||
329 | * @param port Numerical port (unsigned int format). | ||
330 | * | ||
331 | * @return A GNUNET_HashCode usable for the new CADET API. | ||
332 | */ | ||
333 | const struct GNUNET_HashCode * | ||
334 | GC_u2h (uint32_t port); | ||
335 | |||
336 | |||
337 | |||
338 | /** | ||
298 | * Struct to retrieve info about a channel. | 339 | * Struct to retrieve info about a channel. |
299 | */ | 340 | */ |
300 | union GNUNET_CADET_ChannelInfo | 341 | union GNUNET_CADET_ChannelInfo |
@@ -327,76 +368,6 @@ GNUNET_CADET_channel_get_info (struct GNUNET_CADET_Channel *channel, | |||
327 | 368 | ||
328 | 369 | ||
329 | /** | 370 | /** |
330 | * Handle for a transmission request. | ||
331 | */ | ||
332 | struct GNUNET_CADET_TransmitHandle; | ||
333 | |||
334 | |||
335 | /** | ||
336 | * Ask the cadet to call @a notify once it is ready to transmit the | ||
337 | * given number of bytes to the specified channel. | ||
338 | * Only one call can be active at any time, to issue another request, | ||
339 | * wait for the callback or cancel the current request. | ||
340 | * | ||
341 | * @param channel channel to use for transmission | ||
342 | * @param cork is corking allowed for this transmission? | ||
343 | * @param maxdelay how long can the message wait? | ||
344 | * @param notify_size how many bytes of buffer space does notify want? | ||
345 | * @param notify function to call when buffer space is available; | ||
346 | * will be called with NULL on timeout or if the overall queue | ||
347 | * for this peer is larger than queue_size and this is currently | ||
348 | * the message with the lowest priority | ||
349 | * @param notify_cls closure for @a notify | ||
350 | * @return non-NULL if the notify callback was queued, | ||
351 | * NULL if we can not even queue the request (insufficient | ||
352 | * memory); if NULL is returned, @a notify will NOT be called. | ||
353 | */ | ||
354 | struct GNUNET_CADET_TransmitHandle * | ||
355 | GNUNET_CADET_notify_transmit_ready (struct GNUNET_CADET_Channel *channel, | ||
356 | int cork, | ||
357 | struct GNUNET_TIME_Relative maxdelay, | ||
358 | size_t notify_size, | ||
359 | GNUNET_CONNECTION_TransmitReadyNotify notify, | ||
360 | void *notify_cls); | ||
361 | |||
362 | |||
363 | /** | ||
364 | * Cancel the specified transmission-ready notification. | ||
365 | * | ||
366 | * #DEPRECATED | ||
367 | * Since soon we will send immediately with mq (via request_data), | ||
368 | * there will be time or need to cancel a "pending" transmission. | ||
369 | * | ||
370 | * @param th handle that was returned by "notify_transmit_ready". | ||
371 | */ | ||
372 | void | ||
373 | GNUNET_CADET_notify_transmit_ready_cancel (struct GNUNET_CADET_TransmitHandle *th); | ||
374 | |||
375 | |||
376 | /** | ||
377 | * Indicate readiness to receive the next message on a channel. | ||
378 | * | ||
379 | * Should only be called once per handler called. | ||
380 | * | ||
381 | * @param channel Channel that will be allowed to call another handler. | ||
382 | */ | ||
383 | void | ||
384 | GNUNET_CADET_receive_done (struct GNUNET_CADET_Channel *channel); | ||
385 | |||
386 | |||
387 | |||
388 | /******************************************************************************/ | ||
389 | /******************** MONITORING /DEBUG API *************************/ | ||
390 | /******************************************************************************/ | ||
391 | /* The following calls are not useful for normal CADET operation, but for */ | ||
392 | /* debug and monitoring of the cadet state. They can be safely ignored. */ | ||
393 | /* The API can change at any point without notice. */ | ||
394 | /* Please contact the developer if you consider any of this calls useful for */ | ||
395 | /* normal cadet applications. */ | ||
396 | /******************************************************************************/ | ||
397 | |||
398 | |||
399 | /** | ||
400 | * Method called to retrieve information about a specific channel the cadet peer | 371 | * Method called to retrieve information about a specific channel the cadet peer |
401 | * is aware of, including all transit nodes. | 372 | * is aware of, including all transit nodes. |
402 | * | 373 | * |
@@ -482,33 +453,6 @@ typedef void | |||
482 | 453 | ||
483 | 454 | ||
484 | /** | 455 | /** |
485 | * Hash uniquely identifying a connection below a tunnel. | ||
486 | */ | ||
487 | struct GNUNET_CADET_ConnectionTunnelIdentifier | ||
488 | { | ||
489 | struct GNUNET_ShortHashCode connection_of_tunnel; | ||
490 | }; | ||
491 | |||
492 | |||
493 | /** | ||
494 | * Number identifying a CADET channel within a tunnel. | ||
495 | */ | ||
496 | struct GNUNET_CADET_ChannelTunnelNumber | ||
497 | { | ||
498 | /** | ||
499 | * Which number does this channel have that uniquely identfies | ||
500 | * it within its tunnel, in network byte order. | ||
501 | * | ||
502 | * Given two peers, both may initiate channels over the same tunnel. | ||
503 | * The @e cn must be greater or equal to 0x80000000 (high-bit set) | ||
504 | * for tunnels initiated with the peer that has the larger peer | ||
505 | * identity as compared using #GNUNET_CRYPTO_cmp_peer_identity(). | ||
506 | */ | ||
507 | uint32_t cn GNUNET_PACKED; | ||
508 | }; | ||
509 | |||
510 | |||
511 | /** | ||
512 | * Method called to retrieve information about a specific tunnel the cadet peer | 456 | * Method called to retrieve information about a specific tunnel the cadet peer |
513 | * has established, o`r is trying to establish. | 457 | * has established, o`r is trying to establish. |
514 | * | 458 | * |
@@ -667,169 +611,6 @@ GNUNET_CADET_get_tunnel (struct GNUNET_CADET_Handle *h, | |||
667 | void *callback_cls); | 611 | void *callback_cls); |
668 | 612 | ||
669 | 613 | ||
670 | /** | ||
671 | * Create a message queue for a cadet channel. | ||
672 | * The message queue can only be used to transmit messages, | ||
673 | * not to receive them. | ||
674 | * | ||
675 | * @param channel the channel to create the message qeue for | ||
676 | * @return a message queue to messages over the channel | ||
677 | */ | ||
678 | struct GNUNET_MQ_Handle * | ||
679 | GNUNET_CADET_mq_create (struct GNUNET_CADET_Channel *channel); | ||
680 | |||
681 | |||
682 | /** | ||
683 | * Transitional function to convert an unsigned int port to a hash value. | ||
684 | * WARNING: local static value returned, NOT reentrant! | ||
685 | * WARNING: do not use this function for new code! | ||
686 | * | ||
687 | * @param port Numerical port (unsigned int format). | ||
688 | * | ||
689 | * @return A GNUNET_HashCode usable for the new CADET API. | ||
690 | */ | ||
691 | const struct GNUNET_HashCode * | ||
692 | GC_u2h (uint32_t port); | ||
693 | |||
694 | |||
695 | /******************************************************************************/ | ||
696 | /******************************* MQ-BASED API *********************************/ | ||
697 | /******************************************************************************/ | ||
698 | |||
699 | /** | ||
700 | * Method called whenever a peer connects to a port in MQ-based CADET. | ||
701 | * | ||
702 | * @param cls Closure from #GNUNET_CADET_open_porT. | ||
703 | * @param channel New handle to the channel. | ||
704 | * @param source Peer that started this channel. | ||
705 | * @return Closure for the incoming @a channel. It's given to: | ||
706 | * - The #GNUNET_CADET_DisconnectEventHandler (given to | ||
707 | * #GNUNET_CADET_open_porT) when the channel dies. | ||
708 | * - Each the #GNUNET_MQ_MessageCallback handlers for each message | ||
709 | * received on the @a channel. | ||
710 | */ | ||
711 | typedef void * | ||
712 | (*GNUNET_CADET_ConnectEventHandler) (void *cls, | ||
713 | struct GNUNET_CADET_Channel *channel, | ||
714 | const struct GNUNET_PeerIdentity *source); | ||
715 | |||
716 | |||
717 | /** | ||
718 | * Function called whenever an MQ-channel is destroyed, even if the destruction | ||
719 | * was requested by #GNUNET_CADET_channel_destroy. | ||
720 | * It must NOT call #GNUNET_CADET_channel_destroy on the channel. | ||
721 | * | ||
722 | * It should clean up any associated state, including cancelling any pending | ||
723 | * transmission on this channel. | ||
724 | * | ||
725 | * @param cls Channel closure. | ||
726 | * @param channel Connection to the other end (henceforth invalid). | ||
727 | */ | ||
728 | typedef void | ||
729 | (*GNUNET_CADET_DisconnectEventHandler) (void *cls, | ||
730 | const struct GNUNET_CADET_Channel *channel); | ||
731 | |||
732 | |||
733 | /** | ||
734 | * Function called whenever an MQ-channel's transmission window size changes. | ||
735 | * | ||
736 | * The first callback in an outgoing channel will be with a non-zero value | ||
737 | * and will mean the channel is connected to the destination. | ||
738 | * | ||
739 | * For an incoming channel it will be called immediately after the | ||
740 | * #GNUNET_CADET_ConnectEventHandler, also with a non-zero value. | ||
741 | * | ||
742 | * @param cls Channel closure. | ||
743 | * @param channel Connection to the other end --- FIXME: drop? | ||
744 | * @param window_size New window size. If the is more messages than buffer size | ||
745 | * this value will be negative. -- FIXME: make unsigned, we never call negative? | ||
746 | */ | ||
747 | typedef void | ||
748 | (*GNUNET_CADET_WindowSizeEventHandler) (void *cls, | ||
749 | const struct GNUNET_CADET_Channel *channel, | ||
750 | int window_size); | ||
751 | |||
752 | |||
753 | /** | ||
754 | * Connect to the MQ-based cadet service. | ||
755 | * | ||
756 | * @param cfg Configuration to use. | ||
757 | * @return Handle to the cadet service NULL on error. | ||
758 | */ | ||
759 | struct GNUNET_CADET_Handle * | ||
760 | GNUNET_CADET_connecT (const struct GNUNET_CONFIGURATION_Handle *cfg); | ||
761 | |||
762 | |||
763 | /** | ||
764 | * Open a port to receive incomming MQ-based channels. | ||
765 | * | ||
766 | * @param h CADET handle. | ||
767 | * @param port Hash identifying the port. | ||
768 | * @param connects Function called when an incoming channel is connected. | ||
769 | * @param connects_cls Closure for the @a connects handler. | ||
770 | * @param window_changes Function called when the transmit window size changes. | ||
771 | * Can be NULL. | ||
772 | * @param disconnects Function called when a channel is disconnected. | ||
773 | * @param handlers Callbacks for messages we care about, NULL-terminated. | ||
774 | * @return Port handle. | ||
775 | */ | ||
776 | struct GNUNET_CADET_Port * | ||
777 | GNUNET_CADET_open_porT (struct GNUNET_CADET_Handle *h, | ||
778 | const struct GNUNET_HashCode *port, | ||
779 | GNUNET_CADET_ConnectEventHandler connects, | ||
780 | void *connects_cls, | ||
781 | GNUNET_CADET_WindowSizeEventHandler window_changes, | ||
782 | GNUNET_CADET_DisconnectEventHandler disconnects, | ||
783 | const struct GNUNET_MQ_MessageHandler *handlers); | ||
784 | |||
785 | /** | ||
786 | * Create a new channel towards a remote peer. | ||
787 | * | ||
788 | * If the destination port is not open by any peer or the destination peer | ||
789 | * does not accept the channel, #GNUNET_CADET_ChannelEndHandler will be called | ||
790 | * for this channel. | ||
791 | * | ||
792 | * @param h CADET handle. | ||
793 | * @param channel_cls Closure for the channel. It's given to: | ||
794 | * - The management handler @a window_changes. | ||
795 | * - The disconnect handler @a disconnects | ||
796 | * - Each message type callback in @a handlers | ||
797 | * @param destination Peer identity the channel should go to. | ||
798 | * @param port Identification of the destination port. | ||
799 | * @param options CadetOption flag field, with all desired option bits set to 1. | ||
800 | * @param window_changes Function called when the transmit window size changes. | ||
801 | * Can be NULL if this data is of no interest. | ||
802 | * TODO Not yet implemented. | ||
803 | * @param disconnects Function called when the channel is disconnected. | ||
804 | * @param handlers Callbacks for messages we care about, NULL-terminated. | ||
805 | * @return Handle to the channel. | ||
806 | */ | ||
807 | struct GNUNET_CADET_Channel * | ||
808 | GNUNET_CADET_channel_creatE (struct GNUNET_CADET_Handle *h, | ||
809 | void *channel_cls, | ||
810 | const struct GNUNET_PeerIdentity *destination, | ||
811 | const struct GNUNET_HashCode *port, | ||
812 | enum GNUNET_CADET_ChannelOption options, | ||
813 | GNUNET_CADET_WindowSizeEventHandler window_changes, | ||
814 | GNUNET_CADET_DisconnectEventHandler disconnects, | ||
815 | const struct GNUNET_MQ_MessageHandler *handlers); | ||
816 | |||
817 | |||
818 | /** | ||
819 | * Obtain the message queue for a connected channel. | ||
820 | * | ||
821 | * @param channel The channel handle from which to get the MQ. | ||
822 | * @return The message queue of the channel. | ||
823 | */ | ||
824 | struct GNUNET_MQ_Handle * | ||
825 | GNUNET_CADET_get_mq (const struct GNUNET_CADET_Channel *channel); | ||
826 | |||
827 | |||
828 | /******************************************************************************/ | ||
829 | /******************************* MQ-BASED API *********************************/ | ||
830 | /******************************************************************************/ | ||
831 | |||
832 | |||
833 | 614 | ||
834 | #if 0 /* keep Emacsens' auto-indent happy */ | 615 | #if 0 /* keep Emacsens' auto-indent happy */ |
835 | { | 616 | { |