*/
/**
- * @file include/block_dns.h
+ * @file
+ * DNS network structs
+ *
* @author Christian Grothoff
*/
#ifndef BLOCK_DNS_H
*/
/**
- * @file include/block_fs.h
- * @brief fs block formats (shared between fs and block)
+ * @file
+ * FS block formats (shared between FS and Block)
+ *
* @author Christian Grothoff
*/
#ifndef BLOCK_FS_H
*/
/**
- * @file include/block_regex.h
- * @brief regex block formats
+ * @file
+ * regex block formats
+ *
* @author Bartlomiej Polot
*/
#ifndef BLOCK_REGEX_H
-/** ---------------------------------------------------------------------------
+/* ---------------------------------------------------------------------------
* This software is in the public domain, furnished "as is", without technical
* support, and with no warranty, express or implied, as to its usefulness for
* any purpose.
*/
/**
- * @file include/gnunet_applications.h
- * @brief constants for network applications operating on top of the CADET service
+ * @file
+ * Constants for network applications operating on top of the CADET service
+ *
* @author Christian Grothoff
*/
*/
/**
- * @file include/gnunet_arm_service.h
- * @brief API to access gnunet-arm
* @author Christian Grothoff
+ *
+ * @file
+ * API to access gnunet-arm
+ *
+ * @defgroup arm ARM service
+ * Automatic Restart Manager
+ * @{
*/
#ifndef GNUNET_ARM_SERVICE_H
void
GNUNET_ARM_monitor_disconnect_and_free (struct GNUNET_ARM_MonitorHandle *h);
+/** @} */ /* end of group */
#if 0 /* keep Emacsens' auto-indent happy */
{
*/
/**
- * @file include/gnunet_ats_plugin.h
- * @brief API for the ATS solvers. This header
- * specifies the struct that is given to the plugin's entry
- * method and the other struct that must be returned.
- * Note that the destructors of ATS plugins will
- * be given the value returned by the constructor
- * and is expected to return a NULL pointer.
* @author Christian Grothoff
+ *
+ * @file
+ * API for the ATS solvers.
+ *
+ * @defgroup ats-plugin ATS service plugin API
+ * Plugin API for the ATS service.
+ *
+ * Specifies the struct that is given to the plugin's entry method and the other
+ * struct that must be returned. Note that the destructors of ATS plugins will
+ * be given the value returned by the constructor and is expected to return a
+ * NULL pointer.
+ *
+ * @{
*/
#ifndef PLUGIN_ATS_H
#define PLUGIN_ATS_H
unsigned long long in_quota[GNUNET_ATS_NetworkTypeCount];
};
+/** @} */ /* end of group */
+
#endif
Boston, MA 02110-1301, USA.
*/
/**
- * @file include/gnunet_ats_service.h
- * @brief automatic transport selection and outbound bandwidth determination
+ * @file
+ * Automatic transport selection and outbound bandwidth determination
+ *
* @author Christian Grothoff
* @author Matthias Wachs
+ *
+ * @defgroup ats ATS service
+ * Automatic transport selection and outbound bandwidth determination
+ * @{
*/
#ifndef GNUNET_ATS_SERVICE_H
#define GNUNET_ATS_SERVICE_H
const struct GNUNET_TIME_Relative scope,
...);
+/** @} */ /* end of group */
+
#endif
/* end of file gnunet-service-transport_ats.h */
*/
/**
- * @file include/gnunet_bandwidth_lib.h
- * @brief functions related to bandwidth (unit)
* @author Christian Grothoff
+ *
+ * @file
+ * Functions related to bandwidth (unit)
+ *
+ * @defgroup bandwidth Bandwidth library
+ * Functions related to bandwidth (unit)
+ * @{
*/
#ifndef GNUNET_BANDWIDTH_LIB_H
}
#endif
+/** @} */ /* end of group */
+
/* ifndef GNUNET_BANDWIDTH_LIB_H */
#endif
/* end of gnunet_bandwidth_lib.h */
*/
/**
- * @file include/gnunet_bio_lib.h
- * @brief buffered IO API
* @author Christian Grothoff
- * @defgroup bio Buffered binary disk IO (with endianess conversion)
+ *
+ * @file
+ * Buffered IO library
+ *
+ * @defgroup bio BIO library
+ * Buffered binary disk IO (with endianess conversion)
* @{
*/
*/
/**
- * @file include/gnunet_block_lib.h
- * @brief library for data block manipulation
* @author Christian Grothoff
+ *
+ * @file
+ * Library for data block manipulation
+ *
+ * @defgroup block Block library
+ * Library for data block manipulation
+ * @{
*/
#ifndef GNUNET_BLOCK_LIB_H
#define GNUNET_BLOCK_LIB_H
}
#endif
+/** @} */ /* end of group */
+
/* ifndef GNUNET_BLOCK_LIB_H */
#endif
*/
/**
- * @file include/gnunet_block_plugin.h
- * @brief API for block plugins. Each block plugin must conform to
- * the API specified by this header.
* @author Christian Grothoff
- * @defgroup block API to be implemented by applications storing data in the DHT
+ *
+ * @file
+ * API for block plugins. Each block plugin must conform to the API specified by this header.
+ *
+ * @defgroup block-plugin Block plugin API
+ * To be implemented by applications storing data in the DHT.
+ *
+ * Each block plugin must conform to the API specified by this header.
+ *
* @{
*/
+
#ifndef PLUGIN_BLOCK_H
#define PLUGIN_BLOCK_H
Boston, MA 02110-1301, USA.
*/
/**
- * @file include/gnunet_cadet_service.h
- * @brief cadet service; establish channels to distant peers
* @author Christian Grothoff
* @author Bart Polot
+ *
+ * @file
+ * CADET service; establish channels to distant peers
+ *
+ * @defgroup cadet CADET service
+ * Confidential Ad-hoc Decentralized End-to-End Transport
+ *
+ * See also:
+ * - [CADET documentation](https://gnunet.org/cadet-subsystem)
+ * - [CADET paper](https://gnunet.org/cadet)
+ *
+ * @{
*/
#ifndef GNUNET_CADET_SERVICE_H
#define GNUNET_CADET_SERVICE_H
}
#endif
+/** @} */ /* end of group */
+
/* ifndef GNUNET_CADET_SERVICE_H */
#endif
/* end of gnunet_cadet_service.h */
*/
/**
- * @file include/gnunet_client_lib.h
- * @brief functions related to accessing services
* @author Christian Grothoff
- * @defgroup client Generic client-side communication with services
+ *
+ * @file
+ * Functions related to accessing services
+
+ * @defgroup client Client library
+ * Generic client-side communication with services
* @{
*/
*/
/**
- * @file include/gnunet_client_manager_lib.h
- * @brief Client manager; higher level client API with transmission queue
- * and message handler registration.
* @author Gabor X Toth
- * @defgroup client_manager Higher level client-side communication with services.
+ *
+ * @file
+ * Client manager; higher level client API with transmission queue
+ * and message handler registration.
+ *
+ * @defgroup client-manager Client manager library
+ * Higher level client-side communication with services.
+ *
+ * Provides a higher level client API
+ * with transmission queue and message handler registration.
* @{
*/
#ifndef GNUNET_CLIENT_MANAGER_LIB_H
}
#endif
-/** @} */ /* end of group client_manager */
+/** @} */ /* end of group */
/* ifndef GNUNET_CLIENT_MANAGER_LIB_H */
#endif
*/
/**
- * @file include/gnunet_configuration_lib.h
- * @brief configuration API
* @author Christian Grothoff
- * @defgroup configuration Configuration management
+ *
+ * @file
+ * Configuration API
+ *
+ * @defgroup configuration Configuration library
+ * Configuration management
* @{
*/
#ifndef GNUNET_CONFIGURATION_LIB_H
*/
/**
- * @file include/gnunet_connection_lib.h
- * @brief basic, low-level TCP networking interface
* @author Christian Grothoff
+ *
+ * @file include/gnunet_connection_lib.h
+ * Basic, low-level TCP networking interface
+ *
+ * @defgroup connection Connection library
+ * Basic, low-level TCP networking interface
+ * @{
*/
#ifndef GNUNET_CONNECTION_LIB_H
#define GNUNET_CONNECTION_LIB_H
/**
- * Activate proxied connection and destroy initial proxy handshake connection.
+ * Activate proxied connection and destroy initial proxy handshake connection.
* There must not be any pending requests for reading or writing to the
* proxy hadshake connection at this time.
*
}
#endif
+/** @} */ /* end of group */
/* ifndef GNUNET_CONNECTION_LIB_H */
#endif
*/
/**
- * @file include/gnunet_consensus_service.h
- * @brief multi-peer set reconciliation
* @author Florian Dold
+ *
+ * @file
+ * Multi-peer set reconciliation
+ *
+ * @defgroup consensus Consensus service
+ * Multi-peer set reconciliation
+ * @{
*/
#ifndef GNUNET_CONSENSUS_SERVICE_H
void
GNUNET_CONSENSUS_destroy (struct GNUNET_CONSENSUS_Handle *consensus);
+/** @} */ /* end of group */
#if 0 /* keep Emacsens' auto-indent happy */
{
*/
/**
- * @file include/gnunet_constants.h
- * @brief "global" constants for performance tuning
* @author Christian Grothoff
+ *
+ * @file
+ * "Global" constants for performance tuning
*/
#ifndef GNUNET_CONSTANTS_H
*/
/**
- * @file include/gnunet_container_lib.h
- * @brief container classes for GNUnet
* @author Christian Grothoff
* @author Nils Durner
- * @defgroup hashmap multi hash-map
- * @defgroup heap min- or max-heap with arbitrary element removal
- * @defgroup bloomfilter Bloom filter (probabilistic set tests)
- * @defgroup dll Doubly-linked list
- * @defgroup metadata Meta data (GNU libextractor key-value pairs)
+ *
+ * @file
+ * Container classes for GNUnet
+ *
+ * @defgroup hashmap Container library: MultiHashMap
+ * Hash map with multiple values per key.
+ *
+ * @defgroup heap Container library: Heap
+ * Min- or max-heap with arbitrary element removal
+ *
+ * @defgroup bloomfilter Container library: Bloom filter
+ * Probabilistic set tests
+ *
+ * @defgroup dll Container library: Doubly-linked list
+ *
+ * @defgroup metadata Container library: Metadata
+ * GNU libextractor key-value pairs
*/
#ifndef GNUNET_CONTAINER_LIB_H
*/
/**
- * @file include/gnunet_conversation_service.h
- * @brief API to the conversation service
* @author Simon Dieterle
* @author Andreas Fuchs
* @author Christian Grothoff
*
+ * @file
+ * API to the conversation service
+ *
+ * @defgroup conversation Conversation service
+ * One-to-one voice communication over CADET
*
* NOTE: This API is deliberately deceptively simple; the idea
* is that advanced features (such as answering machines) will
* course provided as part of the basic implementation, as only the
* CONVERSATION service can know for sure who it is that we are
* talking to.
+ *
+ * @{
*/
#ifndef GNUNET_CONVERSATION_SERVICE_H
#define GNUNET_CONVERSATION_SERVICE_H
void
GNUNET_CONVERSATION_call_stop (struct GNUNET_CONVERSATION_Call *call);
+/** @} */ /* end of group */
#if 0 /* keep Emacsens' auto-indent happy */
{
Boston, MA 02110-1301, USA.
*/
/**
- * @file include/gnunet_core_service.h
- * @brief core service; this is the main API for encrypted P2P
- * communications
* @author Christian Grothoff
- * @defgroup core encrypted direct communication between peers
+ *
+ * @file include/gnunet_core_service.h
+ * Core service; the main API for encrypted P2P communications
+ *
+ * @defgroup core Core service
+ * Encrypted direct communication between peers
* @{
*/
#ifndef GNUNET_CORE_SERVICE_H
* @author Ioana Patrascu
* @author Tzvetan Horozov
*
- * @defgroup crypto Cryptographic operations
- * @defgroup hash Hashing and operations on hashes
+ * @defgroup crypto Crypto library: cryptographic operations
+ *
+ * @defgroup hash Crypto library: hash operations
+ * Hashing and operations on hashes
*/
#ifndef GNUNET_CRYPTO_LIB_H
*/
/**
- * @file include/gnunet_datacache_lib.h
- * @brief datacache is a simple, transient hash table
- * of bounded size with content expiration.
- * In contrast to the sqstore there is
- * no prioritization, deletion or iteration.
- * All of the data is discarded when the peer shuts down!
* @author Christian Grothoff
+ *
+ * @file
+ * datacache API
+ *
+ * @defgroup datacache Datacache library
+ * Simple, transient hash table of bounded size with content expiration.
+ *
+ * In contrast to the sqstore there is
+ * no prioritization, deletion or iteration.
+ * All of the data is discarded when the peer shuts down!
+ *
+ * @{
*/
#ifndef GNUNET_DATACACHE_LIB_H
GNUNET_DATACACHE_Iterator iter,
void *iter_cls);
+/** @} */ /* end of group */
#if 0 /* keep Emacsens' auto-indent happy */
{
*/
/**
- * @file include/gnunet_datacache_plugin.h
- * @brief API for database backends for the datacache
* @author Christian Grothoff
+ *
+ * @file
+ * API for database backends for the datacache
+ *
+ * @defgroup datacache-plugin Datacache plugin API
+ * API for database backends for the datacache
+ * @{
*/
#ifndef PLUGIN_DATACACHE_H
#define PLUGIN_DATACACHE_H
};
+/** @} */ /* end of group */
#if 0 /* keep Emacsens' auto-indent happy */
{
*/
/**
- * @file include/gnunet_datastore_plugin.h
- * @brief API for the database backend plugins.
* @author Christian Grothoff
+ *
+ * @file
+ * API for the database backend plugins.
+ *
+ * @defgroup datastore-plugin Datastore service plugin API
+ * API for the database backend plugins.
+ * @{
*/
#ifndef PLUGIN_DATASTORE_H
#define PLUGIN_DATASTORE_H
* @param delta change in disk utilization,
* 0 for "reset to empty"
*/
-typedef void
-(*GNUNET_DATASTORE_DiskUtilizationChange) (void *cls,
+typedef void
+(*GNUNET_DATASTORE_DiskUtilizationChange) (void *cls,
int delta);
* @return #GNUNET_OK to keep the item
* #GNUNET_NO to delete the item
*/
-typedef int
-(*PluginDatumProcessor) (void *cls,
+typedef int
+(*PluginDatumProcessor) (void *cls,
const struct GNUNET_HashCode *key,
- uint32_t size,
+ uint32_t size,
const void *data,
enum GNUNET_BLOCK_Type type,
- uint32_t priority,
+ uint32_t priority,
uint32_t anonymity,
struct GNUNET_TIME_Absolute expiration,
uint64_t uid);
* @param status #GNUNET_OK or #GNUNET_SYSERROR
* @param msg error message on error
*/
-typedef void
-(*PluginPutCont) (void *cls,
+typedef void
+(*PluginPutCont) (void *cls,
const struct GNUNET_HashCode *key,
uint32_t size,
- int status,
+ int status,
const char *msg);
* @param cont continuation called with success or failure status
* @param cont_cls continuation closure for @a cont
*/
-typedef void
+typedef void
(*PluginPut) (void *cls, const struct GNUNET_HashCode *key,
uint32_t size,
const void *data,
enum GNUNET_BLOCK_Type type,
- uint32_t priority,
+ uint32_t priority,
uint32_t anonymity,
uint32_t replication,
struct GNUNET_TIME_Absolute expiration,
- PluginPutCont cont,
+ PluginPutCont cont,
void *cont_cls);
* @param key key in the data store, if NULL iteration is finished
* @param count how many values are stored under this key in the datastore
*/
-typedef void
+typedef void
(*PluginKeyProcessor) (void *cls,
const struct GNUNET_HashCode *key,
unsigned int count);
* proc should be called with NULL if there is no result
* @param proc_cls closure for @a proc
*/
-typedef void
-(*PluginGetKey) (void *cls,
+typedef void
+(*PluginGetKey) (void *cls,
uint64_t offset,
const struct GNUNET_HashCode *key,
const struct GNUNET_HashCode *vhash,
* @param proc function to call the value (once only).
* @param proc_cls closure for @a proc
*/
-typedef void
-(*PluginGetRandom) (void *cls,
+typedef void
+(*PluginGetRandom) (void *cls,
PluginDatumProcessor proc,
void *proc_cls);
* @param status #GNUNET_OK or #GNUNET_SYSERROR
* @param msg error message on error
*/
-typedef void
-(*PluginUpdateCont) (void *cls,
+typedef void
+(*PluginUpdateCont) (void *cls,
int status,
const char *msg);
* @param cont continuation called with success or failure status
* @param cons_cls continuation closure
*/
-typedef void
+typedef void
(*PluginUpdate) (void *cls,
uint64_t uid,
int delta,
struct GNUNET_TIME_Absolute expire,
- PluginUpdateCont cont,
+ PluginUpdateCont cont,
void *cont_cls);
* @param proc function to call on the matching value
* @param proc_cls closure for @a proc
*/
-typedef void
+typedef void
(*PluginGetType) (void *cls,
uint64_t offset,
enum GNUNET_BLOCK_Type type,
*
* @param cls closure
*/
-typedef void
+typedef void
(*PluginDrop) (void *cls);
};
+/** @} */ /* end of group */
#endif
*/
/**
- * @file include/gnunet_datastore_service.h
- * @brief API that can be used manage the
- * datastore for files stored on a GNUnet node;
- * note that the datastore is NOT responsible for
- * on-demand encoding, that is achieved using
- * a special kind of entry.
* @author Christian Grothoff
+ *
+ * @file
+ * datastore service
+ *
+ * @defgroup datastore Datastore service
+ * Data store for files stored on a GNUnet node.
+ *
+ * Provides an API that can be used manage the
+ * datastore for files stored on a GNUnet node.
+ * Note that the datastore is NOT responsible for
+ * on-demand encoding, that is achieved using
+ * a special kind of entry.
+ *
+ * @{
*/
#ifndef GNUNET_DATASTORE_SERVICE_H
void
GNUNET_DATASTORE_cancel (struct GNUNET_DATASTORE_QueueEntry *qe);
+/** @} */ /* end of group */
#if 0 /* keep Emacsens' auto-indent happy */
{
*/
/**
- * @file include/gnunet_dht_service.h
- * @brief API to the DHT service
* @author Christian Grothoff
- * @defgroup dht Distributed Hash Table
+ *
+ * @file
+ * API to the DHT service
+ *
+ * @defgroup dht DHT service
+ * Distributed Hash Table
* @{
*/
FIXME: perhaps make this an enum of known malicious behaviors?
*/
struct GNUNET_DHT_ActMaliciousHandle *
-GNUNET_DHT_act_malicious (struct GNUNET_DHT_Handle *handle,
- unsigned int action,
+GNUNET_DHT_act_malicious (struct GNUNET_DHT_Handle *handle,
+ unsigned int action,
GNUNET_DHT_PutContinuation cont,
void *cont_cls);
#endif
Boston, MA 02110-1301, USA.
*/
/**
- * @file include/gnunet_disk_lib.h
- * @brief disk IO apis
* @author Christian Grothoff
+ *
+ * @file
+ * Disk IO APIs
+ *
+ * @defgroup disk Disk library
+ * Disk IO APIs
+ * @{
*/
#ifndef GNUNET_DISK_LIB_H
#define GNUNET_DISK_LIB_H
}
#endif
+/** @} */ /* end of group */
/* ifndef GNUNET_DISK_LIB_H */
#endif
*/
/**
- * @file include/gnunet_dns_service.h
- * @brief API to access the DNS service.
* @author Christian Grothoff
+ *
+ * @file
+ * API to access the DNS service.
+ *
+ * @defgroup dns DNS service
+ * @{
*/
#ifndef GNUNET_DNS_SERVICE_H
#define GNUNET_DNS_SERVICE_H
* @param reply reply data
*/
void
-GNUNET_DNS_request_answer (struct GNUNET_DNS_RequestHandle *rh,
+GNUNET_DNS_request_answer (struct GNUNET_DNS_RequestHandle *rh,
uint16_t reply_length,
const char *reply);
void
GNUNET_DNS_disconnect (struct GNUNET_DNS_Handle *dh);
+/** @} */ /* end of group */
+
#endif
*/
/**
- * @file include/gnunet_dnsparser_lib.h
- * @brief API for helper library to parse DNS packets.
* @author Philipp Toelke
* @author Christian Grothoff
+ *
+ * @file
+ * API for helper library to parse DNS packets.
+ *
+ * @defgroup dns-parser DNS parser library
+ * Helper library to parse DNS packets.
+ * @{
*/
#ifndef GNUNET_DNSPARSER_LIB_H
#define GNUNET_DNSPARSER_LIB_H
GNUNET_DNSPARSER_hex_to_bin (const char *hex,
void *data);
+/** @} */ /* end of group */
#endif
*/
/**
- * @file include/gnunet_dnsstub_lib.h
- * @brief API for helper library to send DNS requests to DNS resolver
* @author Christian Grothoff
+ *
+ * @file
+ * API for helper library to send DNS requests to DNS resolver
+ *
+ * @defgroup dns-stub DNS stub library
+ * Helper library to send DNS requests to DNS resolver
+ * @{
*/
#ifndef GNUNET_DNSSTUB_LIB_H
#define GNUNET_DNSSTUB_LIB_H
void
GNUNET_DNSSTUB_resolve_cancel (struct GNUNET_DNSSTUB_RequestSocket *rs);
+/** @} */ /* end of group */
+
#endif
/**
* @author Christian Grothoff
- * @file include/gnunet_dv_service.h
- * @brief DV service API (should only be used by the DV plugin)
+ *
+ * @file
+ * DV service API (should only be used by the DV plugin)
+ *
+ * @defgroup dv DV service
+ * Distance vector routing
+ *
+ * The DV service API should only be used by the DV plugin.
+ * @{
*/
#ifndef GNUNET_SERVICE_DV_H
#define GNUNET_SERVICE_DV_H
void
GNUNET_DV_send_cancel (struct GNUNET_DV_TransmitHandle *th);
+/** @} */ /* end of group */
#endif
*/
/**
- * @file include/gnunet_env_lib.h
- * @brief Library providing operations for the @e environment of
- * PSYC and Social messages, and for (de)serializing variable values.
* @author Gabor X Toth
+ *
+ * @file
+ * Environment library
+ *
+ * @defgroup env Environment library
+ * Environment data structure for PSYC and Social messages.
+ *
+ * Library providing operations for the @e environment of
+ * PSYC and Social messages, and for (de)serializing variable values.
+ *
+ * @{
*/
}
#endif
+/** @} */ /* end of group */
+
/* ifndef GNUNET_ENV_LIB_H */
#endif
/* end of gnunet_env_lib.h */
Boston, MA 02110-1301, USA.
*/
/**
- * @file include/gnunet_fragmentation_lib.h
- * @brief library to help fragment messages
* @author Christian Grothoff
*
- * TODO: consider additional flow-control for sending from
+ * @file
+ * Library to help fragment messages
+ *
+ * @defgroup fragmentation Fragmentation library
+ * Library to help fragment messages
+ * @{
+ *
+ * @todo Consider additional flow-control for sending from
* fragmentation based on continuations.
*/
const struct GNUNET_MessageHeader *msg);
+/** @} */ /* end of group */
+
#if 0 /* keep Emacsens' auto-indent happy */
{
#endif
*/
/**
- * @file include/gnunet_friends_lib.h
- * @brief library to read and write the FRIENDS file
* @author Christian Grothoff
+ *
+ * @file
+ * Library to read and write the FRIENDS file
+ *
+ * @defgroup friends Friends library
+ * Library to read and write the FRIENDS file
+ * @{
*/
#ifndef GNUNET_FRIENDS_LIB_H
#define GNUNET_FRIENDS_LIB_H
GNUNET_FRIENDS_write (struct GNUNET_FRIENDS_Writer *w,
const struct GNUNET_PeerIdentity *friend_id);
+/** @} */ /* end of group */
- #if 0 /* keep Emacsens' auto-indent happy */
+#if 0 /* keep Emacsens' auto-indent happy */
{
#endif
#ifdef __cplusplus
Boston, MA 02110-1301, USA.
*/
/**
- * @file include/gnunet_fs_service.h
- * @brief API for file-sharing via GNUnet
* @author Christian Grothoff
+ *
+ * @file
+ * API for file sharing via GNUnet
+ *
+ * @defgroup fs FS service
+ * File sharing
+ * @{
*/
#ifndef GNUNET_FS_LIB_H
#define GNUNET_FS_LIB_H
/**
- * Opaqe handle to an asynchronous directory scanning activity.
+ * Opaque handle to an asynchronous directory scanning activity.
*/
struct GNUNET_FS_DirScanner;
void
GNUNET_FS_share_tree_free (struct GNUNET_FS_ShareTreeItem *toplevel);
+/** @} */ /* end of group */
#if 0 /* keep Emacsens' auto-indent happy */
{
*/
/**
- * @file include/gnunet_getopt_lib.h
- * @brief command line parsing and --help formatting
* @author Christian Grothoff
- * @defgroup getopt command-line parsing
+ *
+ * @file
+ * Command line parsing and --help formatting
+ *
+ * @defgroup getopt Getopt library
+ * Command line parsing and --help formatting
* @{
*/
*/
/**
- * @file include/gnunet_gns_service.h
- * @brief API to the GNS service
* @author Martin Schanzenbach
+ *
+ * @file
+ * API to the GNS service
+ *
+ * @defgroup gns GNS service
+ * GNU Name System
+ * @{
*/
#ifndef GNUNET_GNS_SERVICE_H
#define GNUNET_GNS_SERVICE_H
* Never look in the DHT, keep request to local cache.
*/
GNUNET_GNS_LO_NO_DHT = 1,
-
+
/**
* For the rightmost label, only look in the cache (it
* is our master zone), for the others, the DHT is OK.
void
GNUNET_GNS_lookup_cancel (struct GNUNET_GNS_LookupRequest *lr);
+/** @} */ /* end of group */
#if 0 /* keep Emacsens' auto-indent happy */
{
*/
/**
- * @file include/gnunet_gnsrecord_lib.h
- * @brief API that can be used to manipulate GNS record data
* @author Christian Grothoff
+ *
+ * @file
+ * API that can be used to manipulate GNS record data
+ *
+ * @defgroup gns-record GNS record library
+ * Manipulate GNS record data
+ * @{
*/
#ifndef GNUNET_GNSRECORD_LIB_H
#define GNUNET_GNSRECORD_LIB_H
GNUNET_GNSRECORD_record_get_expiration_time (unsigned int rd_count,
const struct GNUNET_GNSRECORD_Data *rd);
-
+/** @} */ /* end of group */
#if 0 /* keep Emacsens' auto-indent happy */
{
*/
/**
- * @file include/gnunet_gnsrecord_plugin.h
- * @brief plugin API for GNS record types
* @author Christian Grothoff
- * @defgroup gnsrecordplugin API to be implemented by applications defining new GNS record types
- * @{ */
+ *
+ * @file
+ * Plugin API for GNS record types
+ *
+ * @defgroup gns-record-plugin GNS record plugin API
+ * To be implemented by applications defining new record types.
+ * @{
+ */
#ifndef GNUNET_GNSRECORD_PLUGIN_H
#define GNUNET_GNSRECORD_PLUGIN_H
};
-
-/** @} */ /* end of group gnsrecordplugin */
+/** @} */ /* end of group */
#if 0 /* keep Emacsens' auto-indent happy */
{
*/
/**
- * @file include/gnunet_hello_lib.h
- * @brief helper library for handling HELLOs
* @author Christian Grothoff
+ * @file
+ * Helper library for handling HELLOs
+ *
+ * @defgroup hello Hello library
+ * Helper library for handling HELLOs
+ * @{
*/
#ifndef GNUNET_HELLO_LIB_H
struct GNUNET_HELLO_Message **hello,
GNUNET_HELLO_TransportPluginsFind plugins_find);
+/** @} */ /* end of group */
+
#if 0 /* keep Emacsens' auto-indent happy */
{
#endif
*/
/**
- * @file include/gnunet_helper_lib.h
- * @brief API for dealing with (SUID) helper processes that communicate via
- * GNUNET_MessageHeaders on stdin/stdout
* @author Philipp Toelke
* @author Christian Grothoff
+ *
+ * @file
+ * API for dealing with SUID helper processes
+ *
+ * @defgroup helper Helper library
+ * Dealing with SUID helper processes.
+ *
+ * Provides an API for dealing with (SUID) helper processes
+ * that communicate via GNUNET_MessageHeaders on STDIN/STDOUT.
+ *
+ * @{
*/
#ifndef GNUNET_HELPER_LIB_H
void
GNUNET_HELPER_send_cancel (struct GNUNET_HELPER_SendHandle *sh);
+/** @} */ /* end of group */
+
#endif
/* end of include guard: GNUNET_HELPER_LIB_H */
*/
/**
- * @file include/gnunet_identity_provider_service.h
- * @brief Identity provider service; implements identity provider for GNUnet
* @author Martin Schanzenbach
*
- * Egos in GNUnet are ECDSA keys. You assume an ego by using (signing
- * with) a particular private key. As GNUnet users are expected to
- * have many egos, we need an identity service to allow users to
- * manage their egos. The identity service manages the egos (private
- * keys) of the local user; it does NOT manage egos of other users
- * (public keys). For giving names to other users and manage their
- * public keys securely, we use GNS.
+ * @file
+ * Identity provider service; implements identity provider for GNUnet
*
- * @defgroup identity-provider service
+ * @defgroup identity-provider Identity provider service
* @{
*/
#ifndef GNUNET_IDENTITY_PROVIDER_SERVICE_H
*/
/**
- * @file include/gnunet_identity_service.h
- * @brief Identity service; implements identity management for GNUnet
* @author Christian Grothoff
*
+ * @file
+ * Identity service; implements identity management for GNUnet
+ *
+ * @defgroup identity Identity service
+ * Identity management.
+ *
* Egos in GNUnet are ECDSA keys. You assume an ego by using (signing
* with) a particular private key. As GNUnet users are expected to
* have many egos, we need an identity service to allow users to
* (public keys). For giving names to other users and manage their
* public keys securely, we use GNS.
*
- * @defgroup identity identity management service
* @{
*/
#ifndef GNUNET_IDENTITY_SERVICE_H
*/
/**
- * @file include/gnunet_load_lib.h
- * @brief functions related to load calculations
* @author Christian Grothoff
+ *
+ * @file
+ * Functions related to load calculations
+ *
+ * @defgroup load Load library
+ * Load calculations.
+ * @{
*/
#ifndef GNUNET_LOAD_LIB_H
void
GNUNET_LOAD_update (struct GNUNET_LOAD_Value *load, uint64_t data);
+/** @} */ /* end of group */
#if 0 /* keep Emacsens' auto-indent happy */
{
*/
/**
- * @file include/gnunet_microphone_lib.h
- * @brief API to access an audio microphone; provides access to hardware microphones
* @author Simon Dieterle
* @author Andreas Fuchs
* @author Christian Grothoff
+ *
+ * @file
+ * API to access an audio microphone; provides access to hardware microphones
+ *
+ * @defgroup microphone Microphone library
+ * Provides access to hardware microphones.
+ * @{
*/
#ifndef GNUNET_MICROPHONE_SERVICE_H
#define GNUNET_MICROPHONE_SERVICE_H
void
GNUNET_MICROPHONE_destroy (struct GNUNET_MICROPHONE_Handle *microphone);
+/** @} */ /* end of group */
#if 0 /* keep Emacsens' auto-indent happy */
{
/**
* @author Florian Dold
- * @file include/gnunet_mq_lib.h
- * @brief general purpose message queue
- * @defgroup mq general purpose message queue
+ *
+ * @file
+ * General-purpose message queue
+ *
+ * @defgroup mq MQ library
+ * General-purpose message queue
* @{
*/
#ifndef GNUNET_MQ_H
*/
/**
- * @file include/gnunet_multicast_service.h
- * @brief multicast service; establish tunnels to distant peers
- * @author Christian Grothoff
* @author Gabor X Toth
+ * @author Christian Grothoff
+ *
+ * @file
+ * Multicast service; multicast messaging via CADET
+ *
+ * @defgroup multicast Multicast service
+ * Multicast messaging via CADET.
+ * @{
*/
#ifndef GNUNET_MULTICAST_SERVICE_H
void
GNUNET_MULTICAST_member_to_origin_cancel (struct GNUNET_MULTICAST_MemberTransmitHandle *th);
+/** @} */ /* end of group */
#if 0 /* keep Emacsens' auto-indent happy */
{
Boston, MA 02110-1301, USA.
*/
/**
- * @file include/gnunet_mysql_lib.h
- * @brief library to help with access to a MySQL database
* @author Christian Grothoff
+ *
+ * @file
+ * Helper library to access a MySQL database
+ *
+ * @defgroup mysql MySQL library
+ * Helper library to access a MySQL database.
+ * @{
*/
#ifndef GNUNET_MYSQL_LIB_H
#define GNUNET_MYSQL_LIB_H
struct GNUNET_MYSQL_StatementHandle *sh,
unsigned long long *insert_id, ...);
+/** @} */ /* end of group */
#if 0 /* keep Emacsens' auto-indent happy */
{
#define GNUNET_NSE_SERVICE_H_
/**
- * @file include/gnunet_nse_service.h
- * @brief API to retrieve the current network size estimate,
- * also to register for notifications whenever a new
- * network size estimate is calculated.
+ * @file
+ * API to retrieve the current network size estimate,
+ * also to register for notifications whenever a new
+ * network size estimate is calculated.
+ *
* @author Nathan Evans
- * @defgroup nse network size estimation service
+ * @defgroup nse Network size estimation service
* @{
*/
*/
/**
- * @file include/gnunet_os_lib.h
- * @brief low level process routines
+ * @file
+ * Low level process routines
+ *
* @author Christian Grothoff
* @author Krista Bennett
* @author Gerd Knorr <kraxel@bytesex.org>
*/
/**
- * @file include/gnunet_program_lib.h
- * @brief functions related to starting programs
+ * @file
+ * Functions related to starting programs
+ *
* @author Christian Grothoff
- * @defgroup program functions for writing command-line programs
+ * @defgroup program Functions for writing command-line programs
* @{
*/
/** S->C: notify about an existing place */
#define GNUNET_MESSAGE_TYPE_SOCIAL_APP_PLACE 854
+/** S->C: */
+#define GNUNET_MESSAGE_TYPE_SOCIAL_HOST_RELAY 855
+
/*******************************************************************************
* X-VINE DHT messages
******************************************************************************/
*/
/**
- * @file include/gnunet_resolver_service.h
- * @brief functions related to doing DNS lookups
* @author Christian Grothoff
- * @defgroup resolver asynchronous standard DNS lookups
+ *
+ * @file
+ * Functions related to doing DNS lookups
+ *
+ * @defgroup resolver Resolver service
+ * Asynchronous standard DNS lookups
* @{
*/
* @file include/gnunet_revocation_service.h
* @brief API to perform and access key revocations
* @author Christian Grothoff
- * @defgroup revocation key revocation service
+ * @defgroup revocation Key revocation service
* @{
*/
* @file include/gnunet_server_lib.h
* @brief library for building GNUnet network servers
* @author Christian Grothoff
- * @defgroup server functions for a server that communicates with clients
+ * @defgroup server Functions for a server that communicates with clients
* @{
*/
* @file include/gnunet_service_lib.h
* @brief functions related to starting services
* @author Christian Grothoff
- * @defgroup service generic functions for implementing service processes
+ * @defgroup service Generic functions for implementing service processes
* @{
*/
*/
/**
- * @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
* 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.
*/
GNUNET_ResultCallback result_cb,
void *result_cls);
+/** @} */ /* end of group social */
#if 0 /* keep Emacsens' auto-indent happy */
{
* the operation of GNUnet; all statistical values
* must be of type `unsigned long long`.
* @author Christian Grothoff
- * @defgroup statistics track statistics or provide access to statistics
+ * @defgroup statistics Track statistics or provide access to statistics
* @{
*/
projects / oweals / gnunet.git / commitdiff