summaryrefslogtreecommitdiff
path: root/src/include/gnunet_social_service.h
diff options
context:
space:
mode:
authorGabor X Toth <*@tg-x.net>2016-01-11 21:23:17 +0000
committerGabor X Toth <*@tg-x.net>2016-01-11 21:23:17 +0000
commitb23f7bcde58fdada9170f16af39ab1e84f4c3a68 (patch)
tree7b41d9839d854eef7ebd6b93fa161c55221a6577 /src/include/gnunet_social_service.h
parent1e53d26243bc986844a7b5b53bedeefb61dd7960 (diff)
doxygen: group/module definitions (part 1)
Diffstat (limited to 'src/include/gnunet_social_service.h')
-rw-r--r--src/include/gnunet_social_service.h187
1 files changed, 184 insertions, 3 deletions
diff --git a/src/include/gnunet_social_service.h b/src/include/gnunet_social_service.h
index bde3dbceb..c5e55bbab 100644
--- a/src/include/gnunet_social_service.h
+++ b/src/include/gnunet_social_service.h
@@ -19,11 +19,191 @@
*/
/**
- * @file include/gnunet_social_service.h
- * @brief Social service; implements social interactions using the PSYC service.
* @author Gabor X Toth
* @author Christian Grothoff
+ *
+ * @file
+ * Social service; implements social interactions through the PSYC service.
*/
+
+/** @defgroup social Social service
+Social interactions through the PSYC service.
+
+# Overview
+
+The social service provides an API for social interactions based on a one-to-many messaging model.
+It manages subscriptions of applications to places, provides messaging functionality in places,
+allows access to the local message history and manages the GNS zone of _egos_ (user identities).
+
+The service stores private and public keys of subscribed places, as well as files received in subscribed places.
+
+# Concepts and terminology
+
+## Ego, Nym
+
+An _ego_ is an identity of a user, a private-public key pair.
+A _nym_ is an identity of another user in the network, identified by its public key.
+Each user can have multiple identities.
+
+struct GNUNET_SOCIAL_Ego and struct GNUNET_SOCIAL_Nym represents one of these identities.
+
+## Place, Host, Guest
+
+A _place_ is where social interactions happen. It is owned and created by an _ego_.
+Creating a new place happens by an _ego_ entering a new place as a _host_,
+where _guests_ can enter later to receive messages sent to the place.
+
+A place is identified by its public key.
+
+- struct GNUNET_SOCIAL_Host represents a place entered as host,
+- struct GNUNET_SOCIAL_Guest is used for a place entered as guest.
+- A struct GNUNET_SOCIAL_Place can be obtained for both a host and guest place
+ using GNUNET_SOCIAL_host_get_place() and GNUNET_SOCIAL_guest_get_place()
+ and can be used with API functions common to hosts and guests.
+
+## History
+
+Messages sent to places are stored locally by the PSYCstore service, and can be queried any time.
+GNUNET_SOCIAL_history_replay_latest() retrieves the latest N messages sent to the place,
+while GNUNET_SOCIAL_history_replay() is used to query a given message ID range.
+
+## GNU Name System
+
+The GNU Name System is used for assigning human-readable names to nyms and places.
+There's a _GNS zone_ corresponding to each _nym_.
+An _ego_ can publish PKEY and PLACE records in its own zone, pointing to nyms and places, respectively.
+
+## Announcement, talk request
+
+The host can _announce_ messages to the place, using GNUNET_SOCIAL_host_announce().
+Guests can send _talk_ requests to the host, using GNUNET_SOCIAL_guest_talk().
+The host receives talk requests of guests and can _relay_ them to the place,
+or process it using a message handler function.
+
+# Using the API
+
+## Connecting to the service
+
+A client first establishes an _application connection_ to the service using
+GNUNET_SOCIAL_app_connect() providing its _application ID_, then receives the
+public keys of subscribed places and available egos and in response.
+
+## Reconnecting to places
+
+Then the application can reconnect to its subscribed places by establishing
+_place connections_ with GNUNET_SOCIAL_host_enter_reconnect() and
+GNUNET_SOCIAL_guest_enter_reconnect().
+
+## Subscribing to a place
+
+Entering and subscribing a new host or guest place is done using
+GNUNET_SOCIAL_host_enter() and GNUNET_SOCIAL_guest_enter().
+
+## Disconnecting from a place
+
+An application can disconnect from a place while the social service keeps its
+network connection active, using GNUNET_SOCIAL_host_disconnect() and
+GNUNET_SOCIAL_guest_disconnect().
+
+## Leaving a place
+
+To permanently leave a place, see GNUNET_SOCIAL_host_leave() and GNUNET_SOCIAL_guest_leave().
+When leaving a place its network connections are closed and all applications are unsubscribed from the place.
+
+# Methods
+
+## _message
+
+A message sent to the place.
+
+### Environment
+
+#### _id_reply_to
+message ID this message is in reply to.
+
+#### _id_thread
+
+thread ID, the first message ID in the thread.
+
+#### _nym_author__
+nym of the author.
+
+#### _sig_author
+signature of the message body and its variables by the author.
+
+## Data
+
+Message body.
+
+## _notice_place
+
+Notification about a place.
+
+TODO: Applications can decide to auto-subscribe to certain places,
+e.g. files under a given size.
+
+### Environment
+
+#### Using GNS
+
+##### _gns_place
+GNS name of the place in a globally unique .zkey zone
+
+#### Without GNS
+
+##### _key_pub_place
+public key of place
+
+##### _peer_origin
+peer ID of origin
+
+##### _list_peer_relays
+list of peer IDs of relays
+
+## _notice_place_file
+
+Notification about a place hosting a file.
+
+### Environment
+
+The environment of _notice_place above, plus the following:
+
+#### _size_file
+size of file
+
+#### _mime_file
+MIME type of file
+
+#### _name_file
+name of file
+
+#### _description_file
+description of file
+
+## _file
+
+Messages with a _file method contain a file,
+which is saved to disk upon receipt at the following location:
+$GNUNET_DATA_HOME/social/files/<H(place_pub)>/<message_id>
+
+### Environment
+
+#### _size_file
+size of file
+
+#### _mime_file
+MIME type of file
+
+#### _name_file
+name of file
+
+#### _description_file
+description
+
+@{
+*/
+
+
#ifndef GNUNET_SOCIAL_SERVICE_H
#define GNUNET_SOCIAL_SERVICE_H
@@ -371,7 +551,7 @@ typedef void
* Message part, as it arrived from the network.
* @param message_id
* Message ID this data fragment belongs to.
- * @param cancelled.
+ * @param cancelled
* #GNUNET_YES if the message was cancelled,
* #GNUNET_NO if the message is complete.
*/
@@ -1334,6 +1514,7 @@ GNUNET_SOCIAL_zone_add_nym (const struct GNUNET_SOCIAL_App *app,
GNUNET_ResultCallback result_cb,
void *result_cls);
+/** @} */ /* end of group social */
#if 0 /* keep Emacsens' auto-indent happy */
{