aboutsummaryrefslogtreecommitdiff
path: root/src/include
diff options
context:
space:
mode:
authorTheJackiMonster <thejackimonster@gmail.com>2020-11-01 22:57:28 +0100
committerTheJackiMonster <thejackimonster@gmail.com>2021-03-06 01:30:37 +0100
commit2925310d67483aca6e055e1ce0593c6463cd6c72 (patch)
tree2cc8aacafc25563cdccde2eee9a90f9ca257d405 /src/include
parent82b864a64679b0a735201724907cdf2b7e4e16c3 (diff)
downloadgnunet-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.h240
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 */
161struct GNUNET_MESSENGER_MessageHeader 179struct 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 */
192struct GNUNET_MESSENGER_MessageInfo 213struct 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 */
208struct GNUNET_MESSENGER_MessageJoin 232struct 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 */
219struct GNUNET_MESSENGER_MessageLeave 246struct 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 */
226struct GNUNET_MESSENGER_MessageName 256struct 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 */
237struct GNUNET_MESSENGER_MessageKey 270struct 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 */
248struct GNUNET_MESSENGER_MessagePeer 284struct 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 */
259struct GNUNET_MESSENGER_MessageId 298struct 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 */
270struct GNUNET_MESSENGER_MessageMiss 312struct 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 */
281struct GNUNET_MESSENGER_MessageMerge 326struct 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 */
292struct GNUNET_MESSENGER_MessageRequest 340struct 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 */
303struct GNUNET_MESSENGER_MessageInvite 354struct 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 */
319struct GNUNET_MESSENGER_MessageText 373struct 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 */
330struct GNUNET_MESSENGER_MessageFile 387struct 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 */
356struct GNUNET_MESSENGER_MessagePrivate 416struct 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 */
440struct 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 */
377struct GNUNET_MESSENGER_MessageBody 456struct 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 */
497enum 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 */
421typedef void 517typedef 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 */
432typedef void 533typedef 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 */
548typedef 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 */
448struct GNUNET_MESSENGER_Handle* 564struct 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 */
464int 580int
465GNUNET_MESSENGER_update (struct GNUNET_MESSENGER_Handle *handle); 581GNUNET_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 */
472void 588void
473GNUNET_MESSENGER_disconnect (struct GNUNET_MESSENGER_Handle *handle); 589GNUNET_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 */
481const char* 597const 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 */
493int 609int
494GNUNET_MESSENGER_set_name (struct GNUNET_MESSENGER_Handle *handle, const char *name); 610GNUNET_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 */
502const struct GNUNET_IDENTITY_PublicKey* 618const struct GNUNET_IDENTITY_PublicKey*
503GNUNET_MESSENGER_get_key (const struct GNUNET_MESSENGER_Handle *handle); 619GNUNET_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 */
521struct GNUNET_MESSENGER_Room* 637struct GNUNET_MESSENGER_Room*
522GNUNET_MESSENGER_open_room (struct GNUNET_MESSENGER_Handle *handle, const struct GNUNET_HashCode *key); 638GNUNET_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 */
542struct GNUNET_MESSENGER_Room* 658struct GNUNET_MESSENGER_Room*
543GNUNET_MESSENGER_entry_room (struct GNUNET_MESSENGER_Handle *handle, const struct GNUNET_PeerIdentity *door, 659GNUNET_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 */
555void 671void
556GNUNET_MESSENGER_close_room (struct GNUNET_MESSENGER_Room *room); 672GNUNET_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 */
567struct GNUNET_MESSENGER_Contact* 683struct GNUNET_MESSENGER_Contact*
568GNUNET_MESSENGER_get_member (const struct GNUNET_MESSENGER_Room *room, const struct GNUNET_ShortHashCode *id); 684GNUNET_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 */
576const char* 692const char*
577GNUNET_MESSENGER_contact_get_name (const struct GNUNET_MESSENGER_Contact *contact); 693GNUNET_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 */
585const struct GNUNET_IDENTITY_PublicKey* 701const struct GNUNET_IDENTITY_PublicKey*
586GNUNET_MESSENGER_contact_get_key (const struct GNUNET_MESSENGER_Contact *contact); 702GNUNET_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 */
599void 722void
600GNUNET_MESSENGER_send_message (struct GNUNET_MESSENGER_Room *room, const struct GNUNET_MESSENGER_Message *message); 723GNUNET_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 */
609const struct GNUNET_MESSENGER_Message* 733const struct GNUNET_MESSENGER_Message*
610GNUNET_MESSENGER_get_message (const struct GNUNET_MESSENGER_Room *room, const struct GNUNET_HashCode *hash); 734GNUNET_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 */
746int
747GNUNET_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