diff options
author | Gabor X Toth <*@tg-x.net> | 2014-05-26 22:16:05 +0000 |
---|---|---|
committer | Gabor X Toth <*@tg-x.net> | 2014-05-26 22:16:05 +0000 |
commit | 83495695331fcfa8824d7a6d407b82cfcfc8b13c (patch) | |
tree | 2d2a7717d81890f5142da9561bccf9e164b1deee /src/include/gnunet_psyc_service.h | |
parent | 1cfab01aaea932539c39dcb2118ec4d6c6d44381 (diff) | |
download | gnunet-83495695331fcfa8824d7a6d407b82cfcfc8b13c.tar.gz gnunet-83495695331fcfa8824d7a6d407b82cfcfc8b13c.zip |
psyc, multicast: join decision, tests
Diffstat (limited to 'src/include/gnunet_psyc_service.h')
-rw-r--r-- | src/include/gnunet_psyc_service.h | 119 |
1 files changed, 71 insertions, 48 deletions
diff --git a/src/include/gnunet_psyc_service.h b/src/include/gnunet_psyc_service.h index 2ae20adc5..4f4c99c1f 100644 --- a/src/include/gnunet_psyc_service.h +++ b/src/include/gnunet_psyc_service.h | |||
@@ -325,17 +325,18 @@ typedef void | |||
325 | /** | 325 | /** |
326 | * Method called from PSYC upon receiving a join request. | 326 | * Method called from PSYC upon receiving a join request. |
327 | * | 327 | * |
328 | * @param cls Closure. | 328 | * @param cls Closure. |
329 | * @param slave requesting to join. | 329 | * @param slave_key Public key of the slave requesting join. |
330 | * @param join_msg Join message sent along with the request. | 330 | * @param join_msg Join message sent along with the request. |
331 | * @param jh Join handle to use with GNUNET_PSYC_join_decision() | 331 | * @param jh Join handle to use with GNUNET_PSYC_join_decision() |
332 | */ | 332 | */ |
333 | typedef void | 333 | typedef void |
334 | (*GNUNET_PSYC_JoinCallback) (void *cls, | 334 | (*GNUNET_PSYC_JoinRequestCallback) (void *cls, |
335 | const struct GNUNET_CRYPTO_EddsaPublicKey | 335 | const struct |
336 | *slave_key, | 336 | GNUNET_CRYPTO_EddsaPublicKey *slave_key, |
337 | const struct GNUNET_PSYC_MessageHeader *join_msg, | 337 | const struct |
338 | struct GNUNET_PSYC_JoinHandle *jh); | 338 | GNUNET_PSYC_MessageHeader *join_msg, |
339 | struct GNUNET_PSYC_JoinHandle *jh); | ||
339 | 340 | ||
340 | 341 | ||
341 | /** | 342 | /** |
@@ -344,32 +345,30 @@ typedef void | |||
344 | * Must be called once and only once in response to an invocation of the | 345 | * Must be called once and only once in response to an invocation of the |
345 | * #GNUNET_PSYC_JoinCallback. | 346 | * #GNUNET_PSYC_JoinCallback. |
346 | * | 347 | * |
347 | * @param jh Join request handle. | 348 | * @param jh Join request handle. |
348 | * @param is_admitted #GNUNET_YES if joining is approved, | 349 | * @param is_admitted #GNUNET_YES if the join is approved, |
349 | * #GNUNET_NO if it is disapproved. | 350 | * #GNUNET_NO if it is disapproved, |
350 | * @param relay_count Number of relays given. | 351 | * #GNUNET_SYSERR if we cannot answer the request. |
351 | * @param relays Array of suggested peers that might be useful relays to use | 352 | * @param relay_count Number of relays given. |
353 | * @param relays Array of suggested peers that might be useful relays to use | ||
352 | * when joining the multicast group (essentially a list of peers that | 354 | * when joining the multicast group (essentially a list of peers that |
353 | * are already part of the multicast group and might thus be willing | 355 | * are already part of the multicast group and might thus be willing |
354 | * to help with routing). If empty, only this local peer (which must | 356 | * to help with routing). If empty, only this local peer (which must |
355 | * be the multicast origin) is a good candidate for building the | 357 | * be the multicast origin) is a good candidate for building the |
356 | * multicast tree. Note that it is unnecessary to specify our own | 358 | * multicast tree. Note that it is unnecessary to specify our own |
357 | * peer identity in this array. | 359 | * peer identity in this array. |
358 | * @param method_name Method name for the message transmitted with the response. | 360 | * @param join_resp Application-dependent join response message to send along |
359 | * @param env Environment containing transient variables for the message, | 361 | * with the decision. |
360 | * or NULL. | 362 | * |
361 | * @param data Data of the message. | 363 | * @return #GNUNET_OK on success, |
362 | * @param data_size Size of @a data. | 364 | * #GNUNET_SYSERR if @a join_resp is too large. |
363 | */ | 365 | */ |
364 | void | 366 | int |
365 | GNUNET_PSYC_join_decision (struct GNUNET_PSYC_JoinHandle *jh, | 367 | GNUNET_PSYC_join_decision (struct GNUNET_PSYC_JoinHandle *jh, |
366 | int is_admitted, | 368 | int is_admitted, |
367 | uint32_t relay_count, | 369 | uint32_t relay_count, |
368 | const struct GNUNET_PeerIdentity *relays, | 370 | const struct GNUNET_PeerIdentity *relays, |
369 | const char *method_name, | 371 | const struct GNUNET_PSYC_MessageHeader *join_resp); |
370 | const struct GNUNET_ENV_Environment *env, | ||
371 | const void *data, | ||
372 | size_t data_size); | ||
373 | 372 | ||
374 | 373 | ||
375 | /** | 374 | /** |
@@ -400,29 +399,31 @@ typedef void | |||
400 | * or part messages, the respective methods must call other PSYC functions to | 399 | * or part messages, the respective methods must call other PSYC functions to |
401 | * inform PSYC about the meaning of the respective events. | 400 | * inform PSYC about the meaning of the respective events. |
402 | * | 401 | * |
403 | * @param cfg Configuration to use (to connect to PSYC service). | 402 | * @param cfg Configuration to use (to connect to PSYC service). |
404 | * @param channel_key ECC key that will be used to sign messages for this | 403 | * @param channel_key ECC key that will be used to sign messages for this |
405 | * PSYC session. The public key is used to identify the PSYC channel. | 404 | * PSYC session. The public key is used to identify the PSYC channel. |
406 | * Note that end-users will usually not use the private key directly, but | 405 | * Note that end-users will usually not use the private key directly, but |
407 | * rather look it up in GNS for places managed by other users, or select | 406 | * rather look it up in GNS for places managed by other users, or select |
408 | * a file with the private key(s) when setting up their own channels | 407 | * a file with the private key(s) when setting up their own channels |
409 | * FIXME: we'll likely want to use NOT the p521 curve here, but a cheaper | 408 | * FIXME: we'll likely want to use NOT the p521 curve here, but a cheaper |
410 | * one in the future. | 409 | * one in the future. |
411 | * @param policy Channel policy specifying join and history restrictions. | 410 | * @param policy Channel policy specifying join and history restrictions. |
412 | * Used to automate join decisions. | 411 | * Used to automate join decisions. |
413 | * @param message_cb Function to invoke on message parts received from slaves. | 412 | * @param master_start_cb Function to invoke after the channel master started. |
414 | * @param join_cb Function to invoke when a peer wants to join. | 413 | * @param join_request_cb Function to invoke when a slave wants to join. |
415 | * @param master_started_cb Function to invoke after the channel master started. | 414 | * @param message_cb Function to invoke on message parts sent to the channel |
416 | * @param cls Closure for @a method and @a join_cb. | 415 | * and received from slaves |
416 | * @param cls Closure for @a method and @a join_cb. | ||
417 | * | ||
417 | * @return Handle for the channel master, NULL on error. | 418 | * @return Handle for the channel master, NULL on error. |
418 | */ | 419 | */ |
419 | struct GNUNET_PSYC_Master * | 420 | struct GNUNET_PSYC_Master * |
420 | GNUNET_PSYC_master_start (const struct GNUNET_CONFIGURATION_Handle *cfg, | 421 | GNUNET_PSYC_master_start (const struct GNUNET_CONFIGURATION_Handle *cfg, |
421 | const struct GNUNET_CRYPTO_EddsaPrivateKey *channel_key, | 422 | const struct GNUNET_CRYPTO_EddsaPrivateKey *channel_key, |
422 | enum GNUNET_PSYC_Policy policy, | 423 | enum GNUNET_PSYC_Policy policy, |
424 | GNUNET_PSYC_MasterStartCallback master_start_cb, | ||
425 | GNUNET_PSYC_JoinRequestCallback join_request_cb, | ||
423 | GNUNET_PSYC_MessageCallback message_cb, | 426 | GNUNET_PSYC_MessageCallback message_cb, |
424 | GNUNET_PSYC_JoinCallback join_cb, | ||
425 | GNUNET_PSYC_MasterStartCallback master_started_cb, | ||
426 | void *cls); | 427 | void *cls); |
427 | 428 | ||
428 | 429 | ||
@@ -580,13 +581,30 @@ struct GNUNET_PSYC_Slave; | |||
580 | 581 | ||
581 | 582 | ||
582 | /** | 583 | /** |
583 | * Function called after the slave joined. | 584 | * Function called after the slave connected to the PSYC service. |
584 | * | 585 | * |
585 | * @param cls Closure. | 586 | * @param cls Closure. |
586 | * @param max_message_id Last message ID sent to the channel. | 587 | * @param max_message_id Last message ID sent to the channel. |
587 | */ | 588 | */ |
588 | typedef void | 589 | typedef void |
589 | (*GNUNET_PSYC_SlaveJoinCallback) (void *cls, uint64_t max_message_id); | 590 | (*GNUNET_PSYC_SlaveConnectCallback) (void *cls, uint64_t max_message_id); |
591 | |||
592 | |||
593 | /** | ||
594 | * Method called to inform about the decision in response to a join request. | ||
595 | * | ||
596 | * If @a is_admitted is not #GNUNET_YES, then sending messages to the channel is | ||
597 | * not possible, but earlier history can be still queried. | ||
598 | * | ||
599 | * @param cls Closure. | ||
600 | * @param is_admitted #GNUNET_YES or #GNUNET_NO or #GNUNET_SYSERR | ||
601 | * @param join_msg Application-dependent join message from the origin. | ||
602 | */ | ||
603 | typedef void | ||
604 | (*GNUNET_PSYC_JoinDecisionCallback) (void *cls, | ||
605 | int is_admitted, | ||
606 | const struct | ||
607 | GNUNET_PSYC_MessageHeader *join_msg); | ||
590 | 608 | ||
591 | 609 | ||
592 | /** | 610 | /** |
@@ -599,24 +617,28 @@ typedef void | |||
599 | * notification on failure (as the channel may simply take days to approve, | 617 | * notification on failure (as the channel may simply take days to approve, |
600 | * and disapproval is simply being ignored). | 618 | * and disapproval is simply being ignored). |
601 | * | 619 | * |
602 | * @param cfg Configuration to use. | 620 | * @param cfg Configuration to use. |
603 | * @param channel_key ECC public key that identifies the channel we wish to join. | 621 | * @param channel_key ECC public key that identifies the channel we wish to join. |
604 | * @param slave_key ECC private-public key pair that identifies the slave, and | 622 | * @param slave_key ECC private-public key pair that identifies the slave, and |
605 | * used by multicast to sign the join request and subsequent unicast | 623 | * used by multicast to sign the join request and subsequent unicast |
606 | * requests sent to the master. | 624 | * requests sent to the master. |
607 | * @param origin Peer identity of the origin. | 625 | * @param origin Peer identity of the origin. |
608 | * @param relay_count Number of peers in the @a relays array. | 626 | * @param relay_count Number of peers in the @a relays array. |
609 | * @param relays Peer identities of members of the multicast group, which serve | 627 | * @param relays Peer identities of members of the multicast group, which serve |
610 | * as relays and used to join the group at. | 628 | * as relays and used to join the group at. |
611 | * @param message_cb Function to invoke on message parts received from the | 629 | * @param message_cb Function to invoke on message parts received from the |
612 | * channel, typically at least contains method handlers for @e join and | 630 | * channel, typically at least contains method handlers for @e join and |
613 | * @e part. | 631 | * @e part. |
614 | * @param slave_joined_cb Function invoked once we have joined the channel. | 632 | * @param slave_connect_cb Function invoked once we have connected to the |
615 | * @param cls Closure for @a message_cb and @a slave_joined_cb. | 633 | * PSYC service. |
616 | * @param method_name Method name for the join request. | 634 | * @param join_decision_cb Function invoked once we have received a join |
617 | * @param env Environment containing transient variables for the request, or NULL. | 635 | * decision. |
618 | * @param data Payload for the join message. | 636 | * @param cls Closure for @a message_cb and @a slave_joined_cb. |
619 | * @param data_size Number of bytes in @a data. | 637 | * @param method_name Method name for the join request. |
638 | * @param env Environment containing transient variables for the request, or NULL. | ||
639 | * @param data Payload for the join message. | ||
640 | * @param data_size Number of bytes in @a data. | ||
641 | * | ||
620 | * @return Handle for the slave, NULL on error. | 642 | * @return Handle for the slave, NULL on error. |
621 | */ | 643 | */ |
622 | struct GNUNET_PSYC_Slave * | 644 | struct GNUNET_PSYC_Slave * |
@@ -627,7 +649,8 @@ GNUNET_PSYC_slave_join (const struct GNUNET_CONFIGURATION_Handle *cfg, | |||
627 | uint32_t relay_count, | 649 | uint32_t relay_count, |
628 | const struct GNUNET_PeerIdentity *relays, | 650 | const struct GNUNET_PeerIdentity *relays, |
629 | GNUNET_PSYC_MessageCallback message_cb, | 651 | GNUNET_PSYC_MessageCallback message_cb, |
630 | GNUNET_PSYC_SlaveJoinCallback slave_joined_cb, | 652 | GNUNET_PSYC_SlaveConnectCallback slave_connect_cb, |
653 | GNUNET_PSYC_JoinDecisionCallback join_decision_cb, | ||
631 | void *cls, | 654 | void *cls, |
632 | const char *method_name, | 655 | const char *method_name, |
633 | const struct GNUNET_ENV_Environment *env, | 656 | const struct GNUNET_ENV_Environment *env, |