[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[GNUnet-SVN] r27430 - gnunet/src/include
From: |
gnunet |
Subject: |
[GNUnet-SVN] r27430 - gnunet/src/include |
Date: |
Wed, 12 Jun 2013 21:47:04 +0200 |
Author: grothoff
Date: 2013-06-12 21:47:04 +0200 (Wed, 12 Jun 2013)
New Revision: 27430
Modified:
gnunet/src/include/gnunet_gns_service.h
gnunet/src/include/gnunet_social_service.h
Log:
first design for social service API
Modified: gnunet/src/include/gnunet_gns_service.h
===================================================================
--- gnunet/src/include/gnunet_gns_service.h 2013-06-12 17:38:58 UTC (rev
27429)
+++ gnunet/src/include/gnunet_gns_service.h 2013-06-12 19:47:04 UTC (rev
27430)
@@ -329,7 +329,7 @@
*/
struct GNUNET_GNS_GetAuthRequest*
GNUNET_GNS_get_authority (struct GNUNET_GNS_Handle *handle,
- const char * name,
+ const char *name,
GNUNET_GNS_GetAuthResultProcessor proc,
void *proc_cls);
Modified: gnunet/src/include/gnunet_social_service.h
===================================================================
--- gnunet/src/include/gnunet_social_service.h 2013-06-12 17:38:58 UTC (rev
27429)
+++ gnunet/src/include/gnunet_social_service.h 2013-06-12 19:47:04 UTC (rev
27430)
@@ -22,6 +22,7 @@
* @file include/gnunet_social_service.h
* @brief Social service; implements social functionality using the PSYC
service
* @author tg
+ * @author Christian Grothoff
*/
#ifndef GNUNET_SOCIAL_SERVICE_H
#define GNUNET_SOCIAL_SERVICE_H
@@ -36,23 +37,505 @@
#include "gnunet_util_lib.h"
#include "gnunet_psyc_service.h"
+#include "gnunet_multicast_service.h"
+
/**
* Version number of GNUnet Social API.
*/
#define GNUNET_SOCIAL_VERSION 0x00000000
+
/**
- * Handle for a social channel
+ * Handle for a place where social interactions happen.
*/
-struct GNUNET_SOCIAL_Channel;
+struct GNUNET_SOCIAL_Place;
/**
- * Handle for a social client
+ * Handle for a place that one of our egos hosts.
*/
-struct GNUNET_SOCIAL_Client;
+struct GNUNET_SOCIAL_Home;
+/**
+ * Handle for our own presence in the network (we can of course have
+ * alter-egos).
+ */
+struct GNUNET_SOCIAL_Ego;
+/**
+ * Handle for another user (who is likely pseudonymous) in the network.
+ */
+struct GNUNET_SOCIAL_Nym;
+
+/**
+ * Handle to an implementation of try-and-slice.
+ */
+struct GNUNET_SOCIAL_Slicer;
+
+
+/**
+ * Method called from SOCIAL upon receiving a message indicating a call
+ * to a 'method'.
+ *
+ * @param cls closure
+ * @param full_method_name original method name from PSYC (may be more
+ * specific than the registered method name due to try-and-slice
matching)
+ * @param message_id unique message counter for this message;
+ * (unique only in combination with the given sender for
+ * this channel)
+ * @param data_off byte offset of 'data' in the overall data of the method
+ * @param data_size number of bytes in 'data';
+ * @param data data stream given to the method (might not be zero-terminated
+ * if data is binary)
+ * @param frag fragmentation status for the data
+ */
+typedef int (*GNUNET_SOCIAL_Method)(void *cls,
+ const char *full_method_name,
+ uint64_t message_id,
+ uint64_t data_off,
+ size_t data_size,
+ const void *data,
+ enum GNUNET_PSYC_FragmentStatus frag);
+
+
+/**
+ * Create a try-and-slice instance.
+ *
+ * @return try-and-slice construct
+ */
+struct GNUNET_SOCIAL_Slicer *
+GNUNET_SOCIAL_slicer_create (void);
+
+
+/**
+ * Add a method to the try-and-slice instance.
+ *
+ * @param slicer 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);
+
+
+/**
+ * Destroy a given try-and-slice instance.
+ *
+ * @param slicer slicer to destroy
+ */
+void
+GNUNET_SOCIAL_slicer_destroy (struct GNUNET_SOCIAL_Slicer *slicer);
+
+
+/**
+ * Create an ego using the private key from the given
+ * file. If the file does not exist, a fresh key is
+ * created.
+ *
+ * @param keyfile name of the file with the private key for the ego,
+ * NULL for ephemeral egos
+ * @return handle to the ego, NULL on error
+ */
+struct GNUNET_SOCIAL_Ego *
+GNUNET_SOCIAL_ego_create (const char *keyfile);
+
+
+/**
+ * Destroy a handle to an ego.
+ *
+ * @param ego ego to destroy
+ */
+void
+GNUNET_SOCIAL_ego_destroy (struct GNUNET_SOCIAL_Ego *ego);
+
+
+/**
+ * Function called asking for nym to be admitted to the room. Should
+ * call either 'GNUNET_SOCIAL_home_admit' or
+ * 'GNUNET_SOCIAL_home_reject_entry' (possibly asynchronously). The
+ * 'nym' reference remains valid until the
+ * 'GNUNET_SOCIAL_FarewellCallback' is invoked for it.
+ *
+ * @param cls closure
+ * @param nym handle for the user who wants to join
+ * @param join_msg_size number of bytes in 'join_msg'
+ * @param join_msg payload given on join
+ */
+typedef void (*GNUNET_SOCIAL_AnswerDoorCallback)(void *cls,
+ struct GNUNET_SOCIAL_Nym *nym,
+ size_t join_msg_size,
+ const void *join_msg);
+
+
+/**
+ * Function called when a 'nym' leaves the room. This is
+ * also called if the 'nym' was never given permission to
+ * enter (i.e. the 'nym' stopped asking to get in).
+ *
+ * @param cls closure
+ * @param nym handle for the user who left
+ */
+typedef void (*GNUNET_SOCIAL_FarewellCallback)(void *cls,
+ struct GNUNET_SOCIAL_Nym *nym);
+
+
+/**
+ * Create a new home to host guests (nyms).
+ *
+ * @param cfg configuration to contact the social service
+ * @param home_keyfile file with the private key for the home,
+ * created if the file does not exist;
+ * pass NULL for ephemeral homes
+ * @param join_policy what is our policy for allowing people in?
+ * @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 join
+ * @param farewell_cb function to handle departing nyms
+ * @param cls closure for 'listener_cb' and 'farewell_cb'
+ * @return handle for a new home
+ */
+struct GNUNET_SOCIAL_Home *
+GNUNET_SOCIAL_home_create (const struct GNUNET_CONFIGURATION_Handle *cfg,
+ const char *home_keyfile,
+ enum GNUNET_MULTICAST_JoinPolicy join_policy,
+ struct GNUNET_SOCIAL_Ego *ego,
+ struct GNUNET_SOCIAL_Slicer *slicer,
+ GNUNET_SOCIAL_AnswerDoorCallback listener_cb,
+ GNUNET_SOCIAL_FarewellCallback farewell_cb,
+ void *cls);
+
+
+/**
+ * Admit 'nym' to the 'home'. 'nym' will remain valid until either
+ * the home is destroyed or 'nym' leaves.
+ *
+ * @param home home to allow 'nym' to join
+ * @param nym handle for the entity that wants to join
+ */
+void
+GNUNET_SOCIAL_home_admit (struct GNUNET_SOCIAL_Home *home,
+ struct GNUNET_SOCIAL_Nym *nym);
+
+
+/**
+ * Throw 'nym' out of the 'home'. 'nym' will remain valid
+ * until the 'GNUNET_SOCIAL_FarewellCallback' is invoked, which
+ * should be very soon after this call.
+ *
+ * @param home home to allow 'nym' to join
+ * @param nym handle for the entity that wants to join
+ */
+void
+GNUNET_SOCIAL_home_evict (struct GNUNET_SOCIAL_Home *home,
+ struct GNUNET_SOCIAL_Nym *nym);
+
+
+/**
+ * Refuse 'nym' entry into the 'home'.
+ *
+ * @param home home to disallow 'nym' to join
+ * @param nym handle for the entity that wanted to join
+ */
+void
+GNUNET_SOCIAL_home_reject_entry (struct GNUNET_SOCIAL_Home *home,
+ struct GNUNET_SOCIAL_Nym *nym);
+
+
+/**
+ * Get the identity of a user (suitable, for example, to be used
+ * with 'GNUNET_NAMESTORE_zone_to_name').
+ *
+ * @param nym pseydonym to map to a cryptographic identifier
+ * @param identity set to the identity of the nym (short hash of the public
key)
+ */
+void
+GNUNET_SOCIAL_nym_get_identity (struct GNUNET_SOCIAL_Nym *nym,
+ struct GNUNET_CRYPTO_ShortHashCode *identity);
+
+
+/**
+ * Obtain the (cryptographic, binary) address for the home.
+ *
+ * @param home home to get the (public) address from
+ * @param crypto_address address suitable for storing in GADS,
+ * i.e. in 'HEX.place' or within the respective GADS record type
("PLACE")
+ */
+void
+GNUNET_SOCIAL_home_get_address (struct GNUNET_SOCIAL_Home *home,
+ struct GNUNET_HashCode *crypto_address);
+
+
+/**
+ * (re)decorate the home by changing objects in it. If
+ * the operation is 'GNUNET_PSYC_SOT_SET_VARIABLE' then
+ * the decoration only applies to the next announcement
+ * by the home owner.
+ *
+ * @param home the home to decorate
+ * @param operation operation to perform on the object
+ * @param object_name name of the object to modify
+ * @param object_value_size size of the given 'object_value'
+ * @param object_value value to use for the modification
+ */
+void
+GNUNET_SOCIAL_home_decorate (struct GNUNET_SOCIAL_Home *home,
+ enum GNUNET_PSYC_Operator operation,
+ const char *object_name,
+ size_t object_value_size,
+ const void *object_value);
+
+
+/**
+ * Handle for an announcement request.
+ */
+struct GNUNET_SOCIAL_Announcement;
+
+
+/**
+ * This function allows the home owner to send a message to all
+ * nyms that are present in the home.
+ *
+ * @param home home to address the announcement to
+ * @param full_method_name method to use for the announcement
+ * @param notify function to call to get the payload of the announcement
+ * @param notify_cls closure for 'notify'
+ * @return NULL on error (announcement already in progress?)
+ */
+struct GNUNET_SOCIAL_Announcement *
+GNUNET_SOCIAL_place_announce (struct GNUNET_SOCIAL_Home *home,
+ const char *full_method_name,
+ GNUNET_PSYC_OriginReadyNotify notify,
+ void *notify_cls);
+
+
+/**
+ * Cancel announcement.
+ *
+ * @param a the announcement to cancel
+ */
+void
+GNUNET_SOCIAL_place_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 'home' is valid;
+ * do NOT try to 'GNUNET_SOCIAL_place_leave' this place, it's your
home!
+ */
+struct GNUNET_SOCIAL_Place *
+GNUNET_SOCIAL_home_to_place (struct GNUNET_SOCIAL_Home *home);
+
+
+/**
+ * Leave a home, visitors can stay.
+ *
+ * @param home home to leave (handle becomes invalid).
+ */
+void
+GNUNET_SOCIAL_home_leave (struct GNUNET_SOCIAL_Home *home);
+
+
+/**
+ * Destroy a home, all guests will be evicted.
+ *
+ * @param home home to destroy
+ */
+void
+GNUNET_SOCIAL_home_destroy (struct GNUNET_SOCIAL_Home *home);
+
+
+/**
+ * Join a place (home hosted by someone else).
+ *
+ * @param cfg configuration to contact the social service
+ * @param ego owner of the home (host)
+ * @param address address of the place to join (GADS name, i.e.
'room.friend.gads'),
+ * if the name has the form 'HEX.place', GADS is not
+ * used and HEX is assumed to be the hash of the public
+ * key already; 'HEX.zkey' however would refer to
+ * the 'PLACE' record in the GADS zone with the public key
+ * 'HEX'.
+ * @param join_msg_size number of bytes in 'join_msg'
+ * @param join_msg message to give to the join callback
+ * @return NULL on errors, otherwise handle to the place
+ */
+struct GNUNET_SOCIAL_Place *
+GNUNET_SOCIAL_place_join (const struct GNUNET_CONFIGURATION_Handle *cfg,
+ struct GNUNET_SOCIAL_Ego *ego,
+ const char *address,
+ struct GNUNET_SOCIAL_Slicer *slicer,
+ size_t join_msg_size,
+ const void *join_msg);
+
+
+/**
+ *
+ */
+struct GNUNET_SOCIAL_WatchHandle;
+
+/**
+ *
+ *
+ * @param
+ * @param
+ * @param
+ * @param
+ */
+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);
+
+
+/**
+ *
+ *
+ * @param
+ */
+void
+GNUNET_SOCIAL_place_watch_cancel (struct GNUNET_SOCIAL_WatchHandle *wh);
+
+
+/**
+ *
+ */
+struct GNUNET_SOCIAL_LookHandle;
+
+/**
+ * Look at all objects in the place.
+ *
+ */
+struct GNUNET_SOCIAL_LookHandle *
+GNUNET_SOCIAL_place_look (struct GNUNET_SOCIAL_Place *place,
+ GNUNET_PSYC_StateCallback state_cb,
+ void *state_cb_cls);
+
+
+/**
+ * Look at matching objects in the place.
+ *
+ */
+struct GNUNET_SOCIAL_LookHandle *
+GNUNET_SOCIAL_place_look_for (struct GNUNET_SOCIAL_Place *place,
+ const char *object_filter,
+ GNUNET_PSYC_StateCallback state_cb,
+ void *state_cb_cls);
+
+
+/**
+ *
+ *
+ */
+void
+GNUNET_SOCIAL_place_look_cancel (struct GNUNET_SOCIAL_LookHandle *lh);
+
+
+
+/**
+ * Look at a particular object in the place.
+ *
+ * @param
+ * @param
+ * @param
+ * @return
+ */
+const void *
+GNUNET_SOCIAL_place_look_at (struct GNUNET_SOCIAL_Place *place,
+ const char *object_name,
+ size_t *value_size);
+
+
+/**
+ * Frame the (next) talk by setting some variables for it.
+ *
+ * @param
+ * @param
+ * @param
+ * @param
+ */
+void
+GNUNET_SOCIAL_place_frame_talk (struct GNUNET_SOCIAL_Place *place,
+ const char *variable_name,
+ size_t value_size,
+ const void *value);
+
+
+/**
+ *
+ */
+struct GNUNET_SOCIAL_TalkRequest;
+
+
+/**
+ * Talk to the host of the place.
+ *
+ * @param
+ * @param
+ * @param
+ * @param cb_cls closure for 'cb'
+ * @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,
+ GNUNET_PSYC_OriginReadyNotify cb,
+ void *cb_cls);
+
+
+/**
+ *
+ *
+ * @param
+ */
+void
+GNUNET_SOCIAL_place_talk_cancel (struct GNUNET_SOCIAL_TalkRequest *tr);
+
+
+struct GNUNET_SOCIAL_HistoryLesson;
+
+
+/**
+ *
+ * @param
+ * @param
+ * @param
+ * @param
+ * @return
+ */
+struct GNUNET_SOCIAL_HistoryLesson *
+GNUNET_SOCIAL_place_get_history (struct GNUNET_SOCIAL_Place *place,
+ uint64_t start_message_id,
+ uint64_t end_message_id,
+ struct GNUNET_SOCIAL_Slicer *slicer);
+
+
+/**
+ *
+ *
+ * @param
+ */
+void
+GNUNET_SOCIAL_place_get_history_cancel (struct GNUNET_SOCIAL_HistoryLesson
*hist);
+
+
+/**
+ * Leave a place (destroys the place handle).
+ *
+ * @param place place to leave
+ */
+void
+GNUNET_SOCIAL_place_leave (struct GNUNET_SOCIAL_Place *place);
+
+
+
#if 0 /* keep Emacsens' auto-indent happy */
{
#endif
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [GNUnet-SVN] r27430 - gnunet/src/include,
gnunet <=