2 This file is part of GNUnet.
3 (C) 2013 Christian Grothoff (and other contributing authors)
5 GNUnet is free software; you can redistribute it and/or modify
6 it under the terms of the GNU General Public License as published
7 by the Free Software Foundation; either version 3, or (at your
8 option) any later version.
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 General Public License for more details.
15 You should have received a copy of the GNU General Public License
16 along with GNUnet; see the file COPYING. If not, write to the
17 Free Software Foundation, Inc., 59 Temple Place - Suite 330,
18 Boston, MA 02111-1307, USA.
22 * @file include/gnunet_social_service.h
23 * @brief Social service; implements social functionality using the PSYC service
25 * @author Christian Grothoff
27 #ifndef GNUNET_SOCIAL_SERVICE_H
28 #define GNUNET_SOCIAL_SERVICE_H
33 #if 0 /* keep Emacsens' auto-indent happy */
38 #include "gnunet_util_lib.h"
39 #include "gnunet_psyc_service.h"
40 #include "gnunet_multicast_service.h"
44 * Version number of GNUnet Social API.
46 #define GNUNET_SOCIAL_VERSION 0x00000000
50 * Handle for a place where social interactions happen.
52 struct GNUNET_SOCIAL_Place;
55 * Handle for a place that one of our egos hosts.
57 struct GNUNET_SOCIAL_Home;
60 * Handle for our own presence in the network (we can of course have
63 struct GNUNET_SOCIAL_Ego;
66 * Handle for another user (who is likely pseudonymous) in the network.
68 struct GNUNET_SOCIAL_Nym;
71 * Handle to an implementation of try-and-slice.
73 struct GNUNET_SOCIAL_Slicer;
77 * Method called from SOCIAL upon receiving a message indicating a call
81 * @param full_method_name original method name from PSYC (may be more
82 * specific than the registered method name due to try-and-slice matching)
83 * @param message_id unique message counter for this message;
84 * (unique only in combination with the given sender for
86 * @param data_off byte offset of 'data' in the overall data of the method
87 * @param data_size number of bytes in 'data';
88 * @param data data stream given to the method (might not be zero-terminated
90 * @param frag fragmentation status for the data
92 typedef int (*GNUNET_SOCIAL_Method)(void *cls,
93 const char *full_method_name,
98 enum GNUNET_PSYC_FragmentStatus frag);
102 * Create a try-and-slice instance.
104 * @return try-and-slice construct
106 struct GNUNET_SOCIAL_Slicer *
107 GNUNET_SOCIAL_slicer_create (void);
111 * Add a method to the try-and-slice instance.
113 * @param slicer try-and-slice instance to extend
114 * @param method_name name of the given method, use empty string for default
115 * @param method method to invoke
116 * @param method_cls closure for method
119 GNUNET_SOCIAL_slicer_add (struct GNUNET_SOCIAL_Slicer *slicer,
120 const char *method_name,
121 GNUNET_SOCIAL_Method method,
126 * Destroy a given try-and-slice instance.
128 * @param slicer slicer to destroy
131 GNUNET_SOCIAL_slicer_destroy (struct GNUNET_SOCIAL_Slicer *slicer);
135 * Create an ego using the private key from the given
136 * file. If the file does not exist, a fresh key is
139 * @param keyfile name of the file with the private key for the ego,
140 * NULL for ephemeral egos
141 * @return handle to the ego, NULL on error
143 struct GNUNET_SOCIAL_Ego *
144 GNUNET_SOCIAL_ego_create (const char *keyfile);
148 * Destroy a handle to an ego.
150 * @param ego ego to destroy
153 GNUNET_SOCIAL_ego_destroy (struct GNUNET_SOCIAL_Ego *ego);
157 * Function called asking for nym to be admitted to the room. Should
158 * call either 'GNUNET_SOCIAL_home_admit' or
159 * 'GNUNET_SOCIAL_home_reject_entry' (possibly asynchronously). If
160 * this owner cannot decide, it is fine to call neither function, in
161 * which case hopefully some other owner of the home exists that will
162 * make the decision. The 'nym' reference remains valid until the
163 * 'GNUNET_SOCIAL_FarewellCallback' is invoked for it.
166 * @param nym handle for the user who wants to join
167 * @param join_msg_size number of bytes in 'join_msg'
168 * @param join_msg payload given on join
170 typedef void (*GNUNET_SOCIAL_AnswerDoorCallback)(void *cls,
171 struct GNUNET_SOCIAL_Nym *nym,
172 size_t join_msg_size,
173 const void *join_msg);
177 * Function called when a 'nym' leaves the room. This is
178 * also called if the 'nym' was never given permission to
179 * enter (i.e. the 'nym' stopped asking to get in).
182 * @param nym handle for the user who left
184 typedef void (*GNUNET_SOCIAL_FarewellCallback)(void *cls,
185 struct GNUNET_SOCIAL_Nym *nym);
189 * Create a new home to host guests (nyms).
191 * @param cfg configuration to contact the social service
192 * @param home_keyfile file with the private key for the home,
193 * created if the file does not exist;
194 * pass NULL for ephemeral homes
195 * @param join_policy what is our policy for allowing people in?
196 * @param ego owner of the home (host)
197 * @param slicer slicer to handle guests talking
198 * @param listener_cb function to handle new nyms that want to join
199 * @param farewell_cb function to handle departing nyms
200 * @param cls closure for 'listener_cb' and 'farewell_cb'
201 * @return handle for a new home
203 struct GNUNET_SOCIAL_Home *
204 GNUNET_SOCIAL_home_enter (const struct GNUNET_CONFIGURATION_Handle *cfg,
205 const char *home_keyfile,
206 enum GNUNET_MULTICAST_JoinPolicy join_policy,
207 struct GNUNET_SOCIAL_Ego *ego,
208 struct GNUNET_SOCIAL_Slicer *slicer,
209 GNUNET_SOCIAL_AnswerDoorCallback listener_cb,
210 GNUNET_SOCIAL_FarewellCallback farewell_cb,
215 * Admit 'nym' to the 'home'. 'nym' will remain valid until either
216 * the home is destroyed or 'nym' leaves.
218 * @param home home to allow 'nym' to join
219 * @param nym handle for the entity that wants to join
222 GNUNET_SOCIAL_home_admit (struct GNUNET_SOCIAL_Home *home,
223 struct GNUNET_SOCIAL_Nym *nym);
227 * Throw 'nym' out of the 'home'. 'nym' will remain valid
228 * until the 'GNUNET_SOCIAL_FarewellCallback' is invoked, which
229 * should be very soon after this call.
231 * @param home home to allow 'nym' to join
232 * @param nym handle for the entity that wants to join
235 GNUNET_SOCIAL_home_evict (struct GNUNET_SOCIAL_Home *home,
236 struct GNUNET_SOCIAL_Nym *nym);
240 * Refuse 'nym' entry into the 'home'.
242 * @param home home to disallow 'nym' to join
243 * @param nym handle for the entity that wanted to join
244 * @param method method name to invoke on caller
245 * @param message_size number of bytes in 'message' for method
246 * @param message rejection message to send back
249 GNUNET_SOCIAL_home_reject_entry (struct GNUNET_SOCIAL_Home *home,
250 struct GNUNET_SOCIAL_Nym *nym,
253 const void *message);
257 * Get the identity of a user (suitable, for example, to be used
258 * with 'GNUNET_NAMESTORE_zone_to_name').
260 * @param nym pseydonym to map to a cryptographic identifier
261 * @param identity set to the identity of the nym (short hash of the public key)
264 GNUNET_SOCIAL_nym_get_identity (struct GNUNET_SOCIAL_Nym *nym,
265 struct GNUNET_CRYPTO_ShortHashCode *identity);
269 * Obtain the (cryptographic, binary) address for the home.
271 * @param home home to get the (public) address from
272 * @param crypto_address address suitable for storing in GADS,
273 * i.e. in 'HEX.place' or within the respective GADS record type ("PLACE")
276 GNUNET_SOCIAL_home_get_address (struct GNUNET_SOCIAL_Home *home,
277 struct GNUNET_HashCode *crypto_address);
281 * (re)decorate the home by changing objects in it. If
282 * the operation is 'GNUNET_PSYC_SOT_SET_VARIABLE' then
283 * the decoration only applies to the next announcement
286 * @param home the home to decorate
287 * @param operation operation to perform on the object
288 * @param object_name name of the object to modify
289 * @param object_value_size size of the given 'object_value'
290 * @param object_value value to use for the modification
293 GNUNET_SOCIAL_home_decorate (struct GNUNET_SOCIAL_Home *home,
294 enum GNUNET_PSYC_Operator operation,
295 const char *object_name,
296 size_t object_value_size,
297 const void *object_value);
301 * Handle for an announcement request.
303 struct GNUNET_SOCIAL_Announcement;
307 * This function allows the home owner to send a message to all
308 * nyms that are present in the home.
310 * @param home home to address the announcement to
311 * @param full_method_name method to use for the announcement
312 * @param notify function to call to get the payload of the announcement
313 * @param notify_cls closure for 'notify'
314 * @return NULL on error (announcement already in progress?)
316 struct GNUNET_SOCIAL_Announcement *
317 GNUNET_SOCIAL_place_announce (struct GNUNET_SOCIAL_Home *home,
318 const char *full_method_name,
319 GNUNET_PSYC_OriginReadyNotify notify,
324 * Cancel announcement.
326 * @param a the announcement to cancel
329 GNUNET_SOCIAL_place_announce_cancel (struct GNUNET_SOCIAL_Announcement *a);
333 * Convert our home to a place so we can access it via the place API.
335 * @param home handle for the home
336 * @return place handle for the same home, valid as long as 'home' is valid;
337 * do NOT try to 'GNUNET_SOCIAL_place_leave' this place, it's your home!
339 struct GNUNET_SOCIAL_Place *
340 GNUNET_SOCIAL_home_to_place (struct GNUNET_SOCIAL_Home *home);
344 * Leave a home, visitors can stay.
346 * @param home home to leave (handle becomes invalid).
349 GNUNET_SOCIAL_home_leave (struct GNUNET_SOCIAL_Home *home);
353 * Destroy a home, all guests will be evicted.
355 * @param home home to destroy
358 GNUNET_SOCIAL_home_destroy (struct GNUNET_SOCIAL_Home *home);
362 * Join a place (home hosted by someone else).
364 * @param cfg configuration to contact the social service
365 * @param ego owner of the home (host)
366 * @param address address of the place to join (GADS name, i.e. 'room.friend.gads'),
367 * if the name has the form 'HEX.place', GADS is not
368 * used and HEX is assumed to be the hash of the public
369 * key already; 'HEX.zkey' however would refer to
370 * the 'PLACE' record in the GADS zone with the public key
372 * @param join_msg_size number of bytes in 'join_msg'
373 * @param join_msg message to give to the join callback
374 * @return NULL on errors, otherwise handle to the place
376 struct GNUNET_SOCIAL_Place *
377 GNUNET_SOCIAL_place_join (const struct GNUNET_CONFIGURATION_Handle *cfg,
378 struct GNUNET_SOCIAL_Ego *ego,
380 struct GNUNET_SOCIAL_Slicer *slicer,
381 size_t join_msg_size,
382 const void *join_msg);
388 struct GNUNET_SOCIAL_WatchHandle;
398 struct GNUNET_SOCIAL_WatchHandle *
399 GNUNET_SOCIAL_place_watch (struct GNUNET_SOCIAL_Place *place,
400 const char *object_filter,
401 GNUNET_PSYC_StateCallback state_cb,
411 GNUNET_SOCIAL_place_watch_cancel (struct GNUNET_SOCIAL_WatchHandle *wh);
417 struct GNUNET_SOCIAL_LookHandle;
420 * Look at all objects in the place.
423 struct GNUNET_SOCIAL_LookHandle *
424 GNUNET_SOCIAL_place_look (struct GNUNET_SOCIAL_Place *place,
425 GNUNET_PSYC_StateCallback state_cb,
430 * Look at matching objects in the place.
433 struct GNUNET_SOCIAL_LookHandle *
434 GNUNET_SOCIAL_place_look_for (struct GNUNET_SOCIAL_Place *place,
435 const char *object_filter,
436 GNUNET_PSYC_StateCallback state_cb,
446 GNUNET_SOCIAL_place_look_cancel (struct GNUNET_SOCIAL_LookHandle *lh);
451 * Look at a particular object in the place.
455 * @param value_size set to the size of the returned value
456 * @return NULL if there is no such object at this place
459 GNUNET_SOCIAL_place_look_at (struct GNUNET_SOCIAL_Place *place,
460 const char *object_name,
465 * Frame the (next) talk by setting some variables for it.
468 * @param variable_name
469 * @param value_size number of bytes in 'value'
473 GNUNET_SOCIAL_place_frame_talk (struct GNUNET_SOCIAL_Place *place,
474 const char *variable_name,
482 struct GNUNET_SOCIAL_TalkRequest;
486 * Talk to the host of the place.
488 * @param place place at which we want to talk to the host
489 * @param method_name method to invoke on the host
490 * @param cb function to use to get the payload for the method
491 * @param cb_cls closure for 'cb'
492 * @return NULL if we are already trying to talk to the host,
493 * otherwise handle to cancel the request
495 struct GNUNET_SOCIAL_TalkRequest *
496 GNUNET_SOCIAL_place_talk (struct GNUNET_SOCIAL_Place *place,
497 const char *method_name,
498 GNUNET_PSYC_OriginReadyNotify cb,
508 GNUNET_SOCIAL_place_talk_cancel (struct GNUNET_SOCIAL_TalkRequest *tr);
514 struct GNUNET_SOCIAL_HistoryLesson;
520 * @param place place we want to learn more about
521 * @param start_message_id first historic message we are interested in
522 * @param end_message_id last historic message we are interested in (inclusive)
523 * @param slicer slicer to use to process history
524 * @return handle to abort history lesson, never NULL (multiple lesssons
525 * at the same time are allowed)
527 struct GNUNET_SOCIAL_HistoryLesson *
528 GNUNET_SOCIAL_place_get_history (struct GNUNET_SOCIAL_Place *place,
529 uint64_t start_message_id,
530 uint64_t end_message_id,
531 struct GNUNET_SOCIAL_Slicer *slicer);
535 * Stop processing messages from the history lesson. Must also be
536 * called explicitly after all of the requested messages have been
539 * @param hist history lesson to cancel
542 GNUNET_SOCIAL_place_get_history_cancel (struct GNUNET_SOCIAL_HistoryLesson *hist);
546 * Leave a place (destroys the place handle). Can either move our
547 * user into an 'away' state (in which we continue to record ongoing
548 * conversations and state changes if our peer is running), or
549 * leave the place entirely and stop following the conversation.
551 * @param place place to leave
552 * @param keep_following GNUNET_YES to ask the social service to continue
553 * to follow the conversation, GNUNET_NO to fully leave the place
556 GNUNET_SOCIAL_place_leave (struct GNUNET_SOCIAL_Place *place,
561 #if 0 /* keep Emacsens' auto-indent happy */
568 /* ifndef GNUNET_SOCIAL_SERVICE_H */
570 /* end of gnunet_social_service.h */