diff options
author | Christian Grothoff <christian@grothoff.org> | 2020-11-14 17:17:42 +0100 |
---|---|---|
committer | Christian Grothoff <christian@grothoff.org> | 2020-11-14 17:17:42 +0100 |
commit | c90b5703c88339f7bdf909b77a45ea93c21792cd (patch) | |
tree | fc3397900dc6bdbcdd17cf773f6d60e53abc025a /src/include | |
parent | f62e24a88c21235bc3c901508cfb474509ef2961 (diff) | |
parent | d36019fe48ff1e4e56754ef3e689bd67445a38f6 (diff) | |
download | gnunet-c90b5703c88339f7bdf909b77a45ea93c21792cd.tar.gz gnunet-c90b5703c88339f7bdf909b77a45ea93c21792cd.zip |
Merge branch 'master' of git+ssh://gnunet.org/gnunet
Diffstat (limited to 'src/include')
-rw-r--r-- | src/include/Makefile.am | 2 | ||||
-rw-r--r-- | src/include/gnunet_messenger_service.h | 621 | ||||
-rw-r--r-- | src/include/gnunet_protocols.h | 43 |
3 files changed, 665 insertions, 1 deletions
diff --git a/src/include/Makefile.am b/src/include/Makefile.am index 202abb7ac..5569c87ed 100644 --- a/src/include/Makefile.am +++ b/src/include/Makefile.am | |||
@@ -51,6 +51,7 @@ gnunetinclude_HEADERS = \ | |||
51 | gnunet_getopt_lib.h \ | 51 | gnunet_getopt_lib.h \ |
52 | gnunet_gns_service.h \ | 52 | gnunet_gns_service.h \ |
53 | gnunet_gnsrecord_lib.h \ | 53 | gnunet_gnsrecord_lib.h \ |
54 | gnunet_gnsrecord_json_lib.h \ | ||
54 | gnunet_gnsrecord_plugin.h \ | 55 | gnunet_gnsrecord_plugin.h \ |
55 | gnunet_hello_lib.h \ | 56 | gnunet_hello_lib.h \ |
56 | gnunet_helper_lib.h \ | 57 | gnunet_helper_lib.h \ |
@@ -62,6 +63,7 @@ gnunetinclude_HEADERS = \ | |||
62 | gnunet_json_lib.h \ | 63 | gnunet_json_lib.h \ |
63 | gnunet_load_lib.h \ | 64 | gnunet_load_lib.h \ |
64 | gnunet_cadet_service.h \ | 65 | gnunet_cadet_service.h \ |
66 | gnunet_messenger_service.h \ | ||
65 | gnunet_mhd_compat.h \ | 67 | gnunet_mhd_compat.h \ |
66 | gnunet_microphone_lib.h \ | 68 | gnunet_microphone_lib.h \ |
67 | gnunet_mst_lib.h \ | 69 | gnunet_mst_lib.h \ |
diff --git a/src/include/gnunet_messenger_service.h b/src/include/gnunet_messenger_service.h new file mode 100644 index 000000000..96d308a01 --- /dev/null +++ b/src/include/gnunet_messenger_service.h | |||
@@ -0,0 +1,621 @@ | |||
1 | /* | ||
2 | This file is part of GNUnet. | ||
3 | Copyright (C) 2020 GNUnet e.V. | ||
4 | |||
5 | GNUnet is free software: you can redistribute it and/or modify it | ||
6 | under the terms of the GNU Affero General Public License as published | ||
7 | by the Free Software Foundation, either version 3 of the License, | ||
8 | or (at your option) any later version. | ||
9 | |||
10 | GNUnet is distributed in the hope that it will be useful, but | ||
11 | WITHOUT ANY WARRANTY; without even the implied warranty of | ||
12 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | ||
13 | Affero General Public License for more details. | ||
14 | |||
15 | You should have received a copy of the GNU Affero General Public License | ||
16 | along with this program. If not, see <http://www.gnu.org/licenses/>. | ||
17 | |||
18 | SPDX-License-Identifier: AGPL3.0-or-later | ||
19 | */ | ||
20 | /** | ||
21 | * @author Tobias Frisch | ||
22 | * | ||
23 | * @file | ||
24 | * MESSENGER service; manages decentralized chat groups | ||
25 | * | ||
26 | * @defgroup messenger MESSENGER service | ||
27 | * Instant messaging based on the CADET subsystem | ||
28 | * | ||
29 | * @{ | ||
30 | */ | ||
31 | |||
32 | #ifndef GNUNET_MESSENGER_SERVICE_H | ||
33 | #define GNUNET_MESSENGER_SERVICE_H | ||
34 | |||
35 | #ifdef __cplusplus | ||
36 | extern "C" { | ||
37 | #if 0 /* keep Emacsens' auto-indent happy */ | ||
38 | } | ||
39 | #endif | ||
40 | #endif | ||
41 | |||
42 | #include "platform.h" | ||
43 | #include "gnunet_configuration_lib.h" | ||
44 | #include "gnunet_crypto_lib.h" | ||
45 | #include "gnunet_identity_service.h" | ||
46 | #include "gnunet_mq_lib.h" | ||
47 | #include "gnunet_protocols.h" | ||
48 | #include "gnunet_scheduler_lib.h" | ||
49 | #include "gnunet_time_lib.h" | ||
50 | |||
51 | #define GNUNET_MESSENGER_SERVICE_NAME "messenger" | ||
52 | |||
53 | /** | ||
54 | * Opaque handle to the messenger | ||
55 | */ | ||
56 | struct GNUNET_MESSENGER_Handle; | ||
57 | |||
58 | /** | ||
59 | * Opaque handle to a room | ||
60 | */ | ||
61 | struct GNUNET_MESSENGER_Room; | ||
62 | |||
63 | /** | ||
64 | * Opaque handle to a contact | ||
65 | */ | ||
66 | struct GNUNET_MESSENGER_Contact; | ||
67 | |||
68 | /** | ||
69 | * Enum for the different supported kinds of messages | ||
70 | */ | ||
71 | enum GNUNET_MESSENGER_MessageKind | ||
72 | { | ||
73 | /** | ||
74 | * The info kind. The message contains a #GNUNET_MESSENGER_MessageInfo body. | ||
75 | */ | ||
76 | GNUNET_MESSENGER_KIND_INFO = 1, | ||
77 | |||
78 | /** | ||
79 | * The join kind. The message contains a #GNUNET_MESSENGER_MessageJoin body. | ||
80 | */ | ||
81 | GNUNET_MESSENGER_KIND_JOIN = 2, | ||
82 | |||
83 | /** | ||
84 | * The leave kind. The message contains a #GNUNET_MESSENGER_MessageLeave body. | ||
85 | */ | ||
86 | GNUNET_MESSENGER_KIND_LEAVE = 3, | ||
87 | |||
88 | /** | ||
89 | * The name kind. The message contains a #GNUNET_MESSENGER_MessageName body. | ||
90 | */ | ||
91 | GNUNET_MESSENGER_KIND_NAME = 4, | ||
92 | |||
93 | /** | ||
94 | * The key kind. The message contains a #GNUNET_MESSENGER_MessageKey body. | ||
95 | */ | ||
96 | GNUNET_MESSENGER_KIND_KEY = 5, | ||
97 | |||
98 | /** | ||
99 | * The peer kind. The message contains a #GNUNET_MESSENGER_MessagePeer body. | ||
100 | */ | ||
101 | GNUNET_MESSENGER_KIND_PEER = 6, | ||
102 | |||
103 | /** | ||
104 | * The id kind. The message contains a #GNUNET_MESSENGER_MessageId body. | ||
105 | */ | ||
106 | GNUNET_MESSENGER_KIND_ID = 7, | ||
107 | |||
108 | /** | ||
109 | * The miss kind. The message contains a #GNUNET_MESSENGER_MessageMiss body. | ||
110 | */ | ||
111 | GNUNET_MESSENGER_KIND_MISS = 8, | ||
112 | |||
113 | /** | ||
114 | * The merge kind. The message contains a #GNUNET_MESSENGER_MessageMerge body. | ||
115 | */ | ||
116 | GNUNET_MESSENGER_KIND_MERGE = 9, | ||
117 | |||
118 | /** | ||
119 | * The request kind. The message contains a #GNUNET_MESSENGER_MessageRequest body. | ||
120 | */ | ||
121 | GNUNET_MESSENGER_KIND_REQUEST = 10, | ||
122 | |||
123 | /** | ||
124 | * The invite kind. The message contains a #GNUNET_MESSENGER_MessageInvite body. | ||
125 | */ | ||
126 | GNUNET_MESSENGER_KIND_INVITE = 11, | ||
127 | |||
128 | /** | ||
129 | * The text kind. The message contains a #GNUNET_MESSENGER_MessageText body. | ||
130 | */ | ||
131 | GNUNET_MESSENGER_KIND_TEXT = 12, | ||
132 | |||
133 | /** | ||
134 | * The file kind. The message contains a #GNUNET_MESSENGER_MessageFile body. | ||
135 | */ | ||
136 | GNUNET_MESSENGER_KIND_FILE = 13, | ||
137 | |||
138 | /** | ||
139 | * The private kind. The message contains a #GNUNET_MESSENGER_MessagePrivate body. | ||
140 | */ | ||
141 | GNUNET_MESSENGER_KIND_PRIVATE = 14, | ||
142 | |||
143 | /** | ||
144 | * The unknown kind. The message contains an unknown body. | ||
145 | */ | ||
146 | GNUNET_MESSENGER_KIND_UNKNOWN = 0 | ||
147 | }; | ||
148 | |||
149 | /** | ||
150 | * Get the name of a message <i>kind</i>. | ||
151 | * | ||
152 | * @param kind Kind of a message | ||
153 | * @return Name of that kind | ||
154 | */ | ||
155 | const char* | ||
156 | GNUNET_MESSENGER_name_of_kind (enum GNUNET_MESSENGER_MessageKind kind); | ||
157 | |||
158 | /** | ||
159 | * The header of a #GNUNET_MESSENGER_Message. | ||
160 | */ | ||
161 | struct GNUNET_MESSENGER_MessageHeader | ||
162 | { | ||
163 | /** | ||
164 | * The signature of the senders private key. | ||
165 | */ | ||
166 | struct GNUNET_IDENTITY_Signature signature; | ||
167 | |||
168 | /** | ||
169 | * The timestamp of the message. | ||
170 | */ | ||
171 | struct GNUNET_TIME_AbsoluteNBO timestamp; | ||
172 | |||
173 | /** | ||
174 | * The senders id inside of the room the message was sent in. | ||
175 | */ | ||
176 | struct GNUNET_ShortHashCode sender_id; | ||
177 | |||
178 | /** | ||
179 | * The hash of the previous message from the senders perspective. | ||
180 | */ | ||
181 | struct GNUNET_HashCode previous; | ||
182 | |||
183 | /** | ||
184 | * The kind of the message. | ||
185 | */ | ||
186 | enum GNUNET_MESSENGER_MessageKind kind; | ||
187 | }; | ||
188 | |||
189 | /** | ||
190 | * An info message body. | ||
191 | */ | ||
192 | struct GNUNET_MESSENGER_MessageInfo | ||
193 | { | ||
194 | /** | ||
195 | * The senders key to verify its signatures. | ||
196 | */ | ||
197 | struct GNUNET_IDENTITY_PublicKey host_key; | ||
198 | |||
199 | /** | ||
200 | * The new unique id for the receiver in a room. | ||
201 | */ | ||
202 | struct GNUNET_ShortHashCode unique_id; | ||
203 | }; | ||
204 | |||
205 | /** | ||
206 | * A join message body. | ||
207 | */ | ||
208 | struct GNUNET_MESSENGER_MessageJoin | ||
209 | { | ||
210 | /** | ||
211 | * The senders public key to verify its signatures. | ||
212 | */ | ||
213 | struct GNUNET_IDENTITY_PublicKey key; | ||
214 | }; | ||
215 | |||
216 | /** | ||
217 | * A leave message body. | ||
218 | */ | ||
219 | struct GNUNET_MESSENGER_MessageLeave | ||
220 | { | ||
221 | }; | ||
222 | |||
223 | /** | ||
224 | * A name message body. | ||
225 | */ | ||
226 | struct GNUNET_MESSENGER_MessageName | ||
227 | { | ||
228 | /** | ||
229 | * The new name which replaces the current senders name. | ||
230 | */ | ||
231 | char *name; | ||
232 | }; | ||
233 | |||
234 | /** | ||
235 | * A key message body. | ||
236 | */ | ||
237 | struct GNUNET_MESSENGER_MessageKey | ||
238 | { | ||
239 | /** | ||
240 | * The new public key which replaces the current senders public key. | ||
241 | */ | ||
242 | struct GNUNET_IDENTITY_PublicKey key; | ||
243 | }; | ||
244 | |||
245 | /** | ||
246 | * A peer message body. | ||
247 | */ | ||
248 | struct GNUNET_MESSENGER_MessagePeer | ||
249 | { | ||
250 | /** | ||
251 | * The peer identity of the sender opening a room. | ||
252 | */ | ||
253 | struct GNUNET_PeerIdentity peer; | ||
254 | }; | ||
255 | |||
256 | /** | ||
257 | * An id message body. | ||
258 | */ | ||
259 | struct GNUNET_MESSENGER_MessageId | ||
260 | { | ||
261 | /** | ||
262 | * The new id which will replace the senders id in a room. | ||
263 | */ | ||
264 | struct GNUNET_ShortHashCode id; | ||
265 | }; | ||
266 | |||
267 | /** | ||
268 | * A miss message body. | ||
269 | */ | ||
270 | struct GNUNET_MESSENGER_MessageMiss | ||
271 | { | ||
272 | /** | ||
273 | * The peer identity of a disconnected door to a room. | ||
274 | */ | ||
275 | struct GNUNET_PeerIdentity peer; | ||
276 | }; | ||
277 | |||
278 | /** | ||
279 | * A merge message body. | ||
280 | */ | ||
281 | struct GNUNET_MESSENGER_MessageMerge | ||
282 | { | ||
283 | /** | ||
284 | * The hash of a second previous message. | ||
285 | */ | ||
286 | struct GNUNET_HashCode previous; | ||
287 | }; | ||
288 | |||
289 | /** | ||
290 | * A request message body. | ||
291 | */ | ||
292 | struct GNUNET_MESSENGER_MessageRequest | ||
293 | { | ||
294 | /** | ||
295 | * The hash of the requested message. | ||
296 | */ | ||
297 | struct GNUNET_HashCode hash; | ||
298 | }; | ||
299 | |||
300 | /** | ||
301 | * An invite message body. | ||
302 | */ | ||
303 | struct GNUNET_MESSENGER_MessageInvite | ||
304 | { | ||
305 | /** | ||
306 | * The peer identity of an open door to a room. | ||
307 | */ | ||
308 | struct GNUNET_PeerIdentity door; | ||
309 | |||
310 | /** | ||
311 | * The hash identifying the port of the room. | ||
312 | */ | ||
313 | struct GNUNET_HashCode key; | ||
314 | }; | ||
315 | |||
316 | /** | ||
317 | * A text message body. | ||
318 | */ | ||
319 | struct GNUNET_MESSENGER_MessageText | ||
320 | { | ||
321 | /** | ||
322 | * The containing text. | ||
323 | */ | ||
324 | char *text; | ||
325 | }; | ||
326 | |||
327 | /** | ||
328 | * A file message body. | ||
329 | */ | ||
330 | struct GNUNET_MESSENGER_MessageFile | ||
331 | { | ||
332 | /** | ||
333 | * The symmetric key to decrypt the file. | ||
334 | */ | ||
335 | struct GNUNET_CRYPTO_SymmetricSessionKey key; | ||
336 | |||
337 | /** | ||
338 | * The hash of the original file. | ||
339 | */ | ||
340 | struct GNUNET_HashCode hash; | ||
341 | |||
342 | /** | ||
343 | * The name of the original file. | ||
344 | */ | ||
345 | char name[NAME_MAX]; | ||
346 | |||
347 | /** | ||
348 | * The uri of the encrypted file. | ||
349 | */ | ||
350 | char *uri; | ||
351 | }; | ||
352 | |||
353 | /** | ||
354 | * A private message body. | ||
355 | */ | ||
356 | struct GNUNET_MESSENGER_MessagePrivate | ||
357 | { | ||
358 | /** | ||
359 | * The ECDH key to decrypt the message. | ||
360 | */ | ||
361 | struct GNUNET_CRYPTO_EcdhePublicKey key; | ||
362 | |||
363 | /** | ||
364 | * The length of the encrypted message. | ||
365 | */ | ||
366 | uint16_t length; | ||
367 | |||
368 | /** | ||
369 | * The data of the encrypted message. | ||
370 | */ | ||
371 | char *data; | ||
372 | }; | ||
373 | |||
374 | /** | ||
375 | * The unified body of a #GNUNET_MESSENGER_Message. | ||
376 | */ | ||
377 | struct GNUNET_MESSENGER_MessageBody | ||
378 | { | ||
379 | union | ||
380 | { | ||
381 | struct GNUNET_MESSENGER_MessageInfo info; | ||
382 | struct GNUNET_MESSENGER_MessageJoin join; | ||
383 | struct GNUNET_MESSENGER_MessageLeave leave; | ||
384 | struct GNUNET_MESSENGER_MessageName name; | ||
385 | struct GNUNET_MESSENGER_MessageKey key; | ||
386 | struct GNUNET_MESSENGER_MessagePeer peer; | ||
387 | struct GNUNET_MESSENGER_MessageId id; | ||
388 | struct GNUNET_MESSENGER_MessageMiss miss; | ||
389 | struct GNUNET_MESSENGER_MessageMerge merge; | ||
390 | struct GNUNET_MESSENGER_MessageRequest request; | ||
391 | struct GNUNET_MESSENGER_MessageInvite invite; | ||
392 | struct GNUNET_MESSENGER_MessageText text; | ||
393 | struct GNUNET_MESSENGER_MessageFile file; | ||
394 | struct GNUNET_MESSENGER_MessagePrivate private; | ||
395 | }; | ||
396 | }; | ||
397 | |||
398 | /** | ||
399 | * Struct to a message | ||
400 | */ | ||
401 | struct GNUNET_MESSENGER_Message | ||
402 | { | ||
403 | /** | ||
404 | * Header. | ||
405 | */ | ||
406 | struct GNUNET_MESSENGER_MessageHeader header; | ||
407 | |||
408 | /** | ||
409 | * Body | ||
410 | */ | ||
411 | struct GNUNET_MESSENGER_MessageBody body; | ||
412 | }; | ||
413 | |||
414 | /** | ||
415 | * 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 keypair will be used instead. | ||
417 | * | ||
418 | * @param cls Closure from <i>GNUNET_MESSENGER_connect</i> | ||
419 | * @param handle Messenger handle | ||
420 | */ | ||
421 | typedef void | ||
422 | (*GNUNET_MESSENGER_IdentityCallback) (void *cls, struct GNUNET_MESSENGER_Handle *handle); | ||
423 | |||
424 | /** | ||
425 | * Method called whenever a message is sent or received from a <i>room</i>. | ||
426 | * | ||
427 | * @param cls Closure from <i>GNUNET_MESSENGER_connect</i> | ||
428 | * @param room Room handle | ||
429 | * @param message Newly received or sent message | ||
430 | * @param hash Hash identifying the message | ||
431 | */ | ||
432 | typedef void | ||
433 | (*GNUNET_MESSENGER_MessageCallback) (void *cls, const struct GNUNET_MESSENGER_Room *room, | ||
434 | const struct GNUNET_MESSENGER_Message *message, const struct GNUNET_HashCode *hash); | ||
435 | |||
436 | /** | ||
437 | * 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. | ||
439 | * | ||
440 | * @param cfg Configuration to use | ||
441 | * @param 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 | ||
443 | * @param identity_cls Closure for the <i>identity_callback</i> handler | ||
444 | * @param msg_callback Function called when a new message is sent or received | ||
445 | * @param msg_cls Closure for the <i>msg_callback</i> handler | ||
446 | * @return Messenger handle to use, NULL on error | ||
447 | */ | ||
448 | struct GNUNET_MESSENGER_Handle* | ||
449 | GNUNET_MESSENGER_connect (const struct GNUNET_CONFIGURATION_Handle *cfg, const char *name, | ||
450 | GNUNET_MESSENGER_IdentityCallback identity_callback, void *identity_cls, | ||
451 | GNUNET_MESSENGER_MessageCallback msg_callback, void *msg_cls); | ||
452 | |||
453 | /** | ||
454 | * Update a handle of the messenger to use a different ego key and replace the old one with a newly generated one. All | ||
455 | * participated rooms get informed about the key renewal. The handle requires a set name for this function to work and | ||
456 | * it needs to be unused by other egos. | ||
457 | * | ||
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 | ||
459 | * as default. | ||
460 | * | ||
461 | * @param handle Messenger handle to use | ||
462 | * @return GNUNET_OK on success, GNUNET_SYSERR on failure | ||
463 | */ | ||
464 | int | ||
465 | GNUNET_MESSENGER_update (struct GNUNET_MESSENGER_Handle *handle); | ||
466 | |||
467 | /** | ||
468 | * Disconnect all of the messengers used services and clears up its used memory. | ||
469 | * | ||
470 | * @param handle Messenger handle to use | ||
471 | */ | ||
472 | void | ||
473 | GNUNET_MESSENGER_disconnect (struct GNUNET_MESSENGER_Handle *handle); | ||
474 | |||
475 | /** | ||
476 | * Get the name (if specified, otherwise NULL) used by the messenger. | ||
477 | * | ||
478 | * @param handle Messenger handle to use | ||
479 | * @return Name used by the messenger or NULL | ||
480 | */ | ||
481 | const char* | ||
482 | GNUNET_MESSENGER_get_name (const struct GNUNET_MESSENGER_Handle *handle); | ||
483 | |||
484 | /** | ||
485 | * 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 | ||
487 | * the messenger won't change as specified. | ||
488 | * | ||
489 | * @param handle Messenger handle to use | ||
490 | * @param 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 | ||
492 | */ | ||
493 | int | ||
494 | GNUNET_MESSENGER_set_name (struct GNUNET_MESSENGER_Handle *handle, const char *name); | ||
495 | |||
496 | /** | ||
497 | * Get the public key used by the messenger. | ||
498 | * | ||
499 | * @param handle Messenger handle to use | ||
500 | * @return Used ego's public key | ||
501 | */ | ||
502 | const struct GNUNET_IDENTITY_PublicKey* | ||
503 | GNUNET_MESSENGER_get_key (const struct GNUNET_MESSENGER_Handle *handle); | ||
504 | |||
505 | /** | ||
506 | * Open a room to send and receive messages. The room will use the specified <i>key</i> as port for the underlying cadet | ||
507 | * service. Opening a room results in opening the port for incoming connections as possible <b>door</b>. | ||
508 | * | ||
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 | ||
510 | * <i>key</i> will result in opening the room once but returning the handle both times because the room stays open. | ||
511 | * | ||
512 | * You can also open a room after entering it through a <b>door</b> using <i>GNUNET_MESSENGER_entry_room(...)</i>. This | ||
513 | * will notify all entered <b>doors</b> to list you as new <b>door</b>. | ||
514 | * | ||
515 | * ( All <b>doors</b> form a ring structured network to shorten the latency sending and receiving messages. ) | ||
516 | * | ||
517 | * @param handle Messenger handle to use | ||
518 | * @param key Hash identifying the port | ||
519 | * @return Room handle, NULL on error | ||
520 | */ | ||
521 | struct GNUNET_MESSENGER_Room* | ||
522 | GNUNET_MESSENGER_open_room (struct GNUNET_MESSENGER_Handle *handle, const struct GNUNET_HashCode *key); | ||
523 | |||
524 | /** | ||
525 | * Enter a room to send and receive messages through a <b>door</b> opened using <i>GNUNET_MESSENGER_open_room(...)</i>. | ||
526 | * | ||
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 | ||
528 | * <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 | ||
530 | * entering the room through the same <b>door</b> won't have any effect after the first time. | ||
531 | * | ||
532 | * You can also enter a room through a <b>door</b> after opening it using <i>GNUNET_MESSENGER_open_room(...)</i>. But the | ||
533 | * <b>door</b> may not be your own peer identity. | ||
534 | * | ||
535 | * ( All <b>doors</b> form a ring structured network to shorten the latency sending and receiving messages. ) | ||
536 | * | ||
537 | * @param handle Messenger handle to use | ||
538 | * @param door Peer identity of an open <b>door</b> | ||
539 | * @param key Hash identifying the port | ||
540 | * @return Room handle, NULL on error | ||
541 | */ | ||
542 | struct GNUNET_MESSENGER_Room* | ||
543 | GNUNET_MESSENGER_entry_room (struct GNUNET_MESSENGER_Handle *handle, const struct GNUNET_PeerIdentity *door, | ||
544 | const struct GNUNET_HashCode *key); | ||
545 | |||
546 | /** | ||
547 | * Close a room which was entered, opened or both in various order and variety. Closing a room will destroy all connections | ||
548 | * from your peer to another and the other way around. | ||
549 | * | ||
550 | * ( 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. ) | ||
552 | * | ||
553 | * @param room Room handle | ||
554 | */ | ||
555 | void | ||
556 | GNUNET_MESSENGER_close_room (struct GNUNET_MESSENGER_Room *room); | ||
557 | |||
558 | /** | ||
559 | * Get the contact of a member in a <i>room</i> identified by their <i>id</i>. | ||
560 | * | ||
561 | * Notice that contacts are independent of rooms but will be removed if all rooms containing these contacts get closed. | ||
562 | * | ||
563 | * @param room Room handle | ||
564 | * @param id Hash identifying a member | ||
565 | * @return Contact handle, NULL if <i>id</i> is not in use | ||
566 | */ | ||
567 | struct GNUNET_MESSENGER_Contact* | ||
568 | GNUNET_MESSENGER_get_member (const struct GNUNET_MESSENGER_Room *room, const struct GNUNET_ShortHashCode *id); | ||
569 | |||
570 | /** | ||
571 | * Get the name used by the <i>contact</i>. | ||
572 | * | ||
573 | * @param contact Contact handle | ||
574 | * @return Name of <i>contact</i> or NULL | ||
575 | */ | ||
576 | const char* | ||
577 | GNUNET_MESSENGER_contact_get_name (const struct GNUNET_MESSENGER_Contact *contact); | ||
578 | |||
579 | /** | ||
580 | * Get the public key used by the <i>contact</i>. | ||
581 | * | ||
582 | * @param contact Contact handle | ||
583 | * @return Public key of the ego used by <i>contact</i> | ||
584 | */ | ||
585 | const struct GNUNET_IDENTITY_PublicKey* | ||
586 | GNUNET_MESSENGER_contact_get_key (const struct GNUNET_MESSENGER_Contact *contact); | ||
587 | |||
588 | /** | ||
589 | * Send a <i>message</i> into a </i>room</i>. If you opened the <i>room</i> all entered members will receive the | ||
590 | * <i>message</i>. If you entered the <i>room</i> through a <b>door</b> all so entered <b>doors</b> will receive the | ||
591 | * <i>message</i> as well. All members receiving the <i>message</i> will also propagate this <i>message</i> recursively | ||
592 | * as long as the <i>message</i> is unknown to them. | ||
593 | * | ||
594 | * Notice that all messages sent and received are also stored and can be propagated to new members entering the room. | ||
595 | * | ||
596 | * @param room Room handle | ||
597 | * @param message New message to send | ||
598 | */ | ||
599 | void | ||
600 | GNUNET_MESSENGER_send_message (struct GNUNET_MESSENGER_Room *room, const struct GNUNET_MESSENGER_Message *message); | ||
601 | |||
602 | /** | ||
603 | * Get the message in a <i>room</i> identified by its <i>hash</i>. | ||
604 | * | ||
605 | * @param room Room handle | ||
606 | * @param hash Hash identifying a message | ||
607 | * @return Message struct or NULL if no message with that hash is known | ||
608 | */ | ||
609 | const struct GNUNET_MESSENGER_Message* | ||
610 | GNUNET_MESSENGER_get_message (const struct GNUNET_MESSENGER_Room *room, const struct GNUNET_HashCode *hash); | ||
611 | |||
612 | #if 0 /* keep Emacsens' auto-indent happy */ | ||
613 | { | ||
614 | #endif | ||
615 | #ifdef __cplusplus | ||
616 | } | ||
617 | #endif | ||
618 | |||
619 | #endif //GNUNET_MESSENGER_SERVICE_H | ||
620 | |||
621 | /** @} *//* end of group */ | ||
diff --git a/src/include/gnunet_protocols.h b/src/include/gnunet_protocols.h index e9b81a654..9aa029e9d 100644 --- a/src/include/gnunet_protocols.h +++ b/src/include/gnunet_protocols.h | |||
@@ -1,6 +1,6 @@ | |||
1 | /* | 1 | /* |
2 | This file is part of GNUnet. | 2 | This file is part of GNUnet. |
3 | Copyright (C) 2001--2018 GNUnet e.V. | 3 | Copyright (C) 2001--2020 GNUnet e.V. |
4 | 4 | ||
5 | GNUnet is free software: you can redistribute it and/or modify it | 5 | GNUnet is free software: you can redistribute it and/or modify it |
6 | under the terms of the GNU Affero General Public License as published | 6 | under the terms of the GNU Affero General Public License as published |
@@ -20,6 +20,7 @@ | |||
20 | 20 | ||
21 | /** | 21 | /** |
22 | * @author Christian Grothoff | 22 | * @author Christian Grothoff |
23 | * @author Tobias Frisch | ||
23 | * | 24 | * |
24 | * @file | 25 | * @file |
25 | * Constants for network protocols | 26 | * Constants for network protocols |
@@ -3508,6 +3509,46 @@ extern "C" { | |||
3508 | #define GNUNET_MESSAGE_TYPE_RECLAIM_REFERENCE_RESULT 1501 | 3509 | #define GNUNET_MESSAGE_TYPE_RECLAIM_REFERENCE_RESULT 1501 |
3509 | 3510 | ||
3510 | 3511 | ||
3512 | /*********************************************************************************/ | ||
3513 | /********************************** MESSENGER **********************************/ | ||
3514 | /*********************************************************************************/ | ||
3515 | /* MESSENGER: message types 1600-1629 | ||
3516 | * 1600-1609 Connection-level Messages | ||
3517 | * 1610-1619 Room-level Messages | ||
3518 | */ | ||
3519 | |||
3520 | /********************************* Connection **********************************/ | ||
3521 | |||
3522 | #define GNUNET_MESSAGE_TYPE_MESSENGER_CONNECTION_CREATE 1600 | ||
3523 | |||
3524 | #define GNUNET_MESSAGE_TYPE_MESSENGER_CONNECTION_UPDATE 1601 | ||
3525 | |||
3526 | #define GNUNET_MESSAGE_TYPE_MESSENGER_CONNECTION_DESTROY 1602 | ||
3527 | |||
3528 | #define GNUNET_MESSAGE_TYPE_MESSENGER_CONNECTION_GET_NAME 1603 | ||
3529 | |||
3530 | #define GNUNET_MESSAGE_TYPE_MESSENGER_CONNECTION_SET_NAME 1604 | ||
3531 | |||
3532 | #define GNUNET_MESSAGE_TYPE_MESSENGER_CONNECTION_GET_KEY 1605 | ||
3533 | |||
3534 | #define GNUNET_MESSAGE_TYPE_MESSENGER_CONNECTION_MEMBER_ID 1606 | ||
3535 | |||
3536 | /************************************ Room *************************************/ | ||
3537 | |||
3538 | #define GNUNET_MESSAGE_TYPE_MESSENGER_ROOM_OPEN 1610 | ||
3539 | |||
3540 | #define GNUNET_MESSAGE_TYPE_MESSENGER_ROOM_ENTRY 1611 | ||
3541 | |||
3542 | #define GNUNET_MESSAGE_TYPE_MESSENGER_ROOM_CLOSE 1612 | ||
3543 | |||
3544 | #define GNUNET_MESSAGE_TYPE_MESSENGER_ROOM_SEND_MESSAGE 1614 | ||
3545 | |||
3546 | #define GNUNET_MESSAGE_TYPE_MESSENGER_ROOM_RECV_MESSAGE 1615 | ||
3547 | |||
3548 | #define GNUNET_MESSAGE_TYPE_MESSENGER_ROOM_GET_MESSAGE 1616 | ||
3549 | |||
3550 | /*********************************************************************************/ | ||
3551 | |||
3511 | /** | 3552 | /** |
3512 | * Type used to match 'all' message types. | 3553 | * Type used to match 'all' message types. |
3513 | */ | 3554 | */ |