[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[GNUnet-SVN] r28749 - gnunet/src/include
|
From: |
gnunet |
|
Subject: |
[GNUnet-SVN] r28749 - gnunet/src/include |
|
Date: |
Wed, 21 Aug 2013 17:16:58 +0200 |
Author: grothoff
Date: 2013-08-21 17:16:58 +0200 (Wed, 21 Aug 2013)
New Revision: 28749
Modified:
gnunet/src/include/gnunet_block_plugin.h
gnunet/src/include/gnunet_client_lib.h
gnunet/src/include/gnunet_container_lib.h
gnunet/src/include/gnunet_core_service.h
gnunet/src/include/gnunet_crypto_lib.h
gnunet/src/include/gnunet_dht_service.h
gnunet/src/include/gnunet_disk_lib.h
gnunet/src/include/gnunet_getopt_lib.h
gnunet/src/include/gnunet_identity_service.h
gnunet/src/include/gnunet_mq_lib.h
gnunet/src/include/gnunet_namestore_service.h
gnunet/src/include/gnunet_nse_service.h
gnunet/src/include/gnunet_program_lib.h
gnunet/src/include/gnunet_protocols.h
gnunet/src/include/gnunet_resolver_service.h
gnunet/src/include/gnunet_server_lib.h
gnunet/src/include/gnunet_service_lib.h
gnunet/src/include/gnunet_signal_lib.h
gnunet/src/include/gnunet_statistics_service.h
Log:
-misc doxygen fixes
Modified: gnunet/src/include/gnunet_block_plugin.h
===================================================================
--- gnunet/src/include/gnunet_block_plugin.h 2013-08-21 15:12:08 UTC (rev
28748)
+++ gnunet/src/include/gnunet_block_plugin.h 2013-08-21 15:16:58 UTC (rev
28749)
@@ -1,6 +1,6 @@
/*
This file is part of GNUnet
- (C) 2010 Christian Grothoff (and other contributing authors)
+ (C) 2010,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
@@ -23,18 +23,19 @@
* @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
+ * @{
*/
#ifndef PLUGIN_BLOCK_H
#define PLUGIN_BLOCK_H
#include "gnunet_util_lib.h"
-#include "gnunet_container_lib.h"
#include "gnunet_block_lib.h"
/**
* Function called to validate a reply or a request. For
- * request evaluation, simply pass "NULL" for the reply_block.
+ * request evaluation, simply pass "NULL" for the @a reply_block.
* Note that it is assumed that the reply has already been
* matched to the key (and signatures checked) as it would
* be done with the "get_key" function.
@@ -43,34 +44,23 @@
* @param type block type
* @param query original query (hash)
* @param bf pointer to bloom filter associated with query; possibly updated
(!)
- * @param bf_mutator mutation value for bf
+ * @param bf_mutator mutation value for @a bf
* @param xquery extrended query data (can be NULL, depending on type)
- * @param xquery_size number of bytes in xquery
+ * @param xquery_size number of bytes in @a xquery
* @param reply_block response to validate
- * @param reply_block_size number of bytes in reply block
+ * @param reply_block_size number of bytes in @a reply_block
* @return characterization of result
*/
-typedef enum
- GNUNET_BLOCK_EvaluationResult (*GNUNET_BLOCK_EvaluationFunction) (void
*cls,
- enum
-
GNUNET_BLOCK_Type
- type,
- const
- struct
GNUNET_HashCode
- * query,
- struct
-
GNUNET_CONTAINER_BloomFilter
- ** bf,
- int32_t
-
bf_mutator,
- const
void
- *xquery,
- size_t
-
xquery_size,
- const
void
-
*reply_block,
- size_t
-
reply_block_size);
+typedef enum GNUNET_BLOCK_EvaluationResult
+(*GNUNET_BLOCK_EvaluationFunction) (void *cls,
+ enum GNUNET_BLOCK_Type type,
+ const struct GNUNET_HashCode *query,
+ struct GNUNET_CONTAINER_BloomFilter **bf,
+ int32_t bf_mutator,
+ const void *xquery,
+ size_t xquery_size,
+ const void *reply_block,
+ size_t reply_block_size);
/**
@@ -79,11 +69,11 @@
* @param cls closure
* @param type block type
* @param block block to get the key for
- * @param block_size number of bytes in block
+ * @param block_size number of bytes in @a block
* @param key set to the key (query) for the given block
- * @return GNUNET_YES on success,
- * GNUNET_NO if the block is malformed
- * GNUNET_SYSERR if type not supported
+ * @return #GNUNET_YES on success,
+ * #GNUNET_NO if the block is malformed
+ * #GNUNET_SYSERR if type not supported
* (or if extracting a key from a block of this type does not work)
*/
typedef int (*GNUNET_BLOCK_GetKeyFunction) (void *cls,
@@ -124,5 +114,6 @@
};
+/** @} */ /* end of group block */
#endif
Modified: gnunet/src/include/gnunet_client_lib.h
===================================================================
--- gnunet/src/include/gnunet_client_lib.h 2013-08-21 15:12:08 UTC (rev
28748)
+++ gnunet/src/include/gnunet_client_lib.h 2013-08-21 15:16:58 UTC (rev
28749)
@@ -22,6 +22,8 @@
* @file include/gnunet_client_lib.h
* @brief functions related to accessing services
* @author Christian Grothoff
+ * @defgroup client Generic client-side communication with services
+ * @{
*/
#ifndef GNUNET_CLIENT_LIB_H
@@ -92,7 +94,7 @@
*
* @param client connection to the service
* @param handler function to call with the message
- * @param handler_cls closure for handler
+ * @param handler_cls closure for @a handler
* @param timeout how long to wait until timing out
*/
void
@@ -115,17 +117,17 @@
* @param client connection to the service
* @param size number of bytes to send
* @param timeout after how long should we give up (and call
- * notify with buf NULL and size 0)?
+ * @a notify with buf NULL and size 0)?
* @param auto_retry if the connection to the service dies, should we
* automatically re-connect and retry (within the timeout period)
- * or should we immediately fail in this case? Pass GNUNET_YES
+ * or should we immediately fail in this case? Pass #GNUNET_YES
* if the caller does not care about temporary connection errors,
* for example because the protocol is stateless
* @param notify function to call
- * @param notify_cls closure for notify
+ * @param notify_cls closure for @a notify
* @return NULL if someone else is already waiting to be notified
* non-NULL if the notify callback was queued (can be used to cancel
- * using GNUNET_CONNECTION_notify_transmit_ready_cancel)
+ * using #GNUNET_CONNECTION_notify_transmit_ready_cancel)
*/
struct GNUNET_CLIENT_TransmitHandle *
GNUNET_CLIENT_notify_transmit_ready (struct GNUNET_CLIENT_Connection *client,
@@ -159,12 +161,12 @@
* and for waiting for a response)
* @param auto_retry if the connection to the service dies, should we
* automatically re-connect and retry (within the timeout period)
- * or should we immediately fail in this case? Pass GNUNET_YES
+ * or should we immediately fail in this case? Pass #GNUNET_YES
* if the caller does not care about temporary connection errors,
* for example because the protocol is stateless
* @param rn function to call with the response
- * @param rn_cls closure for rn
- * @return GNUNET_OK on success, GNUNET_SYSERR if a request
+ * @param rn_cls closure for @a rn
+ * @return #GNUNET_OK on success, #GNUNET_SYSERR if a request
* is already pending
*/
int
@@ -185,9 +187,9 @@
* Function called with the result on the service test.
*
* @param cls closure
- * @param result GNUNET_YES if the service is running,
- * GNUNET_NO if the service is not running
- * GNUNET_SYSERR if the configuration is invalid
+ * @param result #GNUNET_YES if the service is running,
+ * #GNUNET_NO if the service is not running
+ * #GNUNET_SYSERR if the configuration is invalid
*/
typedef void (*GNUNET_CLIENT_TestResultCallback)(void *cls,
int result);
@@ -201,9 +203,9 @@
*
* @param service name of the service to wait for
* @param cfg configuration to use
- * @param timeout how long to wait at most in ms
+ * @param timeout how long to wait at most
* @param cb function to call with the result
- * @param cb_cls closure for 'cb'
+ * @param cb_cls closure for @a cb
* @return handle to cancel the test
*/
struct GNUNET_CLIENT_TestHandle *
@@ -229,6 +231,8 @@
}
#endif
+/** @} */ /* end of group client */
+
/* ifndef GNUNET_CLIENT_LIB_H */
#endif
/* end of gnunet_client_lib.h */
Modified: gnunet/src/include/gnunet_container_lib.h
===================================================================
--- gnunet/src/include/gnunet_container_lib.h 2013-08-21 15:12:08 UTC (rev
28748)
+++ gnunet/src/include/gnunet_container_lib.h 2013-08-21 15:16:58 UTC (rev
28749)
@@ -1,10 +1,10 @@
/*
This file is part of GNUnet.
- (C) 2001, 2002, 2003, 2004, 2005, 2006, 2008, 2009, 2010 Christian
Grothoff (and other contributing authors)
+ (C) 2001-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 2, or (at your
+ 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
@@ -21,9 +21,13 @@
/**
* @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)
*/
#ifndef GNUNET_CONTAINER_LIB_H
@@ -51,28 +55,31 @@
/**
* @brief bloomfilter representation (opaque)
+ * @ingroup bloomfilter
*/
struct GNUNET_CONTAINER_BloomFilter;
/**
- * Iterator over HashCodes.
+ * @ingroup bloomfilter
+ * Iterator over struct GNUNET_HashCodes.
*
* @param cls closure
* @param next set to the next hash code
- * @return GNUNET_YES if next was updated
- * GNUNET_NO if there are no more entries
+ * @return #GNUNET_YES if next was updated
+ * #GNUNET_NO if there are no more entries
*/
typedef int (*GNUNET_HashCodeIterator) (void *cls, struct GNUNET_HashCode *
next);
/**
- * Load a bloom-filter from a file.
+ * @ingroup bloomfilter
+ * Load a Bloom filter from a file.
*
* @param filename the name of the file (or the prefix)
* @param size the size of the bloom-filter (number of
* bytes of storage space to use); will be rounded up
* to next power of 2
- * @param k the number of GNUNET_CRYPTO_hash-functions to apply per
+ * @param k the number of #GNUNET_CRYPTO_hash-functions to apply per
* element (number of bits set per element in the set)
* @return the bloomfilter
*/
@@ -82,15 +89,16 @@
/**
- * Create a bloom filter from raw bits.
+ * @ingroup bloomfilter
+ * Create a Bloom filter from raw bits.
*
* @param data the raw bits in memory (maybe NULL,
* in which case all bits should be considered
* to be zero).
* @param size the size of the bloom-filter (number of
- * bytes of storage space to use); also size of data
+ * bytes of storage space to use); also size of @a data
* -- unless data is NULL. Must be a power of 2.
- * @param k the number of GNUNET_CRYPTO_hash-functions to apply per
+ * @param k the number of #GNUNET_CRYPTO_hash-functions to apply per
* element (number of bits set per element in the set)
* @return the bloomfilter
*/
@@ -100,12 +108,13 @@
/**
- * Copy the raw data of this bloomfilter into
+ * @ingroup bloomfilter
+ * Copy the raw data of this Bloom filter into
* the given data array.
*
* @param data where to write the data
- * @param size the size of the given data array
- * @return GNUNET_SYSERR if the data array of the wrong size
+ * @param size the size of the given @a data array
+ * @return #GNUNET_SYSERR if the data array of the wrong size
*/
int
GNUNET_CONTAINER_bloomfilter_get_raw_data (const struct
@@ -114,10 +123,12 @@
/**
+ * @ingroup bloomfilter
* Test if an element is in the filter.
+ *
* @param e the element
* @param bf the filter
- * @return GNUNET_YES if the element is in the filter, GNUNET_NO if not
+ * @return #GNUNET_YES if the element is in the filter, #GNUNET_NO if not
*/
int
GNUNET_CONTAINER_bloomfilter_test (const struct GNUNET_CONTAINER_BloomFilter
@@ -125,7 +136,9 @@
/**
- * Add an element to the filter
+ * @ingroup bloomfilter
+ * Add an element to the filter.
+ *
* @param bf the filter
* @param e the element
*/
@@ -135,7 +148,9 @@
/**
+ * @ingroup bloomfilter
* Remove an element from the filter.
+ *
* @param bf the filter
* @param e the element to remove
*/
@@ -145,6 +160,7 @@
/**
+ * @ingroup bloomfilter
* Create a copy of a bloomfilter.
*
* @param bf the filter
@@ -157,9 +173,11 @@
/**
+ * @ingroup bloomfilter
* Free the space associcated with a filter
* in memory, flush to drive if needed (do not
- * free the space on the drive)
+ * free the space on the drive).
+ *
* @param bf the filter
*/
void
@@ -167,6 +185,7 @@
/**
+ * @ingroup bloomfilter
* Get size of the bloom filter.
*
* @param bf the filter
@@ -178,52 +197,58 @@
/**
- * Reset a bloom filter to empty.
+ * @ingroup bloomfilter
+ * Reset a Bloom filter to empty.
+ *
* @param bf the filter
*/
void
GNUNET_CONTAINER_bloomfilter_clear (struct GNUNET_CONTAINER_BloomFilter *bf);
+
/**
- * Or the entries of the given raw data array with the
- * data of the given bloom filter. Assumes that
- * the size of the data array and the current filter
+ * @ingroup bloomfilter
+ * "or" the entries of the given raw data array with the
+ * data of the given Bloom filter. Assumes that
+ * the @a size of the @a data array and the current filter
* match.
*
* @param bf the filter
* @param data data to OR-in
- * @param size size of data
- * @return GNUNET_OK on success
+ * @param size size of @a data
+ * @return #GNUNET_OK on success
*/
int
GNUNET_CONTAINER_bloomfilter_or (struct GNUNET_CONTAINER_BloomFilter *bf,
const char *data, size_t size);
+
/**
- * Or the entries of the given raw data array with the
- * data of the given bloom filter. Assumes that
- * the size of the data array and the current filter
- * match.
+ * @ingroup bloomfilter
+ * "or" the entries of the given raw data array with the
+ * data of the given Bloom filter. Assumes that
+ * the size of the two filters matches.
*
* @param bf the filter
* @param to_or the bloomfilter to or-in
- * @param size number of bytes in data
+ * @return #GNUNET_OK on success
*/
int
GNUNET_CONTAINER_bloomfilter_or2 (struct GNUNET_CONTAINER_BloomFilter *bf,
const struct GNUNET_CONTAINER_BloomFilter
- *to_or, size_t size);
+ *to_or);
/**
+ * @ingroup bloomfilter
* Resize a bloom filter. Note that this operation
- * is pretty costly. Essentially, the bloom filter
+ * is pretty costly. Essentially, the Bloom filter
* needs to be completely re-build.
*
* @param bf the filter
* @param iterator an iterator over all elements stored in the BF
- * @param iterator_cls closure for iterator
+ * @param iterator_cls closure for @a iterator
* @param size the new size for the filter
- * @param k the new number of GNUNET_CRYPTO_hash-function to apply per element
+ * @param k the new number of #GNUNET_CRYPTO_hash-function to apply per element
*/
void
GNUNET_CONTAINER_bloomfilter_resize (struct GNUNET_CONTAINER_BloomFilter *bf,
@@ -231,22 +256,27 @@
void *iterator_cls, size_t size,
unsigned int k);
+
/* ****************** metadata ******************* */
/**
+ * @ingroup metadata
* Meta data to associate with a file, directory or namespace.
*/
struct GNUNET_CONTAINER_MetaData;
/**
- * Create a fresh MetaData token.
+ * @ingroup metadata
+ * Create a fresh meta data container.
*
* @return empty meta-data container
*/
struct GNUNET_CONTAINER_MetaData *
GNUNET_CONTAINER_meta_data_create (void);
+
/**
+ * @ingroup metadata
* Duplicate a MetaData token.
*
* @param md what to duplicate
@@ -257,6 +287,7 @@
*md);
/**
+ * @ingroup metadata
* Free meta data.
*
* @param md what to free
@@ -264,7 +295,9 @@
void
GNUNET_CONTAINER_meta_data_destroy (struct GNUNET_CONTAINER_MetaData *md);
+
/**
+ * @ingroup metadata
* Test if two MDs are equal. We consider them equal if
* the meta types, formats and content match (we do not
* include the mime types and plugins names in this
@@ -272,7 +305,7 @@
*
* @param md1 first value to check
* @param md2 other value to check
- * @return GNUNET_YES if they are equal
+ * @return #GNUNET_YES if they are equal
*/
int
GNUNET_CONTAINER_meta_data_test_equal (const struct GNUNET_CONTAINER_MetaData
@@ -282,6 +315,7 @@
/**
+ * @ingroup metadata
* Extend metadata.
*
* @param md metadata to extend
@@ -295,7 +329,7 @@
* can be NULL (if mime-type is not known)
* @param data actual meta-data found
* @param data_size number of bytes in data
- * @return GNUNET_OK on success, GNUNET_SYSERR if this entry already exists
+ * @return #GNUNET_OK on success, #GNUNET_SYSERR if this entry already exists
* data_mime_type and plugin_name are not considered for "exists"
checks
*/
int
@@ -308,6 +342,7 @@
/**
+ * @ingroup metadata
* Extend metadata. Merges the meta data from the second argument
* into the first, discarding duplicate key-value pairs.
*
@@ -320,6 +355,7 @@
/**
+ * @ingroup metadata
* Remove an item.
*
* @param md metadata to manipulate
@@ -327,7 +363,7 @@
* @param data specific value to remove, NULL to remove all
* entries of the given type
* @param data_size number of bytes in data
- * @return GNUNET_OK on success, GNUNET_SYSERR if the item does not exist in md
+ * @return #GNUNET_OK on success, #GNUNET_SYSERR if the item does not exist in
md
*/
int
GNUNET_CONTAINER_meta_data_delete (struct GNUNET_CONTAINER_MetaData *md,
@@ -336,6 +372,7 @@
/**
+ * @ingroup metadata
* Remove all items in the container.
*
* @param md metadata to manipulate
@@ -345,6 +382,7 @@
/**
+ * @ingroup metadata
* Add the current time as the publication date
* to the meta-data.
*
@@ -356,11 +394,12 @@
/**
+ * @ingroup metadata
* Iterate over MD entries.
*
* @param md metadata to inspect
* @param iter function to call on each entry
- * @param iter_cls closure for iterator
+ * @param iter_cls closure for @a iter
* @return number of entries
*/
int
@@ -369,6 +408,7 @@
void *iter_cls);
/**
+ * @ingroup metadata
* Get the first MD entry of the given type. Caller
* is responsible for freeing the return value.
* Also, only meta data items that are strings (0-terminated)
@@ -384,6 +424,7 @@
/**
+ * @ingroup metadata
* Get the first matching MD entry of the given types. Caller is
* responsible for freeing the return value. Also, only meta data
* items that are strings (0-terminated) are returned by this
@@ -400,6 +441,7 @@
...);
/**
+ * @ingroup metadata
* Get a thumbnail from the meta-data (if present). Only matches meta
* data with mime type "image" and binary format.
*
@@ -415,22 +457,26 @@
/**
+ * @ingroup metadata
* Options for metadata serialization.
*/
enum GNUNET_CONTAINER_MetaDataSerializationOptions
{
/**
+ * @ingroup metadata
* Serialize all of the data.
*/
GNUNET_CONTAINER_META_DATA_SERIALIZE_FULL = 0,
/**
+ * @ingroup metadata
* If not enough space is available, it is acceptable
* to only serialize some of the metadata.
*/
GNUNET_CONTAINER_META_DATA_SERIALIZE_PART = 1,
/**
+ * @ingroup metadata
* Speed is of the essence, do not allow compression.
*/
GNUNET_CONTAINER_META_DATA_SERIALIZE_NO_COMPRESS = 2
@@ -438,6 +484,7 @@
/**
+ * @ingroup metadata
* Serialize meta-data to target.
*
* @param md metadata to serialize
@@ -460,6 +507,7 @@
/**
+ * @ingroup metadata
* Get the size of the full meta-data in serialized form.
*
* @param md metadata to inspect
@@ -471,6 +519,7 @@
/**
+ * @ingroup metadata
* Deserialize meta-data. Initializes md.
*
* @param input serialized meta-data.
@@ -485,23 +534,27 @@
/* ******************************* HashMap **************************** */
/**
+ * @ingroup hashmap
* Opaque handle for a HashMap.
*/
struct GNUNET_CONTAINER_MultiHashMap;
/**
+ * @ingroup hashmap
* Opaque handle to an iterator over
* a multihashmap.
*/
struct GNUNET_CONTAINER_MultiHashMapIterator;
/**
+ * @ingroup hashmap
* Options for storing values in the HashMap.
*/
enum GNUNET_CONTAINER_MultiHashMapOption
{
/**
+ * @ingroup hashmap
* If a value with the given key exists, replace it. Note that the
* old value would NOT be freed by replace (the application has to
* make sure that this happens if required).
@@ -509,35 +562,41 @@
GNUNET_CONTAINER_MULTIHASHMAPOPTION_REPLACE,
/**
+ * @ingroup hashmap
* Allow multiple values with the same key.
*/
GNUNET_CONTAINER_MULTIHASHMAPOPTION_MULTIPLE,
/**
+ * @ingroup hashmap
* There must only be one value per key; storing a value should fail
* if a value under the same key already exists.
*/
GNUNET_CONTAINER_MULTIHASHMAPOPTION_UNIQUE_ONLY,
/**
- * There must only be one value per key, but don't bother checking
- * if a value already exists (faster than UNIQUE_ONLY; implemented
- * just like MULTIPLE but this option documents better what is
- * intended if UNIQUE is what is desired).
+ * @ingroup hashmap There must only be one value per key, but don't
+ * bother checking if a value already exists (faster than
+ * #GNUNET_CONTAINER_MULTIHASHMAPOPTION_UNIQUE_ONLY; implemented
+ * just like #GNUNET_CONTAINER_MULTIHASHMAPOPTION_MULTIPLE but this
+ * option documents better what is intended if
+ * #GNUNET_CONTAINER_MULTIHASHMAPOPTION_UNIQUE_ONLY is what is
+ * desired).
*/
GNUNET_CONTAINER_MULTIHASHMAPOPTION_UNIQUE_FAST
};
/**
+ * @ingroup hashmap
* Iterator over hash map entries.
*
* @param cls closure
* @param key current key code
* @param value value in the hash map
- * @return GNUNET_YES if we should continue to
+ * @return #GNUNET_YES if we should continue to
* iterate,
- * GNUNET_NO if not.
+ * #GNUNET_NO if not.
*/
typedef int (*GNUNET_CONTAINER_HashMapIterator) (void *cls,
const struct GNUNET_HashCode
*key,
@@ -545,11 +604,12 @@
/**
+ * @ingroup hashmap
* Create a multi hash map.
*
* @param len initial size (map will grow as needed)
- * @param do_not_copy_keys GNUNET_NO is always safe and should be used by
default;
- * GNUNET_YES means that on 'put', the 'key' does not
have
+ * @param do_not_copy_keys #GNUNET_NO is always safe and should be used by
default;
+ * #GNUNET_YES means that on 'put', the 'key' does not
have
* to be copied as the destination of the pointer is
* guaranteed to be life as long as the value is
stored in
* the hashmap. This can significantly reduce memory
@@ -565,6 +625,7 @@
/**
+ * @ingroup hashmap
* Destroy a hash map. Will not free any values
* stored in the hash map!
*
@@ -576,6 +637,7 @@
/**
+ * @ingroup hashmap
* Given a key find a value in the map matching the key.
*
* @param map the map
@@ -591,6 +653,7 @@
/**
+ * @ingroup hashmap
* Remove the given key-value pair from the map. Note that if the
* key-value pair is in the map multiple times, only one of the pairs
* will be removed.
@@ -598,7 +661,7 @@
* @param map the map
* @param key key of the key-value pair
* @param value value of the key-value pair
- * @return GNUNET_YES on success, GNUNET_NO if the key-value pair
+ * @return #GNUNET_YES on success, #GNUNET_NO if the key-value pair
* is not in the map
*/
int
@@ -607,6 +670,7 @@
const void *value);
/**
+ * @ingroup hashmap
* Remove all entries for the given key from the map.
* Note that the values would not be "freed".
*
@@ -620,13 +684,14 @@
/**
+ * @ingroup hashmap
* Check if the map contains any value under the given
* key (including values that are NULL).
*
* @param map the map
* @param key the key to test if a value exists for it
- * @return GNUNET_YES if such a value exists,
- * GNUNET_NO if not
+ * @return #GNUNET_YES if such a value exists,
+ * #GNUNET_NO if not
*/
int
GNUNET_CONTAINER_multihashmap_contains (const struct
@@ -635,14 +700,15 @@
/**
+ * @ingroup hashmap
* Check if the map contains the given value under the given
* key.
*
* @param map the map
* @param key the key to test if a value exists for it
* @param value value to test for
- * @return GNUNET_YES if such a value exists,
- * GNUNET_NO if not
+ * @return #GNUNET_YES if such a value exists,
+ * #GNUNET_NO if not
*/
int
GNUNET_CONTAINER_multihashmap_contains_value (const struct
@@ -652,15 +718,16 @@
/**
+ * @ingroup hashmap
* Store a key-value pair in the map.
*
* @param map the map
* @param key key to use
* @param value value to use
* @param opt options for put
- * @return GNUNET_OK on success,
- * GNUNET_NO if a value was replaced (with REPLACE)
- * GNUNET_SYSERR if UNIQUE_ONLY was the option and the
+ * @return #GNUNET_OK on success,
+ * #GNUNET_NO if a value was replaced (with REPLACE)
+ * #GNUNET_SYSERR if UNIQUE_ONLY was the option and the
* value already exists
*/
int
@@ -670,6 +737,7 @@
opt);
/**
+ * @ingroup hashmap
* Get the number of key-value pairs in the map.
*
* @param map the map
@@ -681,13 +749,14 @@
/**
+ * @ingroup hashmap
* Iterate over all entries in the map.
*
* @param map the map
* @param it function to call on each entry
- * @param it_cls extra argument to it
+ * @param it_cls extra argument to @a it
* @return the number of key value pairs processed,
- * GNUNET_SYSERR if it aborted iteration
+ * #GNUNET_SYSERR if it aborted iteration
*/
int
GNUNET_CONTAINER_multihashmap_iterate (const struct
@@ -697,6 +766,7 @@
/**
+ * @ingroup hashmap
* Create an iterator for a multihashmap.
* The iterator can be used to retrieve all the elements in the multihashmap
* one by one, without having to handle all elements at once (in contrast to
@@ -706,25 +776,26 @@
* result in skipped or repeated elements.
*
* @param map the map to create an iterator for
- * @return an iterator over the given multihashmap 'map'
+ * @return an iterator over the given multihashmap @a map
*/
struct GNUNET_CONTAINER_MultiHashMapIterator *
GNUNET_CONTAINER_multihashmap_iterator_create (const struct
GNUNET_CONTAINER_MultiHashMap *map);
/**
- * Retrieve the next element from the hash map at the iterator's position.
- * If there are no elements left, GNUNET_NO is returned, and 'key' and 'value'
- * are not modified.
- * This operation is only allowed if no elements have been removed from the
- * multihashmap since the creation of 'iter', and the map has not been
destroyed.
+ * @ingroup hashmap
+ * Retrieve the next element from the hash map at the iterator's
+ * position. If there are no elements left, #GNUNET_NO is returned,
+ * and @a key and @a value are not modified. This operation is only
+ * allowed if no elements have been removed from the multihashmap
+ * since the creation of @a iter, and the map has not been destroyed.
* Adding elements may result in repeating or skipping elements.
*
* @param iter the iterator to get the next element from
* @param key pointer to store the key in, can be NULL
* @param value pointer to store the value in, can be NULL
- * @return GNUNET_YES we returned an element,
- * GNUNET_NO if we are out of elements
+ * @return #GNUNET_YES we returned an element,
+ * #GNUNET_NO if we are out of elements
*/
int
GNUNET_CONTAINER_multihashmap_iterator_next (struct
GNUNET_CONTAINER_MultiHashMapIterator *iter,
@@ -732,6 +803,7 @@
/**
+ * @ingroup hashmap
* Destroy a multihashmap iterator.
*
* @param iter the iterator to destroy
@@ -741,14 +813,15 @@
/**
+ * @ingroup hashmap
* Iterate over all entries in the map that match a particular key.
*
* @param map the map
* @param key key that the entries must correspond to
* @param it function to call on each entry
- * @param it_cls extra argument to it
+ * @param it_cls extra argument to @a it
* @return the number of key value pairs processed,
- * GNUNET_SYSERR if it aborted iteration
+ * #GNUNET_SYSERR if it aborted iteration
*/
int
GNUNET_CONTAINER_multihashmap_get_multiple (const struct
@@ -760,20 +833,22 @@
/* Version of multihashmap with 32 bit keys */
/**
+ * @ingroup hashmap
* Opaque handle for the 32-bit key HashMap.
*/
struct GNUNET_CONTAINER_MultiHashMap32;
/**
+ * @ingroup hashmap
* Iterator over hash map entries.
*
* @param cls closure
* @param key current key code
* @param value value in the hash map
- * @return GNUNET_YES if we should continue to
+ * @return #GNUNET_YES if we should continue to
* iterate,
- * GNUNET_NO if not.
+ * #GNUNET_NO if not.
*/
typedef int (*GNUNET_CONTAINER_HashMapIterator32) (void *cls,
uint32_t key,
@@ -781,6 +856,7 @@
/**
+ * @ingroup hashmap
* Create a 32-bit key multi hash map.
*
* @param len initial size (map will grow as needed)
@@ -791,6 +867,7 @@
/**
+ * @ingroup hashmap
* Destroy a 32-bit key hash map. Will not free any values
* stored in the hash map!
*
@@ -802,6 +879,7 @@
/**
+ * @ingroup hashmap
* Get the number of key-value pairs in the map.
*
* @param map the map
@@ -813,6 +891,7 @@
/**
+ * @ingroup hashmap
* Given a key find a value in the map matching the key.
*
* @param map the map
@@ -829,13 +908,14 @@
/**
+ * @ingroup hashmap
* Iterate over all entries in the map.
*
* @param map the map
* @param it function to call on each entry
- * @param it_cls extra argument to it
+ * @param it_cls extra argument to @a it
* @return the number of key value pairs processed,
- * GNUNET_SYSERR if it aborted iteration
+ * #GNUNET_SYSERR if it aborted iteration
*/
int
GNUNET_CONTAINER_multihashmap32_iterate (const struct
@@ -845,6 +925,7 @@
/**
+ * @ingroup hashmap
* Remove the given key-value pair from the map. Note that if the
* key-value pair is in the map multiple times, only one of the pairs
* will be removed.
@@ -852,7 +933,7 @@
* @param map the map
* @param key key of the key-value pair
* @param value value of the key-value pair
- * @return GNUNET_YES on success, GNUNET_NO if the key-value pair
+ * @return #GNUNET_YES on success, #GNUNET_NO if the key-value pair
* is not in the map
*/
int
@@ -863,6 +944,7 @@
/**
+ * @ingroup hashmap
* Remove all entries for the given key from the map.
* Note that the values would not be "freed".
*
@@ -878,13 +960,14 @@
/**
+ * @ingroup hashmap
* Check if the map contains any value under the given
* key (including values that are NULL).
*
* @param map the map
* @param key the key to test if a value exists for it
- * @return GNUNET_YES if such a value exists,
- * GNUNET_NO if not
+ * @return #GNUNET_YES if such a value exists,
+ * #GNUNET_NO if not
*/
int
GNUNET_CONTAINER_multihashmap32_contains (const struct
@@ -893,14 +976,15 @@
/**
+ * @ingroup hashmap
* Check if the map contains the given value under the given
* key.
*
* @param map the map
* @param key the key to test if a value exists for it
* @param value value to test for
- * @return GNUNET_YES if such a value exists,
- * GNUNET_NO if not
+ * @return #GNUNET_YES if such a value exists,
+ * #GNUNET_NO if not
*/
int
GNUNET_CONTAINER_multihashmap32_contains_value (const struct
@@ -911,15 +995,16 @@
/**
+ * @ingroup hashmap
* Store a key-value pair in the map.
*
* @param map the map
* @param key key to use
* @param value value to use
* @param opt options for put
- * @return GNUNET_OK on success,
- * GNUNET_NO if a value was replaced (with REPLACE)
- * GNUNET_SYSERR if UNIQUE_ONLY was the option and the
+ * @return #GNUNET_OK on success,
+ * #GNUNET_NO if a value was replaced (with REPLACE)
+ * #GNUNET_SYSERR if #GNUNET_CONTAINER_MULTIHASHMAPOPTION_UNIQUE_ONLY
was the option and the
* value already exists
*/
int
@@ -930,14 +1015,15 @@
/**
+ * @ingroup hashmap
* Iterate over all entries in the map that match a particular key.
*
* @param map the map
* @param key key that the entries must correspond to
* @param it function to call on each entry
- * @param it_cls extra argument to it
+ * @param it_cls extra argument to @a it
* @return the number of key value pairs processed,
- * GNUNET_SYSERR if it aborted iteration
+ * #GNUNET_SYSERR if it aborted iteration
*/
int
GNUNET_CONTAINER_multihashmap32_get_multiple (const struct
@@ -953,6 +1039,7 @@
/* To avoid mistakes: head->prev == tail->next == NULL */
/**
+ * @ingroup dll
* Insert an element at the head of a DLL. Assumes that head, tail and
* element are structs with prev and next fields.
*
@@ -973,6 +1060,7 @@
/**
+ * @ingroup dll
* Insert an element at the tail of a DLL. Assumes that head, tail and
* element are structs with prev and next fields.
*
@@ -993,6 +1081,7 @@
/**
+ * @ingroup dll
* Insert an element into a DLL after the given other element. Insert
* at the head if the other element is NULL.
*
@@ -1022,6 +1111,7 @@
/**
+ * @ingroup dll
* Insert an element into a DLL before the given other element. Insert
* at the tail if the other element is NULL.
*
@@ -1051,6 +1141,7 @@
/**
+ * @ingroup dll
* Remove an element from a DLL. Assumes that head, tail and
* element point to structs with prev and next fields.
*
@@ -1082,6 +1173,7 @@
in multiple lists at the same time *********************** */
/**
+ * @ingroup dll
* Insert an element at the head of a MDLL. Assumes that head, tail and
* element are structs with prev and next fields.
*
@@ -1103,6 +1195,7 @@
/**
+ * @ingroup dll
* Insert an element at the tail of a MDLL. Assumes that head, tail and
* element are structs with prev and next fields.
*
@@ -1124,6 +1217,7 @@
/**
+ * @ingroup dll
* Insert an element into a MDLL after the given other element. Insert
* at the head if the other element is NULL.
*
@@ -1154,6 +1248,7 @@
/**
+ * @ingroup dll
* Insert an element into a MDLL before the given other element. Insert
* at the tail if the other element is NULL.
*
@@ -1184,6 +1279,7 @@
/**
+ * @ingroup dll
* Remove an element from a MDLL. Assumes
* that head, tail and element are structs
* with prev and next fields.
@@ -1213,23 +1309,26 @@
/**
+ * @ingroup heap
* Cost by which elements in a heap can be ordered.
*/
typedef uint64_t GNUNET_CONTAINER_HeapCostType;
-/*
- * Heap type, either max or min. Hopefully makes the
- * implementation more useful.
+/**
+ * @ingroup heap
+ * Heap type, either max or min.
*/
enum GNUNET_CONTAINER_HeapOrder
{
/**
+ * @ingroup heap
* Heap with the maximum cost at the root.
*/
GNUNET_CONTAINER_HEAP_ORDER_MAX,
/**
+ * @ingroup heap
* Heap with the minimum cost at the root.
*/
GNUNET_CONTAINER_HEAP_ORDER_MIN
@@ -1237,19 +1336,21 @@
/**
+ * @ingroup heap
* Handle to a Heap.
*/
struct GNUNET_CONTAINER_Heap;
-
/**
+ * @ingroup heap
* Handle to a node in a heap.
*/
struct GNUNET_CONTAINER_HeapNode;
/**
+ * @ingroup heap
* Create a new heap.
*
* @param order how should the heap be sorted?
@@ -1260,6 +1361,7 @@
/**
+ * @ingroup heap
* Destroys the heap. Only call on a heap that
* is already empty.
*
@@ -1270,6 +1372,7 @@
/**
+ * @ingroup heap
* Get element stored at root of heap.
*
* @param heap heap to inspect
@@ -1280,6 +1383,7 @@
/**
+ * @ingroup heap
* Get the current size of the heap
*
* @param heap the heap to get the size of
@@ -1290,6 +1394,7 @@
/**
+ * @ingroup heap
* Get the current cost of the node
*
* @param node the node to get the cost of
@@ -1300,14 +1405,15 @@
*node);
/**
+ * @ingroup heap
* Iterator for heap
*
* @param cls closure
* @param node internal node of the heap
* @param element value stored at the node
* @param cost cost associated with the node
- * @return GNUNET_YES if we should continue to iterate,
- * GNUNET_NO if not.
+ * @return #GNUNET_YES if we should continue to iterate,
+ * #GNUNET_NO if not.
*/
typedef int (*GNUNET_CONTAINER_HeapIterator) (void *cls,
struct GNUNET_CONTAINER_HeapNode
*
@@ -1317,11 +1423,12 @@
/**
+ * @ingroup heap
* Iterate over all entries in the heap.
*
* @param heap the heap
* @param iterator function to call on each entry
- * @param iterator_cls closure for iterator
+ * @param iterator_cls closure for @a iterator
*/
void
GNUNET_CONTAINER_heap_iterate (const struct GNUNET_CONTAINER_Heap *heap,
@@ -1329,6 +1436,7 @@
void *iterator_cls);
/**
+ * @ingroup heap
* Perform a random walk of the tree. The walk is biased
* towards elements closer to the root of the tree (since
* each walk starts at the root and ends at a random leaf).
@@ -1344,6 +1452,7 @@
/**
+ * @ingroup heap
* Inserts a new element into the heap.
*
* @param heap heap to modify
@@ -1357,6 +1466,7 @@
/**
+ * @ingroup heap
* Remove root of the heap.
*
* @param heap heap to modify
@@ -1367,6 +1477,7 @@
/**
+ * @ingroup heap
* Removes a node from the heap.
*
* @param node node to remove
@@ -1377,6 +1488,7 @@
/**
+ * @ingroup heap
* Updates the cost of any node in the tree
*
* @param heap heap to modify
Modified: gnunet/src/include/gnunet_core_service.h
===================================================================
--- gnunet/src/include/gnunet_core_service.h 2013-08-21 15:12:08 UTC (rev
28748)
+++ gnunet/src/include/gnunet_core_service.h 2013-08-21 15:16:58 UTC (rev
28749)
@@ -1,6 +1,6 @@
/*
This file is part of GNUnet.
- (C) 2009, 2010 Christian Grothoff (and other contributing authors)
+ (C) 2009-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
@@ -23,6 +23,8 @@
* @brief core service; this is the main API for encrypted P2P
* communications
* @author Christian Grothoff
+ * @defgroup core encrypted direct communication between peers
+ * @{
*/
#ifndef GNUNET_CORE_SERVICE_H
@@ -58,8 +60,7 @@
* @param peer peer identity this notification is about
*/
typedef void (*GNUNET_CORE_ConnectEventHandler) (void *cls,
- const struct
- GNUNET_PeerIdentity * peer);
+ const struct
GNUNET_PeerIdentity *peer);
/**
@@ -69,8 +70,7 @@
* @param peer peer identity this notification is about
*/
typedef void (*GNUNET_CORE_DisconnectEventHandler) (void *cls,
- const struct
- GNUNET_PeerIdentity *
peer);
+ const struct
GNUNET_PeerIdentity *peer);
/**
@@ -133,8 +133,7 @@
*/
typedef void (*GNUNET_CORE_StartupCallback) (void *cls,
struct GNUNET_CORE_Handle *
server,
- const struct GNUNET_PeerIdentity *
- my_identity);
+ const struct GNUNET_PeerIdentity
*my_identity);
/**
@@ -280,42 +279,6 @@
/**
- * Handle to cancel 'is_peer_connected' test.
- */
-struct GNUNET_CORE_ConnectTestHandle;
-
-
-/**
- * Check if the given peer is currently connected and return information
- * about the session if so. This function is for special cirumstances
- * (GNUNET_TESTING uses it), normal users of the CORE API are
- * expected to track which peers are connected based on the
- * connect/disconnect callbacks from GNUNET_CORE_connect. This
- * function is NOT part of the 'versioned', 'official' API.
- *
- * @param cfg configuration to use
- * @param peer the specific peer to check for
- * @param peer_cb function to call with the peer information
- * @param cb_cls closure for @a peer_cb
- * @return handle to cancel the operation
- */
-struct GNUNET_CORE_ConnectTestHandle *
-GNUNET_CORE_is_peer_connected (const struct GNUNET_CONFIGURATION_Handle *cfg,
- const struct GNUNET_PeerIdentity *peer,
- GNUNET_CORE_ConnectEventHandler peer_cb,
- void *cb_cls);
-
-
-/**
- * Abort 'is_connected' test operation.
- *
- * @param cth handle for operation to cancel
- */
-void
-GNUNET_CORE_is_peer_connected_cancel (struct GNUNET_CORE_ConnectTestHandle
*cth);
-
-
-/**
* Check if the given peer is currently connected. This function is for special
* cirumstances (GNUNET_TESTBED uses it), normal users of the CORE API are
* expected to track which peers are connected based on the connect/disconnect
@@ -342,6 +305,8 @@
}
#endif
+/** @} */ /* end of group core */
+
/* ifndef GNUNET_CORE_SERVICE_H */
#endif
/* end of gnunet_core_service.h */
Modified: gnunet/src/include/gnunet_crypto_lib.h
===================================================================
--- gnunet/src/include/gnunet_crypto_lib.h 2013-08-21 15:12:08 UTC (rev
28748)
+++ gnunet/src/include/gnunet_crypto_lib.h 2013-08-21 15:16:58 UTC (rev
28749)
@@ -55,23 +55,27 @@
/**
- * Desired quality level for cryptographic operations.
+ * Desired quality level for random numbers.
+ * @ingroup crypto
*/
enum GNUNET_CRYPTO_Quality
{
/**
* No good quality of the operation is needed (i.e.,
* random numbers can be pseudo-random).
+ * @ingroup crypto
*/
GNUNET_CRYPTO_QUALITY_WEAK,
/**
* High-quality operations are desired.
+ * @ingroup crypto
*/
GNUNET_CRYPTO_QUALITY_STRONG,
/**
* Randomness for IVs etc. is required.
+ * @ingroup crypto
*/
GNUNET_CRYPTO_QUALITY_NONCE
};
Modified: gnunet/src/include/gnunet_dht_service.h
===================================================================
--- gnunet/src/include/gnunet_dht_service.h 2013-08-21 15:12:08 UTC (rev
28748)
+++ gnunet/src/include/gnunet_dht_service.h 2013-08-21 15:16:58 UTC (rev
28749)
@@ -1,6 +1,6 @@
/*
This file is part of GNUnet
- (C) 2004, 2005, 2006, 2008, 2009, 2011 Christian Grothoff (and other
contributing authors)
+ (C) 2004-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
Modified: gnunet/src/include/gnunet_disk_lib.h
===================================================================
--- gnunet/src/include/gnunet_disk_lib.h 2013-08-21 15:12:08 UTC (rev
28748)
+++ gnunet/src/include/gnunet_disk_lib.h 2013-08-21 15:16:58 UTC (rev
28749)
@@ -4,7 +4,7 @@
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 2, or (at your
+ 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
Modified: gnunet/src/include/gnunet_getopt_lib.h
===================================================================
--- gnunet/src/include/gnunet_getopt_lib.h 2013-08-21 15:12:08 UTC (rev
28748)
+++ gnunet/src/include/gnunet_getopt_lib.h 2013-08-21 15:16:58 UTC (rev
28749)
@@ -1,10 +1,10 @@
/*
This file is part of GNUnet.
- (C) 2001, 2002, 2003, 2004, 2005, 2006, 2009, 2011 Christian Grothoff
(and other contributing authors)
+ (C) 2001-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 2, or (at your
+ 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
@@ -21,8 +21,9 @@
/**
* @file include/gnunet_getopt_lib.h
* @brief command line parsing and --help formatting
- *
* @author Christian Grothoff
+ * @defgroup getopt command-line parsing
+ * @{
*/
#ifndef GNUNET_GETOPT_LIB_H
@@ -83,7 +84,7 @@
* @param scls specific closure (for this processor)
* @param option long name of the option (i.e. "config" for --config)
* @param value argument, NULL if none was given
- * @return GNUNET_OK to continue processing other options, GNUNET_SYSERR to
abort
+ * @return #GNUNET_OK to continue processing other options, #GNUNET_SYSERR to
abort
*/
typedef int (*GNUNET_GETOPT_CommandLineOptionProcessor) (struct
GNUNET_GETOPT_CommandLineProcessorContext
@@ -202,10 +203,10 @@
*
* @param binaryOptions Name of application with option summary
* @param allOptions defined options and handlers
- * @param argc number of arguments
+ * @param argc number of arguments in @a argv
* @param argv actual arguments
* @return index into argv with first non-option
- * argument, or GNUNET_SYSERR on error
+ * argument, or #GNUNET_SYSERR on error
*/
int
GNUNET_GETOPT_run (const char *binaryOptions,
@@ -224,7 +225,7 @@
* @param scls additional closure (will point to the 'unsigned long long')
* @param option name of the option
* @param value actual value of the option as a string.
- * @return GNUNET_OK if parsing the value worked
+ * @return #GNUNET_OK if parsing the value worked
*/
int
GNUNET_GETOPT_set_ulong (struct GNUNET_GETOPT_CommandLineProcessorContext *ctx,
@@ -242,7 +243,7 @@
* @param scls additional closure (will point to the 'struct
GNUNET_TIME_Relative')
* @param option name of the option
* @param value actual value of the option as a string.
- * @return GNUNET_OK if parsing the value worked
+ * @return #GNUNET_OK if parsing the value worked
*/
int
GNUNET_GETOPT_set_relative_time (struct
GNUNET_GETOPT_CommandLineProcessorContext *ctx,
@@ -260,7 +261,7 @@
* @param scls additional closure (will point to the 'unsigned int')
* @param option name of the option
* @param value actual value of the option as a string.
- * @return GNUNET_OK if parsing the value worked
+ * @return #GNUNET_OK if parsing the value worked
*/
int
GNUNET_GETOPT_set_uint (struct GNUNET_GETOPT_CommandLineProcessorContext *ctx,
@@ -279,7 +280,7 @@
* @param scls additional closure (will point to the 'int')
* @param option name of the option
* @param value not used (NULL)
- * @return GNUNET_OK
+ * @return #GNUNET_OK (always)
*/
int
GNUNET_GETOPT_set_one (struct GNUNET_GETOPT_CommandLineProcessorContext *ctx,
@@ -298,7 +299,7 @@
* which will be allocated)
* @param option name of the option
* @param value actual value of the option (a string)
- * @return GNUNET_OK
+ * @return #GNUNET_OK (always)
*/
int
GNUNET_GETOPT_set_string (struct GNUNET_GETOPT_CommandLineProcessorContext
*ctx,
@@ -317,7 +318,7 @@
* which will be allocated)
* @param option name of the option
* @param value actual value of the option (a string)
- * @return GNUNET_OK
+ * @return #GNUNET_OK (always)
*/
int
GNUNET_GETOPT_set_filename (struct GNUNET_GETOPT_CommandLineProcessorContext
*ctx,
@@ -335,7 +336,7 @@
* @param scls additional closure (will point to the 'int')
* @param option name of the option
* @param value not used (NULL)
- * @return GNUNET_OK
+ * @return #GNUNET_OK (always)
*/
int
GNUNET_GETOPT_increment_value (struct GNUNET_GETOPT_CommandLineProcessorContext
@@ -352,7 +353,7 @@
* @param scls additional closure (points to about text)
* @param option name of the option
* @param value not used (NULL)
- * @return GNUNET_NO (do not continue, not an error)
+ * @return #GNUNET_NO (do not continue, not an error)
*/
int
GNUNET_GETOPT_format_help_ (struct GNUNET_GETOPT_CommandLineProcessorContext
@@ -366,7 +367,7 @@
* @param scls additional closure (points to version string)
* @param option name of the option
* @param value not used (NULL)
- * @return GNUNET_NO (do not continue, not an error)
+ * @return #GNUNET_NO (do not continue, not an error)
*/
int
GNUNET_GETOPT_print_version_ (struct GNUNET_GETOPT_CommandLineProcessorContext
@@ -380,6 +381,7 @@
}
#endif
+/** @} */ /* end of group getopt */
/* ifndef GNUNET_GETOPT_LIB_H */
#endif
Modified: gnunet/src/include/gnunet_identity_service.h
===================================================================
--- gnunet/src/include/gnunet_identity_service.h 2013-08-21 15:12:08 UTC
(rev 28748)
+++ gnunet/src/include/gnunet_identity_service.h 2013-08-21 15:16:58 UTC
(rev 28749)
@@ -30,7 +30,10 @@
* manages the egos (private keys) of the local user; it does
* NOT manage identities of other users (public keys). For giving
* names to other users and manage their public keys securely, we
- * use GADS/GNS.
+ * use GNS.
+ *
+ * @defgroup identity identity management service
+ * @{
*/
#ifndef GNUNET_IDENTITY_SERVICE_H
#define GNUNET_IDENTITY_SERVICE_H
@@ -101,27 +104,27 @@
* Method called to inform about the egos of
* this peer.
*
- * When used with 'GNUNET_IDENTITY_connect', this function is
+ * When used with #GNUNET_IDENTITY_connect, this function is
* initially called for all egos and then again whenever a
* ego's name changes or if it is deleted. At the end of
* the initial pass over all egos, the function is once called
- * with 'NULL' for 'ego'. That does NOT mean that the callback won't
+ * with 'NULL' for @a ego. That does NOT mean that the callback won't
* be invoked in the future or that there was an error.
*
- * When used with 'GNUNET_IDENTITY_create' or 'GNUNET_IDENTITY_get',
+ * When used with #GNUNET_IDENTITY_create or #GNUNET_IDENTITY_get,
* this function is only called ONCE, and 'NULL' being passed in
- * 'ego' does indicate an error (i.e. name is taken or no default
- * value is known). If 'ego' is non-NULL and if '*ctx'
+ * @a ego does indicate an error (i.e. name is taken or no default
+ * value is known). If @a ego is non-NULL and if '*ctx'
* is set in those callbacks, the value WILL be passed to a subsequent
- * call to the identity callback of 'GNUNET_IDENTITY_connect' (if
+ * call to the identity callback of #GNUNET_IDENTITY_connect (if
* that one was not NULL).
*
* When an identity is renamed, this function is called with the
- * (known) ego but the NEW name.
+ * (known) @a ego but the NEW @a name.
*
* When an identity is deleted, this function is called with the
- * (known) ego and "NULL" for the 'name'. In this case,
- * the 'ego' is henceforth invalid (and the 'ctx' should also be
+ * (known) ego and "NULL" for the @a name. In this case,
+ * the @a ego is henceforth invalid (and the @a ctx should also be
* cleaned up).
*
* @param cls closure
@@ -143,7 +146,7 @@
*
* @param cfg Configuration to contact the identity service.
* @param cb function to call on all identity events, can be NULL
- * @param cb_cls closure for 'cb'
+ * @param cb_cls closure for @a cb
* @return handle to communicate with identity service
*/
struct GNUNET_IDENTITY_Handle *
@@ -159,7 +162,7 @@
* @param id identity service to query
* @param service_name for which service is an identity wanted
* @param cb function to call with the result (will only be called once)
- * @param cb_cls closure for cb
+ * @param cb_cls closure for @a cb
* @return handle to abort the operation
*/
struct GNUNET_IDENTITY_Operation *
@@ -187,7 +190,7 @@
* @param service_name for which service is an identity set
* @param ego new default identity to be set for this service
* @param cont function to call once the operation finished
- * @param cont_cls closure for cont
+ * @param cont_cls closure for @a cont
* @return handle to abort the operation
*/
struct GNUNET_IDENTITY_Operation *
@@ -213,7 +216,7 @@
* @param id identity service to use
* @param name desired name
* @param cont function to call with the result (will only be called once)
- * @param cont_cls closure for cont
+ * @param cont_cls closure for @a cont
* @return handle to abort the operation
*/
struct GNUNET_IDENTITY_Operation *
@@ -230,7 +233,7 @@
* @param old_name old name
* @param new_name desired new name
* @param cb function to call with the result (will only be called once)
- * @param cb_cls closure for cb
+ * @param cb_cls closure for @a cb
* @return handle to abort the operation
*/
struct GNUNET_IDENTITY_Operation *
@@ -247,7 +250,7 @@
* @param id identity service to use
* @param name name of the identity to delete
* @param cb function to call with the result (will only be called once)
- * @param cb_cls closure for cb
+ * @param cb_cls closure for @a cb
* @return handle to abort the operation
*/
struct GNUNET_IDENTITY_Operation *
@@ -276,6 +279,8 @@
}
#endif
+/** @} */ /* end of group identity */
+
/* ifndef GNUNET_IDENTITY_SERVICE_H */
#endif
/* end of gnunet_identity_service.h */
Modified: gnunet/src/include/gnunet_mq_lib.h
===================================================================
--- gnunet/src/include/gnunet_mq_lib.h 2013-08-21 15:12:08 UTC (rev 28748)
+++ gnunet/src/include/gnunet_mq_lib.h 2013-08-21 15:16:58 UTC (rev 28749)
@@ -1,10 +1,10 @@
/*
This file is part of GNUnet.
- (C) 2012 Christian Grothoff (and other contributing authors)
+ (C) 2012-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 2, or (at your
+ 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
@@ -22,6 +22,8 @@
* @author Florian Dold
* @file include/gnunet_mq_lib.h
* @brief general purpose message queue
+ * @defgroup mq general purpose message queue
+ * @{
*/
#ifndef GNUNET_MQ_H
#define GNUNET_MQ_H
@@ -93,7 +95,7 @@
* @param var pointer to a message struct, the type of the expression
determines the base size,
* the space after the base size is the nested message
* @return a 'struct GNUNET_MessageHeader *' that points at the nested message
of the given message,
- * or NULL if the given message in 'var' does not have any space after
the message struct
+ * or NULL if the given message in @a var does not have any space
after the message struct
*/
#define GNUNET_MQ_extract_nested_mh(var) GNUNET_MQ_extract_nested_mh_ ((struct
GNUNET_MessageHeader *) (var), sizeof (*(var)))
@@ -140,10 +142,25 @@
*/
struct GNUNET_MQ_Envelope;
+
+/**
+ * Error codes for the queue.
+ */
enum GNUNET_MQ_Error
{
+ /**
+ * FIXME: document!
+ */
GNUNET_MQ_ERROR_READ = 1,
+
+ /**
+ * FIXME: document!
+ */
GNUNET_MQ_ERROR_WRITE = 2,
+
+ /**
+ * FIXME: document!
+ */
GNUNET_MQ_ERROR_TIMEOUT = 4
};
@@ -176,8 +193,8 @@
/**
* Signature of functions implementing the
* destruction of a message queue.
- * Implementations must not free 'mq', but should
- * take care of 'impl_state'.
+ * Implementations must not free @a mq, but should
+ * take care of @a impl_state.
*
* @param mq the message queue to destroy
* @param impl_state state of the implementation
@@ -277,12 +294,14 @@
* @param ev the envelope with the message to send.
*/
void
-GNUNET_MQ_send (struct GNUNET_MQ_Handle *mq, struct GNUNET_MQ_Envelope *ev);
+GNUNET_MQ_send (struct GNUNET_MQ_Handle *mq,
+ struct GNUNET_MQ_Envelope *ev);
/**
- * Cancel sending the message. Message must have been sent with GNUNET_MQ_send
before.
- * May not be called after the notify sent callback has been called
+ * Cancel sending the message. Message must have been sent with
+ * #GNUNET_MQ_send before. May not be called after the notify sent
+ * callback has been called
*
* @param ev queued envelope to cancel
*/
@@ -340,7 +359,7 @@
/**
- * Create a message queue for a GNUNET_STREAM_Socket.
+ * Create a message queue for a GNUNET_SERVER_Client.
*
* @param client the client
* @return the message queue
@@ -355,7 +374,7 @@
* @param send function the implements sending messages
* @param destroy function that implements destroying the queue
* @param cancel function that implements canceling a message
- * @param impl_state for the queue, passed to 'send' and 'destroy'
+ * @param impl_state for the queue, passed to @a send, @a destroy and @a cancel
* @param handlers array of message handlers
* @param error_handler handler for read and write errors
* @param cls closure for message handlers and error handler
@@ -497,4 +516,6 @@
void
GNUNET_MQ_impl_send_commit (struct GNUNET_MQ_Handle *mq);
+/** @} */ /* end of group mq */
+
#endif
Modified: gnunet/src/include/gnunet_namestore_service.h
===================================================================
--- gnunet/src/include/gnunet_namestore_service.h 2013-08-21 15:12:08 UTC
(rev 28748)
+++ gnunet/src/include/gnunet_namestore_service.h 2013-08-21 15:16:58 UTC
(rev 28749)
@@ -147,6 +147,7 @@
* This peer is the authority for this record; it must thus
* not be deleted (other records can be deleted if we run
* out of space).
+ * @deprecated
*/
GNUNET_NAMESTORE_RF_AUTHORITY = 1,
@@ -157,8 +158,8 @@
GNUNET_NAMESTORE_RF_PRIVATE = 2,
/**
- * This record was added by the system
- * and is pending user confimation
+ * This record was added automatically by the system
+ * and is pending user confimation.
*/
GNUNET_NAMESTORE_RF_PENDING = 4,
@@ -196,20 +197,16 @@
{
/**
- * Binary value stored in the DNS record.
- * FIXME: goofy API: sometimes 'data' is individually
- * 'malloc'ed, sometimes it points into some existing
- * data area (so sometimes this should be a 'void *',
- * sometimes a 'const void *'). This is unclean. We
- * should go over the code and make sure that 'data'
- * is NEVER individually alloc'ed here but always points
- * to some "other" location.
+ * Binary value stored in the DNS record. Note: "data" must never
+ * be individually 'malloc'ed, but instead always points into some
+ * existing data area.
*/
const void *data;
/**
* Expiration time for the DNS record. Can be relative
- * or absolute, depending on 'flags'.
+ * or absolute, depending on 'flags'. Measured in the same
+ * unit as GNUnet time (microseconds).
*/
uint64_t expiration_time;
Modified: gnunet/src/include/gnunet_nse_service.h
===================================================================
--- gnunet/src/include/gnunet_nse_service.h 2013-08-21 15:12:08 UTC (rev
28748)
+++ gnunet/src/include/gnunet_nse_service.h 2013-08-21 15:16:58 UTC (rev
28749)
@@ -4,7 +4,7 @@
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 2, or (at your
+ 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
@@ -26,8 +26,9 @@
* @brief 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
+ * @{
*/
#ifdef __cplusplus
@@ -80,8 +81,7 @@
*
* @param cfg the configuration to use
* @param func funtion to call with network size estimate
- * @param func_cls closure to pass for network size estimate callback
- *
+ * @param func_cls closure to pass to @a func
* @return handle to use
*/
struct GNUNET_NSE_Handle *
@@ -93,7 +93,6 @@
* Disconnect from network size estimation service
*
* @param h handle to destroy
- *
*/
void
GNUNET_NSE_disconnect (struct GNUNET_NSE_Handle *h);
@@ -106,4 +105,6 @@
}
#endif
+/** @} */ /* end of group nse */
+
#endif /* GNUNET_NSE_SERVICE_H_ */
Modified: gnunet/src/include/gnunet_program_lib.h
===================================================================
--- gnunet/src/include/gnunet_program_lib.h 2013-08-21 15:12:08 UTC (rev
28748)
+++ gnunet/src/include/gnunet_program_lib.h 2013-08-21 15:16:58 UTC (rev
28749)
@@ -1,10 +1,10 @@
/*
This file is part of GNUnet.
- (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2009 Christian Grothoff
(and other contributing authors)
+ (C) 2001-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 2, or (at your
+ 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
@@ -22,6 +22,8 @@
* @file include/gnunet_program_lib.h
* @brief functions related to starting programs
* @author Christian Grothoff
+ * @defgroup program functions for writing command-line programs
+ * @{
*/
#ifndef GNUNET_PROGRAM_LIB_H
@@ -57,16 +59,16 @@
* Run a standard GNUnet command startup sequence (initialize loggers
* and configuration, parse options).
*
- * @param argc number of command line arguments
+ * @param argc number of command line arguments in @a argv
* @param argv command line arguments
* @param binaryName our expected name
* @param binaryHelp help text for the program
* @param options command line options
* @param task main function to run
- * @param task_cls closure for task
- * @param run_without_scheduler GNUNET_NO start the scheduler, GNUNET_YES do
not
- * start the scheduler just run the main task
- * @return GNUNET_SYSERR on error, GNUNET_OK on success
+ * @param task_cls closure for @a task
+ * @param run_without_scheduler #GNUNET_NO start the scheduler,
+ * #GNUNET_YES do not start the scheduler just run the main task
+ * @return #GNUNET_SYSERR on error, #GNUNET_OK on success
*/
int
GNUNET_PROGRAM_run2 (int argc, char *const *argv, const char *binaryName,
@@ -85,8 +87,8 @@
* @param binaryHelp helptext for "-h" option (about the app)
* @param options command line options
* @param task main function to run
- * @param task_cls closure for task
- * @return GNUNET_SYSERR on error, GNUNET_OK on success
+ * @param task_cls closure for @a task
+ * @return #GNUNET_SYSERR on error, #GNUNET_OK on success
*/
int
GNUNET_PROGRAM_run (int argc, char *const *argv, const char *binaryName,
@@ -103,6 +105,8 @@
}
#endif
+/** @} */ /* end of group program */
+
/* ifndef GNUNET_PROGRAM_LIB_H */
#endif
/* end of gnunet_program_lib.h */
Modified: gnunet/src/include/gnunet_protocols.h
===================================================================
--- gnunet/src/include/gnunet_protocols.h 2013-08-21 15:12:08 UTC (rev
28748)
+++ gnunet/src/include/gnunet_protocols.h 2013-08-21 15:16:58 UTC (rev
28749)
@@ -1,10 +1,10 @@
/*
This file is part of GNUnet.
- (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2009, 2010 Christian
Grothoff (and other contributing authors)
+ (C) 2001-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 2, or (at your
+ 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
@@ -345,11 +345,6 @@
#define GNUNET_MESSAGE_TYPE_CORE_ITERATE_PEERS_END 79
/**
- * Check whether a given peer is currently connected to CORE.
- */
-#define GNUNET_MESSAGE_TYPE_CORE_PEER_CONNECTED 80
-
-/**
* Encapsulation for an encrypted message between peers.
*/
#define GNUNET_MESSAGE_TYPE_CORE_ENCRYPTED_MESSAGE 82
Modified: gnunet/src/include/gnunet_resolver_service.h
===================================================================
--- gnunet/src/include/gnunet_resolver_service.h 2013-08-21 15:12:08 UTC
(rev 28748)
+++ gnunet/src/include/gnunet_resolver_service.h 2013-08-21 15:16:58 UTC
(rev 28749)
@@ -22,6 +22,8 @@
* @file include/gnunet_resolver_service.h
* @brief functions related to doing DNS lookups
* @author Christian Grothoff
+ * @defgroup resolver asynchronous standard DNS lookups
+ * @{
*/
#ifndef GNUNET_RESOLVER_SERVICE_H
@@ -45,7 +47,7 @@
*
* @param cls closure
* @param addr one of the addresses of the host, NULL for the last address
- * @param addrlen length of the address
+ * @param addrlen length of @a addr
*/
typedef void (*GNUNET_RESOLVER_AddressCallback) (void *cls,
const struct sockaddr *addr,
@@ -80,7 +82,7 @@
* @param hostname the hostname to resolve
* @param af AF_INET or AF_INET6; use AF_UNSPEC for "any"
* @param callback function to call with addresses
- * @param callback_cls closure for callback
+ * @param callback_cls closure for @a callback
* @param timeout how long to try resolving
* @return handle that can be used to cancel the request, NULL on error
*/
@@ -96,7 +98,7 @@
*
* @param af AF_INET or AF_INET6; use AF_UNSPEC for "any"
* @param callback function to call with addresses
- * @param cls closure for callback
+ * @param cls closure for @a callback
* @param timeout how long to try resolving
* @return handle that can be used to cancel the request, NULL on error
*/
@@ -130,11 +132,11 @@
* Perform a reverse DNS lookup.
*
* @param sa host address
- * @param salen length of host address
- * @param do_resolve use GNUNET_NO to return numeric hostname
+ * @param salen length of @a sa
+ * @param do_resolve use #GNUNET_NO to return numeric hostname
* @param timeout how long to try resolving
* @param callback function to call with hostnames
- * @param cls closure for callback
+ * @param cls closure for @a callback
* @return handle that can be used to cancel the request, NULL on error
*/
struct GNUNET_RESOLVER_RequestHandle *
@@ -164,6 +166,8 @@
}
#endif
+/** @} */ /* end of group resolver */
+
/* ifndef GNUNET_RESOLVER_SERVICE_H */
#endif
/* end of gnunet_resolver_service.h */
Modified: gnunet/src/include/gnunet_server_lib.h
===================================================================
--- gnunet/src/include/gnunet_server_lib.h 2013-08-21 15:12:08 UTC (rev
28748)
+++ gnunet/src/include/gnunet_server_lib.h 2013-08-21 15:16:58 UTC (rev
28749)
@@ -21,8 +21,9 @@
/**
* @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
+ * @{
*/
#ifndef GNUNET_SERVER_LIB_H
@@ -41,7 +42,10 @@
/**
- * Largest supported message.
+ * Largest supported message (to be precise, one byte more
+ * than the largest possible message, so tests involving
+ * this value should check for messages being smaller than
+ * this value).
*/
#define GNUNET_SERVER_MAX_MESSAGE_SIZE 65536
@@ -75,13 +79,11 @@
* @param message the actual message
*/
typedef void (*GNUNET_SERVER_MessageCallback) (void *cls,
- struct GNUNET_SERVER_Client *
- client,
+ struct GNUNET_SERVER_Client
*client,
const struct
GNUNET_MessageHeader
- * message);
+ *message);
-
/**
* Message handler. Each struct specifies how to handle on particular
* type of message received.
@@ -118,10 +120,10 @@
* Create a new server.
*
* @param access function for access control
- * @param access_cls closure for access
+ * @param access_cls closure for @a access
* @param lsocks NULL-terminated array of listen sockets
* @param idle_timeout after how long should we timeout idle connections?
- * @param require_found if YES, connections sending messages of unknown type
+ * @param require_found if #GNUNET_YES, connections sending messages of
unknown type
* will be closed
* @return handle for the new server, NULL on error
* (typically, "port" already in use)
@@ -137,11 +139,11 @@
* Create a new server.
*
* @param access function for access control
- * @param access_cls closure for access
+ * @param access_cls closure for @a access
* @param serverAddr address toes listen on (including port), NULL terminated
array
- * @param socklen lengths of respective serverAddr
+ * @param socklen lengths of respective @a serverAddr
* @param idle_timeout after how long should we timeout idle connections?
- * @param require_found if YES, connections sending messages of unknown type
+ * @param require_found if #GNUNET_YES, connections sending messages of
unknown type
* will be closed
* @return handle for the new server, NULL on error
* (typically, "port" already in use)
@@ -156,6 +158,7 @@
/**
* Suspend accepting connections from the listen socket temporarily.
+ * Resume activity using #GNUNET_SERVER_resume.
*
* @param server server to stop accepting connections.
*/
@@ -173,8 +176,9 @@
/**
- * Stop the listen socket and get ready to shutdown the server
- * once only 'monitor' clients are left.
+ * Stop the listen socket and get ready to shutdown the server once
+ * only clients marked using #GNUNET_SERVER_client_mark_monitor are
+ * left.
*
* @param server server to stop listening on
*/
@@ -219,10 +223,10 @@
* @param timeout after how long should we give up (and call
* notify with buf NULL and size 0)?
* @param callback function to call when space is available
- * @param callback_cls closure for callback
+ * @param callback_cls closure for @a callback
* @return non-NULL if the notify callback was queued; can be used
* to cancel the request using
- * GNUNET_SERVER_notify_transmit_ready_cancel.
+ * #GNUNET_SERVER_notify_transmit_ready_cancel.
* NULL if we are already going to notify someone else (busy)
*/
struct GNUNET_SERVER_TransmitHandle *
@@ -245,12 +249,12 @@
/**
* Set the 'monitor' flag on this client. Clients which have been
* marked as 'monitors' won't prevent the server from shutting down
- * once 'GNUNET_SERVER_stop_listening' has been invoked. The idea is
+ * once #GNUNET_SERVER_stop_listening has been invoked. The idea is
* that for "normal" clients we likely want to allow them to process
* their requests; however, monitor-clients are likely to 'never'
* disconnect during shutdown and thus will not be considered when
* determining if the server should continue to exist after
- * 'GNUNET_SERVER_destroy' has been called.
+ * #GNUNET_SERVER_destroy has been called.
*
* @param client the client to set the 'monitor' flag on
*/
@@ -259,8 +263,11 @@
/**
- * Set the persistent flag on this client, used to setup client connection
- * to only be killed when the service it's connected to is actually dead.
+ * Set the persistent flag on this client, used to setup client
+ * connection to only be killed when the process of the service it's
+ * connected to is actually dead. This API is used during shutdown
+ * signalling within ARM, and it is not expected that typical users
+ * of the API would need this function.
*
* @param client the client to set the persistent flag on
*/
@@ -271,17 +278,18 @@
/**
* Resume receiving from this client, we are done processing the
* current request. This function must be called from within each
- * GNUNET_SERVER_MessageCallback (or its respective continuations).
+ * #GNUNET_SERVER_MessageCallback (or its respective continuations).
*
* @param client client we were processing a message of
- * @param success GNUNET_OK to keep the connection open and
+ * @param success #GNUNET_OK to keep the connection open and
* continue to receive
- * GNUNET_NO to close the connection (normal behavior)
- * GNUNET_SYSERR to close the connection (signal
+ * #GNUNET_NO to close the connection (normal behavior)
+ * #GNUNET_SYSERR to close the connection (signal
* serious error)
*/
void
-GNUNET_SERVER_receive_done (struct GNUNET_SERVER_Client *client, int success);
+GNUNET_SERVER_receive_done (struct GNUNET_SERVER_Client *client,
+ int success);
/**
@@ -297,7 +305,6 @@
struct GNUNET_TIME_Relative timeout);
-
/**
* Return user context associated with the given client.
* Note: you should probably use the macro (call without the underscore).
@@ -365,9 +372,9 @@
* @param sender the "pretended" sender of the message
* can be NULL!
* @param message message to transmit
- * @return GNUNET_OK if the message was OK and the
+ * @return #GNUNET_OK if the message was OK and the
* connection can stay open
- * GNUNET_SYSERR if the connection to the
+ * #GNUNET_SYSERR if the connection to the
* client should be shut down
*/
int
@@ -386,7 +393,7 @@
* @param connection the connection to manage (client must
* stop using this connection from now on)
* @return the client handle (client should call
- * "client_drop" on the return value eventually)
+ * #GNUNET_SERVER_client_drop on the return value eventually)
*/
struct GNUNET_SERVER_Client *
GNUNET_SERVER_connect_socket (struct GNUNET_SERVER_Handle *server,
@@ -421,12 +428,12 @@
*
* @param client the client to get the address for
* @param addr where to store the address
- * @param addrlen where to store the length of the address
- * @return GNUNET_OK on success
+ * @param addrlen where to store the length of @a addr
+ * @return #GNUNET_OK on success
*/
int
GNUNET_SERVER_client_get_address (struct GNUNET_SERVER_Client *client,
- void **addr, size_t * addrlen);
+ void **addr, size_t *addrlen);
/**
@@ -438,9 +445,9 @@
* for the last call when the server is destroyed
*/
typedef void (*GNUNET_SERVER_DisconnectCallback) (void *cls,
- struct GNUNET_SERVER_Client *
- client);
+ struct GNUNET_SERVER_Client
*client);
+
/**
* Functions with this signature are called whenever a client
* is connected on the network level.
@@ -449,10 +456,9 @@
* @param client identification of the client
*/
typedef void (*GNUNET_SERVER_ConnectCallback) (void *cls,
- struct GNUNET_SERVER_Client *client);
+ struct GNUNET_SERVER_Client
*client);
-
/**
* Ask the server to notify us whenever a client disconnects.
* This function is called whenever the actual network connection
@@ -465,7 +471,7 @@
*
* @param server the server manageing the clients
* @param callback function to call on disconnect
- * @param callback_cls closure for callback
+ * @param callback_cls closure for @a callback
*/
void
GNUNET_SERVER_disconnect_notify (struct GNUNET_SERVER_Handle *server,
@@ -477,26 +483,31 @@
* Ask the server to notify us whenever a client connects.
* This function is called whenever the actual network connection
* is opened. If the server is destroyed before this
- * notification is explicitly cancelled, the 'callback' will
+ * notification is explicitly cancelled, the @a callback will
* once be called with a 'client' argument of NULL to indicate
* that the server itself is now gone (and that the callback
* won't be called anymore and also can no longer be cancelled).
*
* @param server the server manageing the clients
* @param callback function to call on sconnect
- * @param callback_cls closure for callback
+ * @param callback_cls closure for @a callback
*/
void
GNUNET_SERVER_connect_notify (struct GNUNET_SERVER_Handle *server,
- GNUNET_SERVER_ConnectCallback callback, void *callback_cls);
+ GNUNET_SERVER_ConnectCallback callback,
+ void *callback_cls);
/**
* Ask the server to stop notifying us whenever a client disconnects.
+ * Arguments must match exactly those given to
+ * #GNUNET_SERVER_disconnect_notify. It is not necessary to call this
+ * function during shutdown of the server; in fact, most applications
+ * will never use this function.
*
* @param server the server manageing the clients
* @param callback function to call on disconnect
- * @param callback_cls closure for callback
+ * @param callback_cls closure for @a callback
*/
void
GNUNET_SERVER_disconnect_notify_cancel (struct GNUNET_SERVER_Handle *server,
@@ -506,21 +517,26 @@
/**
* Ask the server to stop notifying us whenever a client connects.
+ * Arguments must match exactly those given to
+ * #GNUNET_SERVER_connect_notify. It is not necessary to call this
+ * function during shutdown of the server; in fact, most applications
+ * will never use this function.
*
* @param server the server manageing the clients
* @param callback function to call on connect
- * @param callback_cls closure for callback
+ * @param callback_cls closure for @a callback
*/
void
GNUNET_SERVER_connect_notify_cancel (struct GNUNET_SERVER_Handle *server,
- GNUNET_SERVER_ConnectCallback callback, void *callback_cls);
+ GNUNET_SERVER_ConnectCallback callback,
+ void *callback_cls);
/**
- * Ask the server to disconnect from the given client.
- * This is the same as returning GNUNET_SYSERR from a message
- * handler, except that it allows dropping of a client even
- * when not handling a message from that client.
+ * Ask the server to disconnect from the given client. This is the
+ * same as passing #GNUNET_SYSERR to #GNUNET_SERVER_receive_done,
+ * except that it allows dropping of a client even when not handling a
+ * message from that client.
*
* @param client the client to disconnect from
*/
@@ -534,7 +550,7 @@
* instead of potentially buffering multiple messages.
*
* @param client handle to the client
- * @return GNUNET_OK on success
+ * @return #GNUNET_OK on success
*/
int
GNUNET_SERVER_client_disable_corking (struct GNUNET_SERVER_Client *client);
@@ -549,8 +565,7 @@
/**
- * Create a new transmission context for the
- * given client.
+ * Create a new transmission context for the given client.
*
* @param client client to create the context for.
* @return NULL on error
@@ -562,11 +577,11 @@
/**
* Append a message to the transmission context.
* All messages in the context will be sent by
- * the transmit_context_run method.
+ * the #GNUNET_SERVER_transmit_context_run method.
*
* @param tc context to use
* @param data what to append to the result message
- * @param length length of data
+ * @param length length of @a data
* @param type type of the message
*/
void
@@ -594,7 +609,7 @@
/**
* Execute a transmission context. If there is an error in the
* transmission, the receive_done method will be called with an error
- * code (GNUNET_SYSERR), otherwise with GNUNET_OK.
+ * code (#GNUNET_SYSERR), otherwise with #GNUNET_OK.
*
* @param tc transmission context to use
* @param timeout when to time out and abort the transmission
@@ -606,14 +621,14 @@
/**
* Destroy a transmission context. This function must not be called
- * after 'GNUNET_SERVER_transmit_context_run'.
+ * after #GNUNET_SERVER_transmit_context_run.
*
* @param tc transmission context to destroy
- * @param success code to give to 'GNUNET_SERVER_receive_done' for
- * the client: GNUNET_OK to keep the connection open and
+ * @param success code to give to #GNUNET_SERVER_receive_done for
+ * the client: #GNUNET_OK to keep the connection open and
* continue to receive
- * GNUNET_NO to close the connection (normal behavior)
- * GNUNET_SYSERR to close the connection (signal
+ * #GNUNET_NO to close the connection (normal behavior)
+ * #GNUNET_SYSERR to close the connection (signal
* serious error)
*/
void
@@ -702,23 +717,23 @@
*msg, int can_drop);
-
/**
* Handle to a message stream tokenizer.
*/
struct GNUNET_SERVER_MessageStreamTokenizer;
+
/**
* Functions with this signature are called whenever a
* complete message is received by the tokenizer.
*
- * Do not call GNUNET_SERVER_mst_destroy in callback
+ * Do not call #GNUNET_SERVER_mst_destroy from within
+ * the scope of this callback.
*
* @param cls closure
* @param client identification of the client
* @param message the actual message
- *
- * @return GNUNET_OK on success, GNUNET_SYSERR to stop further processing
+ * @return #GNUNET_OK on success, #GNUNET_SYSERR to stop further processing
*/
typedef int (*GNUNET_SERVER_MessageTokenizerCallback) (void *cls, void *client,
const struct
@@ -730,7 +745,7 @@
* Create a message stream tokenizer.
*
* @param cb function to call on completed messages
- * @param cb_cls closure for cb
+ * @param cb_cls closure for @a cb
* @return handle to tokenizer
*/
struct GNUNET_SERVER_MessageStreamTokenizer *
@@ -746,13 +761,13 @@
* @param client_identity ID of client for which this is a buffer,
* can be NULL (will be passed back to 'cb')
* @param buf input data to add
- * @param size number of bytes in buf
+ * @param size number of bytes in @a buf
* @param purge should any excess bytes in the buffer be discarded
* (i.e. for packet-based services like UDP)
* @param one_shot only call callback once, keep rest of message in buffer
- * @return GNUNET_OK if we are done processing (need more data)
- * GNUNET_NO if one_shot was set and we have another message ready
- * GNUNET_SYSERR if the data stream is corrupt
+ * @return #GNUNET_OK if we are done processing (need more data)
+ * #GNUNET_NO if one_shot was set and we have another message ready
+ * #GNUNET_SYSERR if the data stream is corrupt
*/
int
GNUNET_SERVER_mst_receive (struct GNUNET_SERVER_MessageStreamTokenizer *mst,
@@ -779,6 +794,7 @@
typedef void* (*GNUNET_SERVER_MstCreateCallback) (void *cls,
struct GNUNET_SERVER_Client
*client);
+
/**
* Signature of a function to destroy a custom tokenizer.
*
@@ -787,21 +803,22 @@
*/
typedef void (*GNUNET_SERVER_MstDestroyCallback) (void *cls, void *mst);
+
/**
* Signature of a function to receive data for a custom tokenizer.
*
- * @param cls closure from 'GNUNET_SERVER_set_callbacks'
+ * @param cls closure from #GNUNET_SERVER_set_callbacks
* @param mst custom tokenizer handle
* @param client_identity ID of client for which this is a buffer,
* can be NULL (will be passed back to 'cb')
* @param buf input data to add
- * @param size number of bytes in buf
+ * @param size number of bytes in @a buf
* @param purge should any excess bytes in the buffer be discarded
* (i.e. for packet-based services like UDP)
* @param one_shot only call callback once, keep rest of message in buffer
- * @return GNUNET_OK if we are done processing (need more data)
- * GNUNET_NO if one_shot was set and we have another message ready
- * GNUNET_SYSERR if the data stream is corrupt
+ * @return #GNUNET_OK if we are done processing (need more data)
+ * #GNUNET_NO if one_shot was set and we have another message ready
+ * #GNUNET_SYSERR if the data stream is corrupt
*/
typedef int (*GNUNET_SERVER_MstReceiveCallback) (void *cls, void *mst,
struct GNUNET_SERVER_Client
*client,
@@ -817,7 +834,7 @@
* @param create new tokenizer initialization function
* @param destroy new tokenizer destruction function
* @param receive new tokenizer receive function
- * @param cls closure for 'create', 'receive', 'destroy'
+ * @param cls closure for @a create, @a receive and @a destroy
*/
void
GNUNET_SERVER_set_callbacks (struct GNUNET_SERVER_Handle *server,
@@ -834,6 +851,7 @@
}
#endif
+/** @} */ /* end of group server */
/* ifndef GNUNET_SERVER_LIB_H */
#endif
Modified: gnunet/src/include/gnunet_service_lib.h
===================================================================
--- gnunet/src/include/gnunet_service_lib.h 2013-08-21 15:12:08 UTC (rev
28748)
+++ gnunet/src/include/gnunet_service_lib.h 2013-08-21 15:16:58 UTC (rev
28749)
@@ -1,10 +1,10 @@
/*
This file is part of GNUnet.
- (C) 2009 Christian Grothoff (and other contributing authors)
+ (C) 2009-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 2, or (at your
+ 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
@@ -22,6 +22,8 @@
* @file include/gnunet_service_lib.h
* @brief functions related to starting services
* @author Christian Grothoff
+ * @defgroup service generic functions for implementing service processes
+ * @{
*/
#ifndef GNUNET_SERVICE_LIB_H
@@ -49,21 +51,21 @@
* addresses the server should bind to and listen on; the
* array will be NULL-terminated (on success)
* @param addr_lens set (call by reference) to an array of the lengths
- * of the respective 'struct sockaddr' struct in the 'addrs'
+ * of the respective 'struct sockaddr' struct in the @a addrs
* array (on success)
* @return number of addresses found on success,
- * GNUNET_SYSERR if the configuration
+ * #GNUNET_SYSERR if the configuration
* did not specify reasonable finding information or
* if it specified a hostname that could not be resolved;
- * GNUNET_NO if the number of addresses configured is
- * zero (in this case, '*addrs' and '*addr_lens' will be
+ * #GNUNET_NO if the number of addresses configured is
+ * zero (in this case, '* @a addrs' and '* @a addr_lens' will be
* set to NULL).
*/
int
GNUNET_SERVICE_get_server_addresses (const char *service_name,
const struct GNUNET_CONFIGURATION_Handle
*cfg, struct sockaddr ***addrs,
- socklen_t ** addr_lens);
+ socklen_t **addr_lens);
/**
@@ -75,9 +77,8 @@
* @param cfg configuration to use
*/
typedef void (*GNUNET_SERVICE_Main) (void *cls,
- struct GNUNET_SERVER_Handle * server,
- const struct GNUNET_CONFIGURATION_Handle *
- cfg);
+ struct GNUNET_SERVER_Handle *server,
+ const struct GNUNET_CONFIGURATION_Handle
*cfg);
/**
@@ -108,19 +109,21 @@
* Run a standard GNUnet service startup sequence (initialize loggers
* and configuration, parse options).
*
- * @param argc number of command line arguments
+ * @param argc number of command line arguments in @a argv
* @param argv command line arguments
* @param service_name our service name
* @param options service options
* @param task main task of the service
- * @param task_cls closure for task
- * @return GNUNET_SYSERR on error, GNUNET_OK
+ * @param task_cls closure for @a task
+ * @return #GNUNET_SYSERR on error, #GNUNET_OK
* if we shutdown nicely
*/
int
-GNUNET_SERVICE_run (int argc, char *const *argv, const char *service_name,
+GNUNET_SERVICE_run (int argc, char *const *argv,
+ const char *service_name,
enum GNUNET_SERVICE_Options options,
- GNUNET_SERVICE_Main task, void *task_cls);
+ GNUNET_SERVICE_Main task,
+ void *task_cls);
/**
@@ -128,6 +131,7 @@
*/
struct GNUNET_SERVICE_Context;
+
/**
* Run a service startup sequence within an existing
* initialized system.
@@ -155,7 +159,7 @@
/**
- * Stop a service that was started with "GNUNET_SERVICE_start".
+ * Stop a service that was started with #GNUNET_SERVICE_start.
*
* @param sctx the service context returned from the start function
*/
@@ -170,6 +174,10 @@
}
#endif
+
+/** @} */ /* end of group service */
+
+
/* ifndef GNUNET_SERVICE_LIB_H */
#endif
/* end of gnunet_service_lib.h */
Modified: gnunet/src/include/gnunet_signal_lib.h
===================================================================
--- gnunet/src/include/gnunet_signal_lib.h 2013-08-21 15:12:08 UTC (rev
28748)
+++ gnunet/src/include/gnunet_signal_lib.h 2013-08-21 15:16:58 UTC (rev
28749)
@@ -4,7 +4,7 @@
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 2, or (at your
+ 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
Modified: gnunet/src/include/gnunet_statistics_service.h
===================================================================
--- gnunet/src/include/gnunet_statistics_service.h 2013-08-21 15:12:08 UTC
(rev 28748)
+++ gnunet/src/include/gnunet_statistics_service.h 2013-08-21 15:16:58 UTC
(rev 28749)
@@ -1,10 +1,10 @@
/*
This file is part of GNUnet
- (C) 2009, 2010 Christian Grothoff (and other contributing authors)
+ (C) 2009-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 2, or (at your
+ 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
@@ -24,6 +24,8 @@
* 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
+ * @{
*/
#ifndef GNUNET_STATISTICS_SERVICE_H
@@ -58,8 +60,8 @@
* @param subsystem name of subsystem that created the statistic
* @param name the name of the datum
* @param value the current value
- * @param is_persistent GNUNET_YES if the value is persistent, GNUNET_NO if not
- * @return GNUNET_OK to continue, GNUNET_SYSERR to abort iteration
+ * @param is_persistent #GNUNET_YES if the value is persistent, #GNUNET_NO if
not
+ * @return #GNUNET_OK to continue, #GNUNET_SYSERR to abort iteration
*/
typedef int (*GNUNET_STATISTICS_Iterator) (void *cls, const char *subsystem,
const char *name, uint64_t value,
@@ -82,7 +84,7 @@
* it).
*
* @param h statistics handle to destroy
- * @param sync_first set to GNUNET_YES if pending SET requests should
+ * @param sync_first set to #GNUNET_YES if pending SET requests should
* be completed
*/
void
@@ -96,8 +98,8 @@
* @param subsystem limit to the specified subsystem, never NULL
* @param name name of the statistic value, never NULL
* @param proc function to call on each value
- * @param proc_cls closure for proc
- * @return GNUNET_OK on success, GNUNET_SYSERR on error
+ * @param proc_cls closure for @a proc
+ * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
*/
int
GNUNET_STATISTICS_watch (struct GNUNET_STATISTICS_Handle *handle,
@@ -112,8 +114,8 @@
* @param subsystem limit to the specified subsystem, never NULL
* @param name name of the statistic value, never NULL
* @param proc function to call on each value
- * @param proc_cls closure for proc
- * @return GNUNET_OK on success, GNUNET_SYSERR on error (no such watch)
+ * @param proc_cls closure for @a proc
+ * @return #GNUNET_OK on success, #GNUNET_SYSERR on error (no such watch)
*/
int
GNUNET_STATISTICS_watch_cancel (struct GNUNET_STATISTICS_Handle *handle,
@@ -122,11 +124,12 @@
/**
- * Continuation called by the "get_all" and "get" functions.
+ * Continuation called by the #GNUNET_STATISTICS_get_all
+ * and #GNUNET_STATISTICS_get functions.
*
* @param cls closure
- * @param success GNUNET_OK if statistics were
- * successfully obtained, GNUNET_SYSERR if not.
+ * @param success #GNUNET_OK if statistics were
+ * successfully obtained, #GNUNET_SYSERR if not.
*/
typedef void (*GNUNET_STATISTICS_Callback) (void *cls, int success);
@@ -136,6 +139,7 @@
*/
struct GNUNET_STATISTICS_GetHandle;
+
/**
* Get statistic from the peer.
*
@@ -147,7 +151,7 @@
* @param cont continuation to call when done (can be NULL)
* This callback CANNOT destroy the statistics handle in the same call.
* @param proc function to call on each value
- * @param cls closure for proc and cont
+ * @param cls closure for @a proc and @a cont
* @return NULL on error
*/
struct GNUNET_STATISTICS_GetHandle *
@@ -159,7 +163,7 @@
/**
- * Cancel a 'get' request. Must be called before the 'cont'
+ * Cancel a #GNUNET_STATISICS_get request. Must be called before the 'cont'
* function is called.
*
* @param gh handle of the request to cancel
@@ -181,6 +185,7 @@
GNUNET_STATISTICS_set (struct GNUNET_STATISTICS_Handle *handle,
const char *name, uint64_t value, int make_persistent);
+
/**
* Set statistic value for the peer. Will always use our
* subsystem (the argument used when "handle" was created).
@@ -203,4 +208,6 @@
}
#endif
+/** @} */ /* end of group statistics */
+
#endif
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [GNUnet-SVN] r28749 - gnunet/src/include,
gnunet <=