X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=src%2Finclude%2Fgnunet_psyc_service.h;h=91dcd0b07ad741ae42410ac5057eb8a349b5f2fb;hb=27c12911f4f2aba2d90099270d70de846e83854f;hp=a643a5f49d40b5f9f4900d78f832156b37917bd1;hpb=38f919aee243423fdc49828687c5735ab77b9128;p=oweals%2Fgnunet.git diff --git a/src/include/gnunet_psyc_service.h b/src/include/gnunet_psyc_service.h index a643a5f49..91dcd0b07 100644 --- a/src/include/gnunet_psyc_service.h +++ b/src/include/gnunet_psyc_service.h @@ -18,7 +18,7 @@ Boston, MA 02111-1307, USA. */ -/** +/** * @file include/gnunet_psyc_service.h * @brief PSYC service; high-level access to the PSYC protocol * note that clients of this API are NOT expected to @@ -36,7 +36,7 @@ * 'places' and 'persons' are combined within the same * abstraction, that of a "channel". Channels are identified * and accessed in this API using a public/private key. - * Higher-level applications should use NAMES within GADS + * Higher-level applications should use NAMES within GNS * to obtain public keys, and the distinction between * 'places' and 'persons' can then be made with the help * of the naming system (and/or conventions). @@ -52,7 +52,7 @@ * @c \#define for the maximum size of a variable). * - PSYC defines standard variables, methods, etc. This * library deliberately abstracts over all of these; a - * higher-level API should combine the naming system (GADS) + * higher-level API should combine the naming system (GNS) * and standard methods (message, join, part, warn, * fail, error) and variables (action, color, time, * tag, etc.). However, this API does take over the @@ -90,13 +90,13 @@ extern "C" #include "gnunet_multicast_service.h" -/** +/** * Version number of GNUnet-PSYC API. */ #define GNUNET_PSYC_VERSION 0x00000000 -/** +/** * Policy flags for a channel. */ enum GNUNET_PSYC_ChannelFlags @@ -113,7 +113,7 @@ enum GNUNET_PSYC_ChannelFlags GNUNET_PSYC_CHANNEL_RESTRICTED_HISTORY = 1 << 1, }; -/** +/** * PSYC channel policies. */ enum GNUNET_PSYC_Policy @@ -125,7 +125,7 @@ enum GNUNET_PSYC_Policy */ GNUNET_PSYC_CHANNEL_ANONYMOUS = 0, - /** + /** * The master must approve membership to the channel, messages must only be * distributed to current channel slaves. This includes the channel * state as well as transient messages. @@ -135,7 +135,7 @@ enum GNUNET_PSYC_Policy | GNUNET_PSYC_CHANNEL_RESTRICTED_HISTORY, #if IDEAS_FOR_FUTURE - /** + /** * Anyone can freely join the channel (no approval required); * however, messages must only be distributed to current channel * slaves, so the master must still acknowledge that the slave @@ -170,7 +170,7 @@ enum GNUNET_PSYC_MessageFlags */ GNUNET_PSYC_MESSAGE_LAST_FRAGMENT = 1 << 1, - /** + /** * OR'ed flags if message is not fragmented. */ GNUNET_PSYC_MESSAGE_NOT_FRAGMENTED @@ -184,7 +184,97 @@ enum GNUNET_PSYC_MessageFlags }; -/** +/** + * M + */ +struct GNUNET_PSYC_MessageMethod +{ + /** + * Type: GNUNET_MESSAGE_TYPE_PSYC_MESSAGE_METHOD + */ + struct GNUNET_MessageHeader header; + + uint32_t reserved GNUNET_PACKED; + + /** + * Number of modifiers in the message. + */ + uint32_t mod_count GNUNET_PACKED; + + /** + * OR'ed GNUNET_PSYC_MasterTransmitFlags + */ + uint32_t flags GNUNET_PACKED; + + /** + * Sending slave's public key. + * NULL if the message is from the master, or when transmitting a message. + */ + struct GNUNET_CRYPTO_EddsaPublicKey slave_key; + + /* Followed by NUL-terminated method name. */ +}; + + +struct GNUNET_PSYC_MessageModifier +{ + /** + * Type: GNUNET_MESSAGE_TYPE_PSYC_MESSAGE_MODIFIER + */ + struct GNUNET_MessageHeader header; + + /** + * Size of value. + */ + uint32_t value_size GNUNET_PACKED; + + /** + * Size of name, including NUL terminator. + */ + uint16_t name_size GNUNET_PACKED; + + /** + * enum GNUNET_ENV_Operator + */ + uint8_t oper; + + /* Followed by NUL-terminated name, then the value. */ +}; + + +enum GNUNET_PSYC_DataStatus +{ + /** + * To be continued. + */ + GNUNET_PSYC_DATA_CONT = 0, + + /** + * Reached the end of message. + */ + GNUNET_PSYC_DATA_END = 1, + + /** + * Cancelled before the end. + */ + GNUNET_PSYC_DATA_CANCEL = 2 +}; + + +struct GNUNET_PSYC_MessageData +{ + /** + * Type: GNUNET_MESSAGE_TYPE_PSYC_MESSAGE_DATA + */ + struct GNUNET_MessageHeader header; + + /** + * enum GNUNET_PSYC_DataStatus + */ + uint8_t status; +}; + +/** * Handle that identifies a join request. * * Used to match calls to #GNUNET_PSYC_JoinCallback to the @@ -193,15 +283,15 @@ enum GNUNET_PSYC_MessageFlags struct GNUNET_PSYC_JoinHandle; -/** - * Method called from PSYC upon receiving a message indicating a call - * to a @e method. +/** + * Method called from PSYC upon receiving a message indicating a call to a + * @e method. * * @param cls Closure. * @param slave_key Who transmitted the message. * - NULL for multicast messages from the master. - * - The hash of the sending slave's public key for unicast requests from - * one of the slaves to the master. + * - The sending slave's public key for unicast requests from one of the + * slaves to the master. * @param message_id Unique message counter for this message. * Unique only in combination with the given sender for this channel. * @param method_name Method name from PSYC. @@ -215,7 +305,7 @@ struct GNUNET_PSYC_JoinHandle; */ typedef int (*GNUNET_PSYC_Method) (void *cls, - const struct GNUNET_CRYPTO_EccPublicSignKey *slave_key, + const struct GNUNET_CRYPTO_EddsaPublicKey *slave_key, uint64_t message_id, const char *method_name, size_t modifier_count, @@ -226,7 +316,7 @@ typedef int enum GNUNET_PSYC_MessageFlags flags); -/** +/** * Method called from PSYC upon receiving a join request. * * @param cls Closure. @@ -241,7 +331,8 @@ typedef int */ typedef int (*GNUNET_PSYC_JoinCallback) (void *cls, - const struct GNUNET_CRYPTO_EccPublicSignKey *slave_key, + const struct GNUNET_CRYPTO_EddsaPublicKey + *slave_key, const char *method_name, size_t variable_count, const struct GNUNET_ENV_Modifier *variables, @@ -250,7 +341,7 @@ typedef int struct GNUNET_PSYC_JoinHandle *jh); -/** +/** * Function to call with the decision made for a join request. * * Must be called once and only once in response to an invocation of the @@ -268,14 +359,15 @@ typedef int * multicast tree. Note that it is unnecessary to specify our own * peer identity in this array. * @param method_name Method name for the message transmitted with the response. - * @param env Environment containing transient variables for the message, or NULL. + * @param env Environment containing transient variables for the message, + * or NULL. * @param data Data of the message. * @param data_size Size of @a data. */ void GNUNET_PSYC_join_decision (struct GNUNET_PSYC_JoinHandle *jh, int is_admitted, - unsigned int relay_count, + uint32_t relay_count, const struct GNUNET_PeerIdentity *relays, const char *method_name, const struct GNUNET_ENV_Environment *env, @@ -283,13 +375,23 @@ GNUNET_PSYC_join_decision (struct GNUNET_PSYC_JoinHandle *jh, size_t data_size); -/** +/** * Handle for the master of a PSYC channel. */ struct GNUNET_PSYC_Master; -/** +/** + * Function called after the channel master started. + * + * @param cls Closure. + * @param last_message_id Last message ID sent to the channel. + */ +typedef void +(*GNUNET_PSYC_MasterStartCallback) (void *cls, uint64_t max_message_id); + + +/** * Start a PSYC master channel. * * Will start a multicast group identified by the given ECC key. Messages @@ -305,7 +407,7 @@ struct GNUNET_PSYC_Master; * @param channel_key ECC key that will be used to sign messages for this * PSYC session. The public key is used to identify the PSYC channel. * Note that end-users will usually not use the private key directly, but - * rather look it up in GADS for places managed by other users, or select + * rather look it up in GNS for places managed by other users, or select * a file with the private key(s) when setting up their own channels * FIXME: we'll likely want to use NOT the p521 curve here, but a cheaper * one in the future. @@ -313,39 +415,40 @@ struct GNUNET_PSYC_Master; * Used to automate join decisions. * @param method Function to invoke on messages received from slaves. * @param join_cb Function to invoke when a peer wants to join. + * @param master_started_cb Function to invoke after the channel master started. * @param cls Closure for @a method and @a join_cb. * @return Handle for the channel master, NULL on error. */ struct GNUNET_PSYC_Master * GNUNET_PSYC_master_start (const struct GNUNET_CONFIGURATION_Handle *cfg, - const struct GNUNET_CRYPTO_EccPrivateKey *channel_key, + const struct GNUNET_CRYPTO_EddsaPrivateKey *channel_key, enum GNUNET_PSYC_Policy policy, GNUNET_PSYC_Method method, GNUNET_PSYC_JoinCallback join_cb, + GNUNET_PSYC_MasterStartCallback master_started_cb, void *cls); -/** +/** * Function called to provide data for a transmission via PSYC. * * Note that returning #GNUNET_OK or #GNUNET_SYSERR (but not #GNUNET_NO) * invalidates the respective transmission handle. * * @param cls Closure. - * @param message_id Set to the unique message ID that was generated for - * this message. * @param[in,out] data_size Initially set to the number of bytes available in * @a data, should be set to the number of bytes written to data. * @param[out] data Where to write the body of the message to give to the * method. The function must copy at most @a data_size bytes to @a data. * @return #GNUNET_SYSERR on error (fatal, aborts transmission) - * #GNUNET_NO on success, if more data is to be transmitted later - * (should be used if @a data_size was not big enough to take all the data) + * #GNUNET_NO on success, if more data is to be transmitted later. + * Should be used if @a data_size was not big enough to take all the + * data. If 0 is returned in @a data_size the transmission is paused, + * and can be resumed with GNUNET_PSYC_master_transmit_resume(). * #GNUNET_YES if this completes the transmission (all data supplied) */ typedef int (*GNUNET_PSYC_MasterTransmitNotify) (void *cls, - uint64_t message_id, size_t *data_size, void *data); @@ -356,13 +459,13 @@ typedef int enum GNUNET_PSYC_MasterTransmitFlags { GNUNET_PSYC_MASTER_TRANSMIT_NONE = 0, - /** + /** * Whether this message should reset the channel state, * i.e. remove all previously stored state variables. */ GNUNET_PSYC_MASTER_TRANSMIT_RESET_STATE = 1 << 0, - /** + /** * Whether we need to increment the group generation counter after * transmitting this message. */ @@ -375,13 +478,13 @@ enum GNUNET_PSYC_MasterTransmitFlags }; -/** +/** * Handle for a pending PSYC transmission operation. */ struct GNUNET_PSYC_MasterTransmitHandle; -/** +/** * Send a message to call a method to all members in the PSYC channel. * * @param master Handle to the PSYC channel. @@ -402,7 +505,16 @@ GNUNET_PSYC_master_transmit (struct GNUNET_PSYC_Master *master, enum GNUNET_PSYC_MasterTransmitFlags flags); -/** +/** + * Resume transmission to the channel. + * + * @param th Handle of the request that is being resumed. + */ +void +GNUNET_PSYC_master_transmit_resume (struct GNUNET_PSYC_MasterTransmitHandle *th); + + +/** * Abort transmission request to channel. * * @param th Handle of the request that is being aborted. @@ -411,7 +523,7 @@ void GNUNET_PSYC_master_transmit_cancel (struct GNUNET_PSYC_MasterTransmitHandle *th); -/** +/** * Stop a PSYC master channel. * * @param master PSYC channel master to stop. @@ -420,17 +532,27 @@ void GNUNET_PSYC_master_stop (struct GNUNET_PSYC_Master *master); -/** +/** * Handle for a PSYC channel slave. */ struct GNUNET_PSYC_Slave; -/** +/** + * Function called after the slave joined. + * + * @param cls Closure. + * @param max_message_id Last message ID sent to the channel. + */ +typedef void +(*GNUNET_PSYC_SlaveJoinCallback) (void *cls, uint64_t max_message_id); + + +/** * Join a PSYC channel. * * The entity joining is always the local peer. The user must immediately use - * the GNUNET_PSYC_slave_to_master() functions to transmit a @e join_msg to the + * the GNUNET_PSYC_slave_transmit() functions to transmit a @e join_msg to the * channel; if the join request succeeds, the channel state (and @e recent * method calls) will be replayed to the joining member. There is no explicit * notification on failure (as the channel may simply take days to approve, @@ -447,8 +569,10 @@ struct GNUNET_PSYC_Slave; * as relays and used to join the group at. * @param method Function to invoke on messages received from the channel, * typically at least contains functions for @e join and @e part. - * @param join_cb Function to invoke when a peer wants to join. - * @param cls Closure for @a method_cb and @a join_cb. + * @param join_cb function invoked once we have joined with the current + * message ID of the channel + * @param slave_joined_cb Function to invoke when a peer wants to join. + * @param cls Closure for @a method_cb and @a slave_joined_cb. * @param method_name Method name for the join request. * @param env Environment containing transient variables for the request, or NULL. * @param data Payload for the join message. @@ -457,25 +581,26 @@ struct GNUNET_PSYC_Slave; */ struct GNUNET_PSYC_Slave * GNUNET_PSYC_slave_join (const struct GNUNET_CONFIGURATION_Handle *cfg, - const struct GNUNET_CRYPTO_EccPublicSignKey *channel_key, - const struct GNUNET_CRYPTO_EccPrivateKey *slave_key, + const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key, + const struct GNUNET_CRYPTO_EddsaPrivateKey *slave_key, const struct GNUNET_PeerIdentity *origin, - size_t relay_count, + uint32_t relay_count, const struct GNUNET_PeerIdentity *relays, GNUNET_PSYC_Method method, GNUNET_PSYC_JoinCallback join_cb, + GNUNET_PSYC_SlaveJoinCallback slave_joined_cb, void *cls, const char *method_name, const struct GNUNET_ENV_Environment *env, const void *data, - size_t data_size); + uint16_t data_size); -/** +/** * Part a PSYC channel. * * Will terminate the connection to the PSYC service. Polite clients should - * first explicitly send a @e part request (via GNUNET_PSYC_slave_to_master()). + * first explicitly send a part request (via GNUNET_PSYC_slave_transmit()). * * @param slave Slave handle. */ @@ -483,16 +608,17 @@ void GNUNET_PSYC_slave_part (struct GNUNET_PSYC_Slave *slave); -/** - * Function called to provide data for a transmission to the channel - * master (aka the @e host of the channel). +/** + * Function called to provide data for a transmission to the channel master + * (a.k.a. the @e host of the channel). * * Note that returning #GNUNET_OK or #GNUNET_SYSERR (but not #GNUNET_NO) * invalidates the respective transmission handle. * * @param cls Closure. - * @param[in,out] data_size Initially set to the number of bytes available in @a data, - * should be set to the number of bytes written to data (IN/OUT). + * @param[in,out] data_size Initially set to the number of bytes available in + * @a data, should be set to the number of bytes written to data + * (IN/OUT). * @param[out] data Where to write the body of the message to give to the method; * function must copy at most @a *data_size bytes to @a data. * @return #GNUNET_SYSERR on error (fatal, aborts transmission). @@ -514,13 +640,13 @@ enum GNUNET_PSYC_SlaveTransmitFlags }; -/** +/** * Handle for a pending PSYC transmission operation. */ struct GNUNET_PSYC_SlaveTransmitHandle; -/** +/** * Request a message to be sent to the channel master. * * @param slave Slave handle. @@ -540,7 +666,16 @@ GNUNET_PSYC_slave_transmit (struct GNUNET_PSYC_Slave *slave, enum GNUNET_PSYC_SlaveTransmitFlags flags); -/** +/** + * Resume transmission to the master. + * + * @param th Handle of the request that is being resumed. + */ +void +GNUNET_PSYC_slave_transmit_resume (struct GNUNET_PSYC_MasterTransmitHandle *th); + + +/** * Abort transmission request to master. * * @param th Handle of the request that is being aborted. @@ -549,14 +684,15 @@ void GNUNET_PSYC_slave_transmit_cancel (struct GNUNET_PSYC_SlaveTransmitHandle *th); -/** +/** * Handle to access PSYC channel operations for both the master and slaves. */ struct GNUNET_PSYC_Channel; -/** - * Convert a channel @a master to a @e channel handle to access the @e channel APIs. +/** + * Convert a channel @a master to a @e channel handle to access the @e channel + * APIs. * * @param master Channel master handle. * @return Channel handle, valid for as long as @a master is valid. @@ -565,7 +701,7 @@ struct GNUNET_PSYC_Channel * GNUNET_PSYC_master_get_channel (struct GNUNET_PSYC_Master *master); -/** +/** * Convert @a slave to a @e channel handle to access the @e channel APIs. * * @param slave Slave handle. @@ -575,7 +711,7 @@ struct GNUNET_PSYC_Channel * GNUNET_PSYC_slave_get_channel (struct GNUNET_PSYC_Slave *slave); -/** +/** * Add a slave to the channel's membership list. * * Note that this will NOT generate any PSYC traffic, it will merely update the @@ -598,12 +734,12 @@ GNUNET_PSYC_slave_get_channel (struct GNUNET_PSYC_Slave *slave); */ void GNUNET_PSYC_channel_slave_add (struct GNUNET_PSYC_Channel *channel, - const struct GNUNET_CRYPTO_EccPublicSignKey *slave_key, + const struct GNUNET_CRYPTO_EddsaPublicKey *slave_key, uint64_t announced_at, uint64_t effective_since); -/** +/** * Remove a slave from the channel's membership list. * * Note that this will NOT generate any PSYC traffic, it will merely update the @@ -626,11 +762,12 @@ GNUNET_PSYC_channel_slave_add (struct GNUNET_PSYC_Channel *channel, */ void GNUNET_PSYC_channel_slave_remove (struct GNUNET_PSYC_Channel *channel, - const struct GNUNET_CRYPTO_EccPublicSignKey *slave_key, + const struct GNUNET_CRYPTO_EddsaPublicKey + *slave_key, uint64_t announced_at); -/** +/** * Function called to inform a member about stored state values for a channel. * * @param cls Closure. @@ -655,13 +792,13 @@ typedef void (*GNUNET_PSYC_FinishCallback) (void *cls); -/** +/** * Handle to a story telling operation. */ struct GNUNET_PSYC_Story; -/** +/** * Request to be told the message history of the channel. * * Historic messages (but NOT the state at the time) will be replayed (given to @@ -691,7 +828,7 @@ GNUNET_PSYC_channel_story_tell (struct GNUNET_PSYC_Channel *channel, void *cls); -/** +/** * Abort story telling. * * This function must not be called from within method handlers (as given to @@ -702,10 +839,14 @@ GNUNET_PSYC_channel_story_tell (struct GNUNET_PSYC_Channel *channel, void GNUNET_PSYC_channel_story_tell_cancel (struct GNUNET_PSYC_Story *story); + +/** + * Handle for a state query operation. + */ struct GNUNET_PSYC_StateQuery; -/** +/** * Retrieve the best matching channel state variable. * * If the requested variable name is not present in the state, the nearest @@ -727,12 +868,12 @@ GNUNET_PSYC_channel_state_get (struct GNUNET_PSYC_Channel *channel, void *cb_cls); -/** +/** * Return all channel state variables whose name matches a given prefix. * - * A name matches if it starts with the given @a name_prefix, thus requesting the - * empty prefix ("") will match all values; requesting "_a_b" will also return - * values stored under "_a_b_c". + * A name matches if it starts with the given @a name_prefix, thus requesting + * the empty prefix ("") will match all values; requesting "_a_b" will also + * return values stored under "_a_b_c". * * The @a state_cb is invoked on all matching state variables asynchronously, as * the state is stored in and retrieved from the PSYCstore, @@ -750,7 +891,7 @@ GNUNET_PSYC_channel_state_get_prefix (struct GNUNET_PSYC_Channel *channel, void *cb_cls); -/** +/** * Cancel a state query operation. * * @param query Handle for the operation to cancel.