diff options
author | Gabor X Toth <*@tg-x.net> | 2013-09-25 17:46:06 +0000 |
---|---|---|
committer | Gabor X Toth <*@tg-x.net> | 2013-09-25 17:46:06 +0000 |
commit | 7bec38c1bf3572bd01ddd064f69d1b744f7725a8 (patch) | |
tree | e875e7dd3920d201e1e16fc046e8070fed7bd875 /src/include/gnunet_psyc_service.h | |
parent | 303d6a97bc552a337c992944c3151ea53c1f74dc (diff) | |
download | gnunet-7bec38c1bf3572bd01ddd064f69d1b744f7725a8.tar.gz gnunet-7bec38c1bf3572bd01ddd064f69d1b744f7725a8.zip |
psyc service: start/stop, join/part, message transmission: lib -> psyc -> mcast; psyc API: stop/resume transmission
Diffstat (limited to 'src/include/gnunet_psyc_service.h')
-rw-r--r-- | src/include/gnunet_psyc_service.h | 183 |
1 files changed, 163 insertions, 20 deletions
diff --git a/src/include/gnunet_psyc_service.h b/src/include/gnunet_psyc_service.h index a643a5f49..9502b9fd2 100644 --- a/src/include/gnunet_psyc_service.h +++ b/src/include/gnunet_psyc_service.h | |||
@@ -184,6 +184,96 @@ enum GNUNET_PSYC_MessageFlags | |||
184 | }; | 184 | }; |
185 | 185 | ||
186 | 186 | ||
187 | /** | ||
188 | * M | ||
189 | */ | ||
190 | struct GNUNET_PSYC_MessageMethod | ||
191 | { | ||
192 | /** | ||
193 | * Type: GNUNET_MESSAGE_TYPE_PSYC_MESSAGE_METHOD | ||
194 | */ | ||
195 | struct GNUNET_MessageHeader header; | ||
196 | |||
197 | uint32_t reserved GNUNET_PACKED; | ||
198 | |||
199 | /** | ||
200 | * Number of modifiers in the message. | ||
201 | */ | ||
202 | uint32_t mod_count GNUNET_PACKED; | ||
203 | |||
204 | /** | ||
205 | * OR'ed GNUNET_PSYC_MasterTransmitFlags | ||
206 | */ | ||
207 | uint32_t flags GNUNET_PACKED; | ||
208 | |||
209 | /** | ||
210 | * Sending slave's public key. NULL if the message is from the master, or when | ||
211 | * transmitting a message. | ||
212 | */ | ||
213 | struct GNUNET_CRYPTO_EccPublicSignKey slave_key; | ||
214 | |||
215 | /* Followed by NUL-terminated method name. */ | ||
216 | }; | ||
217 | |||
218 | |||
219 | struct GNUNET_PSYC_MessageModifier | ||
220 | { | ||
221 | /** | ||
222 | * Type: GNUNET_MESSAGE_TYPE_PSYC_MESSAGE_MODIFIER | ||
223 | */ | ||
224 | struct GNUNET_MessageHeader header; | ||
225 | |||
226 | /** | ||
227 | * Size of value. | ||
228 | */ | ||
229 | uint32_t value_size GNUNET_PACKED; | ||
230 | |||
231 | /** | ||
232 | * Size of name, including NUL terminator. | ||
233 | */ | ||
234 | uint16_t name_size GNUNET_PACKED; | ||
235 | |||
236 | /** | ||
237 | * enum GNUNET_ENV_Operator | ||
238 | */ | ||
239 | uint8_t oper; | ||
240 | |||
241 | /* Followed by NUL-terminated name, then the value. */ | ||
242 | }; | ||
243 | |||
244 | |||
245 | enum GNUNET_PSYC_DataStatus | ||
246 | { | ||
247 | /** | ||
248 | * To be continued. | ||
249 | */ | ||
250 | GNUNET_PSYC_DATA_CONT = 0, | ||
251 | |||
252 | /** | ||
253 | * Reached the end of message. | ||
254 | */ | ||
255 | GNUNET_PSYC_DATA_END = 1, | ||
256 | |||
257 | /** | ||
258 | * Cancelled before the end. | ||
259 | */ | ||
260 | GNUNET_PSYC_DATA_CANCEL = 2 | ||
261 | }; | ||
262 | |||
263 | |||
264 | struct GNUNET_PSYC_MessageData | ||
265 | { | ||
266 | /** | ||
267 | * Type: GNUNET_MESSAGE_TYPE_PSYC_MESSAGE_MODIFIER | ||
268 | */ | ||
269 | struct GNUNET_MessageHeader header; | ||
270 | |||
271 | /** | ||
272 | * enum GNUNET_PSYC_DataStatus | ||
273 | */ | ||
274 | uint8_t status; | ||
275 | }; | ||
276 | |||
187 | /** | 277 | /** |
188 | * Handle that identifies a join request. | 278 | * Handle that identifies a join request. |
189 | * | 279 | * |
@@ -194,14 +284,14 @@ struct GNUNET_PSYC_JoinHandle; | |||
194 | 284 | ||
195 | 285 | ||
196 | /** | 286 | /** |
197 | * Method called from PSYC upon receiving a message indicating a call | 287 | * Method called from PSYC upon receiving a message indicating a call to a |
198 | * to a @e method. | 288 | * @e method. |
199 | * | 289 | * |
200 | * @param cls Closure. | 290 | * @param cls Closure. |
201 | * @param slave_key Who transmitted the message. | 291 | * @param slave_key Who transmitted the message. |
202 | * - NULL for multicast messages from the master. | 292 | * - NULL for multicast messages from the master. |
203 | * - The hash of the sending slave's public key for unicast requests from | 293 | * - The sending slave's public key for unicast requests from one of the |
204 | * one of the slaves to the master. | 294 | * slaves to the master. |
205 | * @param message_id Unique message counter for this message. | 295 | * @param message_id Unique message counter for this message. |
206 | * Unique only in combination with the given sender for this channel. | 296 | * Unique only in combination with the given sender for this channel. |
207 | * @param method_name Method name from PSYC. | 297 | * @param method_name Method name from PSYC. |
@@ -241,7 +331,8 @@ typedef int | |||
241 | */ | 331 | */ |
242 | typedef int | 332 | typedef int |
243 | (*GNUNET_PSYC_JoinCallback) (void *cls, | 333 | (*GNUNET_PSYC_JoinCallback) (void *cls, |
244 | const struct GNUNET_CRYPTO_EccPublicSignKey *slave_key, | 334 | const struct GNUNET_CRYPTO_EccPublicSignKey |
335 | *slave_key, | ||
245 | const char *method_name, | 336 | const char *method_name, |
246 | size_t variable_count, | 337 | size_t variable_count, |
247 | const struct GNUNET_ENV_Modifier *variables, | 338 | const struct GNUNET_ENV_Modifier *variables, |
@@ -268,7 +359,8 @@ typedef int | |||
268 | * multicast tree. Note that it is unnecessary to specify our own | 359 | * multicast tree. Note that it is unnecessary to specify our own |
269 | * peer identity in this array. | 360 | * peer identity in this array. |
270 | * @param method_name Method name for the message transmitted with the response. | 361 | * @param method_name Method name for the message transmitted with the response. |
271 | * @param env Environment containing transient variables for the message, or NULL. | 362 | * @param env Environment containing transient variables for the message, |
363 | * or NULL. | ||
272 | * @param data Data of the message. | 364 | * @param data Data of the message. |
273 | * @param data_size Size of @a data. | 365 | * @param data_size Size of @a data. |
274 | */ | 366 | */ |
@@ -290,6 +382,16 @@ struct GNUNET_PSYC_Master; | |||
290 | 382 | ||
291 | 383 | ||
292 | /** | 384 | /** |
385 | * Function called after the channel master started. | ||
386 | * | ||
387 | * @param cls Closure. | ||
388 | * @param last_message_id Last message ID sent to the channel. | ||
389 | */ | ||
390 | typedef void | ||
391 | (*GNUNET_PSYC_MasterStartCallback) (void *cls, uint64_t max_message_id); | ||
392 | |||
393 | |||
394 | /** | ||
293 | * Start a PSYC master channel. | 395 | * Start a PSYC master channel. |
294 | * | 396 | * |
295 | * Will start a multicast group identified by the given ECC key. Messages | 397 | * Will start a multicast group identified by the given ECC key. Messages |
@@ -313,6 +415,7 @@ struct GNUNET_PSYC_Master; | |||
313 | * Used to automate join decisions. | 415 | * Used to automate join decisions. |
314 | * @param method Function to invoke on messages received from slaves. | 416 | * @param method Function to invoke on messages received from slaves. |
315 | * @param join_cb Function to invoke when a peer wants to join. | 417 | * @param join_cb Function to invoke when a peer wants to join. |
418 | * @param start_cb Function to invoke after the channel master started. | ||
316 | * @param cls Closure for @a method and @a join_cb. | 419 | * @param cls Closure for @a method and @a join_cb. |
317 | * @return Handle for the channel master, NULL on error. | 420 | * @return Handle for the channel master, NULL on error. |
318 | */ | 421 | */ |
@@ -322,6 +425,7 @@ GNUNET_PSYC_master_start (const struct GNUNET_CONFIGURATION_Handle *cfg, | |||
322 | enum GNUNET_PSYC_Policy policy, | 425 | enum GNUNET_PSYC_Policy policy, |
323 | GNUNET_PSYC_Method method, | 426 | GNUNET_PSYC_Method method, |
324 | GNUNET_PSYC_JoinCallback join_cb, | 427 | GNUNET_PSYC_JoinCallback join_cb, |
428 | GNUNET_PSYC_MasterStartCallback start_cb, | ||
325 | void *cls); | 429 | void *cls); |
326 | 430 | ||
327 | 431 | ||
@@ -339,8 +443,10 @@ GNUNET_PSYC_master_start (const struct GNUNET_CONFIGURATION_Handle *cfg, | |||
339 | * @param[out] data Where to write the body of the message to give to the | 443 | * @param[out] data Where to write the body of the message to give to the |
340 | * method. The function must copy at most @a data_size bytes to @a data. | 444 | * method. The function must copy at most @a data_size bytes to @a data. |
341 | * @return #GNUNET_SYSERR on error (fatal, aborts transmission) | 445 | * @return #GNUNET_SYSERR on error (fatal, aborts transmission) |
342 | * #GNUNET_NO on success, if more data is to be transmitted later | 446 | * #GNUNET_NO on success, if more data is to be transmitted later. |
343 | * (should be used if @a data_size was not big enough to take all the data) | 447 | * Should be used if @a data_size was not big enough to take all the |
448 | * data. If 0 is returned in @a data_size the transmission is paused, | ||
449 | * and can be resumed with GNUNET_PSYC_master_transmit_resume(). | ||
344 | * #GNUNET_YES if this completes the transmission (all data supplied) | 450 | * #GNUNET_YES if this completes the transmission (all data supplied) |
345 | */ | 451 | */ |
346 | typedef int | 452 | typedef int |
@@ -403,6 +509,15 @@ GNUNET_PSYC_master_transmit (struct GNUNET_PSYC_Master *master, | |||
403 | 509 | ||
404 | 510 | ||
405 | /** | 511 | /** |
512 | * Resume transmission to the channel. | ||
513 | * | ||
514 | * @param th Handle of the request that is being resumed. | ||
515 | */ | ||
516 | void | ||
517 | GNUNET_PSYC_master_transmit_resume (struct GNUNET_PSYC_MasterTransmitHandle *th); | ||
518 | |||
519 | |||
520 | /** | ||
406 | * Abort transmission request to channel. | 521 | * Abort transmission request to channel. |
407 | * | 522 | * |
408 | * @param th Handle of the request that is being aborted. | 523 | * @param th Handle of the request that is being aborted. |
@@ -427,10 +542,20 @@ struct GNUNET_PSYC_Slave; | |||
427 | 542 | ||
428 | 543 | ||
429 | /** | 544 | /** |
545 | * Function called after the slave joined. | ||
546 | * | ||
547 | * @param cls Closure. | ||
548 | * @param max_message_id Last message ID sent to the channel. | ||
549 | */ | ||
550 | typedef void | ||
551 | (*GNUNET_PSYC_SlaveJoinCallback) (void *cls, uint64_t max_message_id); | ||
552 | |||
553 | |||
554 | /** | ||
430 | * Join a PSYC channel. | 555 | * Join a PSYC channel. |
431 | * | 556 | * |
432 | * The entity joining is always the local peer. The user must immediately use | 557 | * The entity joining is always the local peer. The user must immediately use |
433 | * the GNUNET_PSYC_slave_to_master() functions to transmit a @e join_msg to the | 558 | * the GNUNET_PSYC_slave_transmit() functions to transmit a @e join_msg to the |
434 | * channel; if the join request succeeds, the channel state (and @e recent | 559 | * channel; if the join request succeeds, the channel state (and @e recent |
435 | * method calls) will be replayed to the joining member. There is no explicit | 560 | * method calls) will be replayed to the joining member. There is no explicit |
436 | * notification on failure (as the channel may simply take days to approve, | 561 | * notification on failure (as the channel may simply take days to approve, |
@@ -464,6 +589,7 @@ GNUNET_PSYC_slave_join (const struct GNUNET_CONFIGURATION_Handle *cfg, | |||
464 | const struct GNUNET_PeerIdentity *relays, | 589 | const struct GNUNET_PeerIdentity *relays, |
465 | GNUNET_PSYC_Method method, | 590 | GNUNET_PSYC_Method method, |
466 | GNUNET_PSYC_JoinCallback join_cb, | 591 | GNUNET_PSYC_JoinCallback join_cb, |
592 | GNUNET_PSYC_SlaveJoinCallback slave_joined_cb, | ||
467 | void *cls, | 593 | void *cls, |
468 | const char *method_name, | 594 | const char *method_name, |
469 | const struct GNUNET_ENV_Environment *env, | 595 | const struct GNUNET_ENV_Environment *env, |
@@ -475,7 +601,7 @@ GNUNET_PSYC_slave_join (const struct GNUNET_CONFIGURATION_Handle *cfg, | |||
475 | * Part a PSYC channel. | 601 | * Part a PSYC channel. |
476 | * | 602 | * |
477 | * Will terminate the connection to the PSYC service. Polite clients should | 603 | * Will terminate the connection to the PSYC service. Polite clients should |
478 | * first explicitly send a @e part request (via GNUNET_PSYC_slave_to_master()). | 604 | * first explicitly send a @e part request (via GNUNET_PSYC_slave_transmit()). |
479 | * | 605 | * |
480 | * @param slave Slave handle. | 606 | * @param slave Slave handle. |
481 | */ | 607 | */ |
@@ -484,15 +610,16 @@ GNUNET_PSYC_slave_part (struct GNUNET_PSYC_Slave *slave); | |||
484 | 610 | ||
485 | 611 | ||
486 | /** | 612 | /** |
487 | * Function called to provide data for a transmission to the channel | 613 | * Function called to provide data for a transmission to the channel master |
488 | * master (aka the @e host of the channel). | 614 | * (a.k.a. the @e host of the channel). |
489 | * | 615 | * |
490 | * Note that returning #GNUNET_OK or #GNUNET_SYSERR (but not #GNUNET_NO) | 616 | * Note that returning #GNUNET_OK or #GNUNET_SYSERR (but not #GNUNET_NO) |
491 | * invalidates the respective transmission handle. | 617 | * invalidates the respective transmission handle. |
492 | * | 618 | * |
493 | * @param cls Closure. | 619 | * @param cls Closure. |
494 | * @param[in,out] data_size Initially set to the number of bytes available in @a data, | 620 | * @param[in,out] data_size Initially set to the number of bytes available in |
495 | * should be set to the number of bytes written to data (IN/OUT). | 621 | * @a data, should be set to the number of bytes written to data |
622 | * (IN/OUT). | ||
496 | * @param[out] data Where to write the body of the message to give to the method; | 623 | * @param[out] data Where to write the body of the message to give to the method; |
497 | * function must copy at most @a *data_size bytes to @a data. | 624 | * function must copy at most @a *data_size bytes to @a data. |
498 | * @return #GNUNET_SYSERR on error (fatal, aborts transmission). | 625 | * @return #GNUNET_SYSERR on error (fatal, aborts transmission). |
@@ -541,6 +668,15 @@ GNUNET_PSYC_slave_transmit (struct GNUNET_PSYC_Slave *slave, | |||
541 | 668 | ||
542 | 669 | ||
543 | /** | 670 | /** |
671 | * Resume transmission to the master. | ||
672 | * | ||
673 | * @param th Handle of the request that is being resumed. | ||
674 | */ | ||
675 | void | ||
676 | GNUNET_PSYC_slave_transmit_resume (struct GNUNET_PSYC_MasterTransmitHandle *th); | ||
677 | |||
678 | |||
679 | /** | ||
544 | * Abort transmission request to master. | 680 | * Abort transmission request to master. |
545 | * | 681 | * |
546 | * @param th Handle of the request that is being aborted. | 682 | * @param th Handle of the request that is being aborted. |
@@ -556,7 +692,8 @@ struct GNUNET_PSYC_Channel; | |||
556 | 692 | ||
557 | 693 | ||
558 | /** | 694 | /** |
559 | * Convert a channel @a master to a @e channel handle to access the @e channel APIs. | 695 | * Convert a channel @a master to a @e channel handle to access the @e channel |
696 | * APIs. | ||
560 | * | 697 | * |
561 | * @param master Channel master handle. | 698 | * @param master Channel master handle. |
562 | * @return Channel handle, valid for as long as @a master is valid. | 699 | * @return Channel handle, valid for as long as @a master is valid. |
@@ -598,7 +735,8 @@ GNUNET_PSYC_slave_get_channel (struct GNUNET_PSYC_Slave *slave); | |||
598 | */ | 735 | */ |
599 | void | 736 | void |
600 | GNUNET_PSYC_channel_slave_add (struct GNUNET_PSYC_Channel *channel, | 737 | GNUNET_PSYC_channel_slave_add (struct GNUNET_PSYC_Channel *channel, |
601 | const struct GNUNET_CRYPTO_EccPublicSignKey *slave_key, | 738 | const struct GNUNET_CRYPTO_EccPublicSignKey |
739 | *slave_key, | ||
602 | uint64_t announced_at, | 740 | uint64_t announced_at, |
603 | uint64_t effective_since); | 741 | uint64_t effective_since); |
604 | 742 | ||
@@ -626,7 +764,8 @@ GNUNET_PSYC_channel_slave_add (struct GNUNET_PSYC_Channel *channel, | |||
626 | */ | 764 | */ |
627 | void | 765 | void |
628 | GNUNET_PSYC_channel_slave_remove (struct GNUNET_PSYC_Channel *channel, | 766 | GNUNET_PSYC_channel_slave_remove (struct GNUNET_PSYC_Channel *channel, |
629 | const struct GNUNET_CRYPTO_EccPublicSignKey *slave_key, | 767 | const struct GNUNET_CRYPTO_EccPublicSignKey |
768 | *slave_key, | ||
630 | uint64_t announced_at); | 769 | uint64_t announced_at); |
631 | 770 | ||
632 | 771 | ||
@@ -702,6 +841,10 @@ GNUNET_PSYC_channel_story_tell (struct GNUNET_PSYC_Channel *channel, | |||
702 | void | 841 | void |
703 | GNUNET_PSYC_channel_story_tell_cancel (struct GNUNET_PSYC_Story *story); | 842 | GNUNET_PSYC_channel_story_tell_cancel (struct GNUNET_PSYC_Story *story); |
704 | 843 | ||
844 | |||
845 | /** | ||
846 | * Handle for a state query operation. | ||
847 | */ | ||
705 | struct GNUNET_PSYC_StateQuery; | 848 | struct GNUNET_PSYC_StateQuery; |
706 | 849 | ||
707 | 850 | ||
@@ -730,9 +873,9 @@ GNUNET_PSYC_channel_state_get (struct GNUNET_PSYC_Channel *channel, | |||
730 | /** | 873 | /** |
731 | * Return all channel state variables whose name matches a given prefix. | 874 | * Return all channel state variables whose name matches a given prefix. |
732 | * | 875 | * |
733 | * A name matches if it starts with the given @a name_prefix, thus requesting the | 876 | * A name matches if it starts with the given @a name_prefix, thus requesting |
734 | * empty prefix ("") will match all values; requesting "_a_b" will also return | 877 | * the empty prefix ("") will match all values; requesting "_a_b" will also |
735 | * values stored under "_a_b_c". | 878 | * return values stored under "_a_b_c". |
736 | * | 879 | * |
737 | * The @a state_cb is invoked on all matching state variables asynchronously, as | 880 | * The @a state_cb is invoked on all matching state variables asynchronously, as |
738 | * the state is stored in and retrieved from the PSYCstore, | 881 | * the state is stored in and retrieved from the PSYCstore, |