path: root/src/include/gnunet_social_service.h

/*
     This file is part of GNUnet.
     Copyright (C) 2013 GNUnet e.V.

     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 of the License,
     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
     Affero General Public License for more details.
*/

/**
 * @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 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.

# Message methods

## _converse

Human conversation in a private or public place.

### Environment

#### _id_reply
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.

FIXME: Are nyms a different data type from egos and person entities?
Do they have a different format than any other entity address?
Questions and thoughts on how to fix this in "questions.org"

#### _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

FIXME: A custom _gns PSYC data type should be avoidable by parsing
and interpreting PSYC uniforms appropriately.
Thoughts on this in "questions.org"

#### Without GNS

##### _key_pub_place
Public key of place

FIXME: _key_pub can't be the data type for GNUnet-specific cryptographic
addressing. Questions and thoughts on how to fix this in "questions.org"

##### _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

#### _type_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 reception at the following location:
$GNUNET_DATA_HOME/social/files/<H(place_pub)>/<H(message_id)>

### Environment

#### _size_file
Size of file

#### _type_file
MIME type of file

#### _name_file
Name of file

#### _description_file
Description of file

@{
*/


#ifndef GNUNET_SOCIAL_SERVICE_H
#define GNUNET_SOCIAL_SERVICE_H

#ifdef __cplusplus
extern "C"
{
#if 0                           /* keep Emacsens' auto-indent happy */
}
#endif
#endif

#include <stdint.h>
#include "gnunet_util_lib.h"
#include "gnunet_psyc_util_lib.h"
#include "gnunet_identity_service.h"
#include "gnunet_namestore_service.h"
#include "gnunet_psyc_service.h"