summaryrefslogtreecommitdiff
path: root/src/social/social_api.c
blob: fd6e8f04a86eb7bd3043dcc0398f393358c6ded6 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
/*
 * This file is part of GNUnet
 * (C) 2013 Christian Grothoff (and other contributing authors)
 *
 * GNUnet is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published
 * by the Free Software Foundation; either version 3, or (at your
 * option) any later version.
 *
 * GNUnet is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with GNUnet; see the file COPYING.  If not, write to the
 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 * Boston, MA 02111-1307, USA.
 */

/**
 * @file social/social_api.c
 * @brief Social service; implements social functionality using the PSYC service.
 * @author Gabor X Toth
 */

#include <inttypes.h>

#include "platform.h"
#include "gnunet_util_lib.h"
#include "gnunet_env_lib.h"
#include "gnunet_psyc_service.h"
#include "gnunet_social_service.h"
#include "social.h"


/**
 * Handle for another user (who is likely pseudonymous) in the network.
 */
struct GNUNET_SOCIAL_Nym
{

};


/**
 * Handle for a place where social interactions happen.
 */
struct GNUNET_SOCIAL_Place
{

};


/**
 * Handle for a place that one of our egos hosts.
 */
struct GNUNET_SOCIAL_Home
{

};


/**
 * Handle to an implementation of try-and-slice.
 */
struct GNUNET_SOCIAL_Slicer
{

};


/**
 * Handle for an announcement request.
 */
struct GNUNET_SOCIAL_Announcement
{

};


struct GNUNET_SOCIAL_WatchHandle
{

};


struct GNUNET_SOCIAL_LookHandle
{

};


/**
 * A talk request.
 */
struct GNUNET_SOCIAL_TalkRequest
{

};


/**
 * A history lesson.
 */
struct GNUNET_SOCIAL_HistoryLesson
{

};


/**
 * Create a try-and-slice instance.
 *
 * @return A new try-and-slice construct.
 */
struct GNUNET_SOCIAL_Slicer *
GNUNET_SOCIAL_slicer_create (void)
{
  return NULL;
}


/**
 * Add a method to the try-and-slice instance.
 *
 * A slicer processes messages and calls methods that match a message. A match
 * happens whenever the method name of a message starts with the method_name
 * parameter given here.
 *
 * @param slicer The try-and-slice instance to extend.
 * @param method_name Name of the given method, use empty string for default.
 * @param method Method to invoke.
 * @param method_cls Closure for method.
 */
void
GNUNET_SOCIAL_slicer_add (struct GNUNET_SOCIAL_Slicer *slicer,
                          const char *method_name,
                          GNUNET_SOCIAL_Method method,
                          void *method_cls)
{

}


/**
 * Remove a registered method from the try-and-slice instance.
 *
 * @param slicer The try-and-slice instance.
 * @param method_name Name of the method to remove.
 * @param method Method handler.
 */
void
GNUNET_SOCIAL_slicer_remove (struct GNUNET_SOCIAL_Slicer *slicer,
                             const char *method_name,
                             GNUNET_SOCIAL_Method method)
{

}


/**
 * Destroy a given try-and-slice instance.
 *
 * @param slicer slicer to destroy
 */
void
GNUNET_SOCIAL_slicer_destroy (struct GNUNET_SOCIAL_Slicer *slicer)
{

}


/**
 * Enter a home where guests (nyms) can be hosted.
 *
 * A home is created upon first entering, and exists until
 * GNUNET_SOCIAL_home_destroy() is called. It can also be left temporarily using
 * GNUNET_SOCIAL_home_leave().
 *
 * @param cfg Configuration to contact the social service.
 * @param home_keyfile File with the private-public key pair of the home,
 *        created if the file does not exist; pass NULL for ephemeral homes.
 * @param policy Policy specifying entry and history restrictions of the home.
 * @param ego Owner of the home (host).
 * @param slicer Slicer to handle guests talking.
 * @param listener_cb Function to handle new nyms that want to enter.
 * @param farewell_cb Function to handle departing nyms.
 * @param cls Closure for @a listener_cb and @a farewell_cb.
 * @return Handle for a new home.
 */
struct GNUNET_SOCIAL_Home *
GNUNET_SOCIAL_home_enter (const struct GNUNET_CONFIGURATION_Handle *cfg,
                          const char *home_keyfile,
                          enum GNUNET_PSYC_Policy policy,
                          struct GNUNET_IDENTITY_Ego *ego,
                          struct GNUNET_SOCIAL_Slicer *slicer,
                          GNUNET_SOCIAL_AnswerDoorCallback listener_cb,
                          GNUNET_SOCIAL_FarewellCallback farewell_cb,
                          void *cls)
{
  return NULL;
}


/**
 * Admit @a nym to the @a home.
 *
 * The @a nym reference will remain valid until either the home is destroyed or
 * @a nym leaves.
 *
 * @param home Home to allow @a nym to enter.
 * @param nym Handle for the entity that wants to enter.
 */
void
GNUNET_SOCIAL_home_admit (struct GNUNET_SOCIAL_Home *home,
                          struct GNUNET_SOCIAL_Nym *nym)
{

}


/**
 * Throw @a nym out of the @a home.
 *
 * The @a nym reference will remain valid until the
 * #GNUNET_SOCIAL_FarewellCallback is invoked,
 * which should be very soon after this call.
 *
 * @param home Home to eject @a nym from.
 * @param nym Handle for the entity to be ejected.
 */
void
GNUNET_SOCIAL_home_eject (struct GNUNET_SOCIAL_Home *home,
                          struct GNUNET_SOCIAL_Nym *nym)
{

}


/**
 * Refuse @a nym entry into the @a home.
 *
 * @param home Home to disallow @a nym to enter.
 * @param nym Handle for the entity that wanted to enter.
 * @param method_name Method name for the rejection message.
 * @param env Environment containing variables for the message, or NULL.
 * @param data Data for the rejection message to send back.
 * @param data_size Number of bytes in @a data for method.
 */
void
GNUNET_SOCIAL_home_reject_entry (struct GNUNET_SOCIAL_Home *home,
                                 struct GNUNET_SOCIAL_Nym *nym,
                                 const char *method_name,
                                 const struct GNUNET_ENV_Environment *env,
                                 const void *data,
                                 size_t data_size)
{

}


/**
 * Get the public key of a nym.
 *
 * Suitable, for example, to be used with GNUNET_NAMESTORE_zone_to_name().
 *
 * @param nym Pseudonym to map to a cryptographic identifier.
 * @param[out] nym_key Set to the public key of the nym.
 */
void
GNUNET_SOCIAL_nym_get_key (struct GNUNET_SOCIAL_Nym *nym,
                           struct GNUNET_CRYPTO_EddsaPublicKey *nym_key)
{

}


/**
 * Obtain the private-public key pair of the home.
 *
 * @param home Home to get the key of.
 * @param[out] home_key Set to the private-public key pair of the home.  The public part is suitable for storing in GNS within a "PLACE" record, along with peer IDs to join at.
 */
void
GNUNET_SOCIAL_home_get_key (struct GNUNET_SOCIAL_Home *home,
                            struct GNUNET_CRYPTO_EddsaPrivateKey *home_key)
{

}


/**
 * Advertise @a home under @a name in the GNS zone of the @e ego.
 *
 * @param home The home to advertise.
 * @param name The name for the PLACE record to put in the zone.
 * @param peer_count Number of elements in the @a peers array.
 * @param peers List of peers in the PLACE record that can be used to send join
 *        requests to.
 * @param expiration_time Expiration time of the record, use 0 to remove the record.
 * @param password Password used to encrypt the record.
 */
void
GNUNET_SOCIAL_home_advertise (struct GNUNET_SOCIAL_Home *home,
                              const char *name,
                              size_t peer_count,
                              const struct GNUNET_PeerIdentity *peers,
                              struct GNUNET_TIME_Relative expiration_time,
                              const char *password)
{

}


/**
 * Send a message to all nyms that are present in the home.
 *
 * This function is restricted to the home owner.  Nyms can only send requests
 * to the home owner who can decide to relay it to other guests.
 *
 * @param home Home to address the announcement to.
 * @param method_name Method to use for the announcement.
 * @param env Environment containing variables for the message and operations on
 *        objects of the home, or NULL.
 * @param notify Function to call to get the payload of the announcement.
 * @param notify_cls Closure for @a notify.
 * @param flags Flags for this announcement.
 * @return NULL on error (announcement already in progress?).
 */
struct GNUNET_SOCIAL_Announcement *
GNUNET_SOCIAL_home_announce (struct GNUNET_SOCIAL_Home *home,
                             const char *method_name,
                             const struct GNUNET_ENV_Environment *env,
                             GNUNET_CONNECTION_TransmitReadyNotify notify,
                             void *notify_cls,
                             enum GNUNET_SOCIAL_AnnounceFlags flags)
{
  return NULL;
}


/**
 * Cancel announcement.
 *
 * @param a The announcement to cancel.
 */
void
GNUNET_SOCIAL_home_announce_cancel (struct GNUNET_SOCIAL_Announcement *a)
{

}


/**
 * Convert our home to a place so we can access it via the place API.
 *
 * @param home Handle for the home.
 * @return Place handle for the same home, valid as long as @a home is valid;
 *         do NOT try to GNUNET_SOCIAL_place_leave() this place, it's your home!
 */
struct GNUNET_SOCIAL_Place *
GNUNET_SOCIAL_home_get_place (struct GNUNET_SOCIAL_Home *home)
{
  return NULL;
}


/**
 * Leave a home.

 * Invalidates home handle.
 * Guests will be disconnected until the home is restarted.
 *
 * @param home Home to leave.
 * @param keep_active Keep home active after last application disconnected.
 */
void
GNUNET_SOCIAL_home_leave (struct GNUNET_SOCIAL_Home *home, int keep_active)
{

}

/**
 * Request entry to a place (home hosted by someone else).
 *
 * @param cfg Configuration to contact the social service.
 * @param ego Owner of the home (host).
 * @param address GNS name of the place to enter.  Either in the form of
 *        'room.friend.gnu', or 'NYMPUBKEY.zkey'.  This latter case refers to
 *        the 'PLACE' record of the empty label ("+") in the GNS zone with the
 *        nym's public key 'NYMPUBKEY', and can be used to request entry to a
 *        pseudonym's place directly.
 * @param method_name Method name for the message.
 * @param env Environment containing variables for the message, or NULL.
 * @param data Payload for the message to give to the enter callback.
 * @param data_size Number of bytes in @a data.
 * @param slicer Slicer to use for processing incoming requests from guests.
 * @return NULL on errors, otherwise handle to the place.
 */
struct GNUNET_SOCIAL_Place *
GNUNET_SOCIAL_place_enter (const struct GNUNET_CONFIGURATION_Handle *cfg,
                           struct GNUNET_IDENTITY_Ego *ego,
                           char *address,
                           const char *method_name,
                           const struct GNUNET_ENV_Environment *env,
                           const void *data,
                           size_t data_size,
                           struct GNUNET_SOCIAL_Slicer *slicer)
{
  return NULL;
}

/**
 * Request entry to a place (home hosted by someone else).
 *
 * @param cfg Configuration to contact the social service.
 * @param ego Owner of the home (host).
 * @param crypto_address Public key of the place to enter.
 * @param origin Peer identity of the origin of the underlying multicast group.
 * @param relay_count Number of elements in the @a relays array.
 * @param relays Relays for the underlying multicast group.
 * @param method_name Method name for the message.
 * @param env Environment containing variables for the message, or NULL.
 * @param data Payload for the message to give to the enter callback.
 * @param data_size Number of bytes in @a data.
 * @param slicer Slicer to use for processing incoming requests from guests.
 * @return NULL on errors, otherwise handle to the place.
 */
struct GNUNET_SOCIAL_Place *
GNUNET_SOCIAL_place_enter2 (const struct GNUNET_CONFIGURATION_Handle *cfg,
                            struct GNUNET_IDENTITY_Ego *ego,
                            struct GNUNET_CRYPTO_EddsaPublicKey *crypto_address,
                            struct GNUNET_PeerIdentity *origin,
                            size_t relay_count,
                            struct GNUNET_PeerIdentity *relays,
                            const char *method_name,
                            const struct GNUNET_ENV_Environment *env,
                            const void *data,
                            size_t data_size,
                            struct GNUNET_SOCIAL_Slicer *slicer)
{
  return NULL;
}


/**
 * Watch a place for changed objects.
 *
 * @param place Place to watch.
 * @param object_filter Object prefix to match.
 * @param state_cb Function to call when an object/state changes.
 * @param state_cb_cls Closure for callback.
 *
 * @return Handle that can be used to cancel watching.
 */
struct GNUNET_SOCIAL_WatchHandle *
GNUNET_SOCIAL_place_watch (struct GNUNET_SOCIAL_Place *place,
                           const char *object_filter,
                           GNUNET_PSYC_StateCallback state_cb,
                           void *state_cb_cls)
{
  return NULL;
}


/**
 * Cancel watching a place for changed objects.
 *
 * @param wh Watch handle to cancel.
 */
void
GNUNET_SOCIAL_place_watch_cancel (struct GNUNET_SOCIAL_WatchHandle *wh)
{

}


/**
 * Look at objects in the place with a matching name prefix.
 *
 * @param place The place to look its objects at.
 * @param name_prefix Look at objects with names beginning with this value.
 * @param state_cb Function to call for each object found.
 * @param state_cb_cls Closure for callback function.
 *
 * @return Handle that can be used to stop looking at objects.
 */
struct GNUNET_SOCIAL_LookHandle *
GNUNET_SOCIAL_place_look (struct GNUNET_SOCIAL_Place *place,
                          const char *name_prefix,
                          GNUNET_PSYC_StateCallback state_cb,
                          void *state_cb_cls)
{
  return NULL;
}


/**
 * Stop looking at objects.
 *
 * @param lh Look handle to stop.
 */
void
GNUNET_SOCIAL_place_look_cancel (struct GNUNET_SOCIAL_LookHandle *lh)
{

}



/**
 * Look at a particular object in the place.
 *
 * The best matching object is returned (its name might be less specific than
 * what was requested).
 *
 * @param place The place to look the object at.
 * @param full_name Full name of the object.
 * @param value_size Set to the size of the returned value.
 * @return NULL if there is no such object at this place.
 */
const void *
GNUNET_SOCIAL_place_look_at (struct GNUNET_SOCIAL_Place *place,
                             const char *full_name,
                             size_t *value_size)
{
  return NULL;
}


/**
 * Talk to the host of the place.
 *
 * @param place Place where we want to talk to the host.
 * @param method_name Method to invoke on the host.
 * @param env Environment containing variables for the message, or NULL.
 * @param notify Function to use to get the payload for the method.
 * @param notify_cls Closure for @a notify.
 * @param flags Flags for the message being sent.
 * @return NULL if we are already trying to talk to the host,
 *         otherwise handle to cancel the request.
 */
struct GNUNET_SOCIAL_TalkRequest *
GNUNET_SOCIAL_place_talk (struct GNUNET_SOCIAL_Place *place,
                          const char *method_name,
                          const struct GNUNET_ENV_Environment *env,
                          GNUNET_CONNECTION_TransmitReadyNotify notify,
                          void *notify_cls,
                          enum GNUNET_SOCIAL_TalkFlags flags)
{
  return NULL;
}


/**
 * Cancel talking to the host of the place.
 *
 * @param tr Talk request to cancel.
 */
void
GNUNET_SOCIAL_place_talk_cancel (struct GNUNET_SOCIAL_TalkRequest *tr)
{

}


/**
 * Learn about the history of a place.
 *
 * Sends messages through the slicer function of the place where
 * start_message_id <= message_id <= end_message_id.
 * The messages will have the #GNUNET_PSYC_MESSAGE_HISTORIC flag set.
 *
 * To get the latest message, use 0 for both the start and end message ID.
 *
 * @param place Place we want to learn more about.
 * @param start_message_id First historic message we are interested in.
 * @param end_message_id Last historic message we are interested in (inclusive).
 * @param slicer Slicer to use to process history.  Can be the same as the
 *               slicer of the place, as the HISTORIC flag allows distinguishing
 *               old messages from fresh ones.
 * @param finish_cb Function called after the last message in the history lesson
 *              is passed through the @a slicer. NULL if not needed.
 * @param finish_cb_cls Closure for @a finish_cb.
 * @return Handle to abort history lesson, never NULL (multiple lessons
 *         at the same time are allowed).
 */
struct GNUNET_SOCIAL_HistoryLesson *
GNUNET_SOCIAL_place_get_history (struct GNUNET_SOCIAL_Place *place,
                                 uint64_t start_message_id,
                                 uint64_t end_message_id,
                                 const struct GNUNET_SOCIAL_Slicer *slicer,
                                 void (*finish_cb)(void *),
                                 void *finish_cb_cls)
{
  return NULL;
}


/**
 * Stop processing messages from the history lesson.
 *
 * Must not be called after the finish callback of the history lesson is called.
 *
 * @param hist History lesson to cancel.
 */
void
GNUNET_SOCIAL_place_get_history_cancel (struct GNUNET_SOCIAL_HistoryLesson *hist)
{

}


/**
 * Leave a place permanently.
 *
 * Notifies the owner of the place about leaving, and destroys the place handle.
 *
 * @param place Place to leave permanently.
 * @param keep_active Keep place active after last application disconnected.
 */
void
GNUNET_SOCIAL_place_leave (struct GNUNET_SOCIAL_Place *place, int keep_active)
{

}