diff options
author | Gabor X Toth <*@tg-x.net> | 2013-07-12 08:47:10 +0000 |
---|---|---|
committer | Gabor X Toth <*@tg-x.net> | 2013-07-12 08:47:10 +0000 |
commit | 15b4d21a45db18ce0384d1c42c83459ba2ed24f8 (patch) | |
tree | a70ebcbc24dca219f1a7df943dc52c0fd706c555 /src/include/gnunet_psyc_service.h | |
parent | 57be99113715a6023164633556ea1de50ceae6e1 (diff) | |
download | gnunet-15b4d21a45db18ce0384d1c42c83459ba2ed24f8.tar.gz gnunet-15b4d21a45db18ce0384d1c42c83459ba2ed24f8.zip |
PSYC APIs: added missing args and functions, more consistent naming
- multicast: origin arg for join; s/leave/part/g
- psyc: origin arg for join; join/part callbacks
- social: enter2, home_advertise, away
- psycstore/social: get latest historic message using ID 0
- added PSYC lib
Diffstat (limited to 'src/include/gnunet_psyc_service.h')
-rw-r--r-- | src/include/gnunet_psyc_service.h | 273 |
1 files changed, 164 insertions, 109 deletions
diff --git a/src/include/gnunet_psyc_service.h b/src/include/gnunet_psyc_service.h index 1eebe0a4b..6987bab82 100644 --- a/src/include/gnunet_psyc_service.h +++ b/src/include/gnunet_psyc_service.h | |||
@@ -28,6 +28,7 @@ | |||
28 | * and this API deliberately exposes as little as possible | 28 | * and this API deliberately exposes as little as possible |
29 | * of the actual data stream format to the application! | 29 | * of the actual data stream format to the application! |
30 | * @author Christian Grothoff | 30 | * @author Christian Grothoff |
31 | * @author Gabor X Toth | ||
31 | * | 32 | * |
32 | * NOTE: | 33 | * NOTE: |
33 | * - this API does not know about psyc's "root" and "places"; | 34 | * - this API does not know about psyc's "root" and "places"; |
@@ -52,7 +53,7 @@ | |||
52 | * - PSYC defines standard variables, methods, etc. This | 53 | * - PSYC defines standard variables, methods, etc. This |
53 | * library deliberately abstracts over all of these; a | 54 | * library deliberately abstracts over all of these; a |
54 | * higher-level API should combine the naming system (GADS) | 55 | * higher-level API should combine the naming system (GADS) |
55 | * and standard methods (message, join, leave, warn, | 56 | * and standard methods (message, join, part, warn, |
56 | * fail, error) and variables (action, color, time, | 57 | * fail, error) and variables (action, color, time, |
57 | * tag, etc.). However, this API does take over the | 58 | * tag, etc.). However, this API does take over the |
58 | * routing variables, specifically 'context' (channel), | 59 | * routing variables, specifically 'context' (channel), |
@@ -75,6 +76,7 @@ | |||
75 | * Idee (lynx): | 76 | * Idee (lynx): |
76 | * - rename "channel" to "master" | 77 | * - rename "channel" to "master" |
77 | * - rename "member" to "slave" | 78 | * - rename "member" to "slave" |
79 | * - rename "group" to "channel" | ||
78 | */ | 80 | */ |
79 | 81 | ||
80 | #ifndef GNUNET_PSYC_SERVICE_H | 82 | #ifndef GNUNET_PSYC_SERVICE_H |
@@ -89,6 +91,7 @@ extern "C" | |||
89 | #endif | 91 | #endif |
90 | 92 | ||
91 | #include "gnunet_util_lib.h" | 93 | #include "gnunet_util_lib.h" |
94 | #include "gnunet_psyc_lib.h" | ||
92 | #include "gnunet_multicast_service.h" | 95 | #include "gnunet_multicast_service.h" |
93 | 96 | ||
94 | 97 | ||
@@ -121,12 +124,27 @@ enum GNUNET_PSYC_FragmentStatus | |||
121 | 124 | ||
122 | 125 | ||
123 | /** | 126 | /** |
127 | * Handle that identifies a join request. | ||
128 | * | ||
129 | * Used to match calls to #GNUNET_PSYC_JoinCallback to the | ||
130 | * corresponding calls to GNUNET_PSYC_join_decision(). | ||
131 | */ | ||
132 | struct GNUNET_PSYC_JoinHandle; | ||
133 | |||
134 | /** | ||
135 | * Handle that identifies a part request. | ||
136 | * | ||
137 | * Used to match calls to #GNUNET_PSYC_PartCallback to the | ||
138 | * corresponding calls to GNUNET_PSYC_part_ack(). | ||
139 | */ | ||
140 | struct GNUNET_PSYC_PartHandle; | ||
141 | |||
142 | |||
143 | /** | ||
124 | * Method called from PSYC upon receiving a message indicating a call | 144 | * Method called from PSYC upon receiving a message indicating a call |
125 | * to a @e method. | 145 | * to a @e method. |
126 | * | 146 | * |
127 | * @param cls Closure. | 147 | * @param cls Closure. |
128 | * @param full_method_name Original method name from PSYC (may be more | ||
129 | * specific than the registered method name due to try-and-slice matching). | ||
130 | * @param sender Who transmitted the message (origin, except for messages | 148 | * @param sender Who transmitted the message (origin, except for messages |
131 | * from one of the members to the origin). | 149 | * from one of the members to the origin). |
132 | * @param message_id Unique message counter for this message; | 150 | * @param message_id Unique message counter for this message; |
@@ -134,6 +152,9 @@ enum GNUNET_PSYC_FragmentStatus | |||
134 | * this channel). | 152 | * this channel). |
135 | * @param group_generation Group generation counter for this message | 153 | * @param group_generation Group generation counter for this message |
136 | * (always zero for messages from members to channel owner); FIXME: needed? | 154 | * (always zero for messages from members to channel owner); FIXME: needed? |
155 | * @param method_name Original method name from PSYC (may be more | ||
156 | * specific than the registered method name due to try-and-slice matching). | ||
157 | * FIXME: no try-and-slice for methods defined here. | ||
137 | * @param data_off Byte offset of @a data in the overall data of the method. | 158 | * @param data_off Byte offset of @a data in the overall data of the method. |
138 | * @param data_size Number of bytes in @a data. | 159 | * @param data_size Number of bytes in @a data. |
139 | * @param data Data stream given to the method (might not be zero-terminated | 160 | * @param data Data stream given to the method (might not be zero-terminated |
@@ -141,10 +162,10 @@ enum GNUNET_PSYC_FragmentStatus | |||
141 | * @param frag Fragmentation status for the data. | 162 | * @param frag Fragmentation status for the data. |
142 | */ | 163 | */ |
143 | typedef int (*GNUNET_PSYC_Method)(void *cls, | 164 | typedef int (*GNUNET_PSYC_Method)(void *cls, |
144 | const char *full_method_name, | ||
145 | const struct GNUNET_PeerIdentity *sender, | 165 | const struct GNUNET_PeerIdentity *sender, |
146 | uint64_t message_id, | 166 | uint64_t message_id, |
147 | uint64_t group_generation, | 167 | uint64_t group_generation, |
168 | const char *method_name, | ||
148 | uint64_t data_off, | 169 | uint64_t data_off, |
149 | size_t data_size, | 170 | size_t data_size, |
150 | const void *data, | 171 | const void *data, |
@@ -152,6 +173,72 @@ typedef int (*GNUNET_PSYC_Method)(void *cls, | |||
152 | 173 | ||
153 | 174 | ||
154 | /** | 175 | /** |
176 | * Method called from PSYC upon receiving a join request. | ||
177 | * | ||
178 | * @param cls Closure. | ||
179 | * @param sender Who transmitted the message. | ||
180 | * @param method_name Method name in the join request. | ||
181 | * @param data_size Number of bytes in @a data. | ||
182 | * @param data Data stream given to the method (might not be zero-terminated | ||
183 | * if data is binary). | ||
184 | */ | ||
185 | typedef int (*GNUNET_PSYC_JoinCallback)(void *cls, | ||
186 | const struct GNUNET_PeerIdentity *sender, | ||
187 | const char *method_name, | ||
188 | size_t data_size, | ||
189 | const void *data, | ||
190 | struct GNUNET_PSYC_JoinHandle *jh); | ||
191 | |||
192 | |||
193 | /** | ||
194 | * Method called from PSYC upon receiving a part request. | ||
195 | * | ||
196 | * @param cls Closure. | ||
197 | * @param sender Who transmitted the message. | ||
198 | * @param method_name Method name in the part request. | ||
199 | * @param data_size Number of bytes in @a data. | ||
200 | * @param data Data stream given to the method (might not be zero-terminated | ||
201 | * if data is binary). | ||
202 | */ | ||
203 | typedef int (*GNUNET_PSYC_PartCallback)(void *cls, | ||
204 | const struct GNUNET_PeerIdentity *sender, | ||
205 | const char *method_name, | ||
206 | size_t data_size, | ||
207 | const void *data, | ||
208 | struct GNUNET_PSYC_PartHandle *ph); | ||
209 | |||
210 | |||
211 | /** | ||
212 | * Function to call with the decision made for a join request. | ||
213 | * | ||
214 | * Must be called once and only once in response to an invocation of the | ||
215 | * #GNUNET_PSYC_JoinCallback. | ||
216 | * | ||
217 | * @param jh Join request handle. | ||
218 | * @param is_admitted #GNUNET_YES if joining is approved, | ||
219 | * #GNUNET_NO if it is disapproved | ||
220 | * @param method_name Method name for the message transmitted with the response. | ||
221 | * @param data_size Size of @a data. | ||
222 | * @param data Data of the message. | ||
223 | */ | ||
224 | void | ||
225 | GNUNET_PSYC_join_decision (struct GNUNET_PSYC_JoinHandle *jh, | ||
226 | int is_admitted, | ||
227 | const char *method_name, | ||
228 | size_t data_size, | ||
229 | const void *data); | ||
230 | |||
231 | |||
232 | /** | ||
233 | * Send a part acknowledgment. | ||
234 | * | ||
235 | * @param ph Part handle. | ||
236 | */ | ||
237 | void | ||
238 | GNUNET_PSYC_part_ack (struct GNUNET_PSYC_PartHandle *ph); | ||
239 | |||
240 | |||
241 | /** | ||
155 | * Handle for the channel of a PSYC group. | 242 | * Handle for the channel of a PSYC group. |
156 | */ | 243 | */ |
157 | struct GNUNET_PSYC_Channel; | 244 | struct GNUNET_PSYC_Channel; |
@@ -166,13 +253,10 @@ struct GNUNET_PSYC_Channel; | |||
166 | * invoked; the join handler must then generate a "join" message to approve the | 253 | * invoked; the join handler must then generate a "join" message to approve the |
167 | * joining of the new member. The channel can also change group membership | 254 | * joining of the new member. The channel can also change group membership |
168 | * without explicit requests. Note that PSYC doesn't itself "understand" join | 255 | * without explicit requests. Note that PSYC doesn't itself "understand" join |
169 | * or leave messages, the respective methods must call other PSYC functions to | 256 | * or part messages, the respective methods must call other PSYC functions to |
170 | * inform PSYC about the meaning of the respective events. | 257 | * inform PSYC about the meaning of the respective events. |
171 | * | 258 | * |
172 | * @param cfg Configuration to use (to connect to PSYC service). | 259 | * @param cfg Configuration to use (to connect to PSYC service). |
173 | * @param method Function to invoke on messages received from members, | ||
174 | * typcially at least contains functions for @e join and @e leave. | ||
175 | * @param method_cls Closure for @a method. | ||
176 | * @param priv_key ECC key that will be used to sign messages for this | 260 | * @param priv_key ECC key that will be used to sign messages for this |
177 | * PSYC session; public key is used to identify the | 261 | * PSYC session; public key is used to identify the |
178 | * PSYC group; FIXME: we'll likely want to use | 262 | * PSYC group; FIXME: we'll likely want to use |
@@ -183,75 +267,46 @@ struct GNUNET_PSYC_Channel; | |||
183 | * key(s) when setting up their own channels | 267 | * key(s) when setting up their own channels |
184 | * @param join_policy What is the membership policy of the group? | 268 | * @param join_policy What is the membership policy of the group? |
185 | * Used to automate group management decisions. | 269 | * Used to automate group management decisions. |
270 | * @param method_cb Function to invoke on messages received from members. | ||
271 | * @param join_cb Function to invoke when a peer wants to join. | ||
272 | * @param part_cb Function to invoke when a peer wants to part. | ||
273 | * @param cls Closure for the callbacks. | ||
186 | * @return Handle for the channel, NULL on error. | 274 | * @return Handle for the channel, NULL on error. |
187 | */ | 275 | */ |
188 | struct GNUNET_PSYC_Channel * | 276 | struct GNUNET_PSYC_Channel * |
189 | GNUNET_PSYC_channel_create (const struct GNUNET_CONFIGURATION_Handle *cfg, | 277 | GNUNET_PSYC_channel_create (const struct GNUNET_CONFIGURATION_Handle *cfg, |
190 | GNUNET_PSYC_Method method, | ||
191 | void *method_cls, | ||
192 | const struct GNUNET_CRYPTO_EccPrivateKey *priv_key, | 278 | const struct GNUNET_CRYPTO_EccPrivateKey *priv_key, |
193 | enum GNUNET_MULTICAST_JoinPolicy join_policy); | 279 | enum GNUNET_MULTICAST_JoinPolicy join_policy, |
194 | 280 | GNUNET_PSYC_Method method_cb, | |
195 | 281 | GNUNET_PSYC_JoinCallback join_cb, | |
196 | /** | 282 | GNUNET_PSYC_PartCallback part_cb, |
197 | * Possible operations on PSYC state (persistent) and variables (per message). | 283 | void *cls); |
198 | */ | ||
199 | enum GNUNET_PSYC_Operator | ||
200 | { | ||
201 | /** | ||
202 | * Replace the full state with the new value ("="). | ||
203 | */ | ||
204 | GNUNET_PSYC_SOT_SET_STATE = 0, | ||
205 | |||
206 | /** | ||
207 | * Delete the complete entry from the state (given data must be | ||
208 | * empty). Equivalent to @a SET with empty data, but more | ||
209 | * explicit ("="); | ||
210 | */ | ||
211 | GNUNET_PSYC_SOT_DELETE = 0, | ||
212 | |||
213 | /** | ||
214 | * Set the value of a variable to a new value (":"). | ||
215 | */ | ||
216 | GNUNET_PSYC_SOT_SET_VARIABLE, | ||
217 | |||
218 | /** | ||
219 | * Add the given value to the set of values in the state ("+"). | ||
220 | */ | ||
221 | GNUNET_PSYC_SOT_ADD_STATE, | ||
222 | |||
223 | /** | ||
224 | * Remove the given value from the set of values in the state ("-"). | ||
225 | */ | ||
226 | GNUNET_PSYC_SOT_REMOVE_STATE | ||
227 | |||
228 | }; | ||
229 | 284 | ||
230 | 285 | ||
231 | /** | 286 | /** |
232 | * Update channel state (or set a variable). | 287 | * Modify channel state (or set a transient variable). |
233 | * | 288 | * |
234 | * The state of a channel must fit into the memory of each member (and the | 289 | * The state of a channel must fit into the memory of each member (and the |
235 | * channel); large values that require streaming must only be passed as the | 290 | * channel); large values that require streaming must only be passed as the |
236 | * stream arguments to methods. State updates might not be transmitted to group | 291 | * stream arguments to methods. State modifications might not be transmitted to |
237 | * members until the next call to GNUNET_PSYC_channel_notify_transmit_ready(). | 292 | * group members until the next call to GNUNET_PSYC_channel_transmit(). |
238 | * Variable updates must be given just before the call to the respective method | 293 | * Variable updates must be given just before the call to the respective method |
239 | * that needs the variables. | 294 | * that needs the variables. |
240 | * | 295 | * |
241 | * @param channel Handle to the PSYC group / channel. | 296 | * @param channel Handle to the PSYC group / channel. |
242 | * @param full_state_name Name of the field in the channel state to change. | 297 | * @param oper Kind of update operation (add, remove, replace, delete). |
243 | * @param type Kind of update operation (add, remove, replace, delete). | 298 | * @param name Name of the state or transient variable to modify. |
244 | * @param data_size Number of bytes in data. | 299 | * @param value_size Number of bytes in @a value. |
245 | * @param data New state value. | 300 | * @param value Value of state variable. |
246 | * @return #GNUNET_OK on success, #GNUNET_SYSERR on internal error | 301 | * @return #GNUNET_OK on success, #GNUNET_SYSERR on internal error |
247 | * (i.e. state too large). | 302 | * (i.e. state too large). |
248 | */ | 303 | */ |
249 | int | 304 | int |
250 | GNUNET_PSYC_channel_state_update (struct GNUNET_PSYC_Channel *channel, | 305 | GNUNET_PSYC_channel_state_modify (struct GNUNET_PSYC_Channel *channel, |
251 | const char *full_state_name, | 306 | enum GNUNET_PSYC_Operator oper, |
252 | enum GNUNET_PSYC_Operator type, | 307 | const char *name, |
253 | size_t data_size, | 308 | size_t value_size, |
254 | const void *data); | 309 | const void *value); |
255 | 310 | ||
256 | 311 | ||
257 | /** | 312 | /** |
@@ -264,10 +319,10 @@ GNUNET_PSYC_channel_state_update (struct GNUNET_PSYC_Channel *channel, | |||
264 | * @param message_id Set to the unique message ID that was generated for | 319 | * @param message_id Set to the unique message ID that was generated for |
265 | * this message. | 320 | * this message. |
266 | * @param group_generation Set to the group generation used for this | 321 | * @param group_generation Set to the group generation used for this |
267 | * message. | 322 | * message. |
268 | * @param data_size[in,out] Initially set to the number of bytes available in @a data, | 323 | * @param data_size[in,out] Initially set to the number of bytes available in @a data, |
269 | * should be set to the number of bytes written to data (IN/OUT). | 324 | * should be set to the number of bytes written to data (IN/OUT). |
270 | * @param data[out] Where to write the body of the message to give to the method; | 325 | * @param[out] data Where to write the body of the message to give to the method; |
271 | * function must copy at most @a *data_size bytes to @a data. | 326 | * function must copy at most @a *data_size bytes to @a data. |
272 | * @return #GNUNET_SYSERR on error (fatal, aborts transmission) | 327 | * @return #GNUNET_SYSERR on error (fatal, aborts transmission) |
273 | * #GNUNET_NO on success, if more data is to be transmitted later | 328 | * #GNUNET_NO on success, if more data is to be transmitted later |
@@ -275,14 +330,14 @@ GNUNET_PSYC_channel_state_update (struct GNUNET_PSYC_Channel *channel, | |||
275 | * #GNUNET_YES if this completes the transmission (all data supplied) | 330 | * #GNUNET_YES if this completes the transmission (all data supplied) |
276 | */ | 331 | */ |
277 | typedef int (*GNUNET_PSYC_ChannelReadyNotify)(void *cls, | 332 | typedef int (*GNUNET_PSYC_ChannelReadyNotify)(void *cls, |
278 | uint64_t message_id, | 333 | uint64_t message_id, |
279 | uint64_t group_generation, | 334 | uint64_t group_generation, |
280 | size_t *data_size, | 335 | size_t *data_size, |
281 | void *data); | 336 | void *data); |
282 | 337 | ||
283 | 338 | ||
284 | /** | 339 | /** |
285 | * Handle for a pending PSYC transmission operation. | 340 | * Handle for a pending PSYC transmission operation. |
286 | */ | 341 | */ |
287 | struct GNUNET_PSYC_ChannelTransmitHandle; | 342 | struct GNUNET_PSYC_ChannelTransmitHandle; |
288 | 343 | ||
@@ -293,17 +348,17 @@ struct GNUNET_PSYC_ChannelTransmitHandle; | |||
293 | * @param channel Handle to the PSYC multicast group. | 348 | * @param channel Handle to the PSYC multicast group. |
294 | * @param increment_group_generation #GNUNET_YES if we need to increment | 349 | * @param increment_group_generation #GNUNET_YES if we need to increment |
295 | * the group generation counter after transmitting this message. | 350 | * the group generation counter after transmitting this message. |
296 | * @param full_method_name Which method should be invoked. | 351 | * @param method_name Which method should be invoked. |
297 | * @param notify Function to call to obtain the arguments. | 352 | * @param notify Function to call to obtain the arguments. |
298 | * @param notify_cls Closure for @a notify. | 353 | * @param notify_cls Closure for @a notify. |
299 | * @return Transmission handle, NULL on error (i.e. more than one request queued). | 354 | * @return Transmission handle, NULL on error (i.e. more than one request queued). |
300 | */ | 355 | */ |
301 | struct GNUNET_PSYC_ChannelTransmitHandle * | 356 | struct GNUNET_PSYC_ChannelTransmitHandle * |
302 | GNUNET_PSYC_channel_notify_transmit_ready (struct GNUNET_PSYC_Channel *channel, | 357 | GNUNET_PSYC_channel_transmit (struct GNUNET_PSYC_Channel *channel, |
303 | int increment_group_generation, | 358 | int increment_group_generation, |
304 | const char *full_method_name, | 359 | const char *method_name, |
305 | GNUNET_PSYC_ChannelReadyNotify notify, | 360 | GNUNET_PSYC_ChannelReadyNotify notify, |
306 | void *notify_cls); | 361 | void *notify_cls); |
307 | 362 | ||
308 | 363 | ||
309 | /** | 364 | /** |
@@ -312,7 +367,7 @@ GNUNET_PSYC_channel_notify_transmit_ready (struct GNUNET_PSYC_Channel *channel, | |||
312 | * @param th Handle of the request that is being aborted. | 367 | * @param th Handle of the request that is being aborted. |
313 | */ | 368 | */ |
314 | void | 369 | void |
315 | GNUNET_PSYC_channel_notify_transmit_ready_cancel (struct GNUNET_PSYC_ChannelTransmitHandle *th); | 370 | GNUNET_PSYC_channel_transmit_cancel (struct GNUNET_PSYC_ChannelTransmitHandle *th); |
316 | 371 | ||
317 | 372 | ||
318 | /** | 373 | /** |
@@ -358,13 +413,12 @@ GNUNET_PSYC_member_get_group (struct GNUNET_PSYC_Member *member); | |||
358 | * channel still needs to explicitly transmit a @e join message to notify other | 413 | * channel still needs to explicitly transmit a @e join message to notify other |
359 | * group members and they then also must still call this function in their | 414 | * group members and they then also must still call this function in their |
360 | * respective methods handling the @e join message. This way, how @e join and | 415 | * respective methods handling the @e join message. This way, how @e join and |
361 | * @e leave operations are exactly implemented is still up to the application; | 416 | * @e part operations are exactly implemented is still up to the application; |
362 | * for example, there might be a @e leave_all method to kick out everyone. | 417 | * for example, there might be a @e part_all method to kick out everyone. |
363 | * | 418 | * |
364 | * Note that group members are explicitly trusted to execute such | 419 | * Note that group members are explicitly trusted to execute such methods |
365 | * methods correctly; not doing so correctly will result in either | 420 | * correctly; not doing so correctly will result in either denying members |
366 | * denying members access or offering access to group data to | 421 | * access or offering access to group data to non-members. |
367 | * non-members. | ||
368 | * | 422 | * |
369 | * @param group Group handle. | 423 | * @param group Group handle. |
370 | * @param member Which peer to add. | 424 | * @param member Which peer to add. |
@@ -383,11 +437,11 @@ GNUNET_PSYC_group_member_add (struct GNUNET_PSYC_Group *group, | |||
383 | * | 437 | * |
384 | * Note that this will NOT generate any PSYC traffic, it will merely update the | 438 | * Note that this will NOT generate any PSYC traffic, it will merely update the |
385 | * local data base to modify how we react to <em>membership test</em> queries. The | 439 | * local data base to modify how we react to <em>membership test</em> queries. The |
386 | * channel still needs to explicitly transmit a @e leave message to notify other | 440 | * channel still needs to explicitly transmit a @e part message to notify other |
387 | * group members and they then also must still call this function in their | 441 | * group members and they then also must still call this function in their |
388 | * respective methods handling the @e leave message. This way, how @e join and | 442 | * respective methods handling the @e part message. This way, how @e join and |
389 | * @e leave operations are exactly implemented is still up to the application; | 443 | * @e part operations are exactly implemented is still up to the application; |
390 | * for example, there might be a @e leave_all message to kick out everyone. | 444 | * for example, there might be a @e part_all message to kick out everyone. |
391 | * | 445 | * |
392 | * Note that group members are explicitly trusted to perform these | 446 | * Note that group members are explicitly trusted to perform these |
393 | * operations correctly; not doing so correctly will result in either | 447 | * operations correctly; not doing so correctly will result in either |
@@ -447,22 +501,22 @@ struct GNUNET_PSYC_StateHandler | |||
447 | 501 | ||
448 | }; | 502 | }; |
449 | 503 | ||
450 | |||
451 | /** | 504 | /** |
452 | * Join a PSYC group. | 505 | * Join a PSYC group. |
453 | * | 506 | * |
454 | * The entity joining is always the local peer. The user must immediately use | 507 | * The entity joining is always the local peer. The user must immediately use |
455 | * the GNUNET_PSYC_member_send_to_host() (and possibly | 508 | * the GNUNET_PSYC_member_to_origin() (and possibly |
456 | * GNUNET_PSYC_member_host_variable_set()) functions to transmit a @e join_msg to | 509 | * GNUNET_PSYC_member_origin_variable_set()) functions to transmit a @e join_msg to |
457 | * the channel; if the join request succeeds, the channel state (and @e recent | 510 | * the channel; if the join request succeeds, the channel state (and @e recent |
458 | * method calls) will be replayed to the joining member. There is no explicit | 511 | * method calls) will be replayed to the joining member. There is no explicit |
459 | * notification on failure (as the channel may simply take days to approve, and | 512 | * notification on failure (as the channel may simply take days to approve, a-v/snd |
460 | * disapproval is simply being ignored). | 513 | * disapproval is simply being ignored). |
461 | * | 514 | * |
462 | * @param cfg Configuration to use. | 515 | * @param cfg Configuration to use. |
463 | * @param pub_key ECC key that identifies the channel we wish to join | 516 | * @param pub_key ECC key that identifies the channel we wish to join |
517 | * @param origin Peer identity of the origin. | ||
464 | * @param method Function to invoke on messages received from the channel, | 518 | * @param method Function to invoke on messages received from the channel, |
465 | * typically at least contains functions for @e join and @e leave. | 519 | * typically at least contains functions for @e join and @e part. |
466 | * @param method_cls Closure for @a method. | 520 | * @param method_cls Closure for @a method. |
467 | * @param state_count Number of @a state_handlers. | 521 | * @param state_count Number of @a state_handlers. |
468 | * @param state_handlers Array of state event handlers. | 522 | * @param state_handlers Array of state event handlers. |
@@ -471,6 +525,7 @@ struct GNUNET_PSYC_StateHandler | |||
471 | struct GNUNET_PSYC_Member * | 525 | struct GNUNET_PSYC_Member * |
472 | GNUNET_PSYC_member_join (const struct GNUNET_CONFIGURATION_Handle *cfg, | 526 | GNUNET_PSYC_member_join (const struct GNUNET_CONFIGURATION_Handle *cfg, |
473 | const struct GNUNET_CRYPTO_EccPublicKey *pub_key, | 527 | const struct GNUNET_CRYPTO_EccPublicKey *pub_key, |
528 | const struct GNUNET_PeerIdentity *origin, | ||
474 | GNUNET_PSYC_Method method, | 529 | GNUNET_PSYC_Method method, |
475 | void *method_cls, | 530 | void *method_cls, |
476 | unsigned int state_count, | 531 | unsigned int state_count, |
@@ -478,16 +533,15 @@ GNUNET_PSYC_member_join (const struct GNUNET_CONFIGURATION_Handle *cfg, | |||
478 | 533 | ||
479 | 534 | ||
480 | /** | 535 | /** |
481 | * Leave a multicast group. | 536 | * Part a PSYC group. |
482 | * | 537 | * |
483 | * Will terminate the connection to the PSYC service. Polite clients should | 538 | * Will terminate the connection to the PSYC service. Polite clients should |
484 | * first explicitly send a @e leave request (via | 539 | * first explicitly send a @e part request (via GNUNET_PSYC_member_to_origin()). |
485 | * GNUNET_PSYC_member_send_to_host()). | ||
486 | * | 540 | * |
487 | * @param member membership handle | 541 | * @param member membership handle |
488 | */ | 542 | */ |
489 | void | 543 | void |
490 | GNUNET_PSYC_member_leave (struct GNUNET_PSYC_Member *member); | 544 | GNUNET_PSYC_member_part (struct GNUNET_PSYC_Member *member); |
491 | 545 | ||
492 | 546 | ||
493 | /** | 547 | /** |
@@ -500,13 +554,13 @@ GNUNET_PSYC_member_leave (struct GNUNET_PSYC_Member *member); | |||
500 | * @param cls Closure. | 554 | * @param cls Closure. |
501 | * @param data_size[in,out] Initially set to the number of bytes available in @a data, | 555 | * @param data_size[in,out] Initially set to the number of bytes available in @a data, |
502 | * should be set to the number of bytes written to data (IN/OUT). | 556 | * should be set to the number of bytes written to data (IN/OUT). |
503 | * @param data[out] Where to write the body of the message to give to the method; | 557 | * @param[out] data Where to write the body of the message to give to the method; |
504 | * function must copy at most @a *data_size bytes to @a data. | 558 | * function must copy at most @a *data_size bytes to @a data. |
505 | * @return #GNUNET_SYSERR on error (fatal, aborts transmission). | 559 | * @return #GNUNET_SYSERR on error (fatal, aborts transmission). |
506 | * #GNUNET_NO on success, if more data is to be transmitted later. | 560 | * #GNUNET_NO on success, if more data is to be transmitted later. |
507 | * #GNUNET_YES if this completes the transmission (all data supplied). | 561 | * #GNUNET_YES if this completes the transmission (all data supplied). |
508 | */ | 562 | */ |
509 | typedef int (*GNUNET_PSYC_OriginReadyNotify)(void *cls, | 563 | typedef int (*GNUNET_PSYC_MemberReadyNotify)(void *cls, |
510 | size_t *data_size, | 564 | size_t *data_size, |
511 | char *data); | 565 | char *data); |
512 | 566 | ||
@@ -514,7 +568,7 @@ typedef int (*GNUNET_PSYC_OriginReadyNotify)(void *cls, | |||
514 | /** | 568 | /** |
515 | * Handle for a pending PSYC transmission operation. | 569 | * Handle for a pending PSYC transmission operation. |
516 | */ | 570 | */ |
517 | struct GNUNET_PSYC_OriginTransmitHandle; | 571 | struct GNUNET_PSYC_MemberTransmitHandle; |
518 | 572 | ||
519 | 573 | ||
520 | /** | 574 | /** |
@@ -526,18 +580,18 @@ struct GNUNET_PSYC_OriginTransmitHandle; | |||
526 | * @param notify_cls Closure for @a notify. | 580 | * @param notify_cls Closure for @a notify. |
527 | * @return Transmission handle, NULL on error (i.e. more than one request queued). | 581 | * @return Transmission handle, NULL on error (i.e. more than one request queued). |
528 | */ | 582 | */ |
529 | struct GNUNET_PSYC_OriginTransmitHandle * | 583 | struct GNUNET_PSYC_MemberTransmitHandle * |
530 | GNUNET_PSYC_member_send_to_origin (struct GNUNET_PSYC_Member *member, | 584 | GNUNET_PSYC_member_to_origin (struct GNUNET_PSYC_Member *member, |
531 | const char *method_name, | 585 | const char *method_name, |
532 | GNUNET_PSYC_OriginReadyNotify notify, | 586 | GNUNET_PSYC_MemberReadyNotify notify, |
533 | void *notify_cls); | 587 | void *notify_cls); |
534 | 588 | ||
535 | 589 | ||
536 | /** | 590 | /** |
537 | * Set a (temporary, ":") variable for the next message being transmitted | 591 | * Set a (temporary, ":") variable for the next message being transmitted |
538 | * via GNUNET_PSYC_member_send_to_host(). | 592 | * via GNUNET_PSYC_member_to_origin(). |
539 | * | 593 | * |
540 | * If GNUNET_PSYC_member_send_to_host() is called and then cancelled, all | 594 | * If GNUNET_PSYC_member_to_origin() is called and then cancelled, all |
541 | * variables that were set using this function will be unset (lost/forgotten). | 595 | * variables that were set using this function will be unset (lost/forgotten). |
542 | * To clear a variable state after setting it, you can also call this function | 596 | * To clear a variable state after setting it, you can also call this function |
543 | * again with NULL/0 for the @a value. | 597 | * again with NULL/0 for the @a value. |
@@ -560,7 +614,7 @@ GNUNET_PSYC_member_origin_variable_set (struct GNUNET_PSYC_Member *member, | |||
560 | * @param th Handle of the request that is being aborted. | 614 | * @param th Handle of the request that is being aborted. |
561 | */ | 615 | */ |
562 | void | 616 | void |
563 | GNUNET_PSYC_member_send_to_origin_cancel (struct GNUNET_PSYC_OriginTransmitHandle *th); | 617 | GNUNET_PSYC_member_to_origin_cancel (struct GNUNET_PSYC_MemberTransmitHandle *th); |
564 | 618 | ||
565 | 619 | ||
566 | /** | 620 | /** |
@@ -575,9 +629,11 @@ struct GNUNET_PSYC_Story; | |||
575 | * Historic messages (but NOT the state at the time) will be replayed (given to | 629 | * Historic messages (but NOT the state at the time) will be replayed (given to |
576 | * the normal method handlers) if available and if access is permitted. | 630 | * the normal method handlers) if available and if access is permitted. |
577 | * | 631 | * |
632 | * To get the latest message, use 0 for both the start and end message ID. | ||
633 | * | ||
578 | * @param member Which channel should be replayed? | 634 | * @param member Which channel should be replayed? |
579 | * @param start Earliest interesting point in history. | 635 | * @param start_message_id Earliest interesting point in history. |
580 | * @param end Last (exclusive) interesting point in history. | 636 | * @param end_message_id Last (exclusive) interesting point in history. |
581 | * @param method Function to invoke on messages received from the story. | 637 | * @param method Function to invoke on messages received from the story. |
582 | * @param method_cls Closure for @a method. | 638 | * @param method_cls Closure for @a method. |
583 | * @param finish_cb Function to call when the requested story has been fully | 639 | * @param finish_cb Function to call when the requested story has been fully |
@@ -591,8 +647,8 @@ struct GNUNET_PSYC_Story; | |||
591 | */ | 647 | */ |
592 | struct GNUNET_PSYC_Story * | 648 | struct GNUNET_PSYC_Story * |
593 | GNUNET_PSYC_member_story_tell (struct GNUNET_PSYC_Member *member, | 649 | GNUNET_PSYC_member_story_tell (struct GNUNET_PSYC_Member *member, |
594 | uint64_t start, | 650 | uint64_t start_message_id, |
595 | uint64_t end, | 651 | uint64_t end_message_id, |
596 | GNUNET_PSYC_Method method, | 652 | GNUNET_PSYC_Method method, |
597 | void *method_cls, | 653 | void *method_cls, |
598 | void (*finish_cb)(void *), | 654 | void (*finish_cb)(void *), |
@@ -651,7 +707,7 @@ GNUNET_PSYC_member_state_get_all (struct GNUNET_PSYC_Member *member, | |||
651 | * | 707 | * |
652 | * @param member Membership handle. | 708 | * @param member Membership handle. |
653 | * @param variable_name Name of the variable to query. | 709 | * @param variable_name Name of the variable to query. |
654 | * @param return_value_size Set to number of bytes in variable, | 710 | * @param[out] return_value_size Set to number of bytes in variable, |
655 | * needed as variables might contain binary data and | 711 | * needed as variables might contain binary data and |
656 | * might also not be 0-terminated; set to 0 on errors. | 712 | * might also not be 0-terminated; set to 0 on errors. |
657 | * @return NULL on error (no matching state or variable), pointer | 713 | * @return NULL on error (no matching state or variable), pointer |
@@ -663,7 +719,6 @@ GNUNET_PSYC_member_state_get (struct GNUNET_PSYC_Member *member, | |||
663 | size_t *return_value_size); | 719 | size_t *return_value_size); |
664 | 720 | ||
665 | 721 | ||
666 | |||
667 | #if 0 /* keep Emacsens' auto-indent happy */ | 722 | #if 0 /* keep Emacsens' auto-indent happy */ |
668 | { | 723 | { |
669 | #endif | 724 | #endif |