diff options
Diffstat (limited to 'src/include/gnunet_social_service.h')
-rw-r--r-- | src/include/gnunet_social_service.h | 1344 |
1 files changed, 1344 insertions, 0 deletions
diff --git a/src/include/gnunet_social_service.h b/src/include/gnunet_social_service.h new file mode 100644 index 0000000..7faa336 --- /dev/null +++ b/src/include/gnunet_social_service.h | |||
@@ -0,0 +1,1344 @@ | |||
1 | /* | ||
2 | This file is part of GNUnet. | ||
3 | Copyright (C) 2013 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 | /** | ||
22 | * @author Gabor X Toth | ||
23 | * @author Christian Grothoff | ||
24 | * | ||
25 | * @file | ||
26 | * Social service; implements social interactions through the PSYC service. | ||
27 | */ | ||
28 | |||
29 | /** @defgroup social Social service | ||
30 | Social interactions through the PSYC service. | ||
31 | |||
32 | # Overview | ||
33 | |||
34 | The social service provides an API for social interactions based on a one-to-many messaging model. | ||
35 | It manages subscriptions of applications to places, provides messaging functionality in places, | ||
36 | allows access to the local message history and manages the GNS zone of _egos_ (user identities). | ||
37 | |||
38 | The service stores private and public keys of subscribed places, as well as files received in subscribed places. | ||
39 | |||
40 | # Concepts and terminology | ||
41 | |||
42 | ## Ego, Nym | ||
43 | |||
44 | An _ego_ is an identity of a user, a private-public key pair. | ||
45 | A _nym_ is an identity of another user in the network, identified by its public key. | ||
46 | Each user can have multiple identities. | ||
47 | |||
48 | struct GNUNET_SOCIAL_Ego and struct GNUNET_SOCIAL_Nym represents one of these identities. | ||
49 | |||
50 | ## Place, Host, Guest | ||
51 | |||
52 | A _place_ is where social interactions happen. It is owned and created by an _ego_. | ||
53 | Creating a new place happens by an _ego_ entering a new place as a _host_, | ||
54 | where _guests_ can enter later to receive messages sent to the place. | ||
55 | |||
56 | A place is identified by its public key. | ||
57 | |||
58 | - struct GNUNET_SOCIAL_Host represents a place entered as host, | ||
59 | - struct GNUNET_SOCIAL_Guest is used for a place entered as guest. | ||
60 | - A struct GNUNET_SOCIAL_Place can be obtained for both a host and guest place | ||
61 | using GNUNET_SOCIAL_host_get_place() and GNUNET_SOCIAL_guest_get_place() | ||
62 | and can be used with API functions common to hosts and guests. | ||
63 | |||
64 | ## History | ||
65 | |||
66 | Messages sent to places are stored locally by the PSYCstore service, and can be queried any time. | ||
67 | GNUNET_SOCIAL_history_replay_latest() retrieves the latest N messages sent to the place, | ||
68 | while GNUNET_SOCIAL_history_replay() is used to query a given message ID range. | ||
69 | |||
70 | ## GNU Name System | ||
71 | |||
72 | The GNU Name System is used for assigning human-readable names to nyms and places. | ||
73 | There's a _GNS zone_ corresponding to each _nym_. | ||
74 | An _ego_ can publish PKEY and PLACE records in its own zone, pointing to nyms and places, respectively. | ||
75 | |||
76 | ## Announcement, talk request | ||
77 | |||
78 | The host can _announce_ messages to the place, using GNUNET_SOCIAL_host_announce(). | ||
79 | Guests can send _talk_ requests to the host, using GNUNET_SOCIAL_guest_talk(). | ||
80 | The host receives talk requests of guests and can _relay_ them to the place, | ||
81 | or process it using a message handler function. | ||
82 | |||
83 | # Using the API | ||
84 | |||
85 | ## Connecting to the service | ||
86 | |||
87 | A client first establishes an _application connection_ to the service using | ||
88 | GNUNET_SOCIAL_app_connect() providing its _application ID_, then receives the | ||
89 | public keys of subscribed places and available egos in response. | ||
90 | |||
91 | ## Reconnecting to places | ||
92 | |||
93 | Then the application can reconnect to its subscribed places by establishing | ||
94 | _place connections_ with GNUNET_SOCIAL_host_enter_reconnect() and | ||
95 | GNUNET_SOCIAL_guest_enter_reconnect(). | ||
96 | |||
97 | ## Subscribing to a place | ||
98 | |||
99 | Entering and subscribing a new host or guest place is done using | ||
100 | GNUNET_SOCIAL_host_enter() and GNUNET_SOCIAL_guest_enter(). | ||
101 | |||
102 | ## Disconnecting from a place | ||
103 | |||
104 | An application can disconnect from a place while the social service keeps its | ||
105 | network connection active, using GNUNET_SOCIAL_host_disconnect() and | ||
106 | GNUNET_SOCIAL_guest_disconnect(). | ||
107 | |||
108 | ## Leaving a place | ||
109 | |||
110 | To permanently leave a place, see GNUNET_SOCIAL_host_leave() and GNUNET_SOCIAL_guest_leave(). | ||
111 | When leaving a place its network connections are closed and all applications are unsubscribed from the place. | ||
112 | |||
113 | # Message methods | ||
114 | |||
115 | ## _converse | ||
116 | |||
117 | Human conversation in a private or public place. | ||
118 | |||
119 | ### Environment | ||
120 | |||
121 | #### _id_reply | ||
122 | Message ID this message is in reply to. | ||
123 | |||
124 | #### _id_thread | ||
125 | Thread ID, the first message ID in the thread. | ||
126 | |||
127 | #### _nym_author | ||
128 | Nym of the author. | ||
129 | |||
130 | FIXME: Are nyms a different data type from egos and person entities? | ||
131 | Do they have a different format than any other entity address? | ||
132 | Questions and thoughts on how to fix this in "questions.org" | ||
133 | |||
134 | #### _sig_author | ||
135 | Signature of the message body and its variables by the author. | ||
136 | |||
137 | ### Data | ||
138 | |||
139 | Message body. | ||
140 | |||
141 | ## _notice_place | ||
142 | |||
143 | Notification about a place. | ||
144 | |||
145 | TODO: Applications can decide to auto-subscribe to certain places, | ||
146 | e.g. files under a given size. | ||
147 | |||
148 | ### Environment | ||
149 | |||
150 | #### Using GNS | ||
151 | |||
152 | ##### _gns_place | ||
153 | GNS name of the place in a globally unique .zkey zone | ||
154 | |||
155 | FIXME: A custom _gns PSYC data type should be avoidable by parsing | ||
156 | and interpreting PSYC uniforms appropriately. | ||
157 | Thoughts on this in "questions.org" | ||
158 | |||
159 | #### Without GNS | ||
160 | |||
161 | ##### _key_pub_place | ||
162 | Public key of place | ||
163 | |||
164 | FIXME: _key_pub can't be the data type for GNUnet-specific cryptographic | ||
165 | addressing. Questions and thoughts on how to fix this in "questions.org" | ||
166 | |||
167 | ##### _peer_origin | ||
168 | Peer ID of origin | ||
169 | |||
170 | ##### _list_peer_relays | ||
171 | List of peer IDs of relays | ||
172 | |||
173 | ## _notice_place_file | ||
174 | |||
175 | Notification about a place hosting a file. | ||
176 | |||
177 | ### Environment | ||
178 | |||
179 | The environment of _notice_place above, plus the following: | ||
180 | |||
181 | #### _size_file | ||
182 | Size of file | ||
183 | |||
184 | #### _type_file | ||
185 | MIME type of file | ||
186 | |||
187 | #### _name_file | ||
188 | Name of file | ||
189 | |||
190 | #### _description_file | ||
191 | Description of file | ||
192 | |||
193 | ## _file | ||
194 | |||
195 | Messages with a _file method contain a file, | ||
196 | which is saved to disk upon reception at the following location: | ||
197 | $GNUNET_DATA_HOME/social/files/<H(place_pub)>/<H(message_id)> | ||
198 | |||
199 | ### Environment | ||
200 | |||
201 | #### _size_file | ||
202 | Size of file | ||
203 | |||
204 | #### _type_file | ||
205 | MIME type of file | ||
206 | |||
207 | #### _name_file | ||
208 | Name of file | ||
209 | |||
210 | #### _description_file | ||
211 | Description of file | ||
212 | |||
213 | @{ | ||
214 | */ | ||
215 | |||
216 | |||
217 | #ifndef GNUNET_SOCIAL_SERVICE_H | ||
218 | #define GNUNET_SOCIAL_SERVICE_H | ||
219 | |||
220 | #ifdef __cplusplus | ||
221 | extern "C" | ||
222 | { | ||
223 | #if 0 /* keep Emacsens' auto-indent happy */ | ||
224 | } | ||
225 | #endif | ||
226 | #endif | ||
227 | |||
228 | #include <stdint.h> | ||
229 | #include "gnunet_util_lib.h" | ||
230 | #include "gnunet_psyc_util_lib.h" | ||
231 | #include "gnunet_identity_service.h" | ||
232 | #include "gnunet_namestore_service.h" | ||
233 | #include "gnunet_psyc_service.h" | ||
234 | |||
235 | |||
236 | /** | ||
237 | * Version number of GNUnet Social API. | ||
238 | */ | ||
239 | #define GNUNET_SOCIAL_VERSION 0x00000000 | ||
240 | |||
241 | /** | ||
242 | * Maximum size of client ID including '\0' terminator. | ||
243 | */ | ||
244 | #define GNUNET_SOCIAL_APP_MAX_ID_SIZE 256 | ||
245 | |||
246 | enum GNUNET_SOCIAL_MsgProcFlags { | ||
247 | GNUNET_SOCIAL_MSG_PROC_NONE = 0, | ||
248 | GNUNET_SOCIAL_MSG_PROC_RELAY = 1, | ||
249 | GNUNET_SOCIAL_MSG_PROC_SAVE= 2, | ||
250 | }; | ||
251 | |||
252 | /** | ||
253 | * Handle for an application. | ||
254 | */ | ||
255 | struct GNUNET_SOCIAL_App; | ||
256 | |||
257 | /** | ||
258 | * Handle for an ego (own identity) | ||
259 | */ | ||
260 | struct GNUNET_SOCIAL_Ego; | ||
261 | |||
262 | /** | ||
263 | * Handle for a pseudonym of another user in the network. | ||
264 | */ | ||
265 | struct GNUNET_SOCIAL_Nym; | ||
266 | |||
267 | /** | ||
268 | * Handle for a place where social interactions happen. | ||
269 | */ | ||
270 | struct GNUNET_SOCIAL_Place; | ||
271 | |||
272 | /** | ||
273 | * Host handle for a place that we entered. | ||
274 | */ | ||
275 | struct GNUNET_SOCIAL_Host; | ||
276 | |||
277 | /** | ||
278 | * Guest handle for place that we entered. | ||
279 | */ | ||
280 | struct GNUNET_SOCIAL_Guest; | ||
281 | |||
282 | /** | ||
283 | * Handle that can be used to reconnect to a place as host. | ||
284 | */ | ||
285 | struct GNUNET_SOCIAL_HostConnection; | ||
286 | |||
287 | /** | ||
288 | * Handle that can be used to reconnect to a place as guest. | ||
289 | */ | ||
290 | struct GNUNET_SOCIAL_GuestConnection; | ||
291 | |||
292 | /** | ||
293 | * Notification about an available identity. | ||
294 | * | ||
295 | * @param cls | ||
296 | * Closure. | ||
297 | * @param pub_key | ||
298 | * Public key of ego. | ||
299 | * @param name | ||
300 | * Name of ego. | ||
301 | */ | ||
302 | typedef void | ||
303 | (*GNUNET_SOCIAL_AppEgoCallback) (void *cls, | ||
304 | struct GNUNET_SOCIAL_Ego *ego, | ||
305 | const struct GNUNET_CRYPTO_EcdsaPublicKey *ego_pub_key, | ||
306 | const char *name); | ||
307 | |||
308 | |||
309 | /** | ||
310 | * Entry status of a place per application. | ||
311 | */ | ||
312 | enum GNUNET_SOCIAL_AppPlaceState | ||
313 | { | ||
314 | /** | ||
315 | * The place was once entered by the ego, but left since. | ||
316 | * It's possible to establish a local connection to the place | ||
317 | * without re-entering to fetch history from the PSYCstore. | ||
318 | * @see enum GNUNET_PSYC_SlaveJoinFlags and GNUNET_SOCIAL_guest_enter() | ||
319 | */ | ||
320 | GNUNET_SOCIAL_PLACE_STATE_ARCHIVED = 0, | ||
321 | |||
322 | /** | ||
323 | * The place is entered by the ego, | ||
324 | * but this application is not subscribed to it. | ||
325 | */ | ||
326 | GNUNET_SOCIAL_PLACE_STATE_ENTERED = 1, | ||
327 | |||
328 | /** | ||
329 | * The place is entered by the ego and | ||
330 | * and this application is subscribed to it. | ||
331 | */ | ||
332 | GNUNET_SOCIAL_PLACE_STATE_SUBSCRIBED = 2, | ||
333 | }; | ||
334 | |||
335 | |||
336 | /** | ||
337 | * Called after receiving initial list of egos and places. | ||
338 | */ | ||
339 | typedef void | ||
340 | (*GNUNET_SOCIAL_AppConnectedCallback) (void *cls); | ||
341 | |||
342 | |||
343 | /** | ||
344 | * Notification about a home. | ||
345 | * | ||
346 | * @param cls | ||
347 | * Closure. | ||
348 | * @param hconn | ||
349 | * Host connection, to be used with GNUNET_SOCIAL_host_enter_reconnect() | ||
350 | * @param ego | ||
351 | * Ego used to enter the place. | ||
352 | * @param place_pub_key | ||
353 | * Public key of the place. | ||
354 | * @param place_state | ||
355 | * @see enum GNUNET_SOCIAL_AppPlaceState | ||
356 | */ | ||
357 | typedef void | ||
358 | (*GNUNET_SOCIAL_AppHostPlaceCallback) (void *cls, | ||
359 | struct GNUNET_SOCIAL_HostConnection *hconn, | ||
360 | struct GNUNET_SOCIAL_Ego *ego, | ||
361 | const struct GNUNET_CRYPTO_EddsaPublicKey *place_pub_key, | ||
362 | enum GNUNET_SOCIAL_AppPlaceState place_state); | ||
363 | |||
364 | /** | ||
365 | * Notification about a place. | ||
366 | * | ||
367 | * @param cls | ||
368 | * Closure. | ||
369 | * @param gconn | ||
370 | * Guest connection, to be used with GNUNET_SOCIAL_guest_enter_reconnect() | ||
371 | * @param ego | ||
372 | * Ego used to enter the place. | ||
373 | * @param place_pub_key | ||
374 | * Public key of the place. | ||
375 | * @param place_state | ||
376 | * @see enum GNUNET_SOCIAL_AppPlaceState | ||
377 | */ | ||
378 | typedef void | ||
379 | (*GNUNET_SOCIAL_AppGuestPlaceCallback) (void *cls, | ||
380 | struct GNUNET_SOCIAL_GuestConnection *gconn, | ||
381 | struct GNUNET_SOCIAL_Ego *ego, | ||
382 | const struct GNUNET_CRYPTO_EddsaPublicKey *place_pub_key, | ||
383 | enum GNUNET_SOCIAL_AppPlaceState place_state); | ||
384 | |||
385 | |||
386 | /** | ||
387 | * Establish application connection to the social service. | ||
388 | * | ||
389 | * The @host_cb and @guest_cb functions are | ||
390 | * initially called for each entered places, | ||
391 | * then later each time a new place is entered with the current app ID. | ||
392 | * | ||
393 | * @param cfg | ||
394 | * Configuration. | ||
395 | * @param ego_cb | ||
396 | * Function to notify about an available ego. | ||
397 | * @param host_cb | ||
398 | * Function to notify about a place entered as host. | ||
399 | * @param guest_cb | ||
400 | * Function to notify about a place entered as guest. | ||
401 | * @param cls | ||
402 | * Closure for the callbacks. | ||
403 | * | ||
404 | * @return Handle that can be used to stop listening. | ||
405 | */ | ||
406 | struct GNUNET_SOCIAL_App * | ||
407 | GNUNET_SOCIAL_app_connect (const struct GNUNET_CONFIGURATION_Handle *cfg, | ||
408 | const char *id, | ||
409 | GNUNET_SOCIAL_AppEgoCallback ego_cb, | ||
410 | GNUNET_SOCIAL_AppHostPlaceCallback host_cb, | ||
411 | GNUNET_SOCIAL_AppGuestPlaceCallback guest_cb, | ||
412 | GNUNET_SOCIAL_AppConnectedCallback connected_cb, | ||
413 | void *cls); | ||
414 | |||
415 | |||
416 | /** | ||
417 | * Disconnect app. | ||
418 | * | ||
419 | * @param app | ||
420 | * Application handle. | ||
421 | * @param disconnect_cb | ||
422 | * Disconnect callback. | ||
423 | * @param disconnect_cls | ||
424 | * Disconnect closure. | ||
425 | */ | ||
426 | void | ||
427 | GNUNET_SOCIAL_app_disconnect (struct GNUNET_SOCIAL_App *app, | ||
428 | GNUNET_ContinuationCallback disconnect_cb, | ||
429 | void *disconnect_cls); | ||
430 | |||
431 | |||
432 | /** | ||
433 | * Get the public key of @a ego. | ||
434 | * | ||
435 | * @param ego | ||
436 | * Ego. | ||
437 | * | ||
438 | * @return Public key of ego. | ||
439 | */ | ||
440 | const struct GNUNET_CRYPTO_EcdsaPublicKey * | ||
441 | GNUNET_SOCIAL_ego_get_pub_key (const struct GNUNET_SOCIAL_Ego *ego); | ||
442 | |||
443 | |||
444 | /** | ||
445 | * Get the name of @a ego. | ||
446 | * | ||
447 | * @param ego | ||
448 | * Ego. | ||
449 | * | ||
450 | * @return Public key of @a ego. | ||
451 | */ | ||
452 | const char * | ||
453 | GNUNET_SOCIAL_ego_get_name (const struct GNUNET_SOCIAL_Ego *ego); | ||
454 | |||
455 | |||
456 | /** | ||
457 | * Get the public key of a @a nym. | ||
458 | * | ||
459 | * Suitable, for example, to be used with GNUNET_SOCIAL_zone_add_nym(). | ||
460 | * | ||
461 | * @param nym | ||
462 | * Pseudonym to map to a cryptographic identifier. | ||
463 | * | ||
464 | * @return Public key of nym. | ||
465 | */ | ||
466 | const struct GNUNET_CRYPTO_EcdsaPublicKey * | ||
467 | GNUNET_SOCIAL_nym_get_pub_key (const struct GNUNET_SOCIAL_Nym *nym); | ||
468 | |||
469 | |||
470 | /** | ||
471 | * Get the hash of the public key of a @a nym. | ||
472 | * | ||
473 | * @param nym | ||
474 | * Pseudonym to map to a cryptographic identifier. | ||
475 | * | ||
476 | * @return Hash of the public key of nym. | ||
477 | */ | ||
478 | const struct GNUNET_HashCode * | ||
479 | GNUNET_SOCIAL_nym_get_pub_key_hash (const struct GNUNET_SOCIAL_Nym *nym); | ||
480 | |||
481 | |||
482 | /** | ||
483 | * Function called asking for nym to be admitted to the place. | ||
484 | * | ||
485 | * Should call either GNUNET_SOCIAL_host_admit() or | ||
486 | * GNUNET_SOCIAL_host_reject_entry() (possibly asynchronously). If this host | ||
487 | * cannot decide, it is fine to call neither function, in which case hopefully | ||
488 | * some other host of the place exists that will make the decision. The @a nym | ||
489 | * reference remains valid until the #GNUNET_SOCIAL_FarewellCallback is invoked | ||
490 | * for it. | ||
491 | * | ||
492 | * @param cls | ||
493 | * Closure. | ||
494 | * @param nym | ||
495 | * Handle for the user who wants to enter. | ||
496 | * @param method_name | ||
497 | * Method name in the entry request. | ||
498 | * @param variable_count | ||
499 | * Number of elements in the @a variables array. | ||
500 | * @param variables | ||
501 | * Variables present in the message. | ||
502 | * @param data | ||
503 | * Payload given on enter (e.g. a password). | ||
504 | * @param data_size | ||
505 | * Number of bytes in @a data. | ||
506 | */ | ||
507 | typedef void | ||
508 | (*GNUNET_SOCIAL_AnswerDoorCallback) (void *cls, | ||
509 | struct GNUNET_SOCIAL_Nym *nym, | ||
510 | const char *method_name, | ||
511 | struct GNUNET_PSYC_Environment *env, | ||
512 | const void *data, | ||
513 | size_t data_size); | ||
514 | |||
515 | |||
516 | /** | ||
517 | * Function called when a @a nym leaves the place. | ||
518 | * | ||
519 | * This is also called if the @a nym was never given permission to enter | ||
520 | * (i.e. the @a nym stopped asking to get in). | ||
521 | * | ||
522 | * @param cls | ||
523 | * Closure. | ||
524 | * @param nym | ||
525 | * Handle for the user who left. | ||
526 | */ | ||
527 | typedef void | ||
528 | (*GNUNET_SOCIAL_FarewellCallback) (void *cls, | ||
529 | const struct GNUNET_SOCIAL_Nym *nym, | ||
530 | struct GNUNET_PSYC_Environment *env); | ||
531 | |||
532 | |||
533 | /** | ||
534 | * Function called after the host entered a home. | ||
535 | * | ||
536 | * @param cls | ||
537 | * Closure. | ||
538 | * @param result | ||
539 | * #GNUNET_OK on success, or | ||
540 | * #GNUNET_SYSERR on error. | ||
541 | * @param place_pub_key | ||
542 | * Public key of home. | ||
543 | * @param max_message_id | ||
544 | * Last message ID sent to the channel. | ||
545 | * Or 0 if no messages have been sent to the place yet. | ||
546 | */ | ||
547 | typedef void | ||
548 | (*GNUNET_SOCIAL_HostEnterCallback) (void *cls, int result, | ||
549 | const struct GNUNET_CRYPTO_EddsaPublicKey *place_pub_key, | ||
550 | uint64_t max_message_id); | ||
551 | |||
552 | |||
553 | /** | ||
554 | * Enter a place as host. | ||
555 | * | ||
556 | * A place is created upon first entering, and it is active until permanently | ||
557 | * left using GNUNET_SOCIAL_host_leave(). | ||
558 | * | ||
559 | * @param cfg | ||
560 | * Configuration to contact the social service. | ||
561 | * @param ego | ||
562 | * Identity of the host. | ||
563 | * @param place_key | ||
564 | * Private-public key pair of the place. | ||
565 | * NULL for ephemeral places. | ||
566 | * @param policy | ||
567 | * Policy specifying entry and history restrictions for the place. | ||
568 | * @param slicer | ||
569 | * Slicer to handle incoming messages. | ||
570 | * @param enter_cb | ||
571 | * Function called when the place is entered and ready to use. | ||
572 | * @param answer_door_cb | ||
573 | * Function to handle new nyms that want to enter. | ||
574 | * @param farewell_cb | ||
575 | * Function to handle departing nyms. | ||
576 | * @param cls | ||
577 | * Closure for the callbacks. | ||
578 | * | ||
579 | * @return Handle for the host. | ||
580 | */ | ||
581 | struct GNUNET_SOCIAL_Host * | ||
582 | GNUNET_SOCIAL_host_enter (const struct GNUNET_SOCIAL_App *app, | ||
583 | const struct GNUNET_SOCIAL_Ego *ego, | ||
584 | enum GNUNET_PSYC_Policy policy, | ||
585 | struct GNUNET_PSYC_Slicer *slicer, | ||
586 | GNUNET_SOCIAL_HostEnterCallback enter_cb, | ||
587 | GNUNET_SOCIAL_AnswerDoorCallback answer_door_cb, | ||
588 | GNUNET_SOCIAL_FarewellCallback farewell_cb, | ||
589 | void *cls); | ||
590 | |||
591 | |||
592 | /** | ||
593 | * Reconnect to an already entered place as host. | ||
594 | * | ||
595 | * @param hconn | ||
596 | * Host connection handle. | ||
597 | * @see GNUNET_SOCIAL_app_connect() & GNUNET_SOCIAL_AppHostPlaceCallback() | ||
598 | * @param slicer | ||
599 | * Slicer to handle incoming messages. | ||
600 | * @param enter_cb | ||
601 | * Function called when the place is entered and ready to use. | ||
602 | * @param answer_door_cb | ||
603 | * Function to handle new nyms that want to enter. | ||
604 | * @param farewell_cb | ||
605 | * Function to handle departing nyms. | ||
606 | * @param cls | ||
607 | * Closure for the callbacks. | ||
608 | * | ||
609 | * @return Handle for the host. | ||
610 | */ | ||
611 | struct GNUNET_SOCIAL_Host * | ||
612 | GNUNET_SOCIAL_host_enter_reconnect (struct GNUNET_SOCIAL_HostConnection *hconn, | ||
613 | struct GNUNET_PSYC_Slicer *slicer, | ||
614 | GNUNET_SOCIAL_HostEnterCallback enter_cb, | ||
615 | GNUNET_SOCIAL_AnswerDoorCallback answer_door_cb, | ||
616 | GNUNET_SOCIAL_FarewellCallback farewell_cb, | ||
617 | void *cls); | ||
618 | |||
619 | |||
620 | /** | ||
621 | * Decision whether to admit @a nym into the place or refuse entry. | ||
622 | * | ||
623 | * @param hst | ||
624 | * Host of the place. | ||
625 | * @param nym | ||
626 | * Handle for the entity that wanted to enter. | ||
627 | * @param is_admitted | ||
628 | * #GNUNET_YES if @a nym is admitted, | ||
629 | * #GNUNET_NO if @a nym is refused entry, | ||
630 | * #GNUNET_SYSERR if we cannot answer the request. | ||
631 | * @param entry_resp | ||
632 | * Entry response message, or NULL. | ||
633 | * @return #GNUNET_OK on success, | ||
634 | * #GNUNET_SYSERR if the message is too large. | ||
635 | */ | ||
636 | int | ||
637 | GNUNET_SOCIAL_host_entry_decision (struct GNUNET_SOCIAL_Host *hst, | ||
638 | struct GNUNET_SOCIAL_Nym *nym, | ||
639 | int is_admitted, | ||
640 | const struct GNUNET_PSYC_Message *entry_resp); | ||
641 | |||
642 | |||
643 | /** | ||
644 | * Throw @a nym out of the place. | ||
645 | * | ||
646 | * Sends a _notice_place_leave announcement to the home. | ||
647 | * | ||
648 | * The @a nym reference will remain valid until the | ||
649 | * #GNUNET_SOCIAL_FarewellCallback is invoked, | ||
650 | * which should be very soon after this call. | ||
651 | * | ||
652 | * @param host | ||
653 | * Host of the place. | ||
654 | * @param nym | ||
655 | * Handle for the entity to be ejected. | ||
656 | * @param env | ||
657 | * Environment for the message or NULL. | ||
658 | * _nym is set to @e nym regardless whether an @e env is provided. | ||
659 | */ | ||
660 | void | ||
661 | GNUNET_SOCIAL_host_eject (struct GNUNET_SOCIAL_Host *host, | ||
662 | const struct GNUNET_SOCIAL_Nym *nym, | ||
663 | struct GNUNET_PSYC_Environment *env); | ||
664 | |||
665 | |||
666 | /** | ||
667 | * Flags for announcements by a host. | ||
668 | */ | ||
669 | enum GNUNET_SOCIAL_AnnounceFlags | ||
670 | { | ||
671 | GNUNET_SOCIAL_ANNOUNCE_NONE = 0, | ||
672 | |||
673 | /** | ||
674 | * Whether this announcement removes all objects from the place. | ||
675 | * | ||
676 | * New objects can be still added to the now empty place using the @e env | ||
677 | * parameter of the same announcement. | ||
678 | */ | ||
679 | GNUNET_SOCIAL_ANNOUNCE_CLEAR_OBJECTS = 1 << 0 | ||
680 | }; | ||
681 | |||
682 | |||
683 | /** | ||
684 | * Handle for an announcement request. | ||
685 | */ | ||
686 | struct GNUNET_SOCIAL_Announcement; | ||
687 | |||
688 | |||
689 | /** | ||
690 | * Send a message to all nyms that are present in the place. | ||
691 | * | ||
692 | * This function is restricted to the host. Nyms can only send requests | ||
693 | * to the host who can decide to relay it to everyone in the place. | ||
694 | * | ||
695 | * @param host | ||
696 | * Host of the place. | ||
697 | * @param method_name | ||
698 | * Method to use for the announcement. | ||
699 | * @param env | ||
700 | * Environment containing variables for the message and operations | ||
701 | * on objects of the place. | ||
702 | * Has to remain available until the first call to @a notify_data. | ||
703 | * Can be NULL. | ||
704 | * @param notify_data | ||
705 | * Function to call to get the payload of the announcement. | ||
706 | * @param notify_data_cls | ||
707 | * Closure for @a notify. | ||
708 | * @param flags | ||
709 | * Flags for this announcement. | ||
710 | * | ||
711 | * @return NULL on error (another announcement already in progress?). | ||
712 | */ | ||
713 | struct GNUNET_SOCIAL_Announcement * | ||
714 | GNUNET_SOCIAL_host_announce (struct GNUNET_SOCIAL_Host *host, | ||
715 | const char *method_name, | ||
716 | const struct GNUNET_PSYC_Environment *env, | ||
717 | GNUNET_PSYC_TransmitNotifyData notify_data, | ||
718 | void *notify_data_cls, | ||
719 | enum GNUNET_SOCIAL_AnnounceFlags flags); | ||
720 | |||
721 | |||
722 | /** | ||
723 | * Resume transmitting announcement. | ||
724 | * | ||
725 | * @param a | ||
726 | * The announcement to resume. | ||
727 | */ | ||
728 | void | ||
729 | GNUNET_SOCIAL_host_announce_resume (struct GNUNET_SOCIAL_Announcement *a); | ||
730 | |||
731 | |||
732 | /** | ||
733 | * Cancel announcement. | ||
734 | * | ||
735 | * @param a | ||
736 | * The announcement to cancel. | ||
737 | */ | ||
738 | void | ||
739 | GNUNET_SOCIAL_host_announce_cancel (struct GNUNET_SOCIAL_Announcement *a); | ||
740 | |||
741 | |||
742 | /** | ||
743 | * Allow relaying messages from guests matching a given @a method_prefix. | ||
744 | * | ||
745 | * @param host | ||
746 | * The host. | ||
747 | * @param method_prefix | ||
748 | * Method prefix to allow. | ||
749 | */ | ||
750 | void | ||
751 | GNUNET_SOCIAL_host_relay_allow_method (struct GNUNET_SOCIAL_Host *host, | ||
752 | const char *method_prefix); | ||
753 | |||
754 | |||
755 | /** | ||
756 | * Allow relaying changes to objects of the place. | ||
757 | * | ||
758 | * Only applies to messages with an allowed method name. | ||
759 | * @see GNUNET_SCOIAL_host_relay_allow_method() | ||
760 | * | ||
761 | * @param host | ||
762 | * The host. | ||
763 | * @param object_prefix | ||
764 | * Object prefix to allow modifying. | ||
765 | */ | ||
766 | void | ||
767 | GNUNET_SOCIAL_host_relay_allow_method (struct GNUNET_SOCIAL_Host *host, | ||
768 | const char *object_prefix); | ||
769 | |||
770 | |||
771 | /** | ||
772 | * Stop relaying messages from guests. | ||
773 | * | ||
774 | * Remove all allowed relay rules. | ||
775 | * | ||
776 | * | ||
777 | * | ||
778 | */ | ||
779 | void | ||
780 | GNUNET_SOCIAL_host_relay_stop (struct GNUNET_SOCIAL_Host *host); | ||
781 | |||
782 | |||
783 | /** | ||
784 | * Obtain handle for a hosted place. | ||
785 | * | ||
786 | * The returned handle can be used to access the place API. | ||
787 | * | ||
788 | * @param host | ||
789 | * Handle for the host. | ||
790 | * | ||
791 | * @return Handle for the hosted place, valid as long as @a host is valid. | ||
792 | */ | ||
793 | struct GNUNET_SOCIAL_Place * | ||
794 | GNUNET_SOCIAL_host_get_place (struct GNUNET_SOCIAL_Host *host); | ||
795 | |||
796 | |||
797 | /** | ||
798 | * Disconnect from a home. | ||
799 | * | ||
800 | * Invalidates host handle. | ||
801 | * | ||
802 | * @param hst | ||
803 | * The host to disconnect. | ||
804 | * @param disconnect_cb | ||
805 | * Function called after disconnected from the service. | ||
806 | * @param cls | ||
807 | * Closure for @a disconnect_cb. | ||
808 | */ | ||
809 | void | ||
810 | GNUNET_SOCIAL_host_disconnect (struct GNUNET_SOCIAL_Host *hst, | ||
811 | GNUNET_ContinuationCallback disconnect_cb, | ||
812 | void *cls); | ||
813 | |||
814 | |||
815 | /** | ||
816 | * Stop hosting a home. | ||
817 | * | ||
818 | * Sends a _notice_place_closing announcement to the home. | ||
819 | * Invalidates host handle. | ||
820 | * | ||
821 | * @param hst | ||
822 | * Host leaving. | ||
823 | * @param env | ||
824 | * Environment for the message or NULL. | ||
825 | * @param disconnect_cb | ||
826 | * Function called after the host left the place | ||
827 | * and disconnected from the service. | ||
828 | * @param cls | ||
829 | * Closure for @a disconnect_cb. | ||
830 | */ | ||
831 | void | ||
832 | GNUNET_SOCIAL_host_leave (struct GNUNET_SOCIAL_Host *hst, | ||
833 | const struct GNUNET_PSYC_Environment *env, | ||
834 | GNUNET_ContinuationCallback disconnect_cb, | ||
835 | void *cls); | ||
836 | |||
837 | |||
838 | /** | ||
839 | * Function called after the guest entered the local copy of the place. | ||
840 | * | ||
841 | * History and object query functions can be used after this call, | ||
842 | * but new messages can't be sent or received. | ||
843 | * | ||
844 | * @param cls | ||
845 | * Closure. | ||
846 | * @param result | ||
847 | * #GNUNET_OK on success, or | ||
848 | * #GNUNET_SYSERR on error, e.g. could not connect to the service, or | ||
849 | * could not resolve GNS name. | ||
850 | * @param place_pub_key | ||
851 | * Public key of place. | ||
852 | * @param max_message_id | ||
853 | * Last message ID sent to the place. | ||
854 | * Or 0 if no messages have been sent to the place yet. | ||
855 | */ | ||
856 | typedef void | ||
857 | (*GNUNET_SOCIAL_GuestEnterCallback) (void *cls, int result, | ||
858 | const struct GNUNET_CRYPTO_EddsaPublicKey *place_pub_key, | ||
859 | uint64_t max_message_id); | ||
860 | |||
861 | |||
862 | /** | ||
863 | * Function called upon a guest receives a decision about entry to the place. | ||
864 | * | ||
865 | * @param is_admitted | ||
866 | * Is the guest admitted to the place? | ||
867 | * #GNUNET_YES if admitted, | ||
868 | * #GNUNET_NO if refused entry, | ||
869 | * #GNUNET_SYSERR if the request could not be answered. | ||
870 | * @param data | ||
871 | * Entry response message. | ||
872 | */ | ||
873 | typedef void | ||
874 | (*GNUNET_SOCIAL_EntryDecisionCallback) (void *cls, | ||
875 | int is_admitted, | ||
876 | const struct GNUNET_PSYC_Message *entry_resp); | ||
877 | |||
878 | |||
879 | /** | ||
880 | * Request entry to a place as a guest. | ||
881 | * | ||
882 | * @param app | ||
883 | * Application handle. | ||
884 | * @param ego | ||
885 | * Identity of the guest. | ||
886 | * @param place_pub_key | ||
887 | * Public key of the place to enter. | ||
888 | * @param flags | ||
889 | * Flags for the entry. | ||
890 | * @param origin | ||
891 | * Peer identity of the origin of the underlying multicast group. | ||
892 | * @param relay_count | ||
893 | * Number of elements in the @a relays array. | ||
894 | * @param relays | ||
895 | * Relays for the underlying multicast group. | ||
896 | * @param entry_msg | ||
897 | * Entry message. | ||
898 | * @param slicer | ||
899 | * Slicer to use for processing incoming requests from guests. | ||
900 | * | ||
901 | * @return NULL on errors, otherwise handle for the guest. | ||
902 | */ | ||
903 | struct GNUNET_SOCIAL_Guest * | ||
904 | GNUNET_SOCIAL_guest_enter (const struct GNUNET_SOCIAL_App *app, | ||
905 | const struct GNUNET_SOCIAL_Ego *ego, | ||
906 | const struct GNUNET_CRYPTO_EddsaPublicKey *place_pub_key, | ||
907 | enum GNUNET_PSYC_SlaveJoinFlags flags, | ||
908 | const struct GNUNET_PeerIdentity *origin, | ||
909 | uint32_t relay_count, | ||
910 | const struct GNUNET_PeerIdentity *relays, | ||
911 | const struct GNUNET_PSYC_Message *entry_msg, | ||
912 | struct GNUNET_PSYC_Slicer *slicer, | ||
913 | GNUNET_SOCIAL_GuestEnterCallback local_enter_cb, | ||
914 | GNUNET_SOCIAL_EntryDecisionCallback entry_dcsn_cb, | ||
915 | void *cls); | ||
916 | |||
917 | |||
918 | /** | ||
919 | * Request entry to a place by name as a guest. | ||
920 | * | ||
921 | * @param app | ||
922 | * Application handle. | ||
923 | * @param ego | ||
924 | * Identity of the guest. | ||
925 | * @param gns_name | ||
926 | * GNS name of the place to enter. Either in the form of | ||
927 | * 'room.friend.gnu', or 'NYMPUBKEY.zkey'. This latter case refers to | ||
928 | * the 'PLACE' record of the empty label ("+") in the GNS zone with the | ||
929 | * nym's public key 'NYMPUBKEY', and can be used to request entry to a | ||
930 | * pseudonym's place directly. | ||
931 | * @param password | ||
932 | * Password to decrypt the record, or NULL for cleartext records. | ||
933 | * @param join_msg | ||
934 | * Entry request message. | ||
935 | * @param slicer | ||
936 | * Slicer to use for processing incoming requests from guests. | ||
937 | * @param local_enter_cb | ||
938 | * Called upon connection established to the social service. | ||
939 | * @param entry_decision_cb | ||
940 | * Called upon receiving entry decision. | ||
941 | * | ||
942 | * @return NULL on errors, otherwise handle for the guest. | ||
943 | */ | ||
944 | struct GNUNET_SOCIAL_Guest * | ||
945 | GNUNET_SOCIAL_guest_enter_by_name (const struct GNUNET_SOCIAL_App *app, | ||
946 | const struct GNUNET_SOCIAL_Ego *ego, | ||
947 | const char *gns_name, | ||
948 | const char *password, | ||
949 | const struct GNUNET_PSYC_Message *join_msg, | ||
950 | struct GNUNET_PSYC_Slicer *slicer, | ||
951 | GNUNET_SOCIAL_GuestEnterCallback local_enter_cb, | ||
952 | GNUNET_SOCIAL_EntryDecisionCallback entry_decision_cb, | ||
953 | void *cls); | ||
954 | |||
955 | |||
956 | /** | ||
957 | * Reconnect to an already entered place as guest. | ||
958 | * | ||
959 | * @param gconn | ||
960 | * Guest connection handle. | ||
961 | * @see GNUNET_SOCIAL_app_connect() & GNUNET_SOCIAL_AppGuestPlaceCallback() | ||
962 | * @param flags | ||
963 | * Flags for the entry. | ||
964 | * @param slicer | ||
965 | * Slicer to use for processing incoming requests from guests. | ||
966 | * @param local_enter_cb | ||
967 | * Called upon connection established to the social service. | ||
968 | * @param entry_decision_cb | ||
969 | * Called upon receiving entry decision. | ||
970 | * | ||
971 | * @return NULL on errors, otherwise handle for the guest. | ||
972 | */ | ||
973 | struct GNUNET_SOCIAL_Guest * | ||
974 | GNUNET_SOCIAL_guest_enter_reconnect (struct GNUNET_SOCIAL_GuestConnection *gconn, | ||
975 | enum GNUNET_PSYC_SlaveJoinFlags flags, | ||
976 | struct GNUNET_PSYC_Slicer *slicer, | ||
977 | GNUNET_SOCIAL_GuestEnterCallback local_enter_cb, | ||
978 | void *cls); | ||
979 | |||
980 | |||
981 | /** | ||
982 | * Flags for talking to the host of a place. | ||
983 | */ | ||
984 | enum GNUNET_SOCIAL_TalkFlags | ||
985 | { | ||
986 | GNUNET_SOCIAL_TALK_NONE = 0 | ||
987 | }; | ||
988 | |||
989 | |||
990 | /** | ||
991 | * A talk request. | ||
992 | */ | ||
993 | struct GNUNET_SOCIAL_TalkRequest; | ||
994 | |||
995 | |||
996 | /** | ||
997 | * Talk to the host of the place. | ||
998 | * | ||
999 | * @param place | ||
1000 | * Place where we want to talk to the host. | ||
1001 | * @param method_name | ||
1002 | * Method to invoke on the host. | ||
1003 | * @param env | ||
1004 | * Environment containing variables for the message, or NULL. | ||
1005 | * @param notify_data | ||
1006 | * Function to use to get the payload for the method. | ||
1007 | * @param notify_data_cls | ||
1008 | * Closure for @a notify_data. | ||
1009 | * @param flags | ||
1010 | * Flags for the message being sent. | ||
1011 | * | ||
1012 | * @return NULL if we are already trying to talk to the host, | ||
1013 | * otherwise handle to cancel the request. | ||
1014 | */ | ||
1015 | struct GNUNET_SOCIAL_TalkRequest * | ||
1016 | GNUNET_SOCIAL_guest_talk (struct GNUNET_SOCIAL_Guest *guest, | ||
1017 | const char *method_name, | ||
1018 | const struct GNUNET_PSYC_Environment *env, | ||
1019 | GNUNET_PSYC_TransmitNotifyData notify_data, | ||
1020 | void *notify_data_cls, | ||
1021 | enum GNUNET_SOCIAL_TalkFlags flags); | ||
1022 | |||
1023 | |||
1024 | /** | ||
1025 | * Resume talking to the host of the place. | ||
1026 | * | ||
1027 | * @param tr | ||
1028 | * Talk request to resume. | ||
1029 | */ | ||
1030 | void | ||
1031 | GNUNET_SOCIAL_guest_talk_resume (struct GNUNET_SOCIAL_TalkRequest *tr); | ||
1032 | |||
1033 | |||
1034 | /** | ||
1035 | * Cancel talking to the host of the place. | ||
1036 | * | ||
1037 | * @param tr | ||
1038 | * Talk request to cancel. | ||
1039 | */ | ||
1040 | void | ||
1041 | GNUNET_SOCIAL_guest_talk_cancel (struct GNUNET_SOCIAL_TalkRequest *tr); | ||
1042 | |||
1043 | |||
1044 | /** | ||
1045 | * Disconnect from a place. | ||
1046 | * | ||
1047 | * Invalidates guest handle. | ||
1048 | * | ||
1049 | * @param gst | ||
1050 | * The guest to disconnect. | ||
1051 | * @param disconnect_cb | ||
1052 | * Function called after disconnected from the service. | ||
1053 | * @param cls | ||
1054 | * Closure for @a disconnect_cb. | ||
1055 | */ | ||
1056 | void | ||
1057 | GNUNET_SOCIAL_guest_disconnect (struct GNUNET_SOCIAL_Guest *gst, | ||
1058 | GNUNET_ContinuationCallback disconnect_cb, | ||
1059 | void *cls); | ||
1060 | |||
1061 | |||
1062 | /** | ||
1063 | * Leave a place temporarily or permanently. | ||
1064 | * | ||
1065 | * Notifies the owner of the place about leaving, and destroys the place handle. | ||
1066 | * | ||
1067 | * @param place | ||
1068 | * Place to leave. | ||
1069 | * @param env | ||
1070 | * Optional environment for the leave message if @a keep_active | ||
1071 | * is #GNUNET_NO. NULL if not needed. | ||
1072 | * @param disconnect_cb | ||
1073 | * Called upon disconnecting from the social service. | ||
1074 | */ | ||
1075 | void | ||
1076 | GNUNET_SOCIAL_guest_leave (struct GNUNET_SOCIAL_Guest *gst, | ||
1077 | struct GNUNET_PSYC_Environment *env, | ||
1078 | GNUNET_ContinuationCallback disconnect_cb, | ||
1079 | void *leave_cls); | ||
1080 | |||
1081 | |||
1082 | /** | ||
1083 | * Obtain handle for a place entered as guest. | ||
1084 | * | ||
1085 | * The returned handle can be used to access the place API. | ||
1086 | * | ||
1087 | * @param guest Handle for the guest. | ||
1088 | * | ||
1089 | * @return Handle for the place, valid as long as @a guest is valid. | ||
1090 | */ | ||
1091 | struct GNUNET_SOCIAL_Place * | ||
1092 | GNUNET_SOCIAL_guest_get_place (struct GNUNET_SOCIAL_Guest *guest); | ||
1093 | |||
1094 | |||
1095 | /** | ||
1096 | * A history request. | ||
1097 | */ | ||
1098 | struct GNUNET_SOCIAL_HistoryRequest; | ||
1099 | |||
1100 | |||
1101 | /** | ||
1102 | * Get the public key of a place. | ||
1103 | * | ||
1104 | * @param plc | ||
1105 | * Place. | ||
1106 | * | ||
1107 | * @return Public key of the place. | ||
1108 | */ | ||
1109 | const struct GNUNET_CRYPTO_EddsaPublicKey * | ||
1110 | GNUNET_SOCIAL_place_get_pub_key (const struct GNUNET_SOCIAL_Place *plc); | ||
1111 | |||
1112 | |||
1113 | /** | ||
1114 | * Set message processing @a flags for a @a method_prefix. | ||
1115 | * | ||
1116 | * @param plc | ||
1117 | * Place. | ||
1118 | * @param method_prefix | ||
1119 | * Method prefix @a flags apply to. | ||
1120 | * @param flags | ||
1121 | * The flags that apply to a matching @a method_prefix. | ||
1122 | */ | ||
1123 | void | ||
1124 | GNUNET_SOCIAL_place_msg_proc_set (struct GNUNET_SOCIAL_Place *plc, | ||
1125 | const char *method_prefix, | ||
1126 | enum GNUNET_SOCIAL_MsgProcFlags flags); | ||
1127 | |||
1128 | /** | ||
1129 | * Clear all message processing flags previously set for this place. | ||
1130 | */ | ||
1131 | void | ||
1132 | GNUNET_SOCIAL_place_msg_proc_clear (struct GNUNET_SOCIAL_Place *plc); | ||
1133 | |||
1134 | |||
1135 | /** | ||
1136 | * Learn about the history of a place. | ||
1137 | * | ||
1138 | * Messages are returned through the @a slicer function | ||
1139 | * and have the #GNUNET_PSYC_MESSAGE_HISTORIC flag set. | ||
1140 | * | ||
1141 | * @param place | ||
1142 | * Place we want to learn more about. | ||
1143 | * @param start_message_id | ||
1144 | * First historic message we are interested in. | ||
1145 | * @param end_message_id | ||
1146 | * Last historic message we are interested in (inclusive). | ||
1147 | * @param method_prefix | ||
1148 | * Only retrieve messages with this method prefix. | ||
1149 | * @param flags | ||
1150 | * OR'ed GNUNET_PSYC_HistoryReplayFlags | ||
1151 | * @param slicer | ||
1152 | * Slicer to use for retrieved messages. | ||
1153 | * Can be the same as the slicer of the place. | ||
1154 | * @param result_cb | ||
1155 | * Function called after all messages retrieved. | ||
1156 | * NULL if not needed. | ||
1157 | * @param cls Closure for @a result_cb. | ||
1158 | */ | ||
1159 | struct GNUNET_SOCIAL_HistoryRequest * | ||
1160 | GNUNET_SOCIAL_place_history_replay (struct GNUNET_SOCIAL_Place *plc, | ||
1161 | uint64_t start_message_id, | ||
1162 | uint64_t end_message_id, | ||
1163 | const char *method_prefix, | ||
1164 | uint32_t flags, | ||
1165 | struct GNUNET_PSYC_Slicer *slicer, | ||
1166 | GNUNET_ResultCallback result_cb, | ||
1167 | void *cls); | ||
1168 | |||
1169 | |||
1170 | /** | ||
1171 | * Learn about the history of a place. | ||
1172 | * | ||
1173 | * Sends messages through the slicer function of the place where | ||
1174 | * start_message_id <= message_id <= end_message_id. | ||
1175 | * The messages will have the #GNUNET_PSYC_MESSAGE_HISTORIC flag set. | ||
1176 | * | ||
1177 | * To get the latest message, use 0 for both the start and end message ID. | ||
1178 | * | ||
1179 | * @param place | ||
1180 | * Place we want to learn more about. | ||
1181 | * @param message_limit | ||
1182 | * Maximum number of historic messages we are interested in. | ||
1183 | * @param result_cb | ||
1184 | * Function called after all messages retrieved. | ||
1185 | * NULL if not needed. | ||
1186 | * @param cls Closure for @a result_cb. | ||
1187 | */ | ||
1188 | struct GNUNET_SOCIAL_HistoryRequest * | ||
1189 | GNUNET_SOCIAL_place_history_replay_latest (struct GNUNET_SOCIAL_Place *plc, | ||
1190 | uint64_t message_limit, | ||
1191 | const char *method_prefix, | ||
1192 | uint32_t flags, | ||
1193 | struct GNUNET_PSYC_Slicer *slicer, | ||
1194 | GNUNET_ResultCallback result_cb, | ||
1195 | void *cls); | ||
1196 | |||
1197 | /** | ||
1198 | * Cancel learning about the history of a place. | ||
1199 | * | ||
1200 | * @param hist | ||
1201 | * History lesson to cancel. | ||
1202 | */ | ||
1203 | void | ||
1204 | GNUNET_SOCIAL_place_history_replay_cancel (struct GNUNET_SOCIAL_HistoryRequest *hist); | ||
1205 | |||
1206 | |||
1207 | struct GNUNET_SOCIAL_LookHandle; | ||
1208 | |||
1209 | |||
1210 | /** | ||
1211 | * Look at a particular object in the place. | ||
1212 | * | ||
1213 | * The best matching object is returned (its name might be less specific than | ||
1214 | * what was requested). | ||
1215 | * | ||
1216 | * @param place | ||
1217 | * The place to look the object at. | ||
1218 | * @param full_name | ||
1219 | * Full name of the object. | ||
1220 | * | ||
1221 | * @return NULL if there is no such object at this place. | ||
1222 | */ | ||
1223 | struct GNUNET_SOCIAL_LookHandle * | ||
1224 | GNUNET_SOCIAL_place_look_at (struct GNUNET_SOCIAL_Place *plc, | ||
1225 | const char *full_name, | ||
1226 | GNUNET_PSYC_StateVarCallback var_cb, | ||
1227 | GNUNET_ResultCallback result_cb, | ||
1228 | void *cls); | ||
1229 | |||
1230 | /** | ||
1231 | * Look for objects in the place with a matching name prefix. | ||
1232 | * | ||
1233 | * @param place | ||
1234 | * The place to look its objects at. | ||
1235 | * @param name_prefix | ||
1236 | * Look at objects with names beginning with this value. | ||
1237 | * @param var_cb | ||
1238 | * Function to call for each object found. | ||
1239 | * @param cls | ||
1240 | * Closure for callback function. | ||
1241 | * | ||
1242 | * @return Handle that can be used to stop looking at objects. | ||
1243 | */ | ||
1244 | struct GNUNET_SOCIAL_LookHandle * | ||
1245 | GNUNET_SOCIAL_place_look_for (struct GNUNET_SOCIAL_Place *plc, | ||
1246 | const char *name_prefix, | ||
1247 | GNUNET_PSYC_StateVarCallback var_cb, | ||
1248 | GNUNET_ResultCallback result_cb, | ||
1249 | void *cls); | ||
1250 | |||
1251 | |||
1252 | /** | ||
1253 | * Stop looking at objects. | ||
1254 | * | ||
1255 | * @param lh Look handle to stop. | ||
1256 | */ | ||
1257 | void | ||
1258 | GNUNET_SOCIAL_place_look_cancel (struct GNUNET_SOCIAL_LookHandle *lh); | ||
1259 | |||
1260 | |||
1261 | /** | ||
1262 | * Advertise a @e place in the GNS zone of @a ego. | ||
1263 | * | ||
1264 | * @param app | ||
1265 | * Application handle. | ||
1266 | * @param ego | ||
1267 | * Ego. | ||
1268 | * @param place_pub_key | ||
1269 | * Public key of place to add. | ||
1270 | * @param name | ||
1271 | * The name for the PLACE record to put in the zone. | ||
1272 | * @param password | ||
1273 | * Password used to encrypt the record or NULL to keep it cleartext. | ||
1274 | * @param relay_count | ||
1275 | * Number of elements in the @a relays array. | ||
1276 | * @param relays | ||
1277 | * List of relays to put in the PLACE record to advertise | ||
1278 | * as entry points to the place in addition to the origin. | ||
1279 | * @param expiration_time | ||
1280 | * Expiration time of the record, use 0 to remove the record. | ||
1281 | * @param result_cb | ||
1282 | * Function called with the result of the operation. | ||
1283 | * @param result_cls | ||
1284 | * Closure for @a result_cb | ||
1285 | * | ||
1286 | * @return #GNUNET_OK if the request was sent, | ||
1287 | * #GNUNET_SYSERR on error, e.g. the name/password is too long. | ||
1288 | */ | ||
1289 | int | ||
1290 | GNUNET_SOCIAL_zone_add_place (const struct GNUNET_SOCIAL_App *app, | ||
1291 | const struct GNUNET_SOCIAL_Ego *ego, | ||
1292 | const char *name, | ||
1293 | const char *password, | ||
1294 | const struct GNUNET_CRYPTO_EddsaPublicKey *place_pub_key, | ||
1295 | const struct GNUNET_PeerIdentity *origin, | ||
1296 | uint32_t relay_count, | ||
1297 | const struct GNUNET_PeerIdentity *relays, | ||
1298 | struct GNUNET_TIME_Absolute expiration_time, | ||
1299 | GNUNET_ResultCallback result_cb, | ||
1300 | void *result_cls); | ||
1301 | |||
1302 | |||
1303 | /** | ||
1304 | * Add public key to the GNS zone of the @e ego. | ||
1305 | * | ||
1306 | * @param cfg | ||
1307 | * Configuration. | ||
1308 | * @param ego | ||
1309 | * Ego. | ||
1310 | * @param name | ||
1311 | * The name for the PKEY record to put in the zone. | ||
1312 | * @param nym_pub_key | ||
1313 | * Public key of nym to add. | ||
1314 | * @param expiration_time | ||
1315 | * Expiration time of the record, use 0 to remove the record. | ||
1316 | * @param result_cb | ||
1317 | * Function called with the result of the operation. | ||
1318 | * @param result_cls | ||
1319 | * Closure for @a result_cb | ||
1320 | * | ||
1321 | * @return #GNUNET_OK if the request was sent, | ||
1322 | * #GNUNET_SYSERR on error, e.g. the name is too long. | ||
1323 | */ | ||
1324 | int | ||
1325 | GNUNET_SOCIAL_zone_add_nym (const struct GNUNET_SOCIAL_App *app, | ||
1326 | const struct GNUNET_SOCIAL_Ego *ego, | ||
1327 | const char *name, | ||
1328 | const struct GNUNET_CRYPTO_EcdsaPublicKey *nym_pub_key, | ||
1329 | struct GNUNET_TIME_Absolute expiration_time, | ||
1330 | GNUNET_ResultCallback result_cb, | ||
1331 | void *result_cls); | ||
1332 | |||
1333 | |||
1334 | #if 0 /* keep Emacsens' auto-indent happy */ | ||
1335 | { | ||
1336 | #endif | ||
1337 | #ifdef __cplusplus | ||
1338 | } | ||
1339 | #endif | ||
1340 | |||
1341 | /* ifndef GNUNET_SOCIAL_SERVICE_H */ | ||
1342 | #endif | ||
1343 | |||
1344 | /** @} */ /* end of group */ | ||