diff options
author | Gabor X Toth <*@tg-x.net> | 2013-06-27 10:05:03 +0000 |
---|---|---|
committer | Gabor X Toth <*@tg-x.net> | 2013-06-27 10:05:03 +0000 |
commit | ef5e0b8e72732876ebf03538b6fb3641ba7039e8 (patch) | |
tree | c650ecb605e67bf0c5f0e352a126e9265856e7f7 /src/include/gnunet_multicast_service.h | |
parent | b569b94c466a281e0996dedb09650d77f6dbdf5b (diff) | |
download | gnunet-ef5e0b8e72732876ebf03538b6fb3641ba7039e8.tar.gz gnunet-ef5e0b8e72732876ebf03538b6fb3641ba7039e8.zip |
multicast: messages types; function & callback for ping/pong messages; separate join/leave callbacks
Diffstat (limited to 'src/include/gnunet_multicast_service.h')
-rw-r--r-- | src/include/gnunet_multicast_service.h | 245 |
1 files changed, 149 insertions, 96 deletions
diff --git a/src/include/gnunet_multicast_service.h b/src/include/gnunet_multicast_service.h index 39987f043..588ae55c3 100644 --- a/src/include/gnunet_multicast_service.h +++ b/src/include/gnunet_multicast_service.h | |||
@@ -95,61 +95,6 @@ enum GNUNET_MULTICAST_JoinPolicy | |||
95 | }; | 95 | }; |
96 | 96 | ||
97 | 97 | ||
98 | /** | ||
99 | * Opaque handle to a replay request from the multicast service. | ||
100 | */ | ||
101 | struct GNUNET_MULTICAST_ReplayHandle; | ||
102 | |||
103 | |||
104 | /** | ||
105 | * Functions with this signature are called whenever the multicast | ||
106 | * service needs a message to be replayed. Implementations of this | ||
107 | * function MUST call GNUNET_MULTICAST_replay() ONCE (with a message | ||
108 | * or an error); however, if the origin is destroyed or the group is | ||
109 | * left, the replay handle must no longer be used. | ||
110 | * | ||
111 | * @param cls Closure (set from GNUNET_MULTICAST_origin_start() | ||
112 | * or GNUNET_MULTICAST_member_join()). | ||
113 | * @param message_id Which message should be replayed. | ||
114 | * @param rh Handle to pass to message transmit function. | ||
115 | */ | ||
116 | typedef void (*GNUNET_MULTICAST_ReplayCallback) (void *cls, | ||
117 | uint64_t message_id, | ||
118 | struct GNUNET_MULTICAST_ReplayHandle *rh); | ||
119 | |||
120 | |||
121 | /** | ||
122 | * Possible error codes during replay. | ||
123 | */ | ||
124 | enum GNUNET_MULTICAST_ReplayErrorCode | ||
125 | { | ||
126 | |||
127 | /** | ||
128 | * Everything is fine. | ||
129 | */ | ||
130 | GNUNET_MULTICAST_REC_OK = 0, | ||
131 | |||
132 | /** | ||
133 | * Message has been discarded (likely transient message that was too old). | ||
134 | */ | ||
135 | GNUNET_MULTICAST_REC_TRANSIENT_LOST = 1, | ||
136 | |||
137 | /** | ||
138 | * Message ID counter was larger than the highest counter this | ||
139 | * replay function has ever encountered; thus it is likely the | ||
140 | * origin never sent it and we're at the HEAD of the multicast | ||
141 | * stream as far as this node is concerned. | ||
142 | */ | ||
143 | GNUNET_MULTICAST_REC_PAST_HEAD = 2, | ||
144 | |||
145 | /** | ||
146 | * Internal error (i.e. database error). Try some other peer. | ||
147 | */ | ||
148 | GNUNET_MULTICAST_REC_INTERNAL_ERROR = 3 | ||
149 | |||
150 | }; | ||
151 | |||
152 | |||
153 | GNUNET_NETWORK_STRUCT_BEGIN | 98 | GNUNET_NETWORK_STRUCT_BEGIN |
154 | 99 | ||
155 | /** | 100 | /** |
@@ -242,32 +187,19 @@ GNUNET_NETWORK_STRUCT_END | |||
242 | 187 | ||
243 | 188 | ||
244 | /** | 189 | /** |
245 | * Replay a message from the multicast group. | ||
246 | * | ||
247 | * @param rh Replay handle identifying which replay operation was requested. | ||
248 | * @param msg Replayed message, NULL if unknown/error. | ||
249 | * @param ec Error code. | ||
250 | */ | ||
251 | void | ||
252 | GNUNET_MULTICAST_replay (struct GNUNET_MULTICAST_ReplayHandle *rh, | ||
253 | const struct GNUNET_MULTICAST_MessageHeader *msg, | ||
254 | enum GNUNET_MULTICAST_ReplayErrorCode ec); | ||
255 | |||
256 | |||
257 | /** | ||
258 | * Handle that identifies a join request. | 190 | * Handle that identifies a join request. |
259 | * | 191 | * |
260 | * Used to match calls to #GNUNET_MULTICAST_MembershipChangeCallback to the | 192 | * Used to match calls to #GNUNET_MULTICAST_JoinCallback to the |
261 | * corresponding calls to GNUNET_MULTICAST_join_decision(). | 193 | * corresponding calls to GNUNET_MULTICAST_join_decision(). |
262 | */ | 194 | */ |
263 | struct GNUNET_MULTICAST_JoinHande; | 195 | struct GNUNET_MULTICAST_JoinHandle; |
264 | 196 | ||
265 | 197 | ||
266 | /** | 198 | /** |
267 | * Function to call with the decision made for a membership change request. | 199 | * Function to call with the decision made for a membership change request. |
268 | * | 200 | * |
269 | * Must be called once and only once in response to an invocation of the | 201 | * Must be called once and only once in response to an invocation of the |
270 | * #GNUNET_MULTICAST_MembershipChangeCallback. | 202 | * #GNUNET_MULTICAST_JoinCallback. |
271 | * | 203 | * |
272 | * @param jh Join request handle. | 204 | * @param jh Join request handle. |
273 | * @param join_response Message to send in response to the joining peer; | 205 | * @param join_response Message to send in response to the joining peer; |
@@ -295,26 +227,38 @@ GNUNET_MULTICAST_join_decision (struct GNUNET_MULTICAST_JoinHandle *jh, | |||
295 | 227 | ||
296 | 228 | ||
297 | /** | 229 | /** |
298 | * Method called whenever another peer wants to join or has left a multicast | 230 | * Method called whenever another peer wants to join the multicast group. |
299 | * group. | ||
300 | * | 231 | * |
301 | * Implementations of this function must call GNUNET_MULTICAST_join_decision() | 232 | * Implementations of this function must call GNUNET_MULTICAST_join_decision() |
302 | * with the decision. | 233 | * with the decision. |
303 | * | 234 | * |
304 | * @param cls Closure. | 235 | * @param cls Closure. |
305 | * @param peer Identity of the peer that wants to join or leave. | 236 | * @param peer Identity of the peer that wants to join. |
306 | * @param join_req Application-dependent join message from the new user | 237 | * @param msg Application-dependent join message from the new user |
307 | * (might, for example, contain a user, | 238 | * (might, for example, contain a user, |
308 | * bind user identity/pseudonym to peer identity, application-level | 239 | * bind user identity/pseudonym to peer identity, application-level |
309 | * message to origin, etc.). | 240 | * message to origin, etc.). |
310 | * @param is_joining #GNUNET_YES if the peer wants to join, #GNUNET_NO if the peer left. | ||
311 | * @param jh Join handle to pass to GNUNET_MULTICAST_join_decison(). | 241 | * @param jh Join handle to pass to GNUNET_MULTICAST_join_decison(). |
312 | */ | 242 | */ |
313 | typedef void (*GNUNET_MULTICAST_MembershipChangeCallback)(void *cls, | 243 | typedef void (*GNUNET_MULTICAST_JoinCallback)(void *cls, |
314 | const struct GNUNET_PeerIdentity *peer, | 244 | const struct GNUNET_PeerIdentity *peer, |
315 | const struct GNUNET_MessageHeader *join_req, | 245 | const struct GNUNET_MessageHeader *msg, |
316 | int is_joining, | 246 | struct GNUNET_MULTICAST_JoinHandle *jh); |
317 | struct GNUNET_MULTICAST_JoinHandle *jh); | 247 | |
248 | /** | ||
249 | * Method called whenever another peer wants to leave the multicast group. | ||
250 | * | ||
251 | * A leave request must be always be honoured. | ||
252 | * | ||
253 | * @param cls Closure. | ||
254 | * @param peer Identity of the peer that wants to leave. | ||
255 | * @param msg Application-dependent leave message from the leaving user. | ||
256 | * @param jh Join handle to pass to GNUNET_MULTICAST_join_decison(). | ||
257 | */ | ||
258 | typedef void (*GNUNET_MULTICAST_LeaveCallback)(void *cls, | ||
259 | const struct GNUNET_PeerIdentity *peer, | ||
260 | const struct GNUNET_MessageHeader *msg, | ||
261 | struct GNUNET_MULTICAST_JoinHandle *jh); | ||
318 | 262 | ||
319 | 263 | ||
320 | /** | 264 | /** |
@@ -355,21 +299,22 @@ typedef void (*GNUNET_MULTICAST_MembershipTestCallback)(void *cls, | |||
355 | * | 299 | * |
356 | * @param cls Closure (set from GNUNET_MULTICAST_origin_start). | 300 | * @param cls Closure (set from GNUNET_MULTICAST_origin_start). |
357 | * @param sender Identity of the sender. | 301 | * @param sender Identity of the sender. |
358 | * @param response_id Unique counter for the response from this sender to this origin. | 302 | * @param request_id Unique counter for the request from this sender to this origin. |
359 | * @param msg Message to the origin. | 303 | * @param msg Message to the origin. |
360 | */ | 304 | */ |
361 | typedef void (*GNUNET_MULTICAST_ResponseCallback) (void *cls, | 305 | typedef void (*GNUNET_MULTICAST_RequestCallback) (void *cls, |
362 | const struct GNUNET_PeerIdentity *sender, | 306 | const struct GNUNET_PeerIdentity *sender, |
363 | uint64_t response_id, | 307 | uint64_t request_id, |
364 | const struct GNUNET_MessageHeader *msg); | 308 | const struct GNUNET_MessageHeader *msg); |
365 | 309 | ||
366 | 310 | ||
367 | /** | 311 | /** |
368 | * Function called whenever a group member is receiving a message from | 312 | * Function called whenever a group member is receiving a message from |
369 | * the origin. If admission to the group is denied, this function is | 313 | * the origin. |
370 | * called once with the response of the @e origin (as given to | 314 | * |
371 | * GNUNET_MULTICAST_join_decision()) and then a second time with NULL | 315 | * If admission to the group is denied, this function is called once with the |
372 | * to indicate that the connection failed for good. | 316 | * response of the @e origin (as given to GNUNET_MULTICAST_join_decision()) and |
317 | * then a second time with NULL to indicate that the connection failed for good. | ||
373 | * | 318 | * |
374 | * @param cls Closure (set from GNUNET_MULTICAST_member_join()) | 319 | * @param cls Closure (set from GNUNET_MULTICAST_member_join()) |
375 | * @param message_id Unique number of the message, 0 for response to join request, | 320 | * @param message_id Unique number of the message, 0 for response to join request, |
@@ -384,6 +329,112 @@ typedef void (*GNUNET_MULTICAST_MulticastMessageCallback) (void *cls, | |||
384 | 329 | ||
385 | 330 | ||
386 | /** | 331 | /** |
332 | * Opaque handle to a replay request from the multicast service. | ||
333 | */ | ||
334 | struct GNUNET_MULTICAST_ReplayHandle; | ||
335 | |||
336 | |||
337 | /** | ||
338 | * Functions with this signature are called whenever the multicast | ||
339 | * service needs a message to be replayed. Implementations of this | ||
340 | * function MUST call GNUNET_MULTICAST_replay() ONCE (with a message | ||
341 | * or an error); however, if the origin is destroyed or the group is | ||
342 | * left, the replay handle must no longer be used. | ||
343 | * | ||
344 | * @param cls Closure (set from GNUNET_MULTICAST_origin_start() | ||
345 | * or GNUNET_MULTICAST_member_join()). | ||
346 | * @param message_id Which message should be replayed. | ||
347 | * @param rh Handle to pass to message transmit function. | ||
348 | */ | ||
349 | typedef void (*GNUNET_MULTICAST_ReplayCallback) (void *cls, | ||
350 | uint64_t message_id, | ||
351 | struct GNUNET_MULTICAST_ReplayHandle *rh); | ||
352 | |||
353 | |||
354 | /** | ||
355 | * Possible error codes during replay. | ||
356 | */ | ||
357 | enum GNUNET_MULTICAST_ReplayErrorCode | ||
358 | { | ||
359 | |||
360 | /** | ||
361 | * Everything is fine. | ||
362 | */ | ||
363 | GNUNET_MULTICAST_REC_OK = 0, | ||
364 | |||
365 | /** | ||
366 | * Message has been discarded (likely transient message that was too old). | ||
367 | */ | ||
368 | GNUNET_MULTICAST_REC_TRANSIENT_LOST = 1, | ||
369 | |||
370 | /** | ||
371 | * Message ID counter was larger than the highest counter this | ||
372 | * replay function has ever encountered; thus it is likely the | ||
373 | * origin never sent it and we're at the HEAD of the multicast | ||
374 | * stream as far as this node is concerned. | ||
375 | */ | ||
376 | GNUNET_MULTICAST_REC_PAST_HEAD = 2, | ||
377 | |||
378 | /** | ||
379 | * Internal error (i.e. database error). Try some other peer. | ||
380 | */ | ||
381 | GNUNET_MULTICAST_REC_INTERNAL_ERROR = 3 | ||
382 | |||
383 | }; | ||
384 | |||
385 | |||
386 | /** | ||
387 | * Replay a message from the multicast group. | ||
388 | * | ||
389 | * @param rh Replay handle identifying which replay operation was requested. | ||
390 | * @param msg Replayed message, NULL if unknown/error. | ||
391 | * @param ec Error code. | ||
392 | */ | ||
393 | void | ||
394 | GNUNET_MULTICAST_replay (struct GNUNET_MULTICAST_ReplayHandle *rh, | ||
395 | const struct GNUNET_MULTICAST_MessageHeader *msg, | ||
396 | enum GNUNET_MULTICAST_ReplayErrorCode ec); | ||
397 | |||
398 | |||
399 | /** | ||
400 | * Handle to pass back for the answer of a ping. | ||
401 | */ | ||
402 | struct GNUNET_MULTICAST_PingHandle; | ||
403 | |||
404 | |||
405 | /** | ||
406 | * A response to a @e ping. | ||
407 | * | ||
408 | * @param ph Handle that was given for the ping. | ||
409 | * @param message_id Latest message ID seen by this peer for this group. | ||
410 | */ | ||
411 | void | ||
412 | GNUNET_MULTICAST_pong (struct GNUNET_MULTICAST_ReplayHandle *rh, | ||
413 | uint64_t message_id); | ||
414 | |||
415 | |||
416 | /** | ||
417 | * Method called whenever a @e ping is received from another member. | ||
418 | * | ||
419 | * A @e ping is sent after a period of inactivity to check if the member has not | ||
420 | * missed any messages. A ping contains the latest message ID a member has | ||
421 | * seen. If the latest message ID on the receiving member is higher, the | ||
422 | * missing messages must be replayed to the requesting member using | ||
423 | * GNUNET_MULTICAST_replay(), otherwise GNUNET_MULTICAST_pong() must be called with | ||
424 | * the same message ID, indicating no newer messages was seen by this peer. | ||
425 | * | ||
426 | * @param cls Closure. | ||
427 | * @param peer Identity of the peer who sent the ping. | ||
428 | * @param latest_message_id Latest message ID seen by the requesting member. | ||
429 | * @param rh Handle to pass back to GNUNET_MULTICAST_pong() or GNUNET_MULTICAST_replay(). | ||
430 | */ | ||
431 | typedef void (*GNUNET_MULTICAST_PingCallback)(void *cls, | ||
432 | const struct GNUNET_PeerIdentity *peer, | ||
433 | uint64_t latest_messaged_id | ||
434 | struct GNUNET_MULTICAST_ReplayHandle *rh); | ||
435 | |||
436 | |||
437 | /** | ||
387 | * Start a multicast group. | 438 | * Start a multicast group. |
388 | * | 439 | * |
389 | * Will advertise the origin in the P2P overlay network under the respective | 440 | * Will advertise the origin in the P2P overlay network under the respective |
@@ -404,10 +455,10 @@ typedef void (*GNUNET_MULTICAST_MulticastMessageCallback) (void *cls, | |||
404 | * @param join_policy What is the membership policy of the group? | 455 | * @param join_policy What is the membership policy of the group? |
405 | * @param replay_cb Function that can be called to replay a message. | 456 | * @param replay_cb Function that can be called to replay a message. |
406 | * @param test_cb Function multicast can use to test group membership. | 457 | * @param test_cb Function multicast can use to test group membership. |
407 | * @param join_cb Function called to approve / disapprove joining of a peer, | 458 | * @param ping_cb Function called to answer a ping. |
408 | * and to inform about a leaving member. | 459 | * @param join_cb Function called to approve / disapprove joining of a peer. |
409 | * @param leave_cb Function called to inform about a leaving member. | 460 | * @param leave_cb Function called when a member wants to leave the group. |
410 | * @param response_cb Function called with messages from group members. | 461 | * @param request_cb Function called with messages from group members. |
411 | * @return Handle for the origin, NULL on error. | 462 | * @return Handle for the origin, NULL on error. |
412 | */ | 463 | */ |
413 | struct GNUNET_MULTICAST_Origin * | 464 | struct GNUNET_MULTICAST_Origin * |
@@ -417,8 +468,10 @@ GNUNET_MULTICAST_origin_start (const struct GNUNET_CONFIGURATION_Handle *cfg, | |||
417 | enum GNUNET_MULTICAST_JoinPolicy join_policy, | 468 | enum GNUNET_MULTICAST_JoinPolicy join_policy, |
418 | GNUNET_MULITCAST_ReplayCallback replay_cb, | 469 | GNUNET_MULITCAST_ReplayCallback replay_cb, |
419 | GNUNET_MULITCAST_MembershipTestCallback test_cb, | 470 | GNUNET_MULITCAST_MembershipTestCallback test_cb, |
420 | GNUNET_MULTICAST_MembershipChangeCallback join_cb, | 471 | GNUNET_MULITCAST_PingCallback ping_cb, |
421 | GNUNET_MULTICAST_ResponseCallback response_cb); | 472 | GNUNET_MULTICAST_JoinCallback join_cb, |
473 | GNUNET_MULTICAST_LeaveCallback leave_cb, | ||
474 | GNUNET_MULTICAST_RequestCallback request_cb); | ||
422 | 475 | ||
423 | 476 | ||
424 | /** | 477 | /** |