diff options
author | TheJackiMonster <thejackimonster@gmail.com> | 2020-11-01 22:57:28 +0100 |
---|---|---|
committer | TheJackiMonster <thejackimonster@gmail.com> | 2021-03-06 01:30:37 +0100 |
commit | 2925310d67483aca6e055e1ce0593c6463cd6c72 (patch) | |
tree | 2cc8aacafc25563cdccde2eee9a90f9ca257d405 /src/include | |
parent | 82b864a64679b0a735201724907cdf2b7e4e16c3 (diff) | |
download | gnunet-2925310d67483aca6e055e1ce0593c6463cd6c72.tar.gz gnunet-2925310d67483aca6e055e1ce0593c6463cd6c72.zip |
-added core functionality of the messenger service
Signed-off-by: TheJackiMonster <thejackimonster@gmail.com>
formatting messenger code
Signed-off-by: TheJackiMonster <thejackimonster@gmail.com>
-completed core functionality of messenger service
Signed-off-by: TheJackiMonster <thejackimonster@gmail.com>
-code cleanup and reuse
Signed-off-by: TheJackiMonster <thejackimonster@gmail.com>
+added structure to memberships of rooms
Signed-off-by: TheJackiMonster <thejackimonster@gmail.com>
-implemented member permission checks and deletion of messages
Signed-off-by: TheJackiMonster <thejackimonster@gmail.com>
-moved solving requests out of updating last messages (also forward before update)
Signed-off-by: TheJackiMonster <thejackimonster@gmail.com>
-reduced complexity of permisson check and changed load/save of rooms
Signed-off-by: TheJackiMonster <thejackimonster@gmail.com>
-added save/load for accessed keys and basement peers of a room
Signed-off-by: TheJackiMonster <thejackimonster@gmail.com>
-implemented save/load for members with their history and session
Signed-off-by: TheJackiMonster <thejackimonster@gmail.com>
-abstracted management of egos and contacts
Signed-off-by: TheJackiMonster <thejackimonster@gmail.com>
-fix warning
Signed-off-by: TheJackiMonster <thejackimonster@gmail.com>
-abstracted management of members
Signed-off-by: TheJackiMonster <thejackimonster@gmail.com>
-fixed and adjusted test case
Signed-off-by: TheJackiMonster <thejackimonster@gmail.com>
-separated handling of direct and anonymous contacts
Signed-off-by: TheJackiMonster <thejackimonster@gmail.com>
-messenger added member-sessions which fix multiple edge cases, also additional cleanup
Signed-off-by: TheJackiMonster <thejackimonster@gmail.com>
-updated docs and fixed memory leak
Signed-off-by: TheJackiMonster <thejackimonster@gmail.com>
-changed info messages and added protocol version exchange
Signed-off-by: TheJackiMonster <thejackimonster@gmail.com>
-adjusted client api to use contacts from sessions
Signed-off-by: TheJackiMonster <thejackimonster@gmail.com>
-added more logging and fixed wrong session usage
Signed-off-by: TheJackiMonster <thejackimonster@gmail.com>
-adjusted comm0 test case and removed adding members from checking messages
Signed-off-by: TheJackiMonster <thejackimonster@gmail.com>
-fixed test-case for peer exchange
Signed-off-by: TheJackiMonster <thejackimonster@gmail.com>
-getting multiple peers connected in test-case with cadet
Signed-off-by: TheJackiMonster <thejackimonster@gmail.com>
-fixed wrong assert and added tunnel version check
-simplified handling and forwarding
Signed-off-by: TheJackiMonster <thejackimonster@gmail.com>
-fixed merging last messages and cycling info messages
Signed-off-by: TheJackiMonster <thejackimonster@gmail.com>
-automated adding sessions and members
Signed-off-by: TheJackiMonster <thejackimonster@gmail.com>
-corrected use of identity keys and signatures
Signed-off-by: TheJackiMonster <thejackimonster@gmail.com>
-adding local joining on entering external room
Signed-off-by: TheJackiMonster <thejackimonster@gmail.com>
-fixed test-case comm0
Signed-off-by: TheJackiMonster <thejackimonster@gmail.com>
-added more test-cases with generic setup
Signed-off-by: TheJackiMonster <thejackimonster@gmail.com>
-fixed multiple simultaneous channels blocking each other
Signed-off-by: TheJackiMonster <thejackimonster@gmail.com>
-making test-cases more precise
Signed-off-by: TheJackiMonster <thejackimonster@gmail.com>
-added check of members in test-cases, reduced merge messages
Signed-off-by: TheJackiMonster <thejackimonster@gmail.com>
-unified delayed operations: requests, deletions and merges
Signed-off-by: TheJackiMonster <thejackimonster@gmail.com>
-finished handling of operations
Signed-off-by: TheJackiMonster <thejackimonster@gmail.com>
-fixed member session historystorage, added request permission check and padding for transmission
Signed-off-by: TheJackiMonster <thejackimonster@gmail.com>
-improved padding and removed automatic recursive requests
Signed-off-by: TheJackiMonster <thejackimonster@gmail.com>
-implemented filter for sending messages and added private messages to API level
Signed-off-by: TheJackiMonster <thejackimonster@gmail.com>
-wrong setups fixed with proper ego lookups
Signed-off-by: TheJackiMonster <thejackimonster@gmail.com>
-fixed problem with anonymous ego and changed to discrete-level padding
Signed-off-by: TheJackiMonster <thejackimonster@gmail.com>
-added links to replace deleted messages, added local deletion and fixed anonymous id changing
Signed-off-by: TheJackiMonster <thejackimonster@gmail.com>
-added session completion and removal through completion process
Signed-off-by: TheJackiMonster <thejackimonster@gmail.com>
Diffstat (limited to 'src/include')
-rw-r--r-- | src/include/gnunet_messenger_service.h | 240 |
1 files changed, 189 insertions, 51 deletions
diff --git a/src/include/gnunet_messenger_service.h b/src/include/gnunet_messenger_service.h index 389b6b8fd..99d4cf267 100644 --- a/src/include/gnunet_messenger_service.h +++ b/src/include/gnunet_messenger_service.h | |||
@@ -48,6 +48,14 @@ extern "C" { | |||
48 | #include "gnunet_scheduler_lib.h" | 48 | #include "gnunet_scheduler_lib.h" |
49 | #include "gnunet_time_lib.h" | 49 | #include "gnunet_time_lib.h" |
50 | 50 | ||
51 | /** | ||
52 | * Version number of GNUnet Messenger API. | ||
53 | */ | ||
54 | #define GNUNET_MESSENGER_VERSION 0x00000001 | ||
55 | |||
56 | /** | ||
57 | * Identifier of GNUnet MESSENGER Service. | ||
58 | */ | ||
51 | #define GNUNET_MESSENGER_SERVICE_NAME "messenger" | 59 | #define GNUNET_MESSENGER_SERVICE_NAME "messenger" |
52 | 60 | ||
53 | /** | 61 | /** |
@@ -141,11 +149,18 @@ enum GNUNET_MESSENGER_MessageKind | |||
141 | GNUNET_MESSENGER_KIND_PRIVATE = 14, | 149 | GNUNET_MESSENGER_KIND_PRIVATE = 14, |
142 | 150 | ||
143 | /** | 151 | /** |
152 | * The delete kind. The message contains a #GNUNET_MESSENGER_MessageDelete body. | ||
153 | */ | ||
154 | GNUNET_MESSENGER_KIND_DELETE = 15, | ||
155 | |||
156 | /** | ||
144 | * The unknown kind. The message contains an unknown body. | 157 | * The unknown kind. The message contains an unknown body. |
145 | */ | 158 | */ |
146 | GNUNET_MESSENGER_KIND_UNKNOWN = 0 | 159 | GNUNET_MESSENGER_KIND_UNKNOWN = 0 |
147 | }; | 160 | }; |
148 | 161 | ||
162 | #define GNUNET_MESSENGER_KIND_MAX (GNUNET_MESSENGER_KIND_DELETE) | ||
163 | |||
149 | /** | 164 | /** |
150 | * Get the name of a message <i>kind</i>. | 165 | * Get the name of a message <i>kind</i>. |
151 | * | 166 | * |
@@ -157,6 +172,9 @@ GNUNET_MESSENGER_name_of_kind (enum GNUNET_MESSENGER_MessageKind kind); | |||
157 | 172 | ||
158 | /** | 173 | /** |
159 | * The header of a #GNUNET_MESSENGER_Message. | 174 | * The header of a #GNUNET_MESSENGER_Message. |
175 | * This allows authentification of the sender, temporal ordering and finding potentially missed messages. | ||
176 | * | ||
177 | * Message-header-size: 40+ bytes | ||
160 | */ | 178 | */ |
161 | struct GNUNET_MESSENGER_MessageHeader | 179 | struct GNUNET_MESSENGER_MessageHeader |
162 | { | 180 | { |
@@ -188,6 +206,9 @@ struct GNUNET_MESSENGER_MessageHeader | |||
188 | 206 | ||
189 | /** | 207 | /** |
190 | * An info message body. | 208 | * An info message body. |
209 | * This allows ensuring member ids are unique and this first message can be verified. | ||
210 | * | ||
211 | * Message-body-size: 8+ bytes | ||
191 | */ | 212 | */ |
192 | struct GNUNET_MESSENGER_MessageInfo | 213 | struct GNUNET_MESSENGER_MessageInfo |
193 | { | 214 | { |
@@ -197,13 +218,16 @@ struct GNUNET_MESSENGER_MessageInfo | |||
197 | struct GNUNET_IDENTITY_PublicKey host_key; | 218 | struct GNUNET_IDENTITY_PublicKey host_key; |
198 | 219 | ||
199 | /** | 220 | /** |
200 | * The new unique id for the receiver in a room. | 221 | * The version of GNUnet Messenger API. |
201 | */ | 222 | */ |
202 | struct GNUNET_ShortHashCode unique_id; | 223 | uint32_t messenger_version; |
203 | }; | 224 | }; |
204 | 225 | ||
205 | /** | 226 | /** |
206 | * A join message body. | 227 | * A join message body. |
228 | * This allows informing others about joining the room with a given key pair. | ||
229 | * | ||
230 | * Message-body-size: 4+ bytes | ||
207 | */ | 231 | */ |
208 | struct GNUNET_MESSENGER_MessageJoin | 232 | struct GNUNET_MESSENGER_MessageJoin |
209 | { | 233 | { |
@@ -215,6 +239,9 @@ struct GNUNET_MESSENGER_MessageJoin | |||
215 | 239 | ||
216 | /** | 240 | /** |
217 | * A leave message body. | 241 | * A leave message body. |
242 | * This allows informing others about leaving the room. | ||
243 | * | ||
244 | * Message-body-size: 0 bytes | ||
218 | */ | 245 | */ |
219 | struct GNUNET_MESSENGER_MessageLeave | 246 | struct GNUNET_MESSENGER_MessageLeave |
220 | { | 247 | { |
@@ -222,6 +249,9 @@ struct GNUNET_MESSENGER_MessageLeave | |||
222 | 249 | ||
223 | /** | 250 | /** |
224 | * A name message body. | 251 | * A name message body. |
252 | * This allows replacing the current name with another one. | ||
253 | * | ||
254 | * Message-body-size: 0+ bytes | ||
225 | */ | 255 | */ |
226 | struct GNUNET_MESSENGER_MessageName | 256 | struct GNUNET_MESSENGER_MessageName |
227 | { | 257 | { |
@@ -233,6 +263,9 @@ struct GNUNET_MESSENGER_MessageName | |||
233 | 263 | ||
234 | /** | 264 | /** |
235 | * A key message body. | 265 | * A key message body. |
266 | * This allows replacing the current key pair with another one. | ||
267 | * | ||
268 | * Message-body-size: 4+ bytes | ||
236 | */ | 269 | */ |
237 | struct GNUNET_MESSENGER_MessageKey | 270 | struct GNUNET_MESSENGER_MessageKey |
238 | { | 271 | { |
@@ -244,6 +277,9 @@ struct GNUNET_MESSENGER_MessageKey | |||
244 | 277 | ||
245 | /** | 278 | /** |
246 | * A peer message body. | 279 | * A peer message body. |
280 | * This allows informing others to open a peer as a door to the current room. | ||
281 | * | ||
282 | * Message-body-size: 32 bytes | ||
247 | */ | 283 | */ |
248 | struct GNUNET_MESSENGER_MessagePeer | 284 | struct GNUNET_MESSENGER_MessagePeer |
249 | { | 285 | { |
@@ -255,6 +291,9 @@ struct GNUNET_MESSENGER_MessagePeer | |||
255 | 291 | ||
256 | /** | 292 | /** |
257 | * An id message body. | 293 | * An id message body. |
294 | * This allows replacing the member id with a newly unique generated one. | ||
295 | * | ||
296 | * Message-body-size: 8 bytes | ||
258 | */ | 297 | */ |
259 | struct GNUNET_MESSENGER_MessageId | 298 | struct GNUNET_MESSENGER_MessageId |
260 | { | 299 | { |
@@ -266,6 +305,9 @@ struct GNUNET_MESSENGER_MessageId | |||
266 | 305 | ||
267 | /** | 306 | /** |
268 | * A miss message body. | 307 | * A miss message body. |
308 | * This allows informing others about a disconnection of any door. | ||
309 | * | ||
310 | * Message-body-size: 32 bytes | ||
269 | */ | 311 | */ |
270 | struct GNUNET_MESSENGER_MessageMiss | 312 | struct GNUNET_MESSENGER_MessageMiss |
271 | { | 313 | { |
@@ -277,6 +319,9 @@ struct GNUNET_MESSENGER_MessageMiss | |||
277 | 319 | ||
278 | /** | 320 | /** |
279 | * A merge message body. | 321 | * A merge message body. |
322 | * This allows merging message history branches together. | ||
323 | * | ||
324 | * Message-body-size: 16 bytes | ||
280 | */ | 325 | */ |
281 | struct GNUNET_MESSENGER_MessageMerge | 326 | struct GNUNET_MESSENGER_MessageMerge |
282 | { | 327 | { |
@@ -288,6 +333,9 @@ struct GNUNET_MESSENGER_MessageMerge | |||
288 | 333 | ||
289 | /** | 334 | /** |
290 | * A request message body. | 335 | * A request message body. |
336 | * This allows requesting the content of a specific message which is currently missing. | ||
337 | * | ||
338 | * Message-body-size: 16 bytes | ||
291 | */ | 339 | */ |
292 | struct GNUNET_MESSENGER_MessageRequest | 340 | struct GNUNET_MESSENGER_MessageRequest |
293 | { | 341 | { |
@@ -299,6 +347,9 @@ struct GNUNET_MESSENGER_MessageRequest | |||
299 | 347 | ||
300 | /** | 348 | /** |
301 | * An invite message body. | 349 | * An invite message body. |
350 | * This allows sharing information about other rooms in form of an invitation. | ||
351 | * | ||
352 | * Message-body-size: 48 bytes | ||
302 | */ | 353 | */ |
303 | struct GNUNET_MESSENGER_MessageInvite | 354 | struct GNUNET_MESSENGER_MessageInvite |
304 | { | 355 | { |
@@ -315,6 +366,9 @@ struct GNUNET_MESSENGER_MessageInvite | |||
315 | 366 | ||
316 | /** | 367 | /** |
317 | * A text message body. | 368 | * A text message body. |
369 | * This allows general communication in text form. | ||
370 | * | ||
371 | * Message-body-size: 0+ bytes | ||
318 | */ | 372 | */ |
319 | struct GNUNET_MESSENGER_MessageText | 373 | struct GNUNET_MESSENGER_MessageText |
320 | { | 374 | { |
@@ -326,6 +380,9 @@ struct GNUNET_MESSENGER_MessageText | |||
326 | 380 | ||
327 | /** | 381 | /** |
328 | * A file message body. | 382 | * A file message body. |
383 | * This allows sending necessary details about an uploaded encrypted file to allow access to it. | ||
384 | * | ||
385 | * Message-body-size: 335+ bytes | ||
329 | */ | 386 | */ |
330 | struct GNUNET_MESSENGER_MessageFile | 387 | struct GNUNET_MESSENGER_MessageFile |
331 | { | 388 | { |
@@ -352,6 +409,9 @@ struct GNUNET_MESSENGER_MessageFile | |||
352 | 409 | ||
353 | /** | 410 | /** |
354 | * A private message body. | 411 | * A private message body. |
412 | * This allows to encapsulate any message to be encrypted for only one specific member to receive in a room. | ||
413 | * | ||
414 | * Message-body-size: 32+ bytes | ||
355 | */ | 415 | */ |
356 | struct GNUNET_MESSENGER_MessagePrivate | 416 | struct GNUNET_MESSENGER_MessagePrivate |
357 | { | 417 | { |
@@ -372,6 +432,25 @@ struct GNUNET_MESSENGER_MessagePrivate | |||
372 | }; | 432 | }; |
373 | 433 | ||
374 | /** | 434 | /** |
435 | * A delete message body | ||
436 | * This allows deletion of an own previous message with any custom automatic delay. | ||
437 | * | ||
438 | * Message-body-size: 24 bytes | ||
439 | */ | ||
440 | struct GNUNET_MESSENGER_MessageDelete | ||
441 | { | ||
442 | /** | ||
443 | * The hash of the message to delete. | ||
444 | */ | ||
445 | struct GNUNET_HashCode hash; | ||
446 | |||
447 | /** | ||
448 | * The delay of the delete operation to get processed. | ||
449 | */ | ||
450 | struct GNUNET_TIME_RelativeNBO delay; | ||
451 | }; | ||
452 | |||
453 | /** | ||
375 | * The unified body of a #GNUNET_MESSENGER_Message. | 454 | * The unified body of a #GNUNET_MESSENGER_Message. |
376 | */ | 455 | */ |
377 | struct GNUNET_MESSENGER_MessageBody | 456 | struct GNUNET_MESSENGER_MessageBody |
@@ -392,6 +471,7 @@ struct GNUNET_MESSENGER_MessageBody | |||
392 | struct GNUNET_MESSENGER_MessageText text; | 471 | struct GNUNET_MESSENGER_MessageText text; |
393 | struct GNUNET_MESSENGER_MessageFile file; | 472 | struct GNUNET_MESSENGER_MessageFile file; |
394 | struct GNUNET_MESSENGER_MessagePrivate private; | 473 | struct GNUNET_MESSENGER_MessagePrivate private; |
474 | struct GNUNET_MESSENGER_MessageDelete delete; | ||
395 | }; | 475 | }; |
396 | }; | 476 | }; |
397 | 477 | ||
@@ -412,11 +492,27 @@ struct GNUNET_MESSENGER_Message | |||
412 | }; | 492 | }; |
413 | 493 | ||
414 | /** | 494 | /** |
495 | * Enum for the different supported flags used by message handling | ||
496 | */ | ||
497 | enum GNUNET_MESSENGER_MessageFlags | ||
498 | { | ||
499 | /** | ||
500 | * The none flag. The flag indicates that the message is not affected by any special context. | ||
501 | */ | ||
502 | GNUNET_MESSENGER_FLAG_NONE = 0, | ||
503 | |||
504 | /** | ||
505 | * The private flag. The flag indicates that the message was privately encrypted. | ||
506 | */ | ||
507 | GNUNET_MESSENGER_FLAG_PRIVATE = 1, | ||
508 | }; | ||
509 | |||
510 | /** | ||
415 | * Method called whenever the EGO of a <i>handle</i> changes or if the first connection fails | 511 | * Method called whenever the EGO of a <i>handle</i> changes or if the first connection fails |
416 | * to load a valid EGO and the anonymous key pair will be used instead. | 512 | * to load a valid EGO and the anonymous key pair will be used instead. |
417 | * | 513 | * |
418 | * @param cls Closure from <i>GNUNET_MESSENGER_connect</i> | 514 | * @param[in/out] cls Closure from #GNUNET_MESSENGER_connect |
419 | * @param handle Messenger handle | 515 | * @param[in/out] handle Messenger handle |
420 | */ | 516 | */ |
421 | typedef void | 517 | typedef void |
422 | (*GNUNET_MESSENGER_IdentityCallback) (void *cls, struct GNUNET_MESSENGER_Handle *handle); | 518 | (*GNUNET_MESSENGER_IdentityCallback) (void *cls, struct GNUNET_MESSENGER_Handle *handle); |
@@ -424,25 +520,45 @@ typedef void | |||
424 | /** | 520 | /** |
425 | * Method called whenever a message is sent or received from a <i>room</i>. | 521 | * Method called whenever a message is sent or received from a <i>room</i>. |
426 | * | 522 | * |
427 | * @param cls Closure from <i>GNUNET_MESSENGER_connect</i> | 523 | * The flag <i>private_message</i> will be #GNUNET_YES if a message was |
428 | * @param room Room handle | 524 | * received privately, otherwise #GNUNET_NO. |
429 | * @param message Newly received or sent message | 525 | * |
430 | * @param hash Hash identifying the message | 526 | * @param[in/out] cls Closure from #GNUNET_MESSENGER_connect |
527 | * @param[in] room Room handle | ||
528 | * @param[in] sender Sender of message | ||
529 | * @param[in] message Newly received or sent message | ||
530 | * @param[in] hash Hash identifying the message | ||
531 | * @param[in] flags Flags of the message | ||
431 | */ | 532 | */ |
432 | typedef void | 533 | typedef void |
433 | (*GNUNET_MESSENGER_MessageCallback) (void *cls, const struct GNUNET_MESSENGER_Room *room, | 534 | (*GNUNET_MESSENGER_MessageCallback) (void *cls, struct GNUNET_MESSENGER_Room *room, |
434 | const struct GNUNET_MESSENGER_Message *message, const struct GNUNET_HashCode *hash); | 535 | const struct GNUNET_MESSENGER_Contact *sender, |
536 | const struct GNUNET_MESSENGER_Message *message, | ||
537 | const struct GNUNET_HashCode *hash, | ||
538 | enum GNUNET_MESSENGER_MessageFlags flags); | ||
539 | |||
540 | /** | ||
541 | * Method called for each member in a <i>room</i> during iteration. If the method returns | ||
542 | * #GNUNET_YES the iteration continues, otherwise it will quit the iteration. | ||
543 | * | ||
544 | * @param[in/out] cls Closure from #GNUNET_MESSENGER_iterate_members | ||
545 | * @param[in] room Room handle | ||
546 | * @param[in] contact Contact handle | ||
547 | */ | ||
548 | typedef int | ||
549 | (*GNUNET_MESSENGER_MemberCallback) (void* cls, struct GNUNET_MESSENGER_Room *room, | ||
550 | const struct GNUNET_MESSENGER_Contact *contact); | ||
435 | 551 | ||
436 | /** | 552 | /** |
437 | * Set up a handle for the messenger related functions and connects to all necessary services. It will look up the ego | 553 | * Set up a handle for the messenger related functions and connects to all necessary services. It will look up the ego |
438 | * key identified by its <i>name</i> and use it for signing all messages from the handle. | 554 | * key identified by its <i>name</i> and use it for signing all messages from the handle. |
439 | * | 555 | * |
440 | * @param cfg Configuration to use | 556 | * @param[in] cfg Configuration to use |
441 | * @param name Name to look up an ego or NULL to stay anonymous | 557 | * @param[in] name Name to look up an ego or NULL to stay anonymous |
442 | * @param identity_callback Function called when the EGO of the handle changes | 558 | * @param[in] identity_callback Function called when the EGO of the handle changes |
443 | * @param identity_cls Closure for the <i>identity_callback</i> handler | 559 | * @param[in/out] identity_cls Closure for the <i>identity_callback</i> handler |
444 | * @param msg_callback Function called when a new message is sent or received | 560 | * @param[in] msg_callback Function called when a new message is sent or received |
445 | * @param msg_cls Closure for the <i>msg_callback</i> handler | 561 | * @param[in/out] msg_cls Closure for the <i>msg_callback</i> handler |
446 | * @return Messenger handle to use, NULL on error | 562 | * @return Messenger handle to use, NULL on error |
447 | */ | 563 | */ |
448 | struct GNUNET_MESSENGER_Handle* | 564 | struct GNUNET_MESSENGER_Handle* |
@@ -458,8 +574,8 @@ GNUNET_MESSENGER_connect (const struct GNUNET_CONFIGURATION_Handle *cfg, const c | |||
458 | * Keep in mind that this will fully delete the old ego key (if any is used) even if any other service wants to use it | 574 | * Keep in mind that this will fully delete the old ego key (if any is used) even if any other service wants to use it |
459 | * as default. | 575 | * as default. |
460 | * | 576 | * |
461 | * @param handle Messenger handle to use | 577 | * @param[in/out] handle Messenger handle to use |
462 | * @return GNUNET_OK on success, GNUNET_SYSERR on failure | 578 | * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure |
463 | */ | 579 | */ |
464 | int | 580 | int |
465 | GNUNET_MESSENGER_update (struct GNUNET_MESSENGER_Handle *handle); | 581 | GNUNET_MESSENGER_update (struct GNUNET_MESSENGER_Handle *handle); |
@@ -467,7 +583,7 @@ GNUNET_MESSENGER_update (struct GNUNET_MESSENGER_Handle *handle); | |||
467 | /** | 583 | /** |
468 | * Disconnect all of the messengers used services and clears up its used memory. | 584 | * Disconnect all of the messengers used services and clears up its used memory. |
469 | * | 585 | * |
470 | * @param handle Messenger handle to use | 586 | * @param[in/out] handle Messenger handle to use |
471 | */ | 587 | */ |
472 | void | 588 | void |
473 | GNUNET_MESSENGER_disconnect (struct GNUNET_MESSENGER_Handle *handle); | 589 | GNUNET_MESSENGER_disconnect (struct GNUNET_MESSENGER_Handle *handle); |
@@ -475,7 +591,7 @@ GNUNET_MESSENGER_disconnect (struct GNUNET_MESSENGER_Handle *handle); | |||
475 | /** | 591 | /** |
476 | * Get the name (if specified, otherwise NULL) used by the messenger. | 592 | * Get the name (if specified, otherwise NULL) used by the messenger. |
477 | * | 593 | * |
478 | * @param handle Messenger handle to use | 594 | * @param[in] handle Messenger handle to use |
479 | * @return Name used by the messenger or NULL | 595 | * @return Name used by the messenger or NULL |
480 | */ | 596 | */ |
481 | const char* | 597 | const char* |
@@ -483,21 +599,21 @@ GNUNET_MESSENGER_get_name (const struct GNUNET_MESSENGER_Handle *handle); | |||
483 | 599 | ||
484 | /** | 600 | /** |
485 | * Set the name for the messenger. This will rename the currently used ego and move all stored files related to the current | 601 | * Set the name for the messenger. This will rename the currently used ego and move all stored files related to the current |
486 | * name to its new directory. If anything fails during this process the function returns GNUNET_NO and the name for | 602 | * name to its new directory. If anything fails during this process the function returns #GNUNET_NO and the name for |
487 | * the messenger won't change as specified. | 603 | * the messenger won't change as specified. |
488 | * | 604 | * |
489 | * @param handle Messenger handle to use | 605 | * @param[in/out] handle Messenger handle to use |
490 | * @param name Name for the messenger to change to | 606 | * @param[in] name Name for the messenger to change to |
491 | * @return GNUNET_YES on success, GNUNET_NO on failure and GNUNET_SYSERR if <i>handle</i> is NULL | 607 | * @return #GNUNET_YES on success, #GNUNET_NO on failure and #GNUNET_SYSERR if <i>handle</i> is NULL |
492 | */ | 608 | */ |
493 | int | 609 | int |
494 | GNUNET_MESSENGER_set_name (struct GNUNET_MESSENGER_Handle *handle, const char *name); | 610 | GNUNET_MESSENGER_set_name (struct GNUNET_MESSENGER_Handle *handle, const char *name); |
495 | 611 | ||
496 | /** | 612 | /** |
497 | * Get the public key used by the messenger. | 613 | * Get the public key used by the messenger or NULL if the anonymous key was used. |
498 | * | 614 | * |
499 | * @param handle Messenger handle to use | 615 | * @param[in] handle Messenger handle to use |
500 | * @return Used ego's public key | 616 | * @return Used ego's public key or NULL |
501 | */ | 617 | */ |
502 | const struct GNUNET_IDENTITY_PublicKey* | 618 | const struct GNUNET_IDENTITY_PublicKey* |
503 | GNUNET_MESSENGER_get_key (const struct GNUNET_MESSENGER_Handle *handle); | 619 | GNUNET_MESSENGER_get_key (const struct GNUNET_MESSENGER_Handle *handle); |
@@ -509,38 +625,38 @@ GNUNET_MESSENGER_get_key (const struct GNUNET_MESSENGER_Handle *handle); | |||
509 | * Notice that there can only be one room related to a specific <i>key</i>. So trying to open two rooms with the same | 625 | * Notice that there can only be one room related to a specific <i>key</i>. So trying to open two rooms with the same |
510 | * <i>key</i> will result in opening the room once but returning the handle both times because the room stays open. | 626 | * <i>key</i> will result in opening the room once but returning the handle both times because the room stays open. |
511 | * | 627 | * |
512 | * You can also open a room after entering it through a <b>door</b> using <i>GNUNET_MESSENGER_entry_room(...)</i>. This | 628 | * You can also open a room after entering it through a <b>door</b> using #GNUNET_MESSENGER_enter_room. This |
513 | * will notify all entered <b>doors</b> to list you as new <b>door</b>. | 629 | * will notify all entered <b>doors</b> to list you as new <b>door</b>. |
514 | * | 630 | * |
515 | * ( All <b>doors</b> form a ring structured network to shorten the latency sending and receiving messages. ) | 631 | * ( All <b>doors</b> form a ring structured network to shorten the latency sending and receiving messages. ) |
516 | * | 632 | * |
517 | * @param handle Messenger handle to use | 633 | * @param[in/out] handle Messenger handle to use |
518 | * @param key Hash identifying the port | 634 | * @param[in] key Hash identifying the port |
519 | * @return Room handle, NULL on error | 635 | * @return Room handle, NULL on error |
520 | */ | 636 | */ |
521 | struct GNUNET_MESSENGER_Room* | 637 | struct GNUNET_MESSENGER_Room* |
522 | GNUNET_MESSENGER_open_room (struct GNUNET_MESSENGER_Handle *handle, const struct GNUNET_HashCode *key); | 638 | GNUNET_MESSENGER_open_room (struct GNUNET_MESSENGER_Handle *handle, const struct GNUNET_HashCode *key); |
523 | 639 | ||
524 | /** | 640 | /** |
525 | * Enter a room to send and receive messages through a <b>door</b> opened using <i>GNUNET_MESSENGER_open_room(...)</i>. | 641 | * Enter a room to send and receive messages through a <b>door</b> opened using #GNUNET_MESSENGER_open_room. |
526 | * | 642 | * |
527 | * Notice that there can only be one room related to a specific <i>key</i>. So trying to enter two rooms with the same | 643 | * Notice that there can only be one room related to a specific <i>key</i>. So trying to enter two rooms with the same |
528 | * <i>key</i> will result in entering the room once but returning the handle both times because the room stays entered. | 644 | * <i>key</i> will result in entering the room once but returning the handle both times because the room stays entered. |
529 | * You can however enter a room through multiple <b>doors</b> in parallel which results in connecting both ends. But | 645 | * You can however enter a room through multiple <b>doors</b> in parallel which results in connecting both ends. But |
530 | * entering the room through the same <b>door</b> won't have any effect after the first time. | 646 | * entering the room through the same <b>door</b> won't have any effect after the first time. |
531 | * | 647 | * |
532 | * You can also enter a room through a <b>door</b> after opening it using <i>GNUNET_MESSENGER_open_room(...)</i>. But the | 648 | * You can also enter a room through a <b>door</b> after opening it using #GNUNET_MESSENGER_open_room. But the |
533 | * <b>door</b> may not be your own peer identity. | 649 | * <b>door</b> may not be your own peer identity. |
534 | * | 650 | * |
535 | * ( All <b>doors</b> form a ring structured network to shorten the latency sending and receiving messages. ) | 651 | * ( All <b>doors</b> form a ring structured network to shorten the latency sending and receiving messages. ) |
536 | * | 652 | * |
537 | * @param handle Messenger handle to use | 653 | * @param[in/out] handle Messenger handle to use |
538 | * @param door Peer identity of an open <b>door</b> | 654 | * @param[in] door Peer identity of an open <b>door</b> |
539 | * @param key Hash identifying the port | 655 | * @param[in] key Hash identifying the port |
540 | * @return Room handle, NULL on error | 656 | * @return Room handle, NULL on error |
541 | */ | 657 | */ |
542 | struct GNUNET_MESSENGER_Room* | 658 | struct GNUNET_MESSENGER_Room* |
543 | GNUNET_MESSENGER_entry_room (struct GNUNET_MESSENGER_Handle *handle, const struct GNUNET_PeerIdentity *door, | 659 | GNUNET_MESSENGER_enter_room (struct GNUNET_MESSENGER_Handle *handle, const struct GNUNET_PeerIdentity *door, |
544 | const struct GNUNET_HashCode *key); | 660 | const struct GNUNET_HashCode *key); |
545 | 661 | ||
546 | /** | 662 | /** |
@@ -550,37 +666,37 @@ GNUNET_MESSENGER_entry_room (struct GNUNET_MESSENGER_Handle *handle, const struc | |||
550 | * ( After a member closes a <b>door</b>, all members entered through that specific <b>door</b> have to use another one | 666 | * ( After a member closes a <b>door</b>, all members entered through that specific <b>door</b> have to use another one |
551 | * or open the room on their own. ) | 667 | * or open the room on their own. ) |
552 | * | 668 | * |
553 | * @param room Room handle | 669 | * @param[in/out] room Room handle |
554 | */ | 670 | */ |
555 | void | 671 | void |
556 | GNUNET_MESSENGER_close_room (struct GNUNET_MESSENGER_Room *room); | 672 | GNUNET_MESSENGER_close_room (struct GNUNET_MESSENGER_Room *room); |
557 | 673 | ||
558 | /** | 674 | /** |
559 | * Get the contact of a member in a <i>room</i> identified by their <i>id</i>. | 675 | * Get the contact of a member in a <i>room</i> which sent a specific message identified with a given <i>hash</i>. |
560 | * | 676 | * |
561 | * Notice that contacts are independent of rooms but will be removed if all rooms containing these contacts get closed. | 677 | * Notice that contacts are independent of rooms but will be removed if all rooms containing these contacts get closed. |
562 | * | 678 | * |
563 | * @param room Room handle | 679 | * @param[in] room Room handle |
564 | * @param id Hash identifying a member | 680 | * @param[in] hash Hash identifying a message |
565 | * @return Contact handle, NULL if <i>id</i> is not in use | 681 | * @return Contact handle, NULL otherwise |
566 | */ | 682 | */ |
567 | struct GNUNET_MESSENGER_Contact* | 683 | struct GNUNET_MESSENGER_Contact* |
568 | GNUNET_MESSENGER_get_member (const struct GNUNET_MESSENGER_Room *room, const struct GNUNET_ShortHashCode *id); | 684 | GNUNET_MESSENGER_get_sender (const struct GNUNET_MESSENGER_Room *room, const struct GNUNET_HashCode *hash); |
569 | 685 | ||
570 | /** | 686 | /** |
571 | * Get the name used by the <i>contact</i>. | 687 | * Get the name used by the <i>contact</i>. |
572 | * | 688 | * |
573 | * @param contact Contact handle | 689 | * @param[in] contact Contact handle |
574 | * @return Name of <i>contact</i> or NULL | 690 | * @return Name of <i>contact</i> or NULL |
575 | */ | 691 | */ |
576 | const char* | 692 | const char* |
577 | GNUNET_MESSENGER_contact_get_name (const struct GNUNET_MESSENGER_Contact *contact); | 693 | GNUNET_MESSENGER_contact_get_name (const struct GNUNET_MESSENGER_Contact *contact); |
578 | 694 | ||
579 | /** | 695 | /** |
580 | * Get the public key used by the <i>contact</i>. | 696 | * Get the public key used by the <i>contact</i> or NULL if the anonymous key was used. |
581 | * | 697 | * |
582 | * @param contact Contact handle | 698 | * @param[in] contact Contact handle |
583 | * @return Public key of the ego used by <i>contact</i> | 699 | * @return Public key of the ego used by <i>contact</i> or NULL |
584 | */ | 700 | */ |
585 | const struct GNUNET_IDENTITY_PublicKey* | 701 | const struct GNUNET_IDENTITY_PublicKey* |
586 | GNUNET_MESSENGER_contact_get_key (const struct GNUNET_MESSENGER_Contact *contact); | 702 | GNUNET_MESSENGER_contact_get_key (const struct GNUNET_MESSENGER_Contact *contact); |
@@ -593,22 +709,44 @@ GNUNET_MESSENGER_contact_get_key (const struct GNUNET_MESSENGER_Contact *contact | |||
593 | * | 709 | * |
594 | * Notice that all messages sent and received are also stored and can be propagated to new members entering the room. | 710 | * Notice that all messages sent and received are also stored and can be propagated to new members entering the room. |
595 | * | 711 | * |
596 | * @param room Room handle | 712 | * If you provide a specific <i>contact</i> as receiver of the given message, the message will automatically be |
597 | * @param message New message to send | 713 | * encrypted and sent as a private message (see #GNUNET_MESSENGER_MessagePrivate). Therefore the selected contact |
714 | * will be the only member receiving the actual message. | ||
715 | * | ||
716 | * Sending a message to all members in a given room can be done by providing NULL as contact. | ||
717 | * | ||
718 | * @param[in/out] room Room handle | ||
719 | * @param[in] message New message to send | ||
720 | * @param[in] contact Contact or NULL | ||
598 | */ | 721 | */ |
599 | void | 722 | void |
600 | GNUNET_MESSENGER_send_message (struct GNUNET_MESSENGER_Room *room, const struct GNUNET_MESSENGER_Message *message); | 723 | GNUNET_MESSENGER_send_message (struct GNUNET_MESSENGER_Room *room, const struct GNUNET_MESSENGER_Message *message, |
724 | const struct GNUNET_MESSENGER_Contact* contact); | ||
601 | 725 | ||
602 | /** | 726 | /** |
603 | * Get the message in a <i>room</i> identified by its <i>hash</i>. | 727 | * Get the message in a <i>room</i> identified by its <i>hash</i>. |
604 | * | 728 | * |
605 | * @param room Room handle | 729 | * @param[in] room Room handle |
606 | * @param hash Hash identifying a message | 730 | * @param[in] hash Hash identifying a message |
607 | * @return Message struct or NULL if no message with that hash is known | 731 | * @return Message struct or NULL if no message with that hash is known |
608 | */ | 732 | */ |
609 | const struct GNUNET_MESSENGER_Message* | 733 | const struct GNUNET_MESSENGER_Message* |
610 | GNUNET_MESSENGER_get_message (const struct GNUNET_MESSENGER_Room *room, const struct GNUNET_HashCode *hash); | 734 | GNUNET_MESSENGER_get_message (const struct GNUNET_MESSENGER_Room *room, const struct GNUNET_HashCode *hash); |
611 | 735 | ||
736 | /** | ||
737 | * Iterates through all members of a given <i>room</i> and calls a selected <i>callback</i> | ||
738 | * for each of them with a provided closure. The callback will receive the contact of each | ||
739 | * member. The function returns the amount of members iterated with the given callback. | ||
740 | * | ||
741 | * @param[in] room Room handle | ||
742 | * @param[in] callback Function called for each member | ||
743 | * @param[in] cls Closure for the <i>callback</i> handler | ||
744 | * @return Amount of members iterated | ||
745 | */ | ||
746 | int | ||
747 | GNUNET_MESSENGER_iterate_members (struct GNUNET_MESSENGER_Room *room, GNUNET_MESSENGER_MemberCallback callback, | ||
748 | void* cls); | ||
749 | |||
612 | #if 0 /* keep Emacsens' auto-indent happy */ | 750 | #if 0 /* keep Emacsens' auto-indent happy */ |
613 | { | 751 | { |
614 | #endif | 752 | #endif |