aboutsummaryrefslogtreecommitdiff
path: root/src
diff options
context:
space:
mode:
authorChristian Grothoff <christian@grothoff.org>2013-08-21 15:16:58 +0000
committerChristian Grothoff <christian@grothoff.org>2013-08-21 15:16:58 +0000
commit5a38c8f0d1826ea964e3e3452e1a3a2a24d7d35b (patch)
tree7ba261fc1882bcfa6dc0da916272a0ed0d17468e /src
parent1fca0c918c8468ba16666e8a1c41526cacdc6df2 (diff)
downloadgnunet-5a38c8f0d1826ea964e3e3452e1a3a2a24d7d35b.tar.gz
gnunet-5a38c8f0d1826ea964e3e3452e1a3a2a24d7d35b.zip
-misc doxygen fixes
Diffstat (limited to 'src')
-rw-r--r--src/include/gnunet_block_plugin.h53
-rw-r--r--src/include/gnunet_client_lib.h30
-rw-r--r--src/include/gnunet_container_lib.h284
-rw-r--r--src/include/gnunet_core_service.h51
-rw-r--r--src/include/gnunet_crypto_lib.h6
-rw-r--r--src/include/gnunet_dht_service.h2
-rw-r--r--src/include/gnunet_disk_lib.h2
-rw-r--r--src/include/gnunet_getopt_lib.h32
-rw-r--r--src/include/gnunet_identity_service.h37
-rw-r--r--src/include/gnunet_mq_lib.h41
-rw-r--r--src/include/gnunet_namestore_service.h19
-rw-r--r--src/include/gnunet_nse_service.h11
-rw-r--r--src/include/gnunet_program_lib.h22
-rw-r--r--src/include/gnunet_protocols.h9
-rw-r--r--src/include/gnunet_resolver_service.h16
-rw-r--r--src/include/gnunet_server_lib.h162
-rw-r--r--src/include/gnunet_service_lib.h40
-rw-r--r--src/include/gnunet_signal_lib.h2
-rw-r--r--src/include/gnunet_statistics_service.h35
19 files changed, 496 insertions, 358 deletions
diff --git a/src/include/gnunet_block_plugin.h b/src/include/gnunet_block_plugin.h
index ac549fec7..aadfdb5a4 100644
--- a/src/include/gnunet_block_plugin.h
+++ b/src/include/gnunet_block_plugin.h
@@ -1,6 +1,6 @@
1/* 1/*
2 This file is part of GNUnet 2 This file is part of GNUnet
3 (C) 2010 Christian Grothoff (and other contributing authors) 3 (C) 2010,2013 Christian Grothoff (and other contributing authors)
4 4
5 GNUnet is free software; you can redistribute it and/or modify 5 GNUnet is free software; you can redistribute it and/or modify
6 it under the terms of the GNU General Public License as published 6 it under the terms of the GNU General Public License as published
@@ -23,18 +23,19 @@
23 * @brief API for block plugins. Each block plugin must conform to 23 * @brief API for block plugins. Each block plugin must conform to
24 * the API specified by this header. 24 * the API specified by this header.
25 * @author Christian Grothoff 25 * @author Christian Grothoff
26 * @defgroup block API to be implemented by applications storing data in the DHT
27 * @{
26 */ 28 */
27#ifndef PLUGIN_BLOCK_H 29#ifndef PLUGIN_BLOCK_H
28#define PLUGIN_BLOCK_H 30#define PLUGIN_BLOCK_H
29 31
30#include "gnunet_util_lib.h" 32#include "gnunet_util_lib.h"
31#include "gnunet_container_lib.h"
32#include "gnunet_block_lib.h" 33#include "gnunet_block_lib.h"
33 34
34 35
35/** 36/**
36 * Function called to validate a reply or a request. For 37 * Function called to validate a reply or a request. For
37 * request evaluation, simply pass "NULL" for the reply_block. 38 * request evaluation, simply pass "NULL" for the @a reply_block.
38 * Note that it is assumed that the reply has already been 39 * Note that it is assumed that the reply has already been
39 * matched to the key (and signatures checked) as it would 40 * matched to the key (and signatures checked) as it would
40 * be done with the "get_key" function. 41 * be done with the "get_key" function.
@@ -43,34 +44,23 @@
43 * @param type block type 44 * @param type block type
44 * @param query original query (hash) 45 * @param query original query (hash)
45 * @param bf pointer to bloom filter associated with query; possibly updated (!) 46 * @param bf pointer to bloom filter associated with query; possibly updated (!)
46 * @param bf_mutator mutation value for bf 47 * @param bf_mutator mutation value for @a bf
47 * @param xquery extrended query data (can be NULL, depending on type) 48 * @param xquery extrended query data (can be NULL, depending on type)
48 * @param xquery_size number of bytes in xquery 49 * @param xquery_size number of bytes in @a xquery
49 * @param reply_block response to validate 50 * @param reply_block response to validate
50 * @param reply_block_size number of bytes in reply block 51 * @param reply_block_size number of bytes in @a reply_block
51 * @return characterization of result 52 * @return characterization of result
52 */ 53 */
53typedef enum 54typedef enum GNUNET_BLOCK_EvaluationResult
54 GNUNET_BLOCK_EvaluationResult (*GNUNET_BLOCK_EvaluationFunction) (void *cls, 55(*GNUNET_BLOCK_EvaluationFunction) (void *cls,
55 enum 56 enum GNUNET_BLOCK_Type type,
56 GNUNET_BLOCK_Type 57 const struct GNUNET_HashCode *query,
57 type, 58 struct GNUNET_CONTAINER_BloomFilter **bf,
58 const 59 int32_t bf_mutator,
59 struct GNUNET_HashCode 60 const void *xquery,
60 * query, 61 size_t xquery_size,
61 struct 62 const void *reply_block,
62 GNUNET_CONTAINER_BloomFilter 63 size_t reply_block_size);
63 ** bf,
64 int32_t
65 bf_mutator,
66 const void
67 *xquery,
68 size_t
69 xquery_size,
70 const void
71 *reply_block,
72 size_t
73 reply_block_size);
74 64
75 65
76/** 66/**
@@ -79,11 +69,11 @@ typedef enum
79 * @param cls closure 69 * @param cls closure
80 * @param type block type 70 * @param type block type
81 * @param block block to get the key for 71 * @param block block to get the key for
82 * @param block_size number of bytes in block 72 * @param block_size number of bytes in @a block
83 * @param key set to the key (query) for the given block 73 * @param key set to the key (query) for the given block
84 * @return GNUNET_YES on success, 74 * @return #GNUNET_YES on success,
85 * GNUNET_NO if the block is malformed 75 * #GNUNET_NO if the block is malformed
86 * GNUNET_SYSERR if type not supported 76 * #GNUNET_SYSERR if type not supported
87 * (or if extracting a key from a block of this type does not work) 77 * (or if extracting a key from a block of this type does not work)
88 */ 78 */
89typedef int (*GNUNET_BLOCK_GetKeyFunction) (void *cls, 79typedef int (*GNUNET_BLOCK_GetKeyFunction) (void *cls,
@@ -124,5 +114,6 @@ struct GNUNET_BLOCK_PluginFunctions
124 114
125}; 115};
126 116
117/** @} */ /* end of group block */
127 118
128#endif 119#endif
diff --git a/src/include/gnunet_client_lib.h b/src/include/gnunet_client_lib.h
index a2a7bd542..d6eaca56a 100644
--- a/src/include/gnunet_client_lib.h
+++ b/src/include/gnunet_client_lib.h
@@ -22,6 +22,8 @@
22 * @file include/gnunet_client_lib.h 22 * @file include/gnunet_client_lib.h
23 * @brief functions related to accessing services 23 * @brief functions related to accessing services
24 * @author Christian Grothoff 24 * @author Christian Grothoff
25 * @defgroup client Generic client-side communication with services
26 * @{
25 */ 27 */
26 28
27#ifndef GNUNET_CLIENT_LIB_H 29#ifndef GNUNET_CLIENT_LIB_H
@@ -92,7 +94,7 @@ typedef void (*GNUNET_CLIENT_MessageHandler) (void *cls,
92 * 94 *
93 * @param client connection to the service 95 * @param client connection to the service
94 * @param handler function to call with the message 96 * @param handler function to call with the message
95 * @param handler_cls closure for handler 97 * @param handler_cls closure for @a handler
96 * @param timeout how long to wait until timing out 98 * @param timeout how long to wait until timing out
97 */ 99 */
98void 100void
@@ -115,17 +117,17 @@ struct GNUNET_CLIENT_TransmitHandle;
115 * @param client connection to the service 117 * @param client connection to the service
116 * @param size number of bytes to send 118 * @param size number of bytes to send
117 * @param timeout after how long should we give up (and call 119 * @param timeout after how long should we give up (and call
118 * notify with buf NULL and size 0)? 120 * @a notify with buf NULL and size 0)?
119 * @param auto_retry if the connection to the service dies, should we 121 * @param auto_retry if the connection to the service dies, should we
120 * automatically re-connect and retry (within the timeout period) 122 * automatically re-connect and retry (within the timeout period)
121 * or should we immediately fail in this case? Pass GNUNET_YES 123 * or should we immediately fail in this case? Pass #GNUNET_YES
122 * if the caller does not care about temporary connection errors, 124 * if the caller does not care about temporary connection errors,
123 * for example because the protocol is stateless 125 * for example because the protocol is stateless
124 * @param notify function to call 126 * @param notify function to call
125 * @param notify_cls closure for notify 127 * @param notify_cls closure for @a notify
126 * @return NULL if someone else is already waiting to be notified 128 * @return NULL if someone else is already waiting to be notified
127 * non-NULL if the notify callback was queued (can be used to cancel 129 * non-NULL if the notify callback was queued (can be used to cancel
128 * using GNUNET_CONNECTION_notify_transmit_ready_cancel) 130 * using #GNUNET_CONNECTION_notify_transmit_ready_cancel)
129 */ 131 */
130struct GNUNET_CLIENT_TransmitHandle * 132struct GNUNET_CLIENT_TransmitHandle *
131GNUNET_CLIENT_notify_transmit_ready (struct GNUNET_CLIENT_Connection *client, 133GNUNET_CLIENT_notify_transmit_ready (struct GNUNET_CLIENT_Connection *client,
@@ -159,12 +161,12 @@ GNUNET_CLIENT_notify_transmit_ready_cancel (struct GNUNET_CLIENT_TransmitHandle
159 * and for waiting for a response) 161 * and for waiting for a response)
160 * @param auto_retry if the connection to the service dies, should we 162 * @param auto_retry if the connection to the service dies, should we
161 * automatically re-connect and retry (within the timeout period) 163 * automatically re-connect and retry (within the timeout period)
162 * or should we immediately fail in this case? Pass GNUNET_YES 164 * or should we immediately fail in this case? Pass #GNUNET_YES
163 * if the caller does not care about temporary connection errors, 165 * if the caller does not care about temporary connection errors,
164 * for example because the protocol is stateless 166 * for example because the protocol is stateless
165 * @param rn function to call with the response 167 * @param rn function to call with the response
166 * @param rn_cls closure for rn 168 * @param rn_cls closure for @a rn
167 * @return GNUNET_OK on success, GNUNET_SYSERR if a request 169 * @return #GNUNET_OK on success, #GNUNET_SYSERR if a request
168 * is already pending 170 * is already pending
169 */ 171 */
170int 172int
@@ -185,9 +187,9 @@ struct GNUNET_CLIENT_TestHandle;
185 * Function called with the result on the service test. 187 * Function called with the result on the service test.
186 * 188 *
187 * @param cls closure 189 * @param cls closure
188 * @param result GNUNET_YES if the service is running, 190 * @param result #GNUNET_YES if the service is running,
189 * GNUNET_NO if the service is not running 191 * #GNUNET_NO if the service is not running
190 * GNUNET_SYSERR if the configuration is invalid 192 * #GNUNET_SYSERR if the configuration is invalid
191 */ 193 */
192typedef void (*GNUNET_CLIENT_TestResultCallback)(void *cls, 194typedef void (*GNUNET_CLIENT_TestResultCallback)(void *cls,
193 int result); 195 int result);
@@ -201,9 +203,9 @@ typedef void (*GNUNET_CLIENT_TestResultCallback)(void *cls,
201 * 203 *
202 * @param service name of the service to wait for 204 * @param service name of the service to wait for
203 * @param cfg configuration to use 205 * @param cfg configuration to use
204 * @param timeout how long to wait at most in ms 206 * @param timeout how long to wait at most
205 * @param cb function to call with the result 207 * @param cb function to call with the result
206 * @param cb_cls closure for 'cb' 208 * @param cb_cls closure for @a cb
207 * @return handle to cancel the test 209 * @return handle to cancel the test
208 */ 210 */
209struct GNUNET_CLIENT_TestHandle * 211struct GNUNET_CLIENT_TestHandle *
@@ -229,6 +231,8 @@ GNUNET_CLIENT_service_test_cancel (struct GNUNET_CLIENT_TestHandle *th);
229} 231}
230#endif 232#endif
231 233
234/** @} */ /* end of group client */
235
232/* ifndef GNUNET_CLIENT_LIB_H */ 236/* ifndef GNUNET_CLIENT_LIB_H */
233#endif 237#endif
234/* end of gnunet_client_lib.h */ 238/* end of gnunet_client_lib.h */
diff --git a/src/include/gnunet_container_lib.h b/src/include/gnunet_container_lib.h
index c0aa176c5..a808c52a6 100644
--- a/src/include/gnunet_container_lib.h
+++ b/src/include/gnunet_container_lib.h
@@ -1,10 +1,10 @@
1/* 1/*
2 This file is part of GNUnet. 2 This file is part of GNUnet.
3 (C) 2001, 2002, 2003, 2004, 2005, 2006, 2008, 2009, 2010 Christian Grothoff (and other contributing authors) 3 (C) 2001-2013 Christian Grothoff (and other contributing authors)
4 4
5 GNUnet is free software; you can redistribute it and/or modify 5 GNUnet is free software; you can redistribute it and/or modify
6 it under the terms of the GNU General Public License as published 6 it under the terms of the GNU General Public License as published
7 by the Free Software Foundation; either version 2, or (at your 7 by the Free Software Foundation; either version 3, or (at your
8 option) any later version. 8 option) any later version.
9 9
10 GNUnet is distributed in the hope that it will be useful, but 10 GNUnet is distributed in the hope that it will be useful, but
@@ -21,9 +21,13 @@
21/** 21/**
22 * @file include/gnunet_container_lib.h 22 * @file include/gnunet_container_lib.h
23 * @brief container classes for GNUnet 23 * @brief container classes for GNUnet
24 *
25 * @author Christian Grothoff 24 * @author Christian Grothoff
26 * @author Nils Durner 25 * @author Nils Durner
26 * @defgroup hashmap multi hash-map
27 * @defgroup heap min- or max-heap with arbitrary element removal
28 * @defgroup bloomfilter Bloom filter (probabilistic set tests)
29 * @defgroup dll Doubly-linked list
30 * @defgroup metadata Meta data (GNU libextractor key-value pairs)
27 */ 31 */
28 32
29#ifndef GNUNET_CONTAINER_LIB_H 33#ifndef GNUNET_CONTAINER_LIB_H
@@ -51,28 +55,31 @@ extern "C"
51 55
52/** 56/**
53 * @brief bloomfilter representation (opaque) 57 * @brief bloomfilter representation (opaque)
58 * @ingroup bloomfilter
54 */ 59 */
55struct GNUNET_CONTAINER_BloomFilter; 60struct GNUNET_CONTAINER_BloomFilter;
56 61
57/** 62/**
58 * Iterator over HashCodes. 63 * @ingroup bloomfilter
64 * Iterator over struct GNUNET_HashCodes.
59 * 65 *
60 * @param cls closure 66 * @param cls closure
61 * @param next set to the next hash code 67 * @param next set to the next hash code
62 * @return GNUNET_YES if next was updated 68 * @return #GNUNET_YES if next was updated
63 * GNUNET_NO if there are no more entries 69 * #GNUNET_NO if there are no more entries
64 */ 70 */
65typedef int (*GNUNET_HashCodeIterator) (void *cls, struct GNUNET_HashCode * next); 71typedef int (*GNUNET_HashCodeIterator) (void *cls, struct GNUNET_HashCode * next);
66 72
67 73
68/** 74/**
69 * Load a bloom-filter from a file. 75 * @ingroup bloomfilter
76 * Load a Bloom filter from a file.
70 * 77 *
71 * @param filename the name of the file (or the prefix) 78 * @param filename the name of the file (or the prefix)
72 * @param size the size of the bloom-filter (number of 79 * @param size the size of the bloom-filter (number of
73 * bytes of storage space to use); will be rounded up 80 * bytes of storage space to use); will be rounded up
74 * to next power of 2 81 * to next power of 2
75 * @param k the number of GNUNET_CRYPTO_hash-functions to apply per 82 * @param k the number of #GNUNET_CRYPTO_hash-functions to apply per
76 * element (number of bits set per element in the set) 83 * element (number of bits set per element in the set)
77 * @return the bloomfilter 84 * @return the bloomfilter
78 */ 85 */
@@ -82,15 +89,16 @@ GNUNET_CONTAINER_bloomfilter_load (const char *filename, size_t size,
82 89
83 90
84/** 91/**
85 * Create a bloom filter from raw bits. 92 * @ingroup bloomfilter
93 * Create a Bloom filter from raw bits.
86 * 94 *
87 * @param data the raw bits in memory (maybe NULL, 95 * @param data the raw bits in memory (maybe NULL,
88 * in which case all bits should be considered 96 * in which case all bits should be considered
89 * to be zero). 97 * to be zero).
90 * @param size the size of the bloom-filter (number of 98 * @param size the size of the bloom-filter (number of
91 * bytes of storage space to use); also size of data 99 * bytes of storage space to use); also size of @a data
92 * -- unless data is NULL. Must be a power of 2. 100 * -- unless data is NULL. Must be a power of 2.
93 * @param k the number of GNUNET_CRYPTO_hash-functions to apply per 101 * @param k the number of #GNUNET_CRYPTO_hash-functions to apply per
94 * element (number of bits set per element in the set) 102 * element (number of bits set per element in the set)
95 * @return the bloomfilter 103 * @return the bloomfilter
96 */ 104 */
@@ -100,12 +108,13 @@ GNUNET_CONTAINER_bloomfilter_init (const char *data, size_t size,
100 108
101 109
102/** 110/**
103 * Copy the raw data of this bloomfilter into 111 * @ingroup bloomfilter
112 * Copy the raw data of this Bloom filter into
104 * the given data array. 113 * the given data array.
105 * 114 *
106 * @param data where to write the data 115 * @param data where to write the data
107 * @param size the size of the given data array 116 * @param size the size of the given @a data array
108 * @return GNUNET_SYSERR if the data array of the wrong size 117 * @return #GNUNET_SYSERR if the data array of the wrong size
109 */ 118 */
110int 119int
111GNUNET_CONTAINER_bloomfilter_get_raw_data (const struct 120GNUNET_CONTAINER_bloomfilter_get_raw_data (const struct
@@ -114,10 +123,12 @@ GNUNET_CONTAINER_bloomfilter_get_raw_data (const struct
114 123
115 124
116/** 125/**
126 * @ingroup bloomfilter
117 * Test if an element is in the filter. 127 * Test if an element is in the filter.
128 *
118 * @param e the element 129 * @param e the element
119 * @param bf the filter 130 * @param bf the filter
120 * @return GNUNET_YES if the element is in the filter, GNUNET_NO if not 131 * @return #GNUNET_YES if the element is in the filter, #GNUNET_NO if not
121 */ 132 */
122int 133int
123GNUNET_CONTAINER_bloomfilter_test (const struct GNUNET_CONTAINER_BloomFilter 134GNUNET_CONTAINER_bloomfilter_test (const struct GNUNET_CONTAINER_BloomFilter
@@ -125,7 +136,9 @@ GNUNET_CONTAINER_bloomfilter_test (const struct GNUNET_CONTAINER_BloomFilter
125 136
126 137
127/** 138/**
128 * Add an element to the filter 139 * @ingroup bloomfilter
140 * Add an element to the filter.
141 *
129 * @param bf the filter 142 * @param bf the filter
130 * @param e the element 143 * @param e the element
131 */ 144 */
@@ -135,7 +148,9 @@ GNUNET_CONTAINER_bloomfilter_add (struct GNUNET_CONTAINER_BloomFilter *bf,
135 148
136 149
137/** 150/**
151 * @ingroup bloomfilter
138 * Remove an element from the filter. 152 * Remove an element from the filter.
153 *
139 * @param bf the filter 154 * @param bf the filter
140 * @param e the element to remove 155 * @param e the element to remove
141 */ 156 */
@@ -145,6 +160,7 @@ GNUNET_CONTAINER_bloomfilter_remove (struct GNUNET_CONTAINER_BloomFilter *bf,
145 160
146 161
147/** 162/**
163 * @ingroup bloomfilter
148 * Create a copy of a bloomfilter. 164 * Create a copy of a bloomfilter.
149 * 165 *
150 * @param bf the filter 166 * @param bf the filter
@@ -157,9 +173,11 @@ GNUNET_CONTAINER_bloomfilter_copy (const struct GNUNET_CONTAINER_BloomFilter
157 173
158 174
159/** 175/**
176 * @ingroup bloomfilter
160 * Free the space associcated with a filter 177 * Free the space associcated with a filter
161 * in memory, flush to drive if needed (do not 178 * in memory, flush to drive if needed (do not
162 * free the space on the drive) 179 * free the space on the drive).
180 *
163 * @param bf the filter 181 * @param bf the filter
164 */ 182 */
165void 183void
@@ -167,6 +185,7 @@ GNUNET_CONTAINER_bloomfilter_free (struct GNUNET_CONTAINER_BloomFilter *bf);
167 185
168 186
169/** 187/**
188 * @ingroup bloomfilter
170 * Get size of the bloom filter. 189 * Get size of the bloom filter.
171 * 190 *
172 * @param bf the filter 191 * @param bf the filter
@@ -178,52 +197,58 @@ GNUNET_CONTAINER_bloomfilter_get_size (const struct GNUNET_CONTAINER_BloomFilter
178 197
179 198
180/** 199/**
181 * Reset a bloom filter to empty. 200 * @ingroup bloomfilter
201 * Reset a Bloom filter to empty.
202 *
182 * @param bf the filter 203 * @param bf the filter
183 */ 204 */
184void 205void
185GNUNET_CONTAINER_bloomfilter_clear (struct GNUNET_CONTAINER_BloomFilter *bf); 206GNUNET_CONTAINER_bloomfilter_clear (struct GNUNET_CONTAINER_BloomFilter *bf);
186 207
208
187/** 209/**
188 * Or the entries of the given raw data array with the 210 * @ingroup bloomfilter
189 * data of the given bloom filter. Assumes that 211 * "or" the entries of the given raw data array with the
190 * the size of the data array and the current filter 212 * data of the given Bloom filter. Assumes that
213 * the @a size of the @a data array and the current filter
191 * match. 214 * match.
192 * 215 *
193 * @param bf the filter 216 * @param bf the filter
194 * @param data data to OR-in 217 * @param data data to OR-in
195 * @param size size of data 218 * @param size size of @a data
196 * @return GNUNET_OK on success 219 * @return #GNUNET_OK on success
197 */ 220 */
198int 221int
199GNUNET_CONTAINER_bloomfilter_or (struct GNUNET_CONTAINER_BloomFilter *bf, 222GNUNET_CONTAINER_bloomfilter_or (struct GNUNET_CONTAINER_BloomFilter *bf,
200 const char *data, size_t size); 223 const char *data, size_t size);
201 224
225
202/** 226/**
203 * Or the entries of the given raw data array with the 227 * @ingroup bloomfilter
204 * data of the given bloom filter. Assumes that 228 * "or" the entries of the given raw data array with the
205 * the size of the data array and the current filter 229 * data of the given Bloom filter. Assumes that
206 * match. 230 * the size of the two filters matches.
207 * 231 *
208 * @param bf the filter 232 * @param bf the filter
209 * @param to_or the bloomfilter to or-in 233 * @param to_or the bloomfilter to or-in
210 * @param size number of bytes in data 234 * @return #GNUNET_OK on success
211 */ 235 */
212int 236int
213GNUNET_CONTAINER_bloomfilter_or2 (struct GNUNET_CONTAINER_BloomFilter *bf, 237GNUNET_CONTAINER_bloomfilter_or2 (struct GNUNET_CONTAINER_BloomFilter *bf,
214 const struct GNUNET_CONTAINER_BloomFilter 238 const struct GNUNET_CONTAINER_BloomFilter
215 *to_or, size_t size); 239 *to_or);
216 240
217/** 241/**
242 * @ingroup bloomfilter
218 * Resize a bloom filter. Note that this operation 243 * Resize a bloom filter. Note that this operation
219 * is pretty costly. Essentially, the bloom filter 244 * is pretty costly. Essentially, the Bloom filter
220 * needs to be completely re-build. 245 * needs to be completely re-build.
221 * 246 *
222 * @param bf the filter 247 * @param bf the filter
223 * @param iterator an iterator over all elements stored in the BF 248 * @param iterator an iterator over all elements stored in the BF
224 * @param iterator_cls closure for iterator 249 * @param iterator_cls closure for @a iterator
225 * @param size the new size for the filter 250 * @param size the new size for the filter
226 * @param k the new number of GNUNET_CRYPTO_hash-function to apply per element 251 * @param k the new number of #GNUNET_CRYPTO_hash-function to apply per element
227 */ 252 */
228void 253void
229GNUNET_CONTAINER_bloomfilter_resize (struct GNUNET_CONTAINER_BloomFilter *bf, 254GNUNET_CONTAINER_bloomfilter_resize (struct GNUNET_CONTAINER_BloomFilter *bf,
@@ -231,22 +256,27 @@ GNUNET_CONTAINER_bloomfilter_resize (struct GNUNET_CONTAINER_BloomFilter *bf,
231 void *iterator_cls, size_t size, 256 void *iterator_cls, size_t size,
232 unsigned int k); 257 unsigned int k);
233 258
259
234/* ****************** metadata ******************* */ 260/* ****************** metadata ******************* */
235 261
236/** 262/**
263 * @ingroup metadata
237 * Meta data to associate with a file, directory or namespace. 264 * Meta data to associate with a file, directory or namespace.
238 */ 265 */
239struct GNUNET_CONTAINER_MetaData; 266struct GNUNET_CONTAINER_MetaData;
240 267
241/** 268/**
242 * Create a fresh MetaData token. 269 * @ingroup metadata
270 * Create a fresh meta data container.
243 * 271 *
244 * @return empty meta-data container 272 * @return empty meta-data container
245 */ 273 */
246struct GNUNET_CONTAINER_MetaData * 274struct GNUNET_CONTAINER_MetaData *
247GNUNET_CONTAINER_meta_data_create (void); 275GNUNET_CONTAINER_meta_data_create (void);
248 276
277
249/** 278/**
279 * @ingroup metadata
250 * Duplicate a MetaData token. 280 * Duplicate a MetaData token.
251 * 281 *
252 * @param md what to duplicate 282 * @param md what to duplicate
@@ -257,6 +287,7 @@ GNUNET_CONTAINER_meta_data_duplicate (const struct GNUNET_CONTAINER_MetaData
257 *md); 287 *md);
258 288
259/** 289/**
290 * @ingroup metadata
260 * Free meta data. 291 * Free meta data.
261 * 292 *
262 * @param md what to free 293 * @param md what to free
@@ -264,7 +295,9 @@ GNUNET_CONTAINER_meta_data_duplicate (const struct GNUNET_CONTAINER_MetaData
264void 295void
265GNUNET_CONTAINER_meta_data_destroy (struct GNUNET_CONTAINER_MetaData *md); 296GNUNET_CONTAINER_meta_data_destroy (struct GNUNET_CONTAINER_MetaData *md);
266 297
298
267/** 299/**
300 * @ingroup metadata
268 * Test if two MDs are equal. We consider them equal if 301 * Test if two MDs are equal. We consider them equal if
269 * the meta types, formats and content match (we do not 302 * the meta types, formats and content match (we do not
270 * include the mime types and plugins names in this 303 * include the mime types and plugins names in this
@@ -272,7 +305,7 @@ GNUNET_CONTAINER_meta_data_destroy (struct GNUNET_CONTAINER_MetaData *md);
272 * 305 *
273 * @param md1 first value to check 306 * @param md1 first value to check
274 * @param md2 other value to check 307 * @param md2 other value to check
275 * @return GNUNET_YES if they are equal 308 * @return #GNUNET_YES if they are equal
276 */ 309 */
277int 310int
278GNUNET_CONTAINER_meta_data_test_equal (const struct GNUNET_CONTAINER_MetaData 311GNUNET_CONTAINER_meta_data_test_equal (const struct GNUNET_CONTAINER_MetaData
@@ -282,6 +315,7 @@ GNUNET_CONTAINER_meta_data_test_equal (const struct GNUNET_CONTAINER_MetaData
282 315
283 316
284/** 317/**
318 * @ingroup metadata
285 * Extend metadata. 319 * Extend metadata.
286 * 320 *
287 * @param md metadata to extend 321 * @param md metadata to extend
@@ -295,7 +329,7 @@ GNUNET_CONTAINER_meta_data_test_equal (const struct GNUNET_CONTAINER_MetaData
295 * can be NULL (if mime-type is not known) 329 * can be NULL (if mime-type is not known)
296 * @param data actual meta-data found 330 * @param data actual meta-data found
297 * @param data_size number of bytes in data 331 * @param data_size number of bytes in data
298 * @return GNUNET_OK on success, GNUNET_SYSERR if this entry already exists 332 * @return #GNUNET_OK on success, #GNUNET_SYSERR if this entry already exists
299 * data_mime_type and plugin_name are not considered for "exists" checks 333 * data_mime_type and plugin_name are not considered for "exists" checks
300 */ 334 */
301int 335int
@@ -308,6 +342,7 @@ GNUNET_CONTAINER_meta_data_insert (struct GNUNET_CONTAINER_MetaData *md,
308 342
309 343
310/** 344/**
345 * @ingroup metadata
311 * Extend metadata. Merges the meta data from the second argument 346 * Extend metadata. Merges the meta data from the second argument
312 * into the first, discarding duplicate key-value pairs. 347 * into the first, discarding duplicate key-value pairs.
313 * 348 *
@@ -320,6 +355,7 @@ GNUNET_CONTAINER_meta_data_merge (struct GNUNET_CONTAINER_MetaData *md,
320 355
321 356
322/** 357/**
358 * @ingroup metadata
323 * Remove an item. 359 * Remove an item.
324 * 360 *
325 * @param md metadata to manipulate 361 * @param md metadata to manipulate
@@ -327,7 +363,7 @@ GNUNET_CONTAINER_meta_data_merge (struct GNUNET_CONTAINER_MetaData *md,
327 * @param data specific value to remove, NULL to remove all 363 * @param data specific value to remove, NULL to remove all
328 * entries of the given type 364 * entries of the given type
329 * @param data_size number of bytes in data 365 * @param data_size number of bytes in data
330 * @return GNUNET_OK on success, GNUNET_SYSERR if the item does not exist in md 366 * @return #GNUNET_OK on success, #GNUNET_SYSERR if the item does not exist in md
331 */ 367 */
332int 368int
333GNUNET_CONTAINER_meta_data_delete (struct GNUNET_CONTAINER_MetaData *md, 369GNUNET_CONTAINER_meta_data_delete (struct GNUNET_CONTAINER_MetaData *md,
@@ -336,6 +372,7 @@ GNUNET_CONTAINER_meta_data_delete (struct GNUNET_CONTAINER_MetaData *md,
336 372
337 373
338/** 374/**
375 * @ingroup metadata
339 * Remove all items in the container. 376 * Remove all items in the container.
340 * 377 *
341 * @param md metadata to manipulate 378 * @param md metadata to manipulate
@@ -345,6 +382,7 @@ GNUNET_CONTAINER_meta_data_clear (struct GNUNET_CONTAINER_MetaData *md);
345 382
346 383
347/** 384/**
385 * @ingroup metadata
348 * Add the current time as the publication date 386 * Add the current time as the publication date
349 * to the meta-data. 387 * to the meta-data.
350 * 388 *
@@ -356,11 +394,12 @@ GNUNET_CONTAINER_meta_data_add_publication_date (struct
356 394
357 395
358/** 396/**
397 * @ingroup metadata
359 * Iterate over MD entries. 398 * Iterate over MD entries.
360 * 399 *
361 * @param md metadata to inspect 400 * @param md metadata to inspect
362 * @param iter function to call on each entry 401 * @param iter function to call on each entry
363 * @param iter_cls closure for iterator 402 * @param iter_cls closure for @a iter
364 * @return number of entries 403 * @return number of entries
365 */ 404 */
366int 405int
@@ -369,6 +408,7 @@ GNUNET_CONTAINER_meta_data_iterate (const struct GNUNET_CONTAINER_MetaData *md,
369 void *iter_cls); 408 void *iter_cls);
370 409
371/** 410/**
411 * @ingroup metadata
372 * Get the first MD entry of the given type. Caller 412 * Get the first MD entry of the given type. Caller
373 * is responsible for freeing the return value. 413 * is responsible for freeing the return value.
374 * Also, only meta data items that are strings (0-terminated) 414 * Also, only meta data items that are strings (0-terminated)
@@ -384,6 +424,7 @@ GNUNET_CONTAINER_meta_data_get_by_type (const struct GNUNET_CONTAINER_MetaData
384 424
385 425
386/** 426/**
427 * @ingroup metadata
387 * Get the first matching MD entry of the given types. Caller is 428 * Get the first matching MD entry of the given types. Caller is
388 * responsible for freeing the return value. Also, only meta data 429 * responsible for freeing the return value. Also, only meta data
389 * items that are strings (0-terminated) are returned by this 430 * items that are strings (0-terminated) are returned by this
@@ -400,6 +441,7 @@ GNUNET_CONTAINER_meta_data_get_first_by_types (const struct
400 ...); 441 ...);
401 442
402/** 443/**
444 * @ingroup metadata
403 * Get a thumbnail from the meta-data (if present). Only matches meta 445 * Get a thumbnail from the meta-data (if present). Only matches meta
404 * data with mime type "image" and binary format. 446 * data with mime type "image" and binary format.
405 * 447 *
@@ -415,22 +457,26 @@ GNUNET_CONTAINER_meta_data_get_thumbnail (const struct GNUNET_CONTAINER_MetaData
415 457
416 458
417/** 459/**
460 * @ingroup metadata
418 * Options for metadata serialization. 461 * Options for metadata serialization.
419 */ 462 */
420enum GNUNET_CONTAINER_MetaDataSerializationOptions 463enum GNUNET_CONTAINER_MetaDataSerializationOptions
421{ 464{
422 /** 465 /**
466 * @ingroup metadata
423 * Serialize all of the data. 467 * Serialize all of the data.
424 */ 468 */
425 GNUNET_CONTAINER_META_DATA_SERIALIZE_FULL = 0, 469 GNUNET_CONTAINER_META_DATA_SERIALIZE_FULL = 0,
426 470
427 /** 471 /**
472 * @ingroup metadata
428 * If not enough space is available, it is acceptable 473 * If not enough space is available, it is acceptable
429 * to only serialize some of the metadata. 474 * to only serialize some of the metadata.
430 */ 475 */
431 GNUNET_CONTAINER_META_DATA_SERIALIZE_PART = 1, 476 GNUNET_CONTAINER_META_DATA_SERIALIZE_PART = 1,
432 477
433 /** 478 /**
479 * @ingroup metadata
434 * Speed is of the essence, do not allow compression. 480 * Speed is of the essence, do not allow compression.
435 */ 481 */
436 GNUNET_CONTAINER_META_DATA_SERIALIZE_NO_COMPRESS = 2 482 GNUNET_CONTAINER_META_DATA_SERIALIZE_NO_COMPRESS = 2
@@ -438,6 +484,7 @@ enum GNUNET_CONTAINER_MetaDataSerializationOptions
438 484
439 485
440/** 486/**
487 * @ingroup metadata
441 * Serialize meta-data to target. 488 * Serialize meta-data to target.
442 * 489 *
443 * @param md metadata to serialize 490 * @param md metadata to serialize
@@ -460,6 +507,7 @@ GNUNET_CONTAINER_meta_data_serialize (const struct GNUNET_CONTAINER_MetaData
460 507
461 508
462/** 509/**
510 * @ingroup metadata
463 * Get the size of the full meta-data in serialized form. 511 * Get the size of the full meta-data in serialized form.
464 * 512 *
465 * @param md metadata to inspect 513 * @param md metadata to inspect
@@ -471,6 +519,7 @@ GNUNET_CONTAINER_meta_data_get_serialized_size (const struct
471 519
472 520
473/** 521/**
522 * @ingroup metadata
474 * Deserialize meta-data. Initializes md. 523 * Deserialize meta-data. Initializes md.
475 * 524 *
476 * @param input serialized meta-data. 525 * @param input serialized meta-data.
@@ -485,23 +534,27 @@ GNUNET_CONTAINER_meta_data_deserialize (const char *input, size_t size);
485/* ******************************* HashMap **************************** */ 534/* ******************************* HashMap **************************** */
486 535
487/** 536/**
537 * @ingroup hashmap
488 * Opaque handle for a HashMap. 538 * Opaque handle for a HashMap.
489 */ 539 */
490struct GNUNET_CONTAINER_MultiHashMap; 540struct GNUNET_CONTAINER_MultiHashMap;
491 541
492/** 542/**
543 * @ingroup hashmap
493 * Opaque handle to an iterator over 544 * Opaque handle to an iterator over
494 * a multihashmap. 545 * a multihashmap.
495 */ 546 */
496struct GNUNET_CONTAINER_MultiHashMapIterator; 547struct GNUNET_CONTAINER_MultiHashMapIterator;
497 548
498/** 549/**
550 * @ingroup hashmap
499 * Options for storing values in the HashMap. 551 * Options for storing values in the HashMap.
500 */ 552 */
501enum GNUNET_CONTAINER_MultiHashMapOption 553enum GNUNET_CONTAINER_MultiHashMapOption
502{ 554{
503 555
504 /** 556 /**
557 * @ingroup hashmap
505 * If a value with the given key exists, replace it. Note that the 558 * If a value with the given key exists, replace it. Note that the
506 * old value would NOT be freed by replace (the application has to 559 * old value would NOT be freed by replace (the application has to
507 * make sure that this happens if required). 560 * make sure that this happens if required).
@@ -509,35 +562,41 @@ enum GNUNET_CONTAINER_MultiHashMapOption
509 GNUNET_CONTAINER_MULTIHASHMAPOPTION_REPLACE, 562 GNUNET_CONTAINER_MULTIHASHMAPOPTION_REPLACE,
510 563
511 /** 564 /**
565 * @ingroup hashmap
512 * Allow multiple values with the same key. 566 * Allow multiple values with the same key.
513 */ 567 */
514 GNUNET_CONTAINER_MULTIHASHMAPOPTION_MULTIPLE, 568 GNUNET_CONTAINER_MULTIHASHMAPOPTION_MULTIPLE,
515 569
516 /** 570 /**
571 * @ingroup hashmap
517 * There must only be one value per key; storing a value should fail 572 * There must only be one value per key; storing a value should fail
518 * if a value under the same key already exists. 573 * if a value under the same key already exists.
519 */ 574 */
520 GNUNET_CONTAINER_MULTIHASHMAPOPTION_UNIQUE_ONLY, 575 GNUNET_CONTAINER_MULTIHASHMAPOPTION_UNIQUE_ONLY,
521 576
522 /** 577 /**
523 * There must only be one value per key, but don't bother checking 578 * @ingroup hashmap There must only be one value per key, but don't
524 * if a value already exists (faster than UNIQUE_ONLY; implemented 579 * bother checking if a value already exists (faster than
525 * just like MULTIPLE but this option documents better what is 580 * #GNUNET_CONTAINER_MULTIHASHMAPOPTION_UNIQUE_ONLY; implemented
526 * intended if UNIQUE is what is desired). 581 * just like #GNUNET_CONTAINER_MULTIHASHMAPOPTION_MULTIPLE but this
582 * option documents better what is intended if
583 * #GNUNET_CONTAINER_MULTIHASHMAPOPTION_UNIQUE_ONLY is what is
584 * desired).
527 */ 585 */
528 GNUNET_CONTAINER_MULTIHASHMAPOPTION_UNIQUE_FAST 586 GNUNET_CONTAINER_MULTIHASHMAPOPTION_UNIQUE_FAST
529}; 587};
530 588
531 589
532/** 590/**
591 * @ingroup hashmap
533 * Iterator over hash map entries. 592 * Iterator over hash map entries.
534 * 593 *
535 * @param cls closure 594 * @param cls closure
536 * @param key current key code 595 * @param key current key code
537 * @param value value in the hash map 596 * @param value value in the hash map
538 * @return GNUNET_YES if we should continue to 597 * @return #GNUNET_YES if we should continue to
539 * iterate, 598 * iterate,
540 * GNUNET_NO if not. 599 * #GNUNET_NO if not.
541 */ 600 */
542typedef int (*GNUNET_CONTAINER_HashMapIterator) (void *cls, 601typedef int (*GNUNET_CONTAINER_HashMapIterator) (void *cls,
543 const struct GNUNET_HashCode *key, 602 const struct GNUNET_HashCode *key,
@@ -545,11 +604,12 @@ typedef int (*GNUNET_CONTAINER_HashMapIterator) (void *cls,
545 604
546 605
547/** 606/**
607 * @ingroup hashmap
548 * Create a multi hash map. 608 * Create a multi hash map.
549 * 609 *
550 * @param len initial size (map will grow as needed) 610 * @param len initial size (map will grow as needed)
551 * @param do_not_copy_keys GNUNET_NO is always safe and should be used by default; 611 * @param do_not_copy_keys #GNUNET_NO is always safe and should be used by default;
552 * GNUNET_YES means that on 'put', the 'key' does not have 612 * #GNUNET_YES means that on 'put', the 'key' does not have
553 * to be copied as the destination of the pointer is 613 * to be copied as the destination of the pointer is
554 * guaranteed to be life as long as the value is stored in 614 * guaranteed to be life as long as the value is stored in
555 * the hashmap. This can significantly reduce memory 615 * the hashmap. This can significantly reduce memory
@@ -565,6 +625,7 @@ GNUNET_CONTAINER_multihashmap_create (unsigned int len,
565 625
566 626
567/** 627/**
628 * @ingroup hashmap
568 * Destroy a hash map. Will not free any values 629 * Destroy a hash map. Will not free any values
569 * stored in the hash map! 630 * stored in the hash map!
570 * 631 *
@@ -576,6 +637,7 @@ GNUNET_CONTAINER_multihashmap_destroy (struct GNUNET_CONTAINER_MultiHashMap
576 637
577 638
578/** 639/**
640 * @ingroup hashmap
579 * Given a key find a value in the map matching the key. 641 * Given a key find a value in the map matching the key.
580 * 642 *
581 * @param map the map 643 * @param map the map
@@ -591,6 +653,7 @@ GNUNET_CONTAINER_multihashmap_get (const struct GNUNET_CONTAINER_MultiHashMap
591 653
592 654
593/** 655/**
656 * @ingroup hashmap
594 * Remove the given key-value pair from the map. Note that if the 657 * Remove the given key-value pair from the map. Note that if the
595 * key-value pair is in the map multiple times, only one of the pairs 658 * key-value pair is in the map multiple times, only one of the pairs
596 * will be removed. 659 * will be removed.
@@ -598,7 +661,7 @@ GNUNET_CONTAINER_multihashmap_get (const struct GNUNET_CONTAINER_MultiHashMap
598 * @param map the map 661 * @param map the map
599 * @param key key of the key-value pair 662 * @param key key of the key-value pair
600 * @param value value of the key-value pair 663 * @param value value of the key-value pair
601 * @return GNUNET_YES on success, GNUNET_NO if the key-value pair 664 * @return #GNUNET_YES on success, #GNUNET_NO if the key-value pair
602 * is not in the map 665 * is not in the map
603 */ 666 */
604int 667int
@@ -607,6 +670,7 @@ GNUNET_CONTAINER_multihashmap_remove (struct GNUNET_CONTAINER_MultiHashMap *map,
607 const void *value); 670 const void *value);
608 671
609/** 672/**
673 * @ingroup hashmap
610 * Remove all entries for the given key from the map. 674 * Remove all entries for the given key from the map.
611 * Note that the values would not be "freed". 675 * Note that the values would not be "freed".
612 * 676 *
@@ -620,13 +684,14 @@ GNUNET_CONTAINER_multihashmap_remove_all (struct GNUNET_CONTAINER_MultiHashMap
620 684
621 685
622/** 686/**
687 * @ingroup hashmap
623 * Check if the map contains any value under the given 688 * Check if the map contains any value under the given
624 * key (including values that are NULL). 689 * key (including values that are NULL).
625 * 690 *
626 * @param map the map 691 * @param map the map
627 * @param key the key to test if a value exists for it 692 * @param key the key to test if a value exists for it
628 * @return GNUNET_YES if such a value exists, 693 * @return #GNUNET_YES if such a value exists,
629 * GNUNET_NO if not 694 * #GNUNET_NO if not
630 */ 695 */
631int 696int
632GNUNET_CONTAINER_multihashmap_contains (const struct 697GNUNET_CONTAINER_multihashmap_contains (const struct
@@ -635,14 +700,15 @@ GNUNET_CONTAINER_multihashmap_contains (const struct
635 700
636 701
637/** 702/**
703 * @ingroup hashmap
638 * Check if the map contains the given value under the given 704 * Check if the map contains the given value under the given
639 * key. 705 * key.
640 * 706 *
641 * @param map the map 707 * @param map the map
642 * @param key the key to test if a value exists for it 708 * @param key the key to test if a value exists for it
643 * @param value value to test for 709 * @param value value to test for
644 * @return GNUNET_YES if such a value exists, 710 * @return #GNUNET_YES if such a value exists,
645 * GNUNET_NO if not 711 * #GNUNET_NO if not
646 */ 712 */
647int 713int
648GNUNET_CONTAINER_multihashmap_contains_value (const struct 714GNUNET_CONTAINER_multihashmap_contains_value (const struct
@@ -652,15 +718,16 @@ GNUNET_CONTAINER_multihashmap_contains_value (const struct
652 718
653 719
654/** 720/**
721 * @ingroup hashmap
655 * Store a key-value pair in the map. 722 * Store a key-value pair in the map.
656 * 723 *
657 * @param map the map 724 * @param map the map
658 * @param key key to use 725 * @param key key to use
659 * @param value value to use 726 * @param value value to use
660 * @param opt options for put 727 * @param opt options for put
661 * @return GNUNET_OK on success, 728 * @return #GNUNET_OK on success,
662 * GNUNET_NO if a value was replaced (with REPLACE) 729 * #GNUNET_NO if a value was replaced (with REPLACE)
663 * GNUNET_SYSERR if UNIQUE_ONLY was the option and the 730 * #GNUNET_SYSERR if UNIQUE_ONLY was the option and the
664 * value already exists 731 * value already exists
665 */ 732 */
666int 733int
@@ -670,6 +737,7 @@ GNUNET_CONTAINER_multihashmap_put (struct GNUNET_CONTAINER_MultiHashMap *map,
670 opt); 737 opt);
671 738
672/** 739/**
740 * @ingroup hashmap
673 * Get the number of key-value pairs in the map. 741 * Get the number of key-value pairs in the map.
674 * 742 *
675 * @param map the map 743 * @param map the map
@@ -681,13 +749,14 @@ GNUNET_CONTAINER_multihashmap_size (const struct GNUNET_CONTAINER_MultiHashMap
681 749
682 750
683/** 751/**
752 * @ingroup hashmap
684 * Iterate over all entries in the map. 753 * Iterate over all entries in the map.
685 * 754 *
686 * @param map the map 755 * @param map the map
687 * @param it function to call on each entry 756 * @param it function to call on each entry
688 * @param it_cls extra argument to it 757 * @param it_cls extra argument to @a it
689 * @return the number of key value pairs processed, 758 * @return the number of key value pairs processed,
690 * GNUNET_SYSERR if it aborted iteration 759 * #GNUNET_SYSERR if it aborted iteration
691 */ 760 */
692int 761int
693GNUNET_CONTAINER_multihashmap_iterate (const struct 762GNUNET_CONTAINER_multihashmap_iterate (const struct
@@ -697,6 +766,7 @@ GNUNET_CONTAINER_multihashmap_iterate (const struct
697 766
698 767
699/** 768/**
769 * @ingroup hashmap
700 * Create an iterator for a multihashmap. 770 * Create an iterator for a multihashmap.
701 * The iterator can be used to retrieve all the elements in the multihashmap 771 * The iterator can be used to retrieve all the elements in the multihashmap
702 * one by one, without having to handle all elements at once (in contrast to 772 * one by one, without having to handle all elements at once (in contrast to
@@ -706,25 +776,26 @@ GNUNET_CONTAINER_multihashmap_iterate (const struct
706 * result in skipped or repeated elements. 776 * result in skipped or repeated elements.
707 * 777 *
708 * @param map the map to create an iterator for 778 * @param map the map to create an iterator for
709 * @return an iterator over the given multihashmap 'map' 779 * @return an iterator over the given multihashmap @a map
710 */ 780 */
711struct GNUNET_CONTAINER_MultiHashMapIterator * 781struct GNUNET_CONTAINER_MultiHashMapIterator *
712GNUNET_CONTAINER_multihashmap_iterator_create (const struct GNUNET_CONTAINER_MultiHashMap *map); 782GNUNET_CONTAINER_multihashmap_iterator_create (const struct GNUNET_CONTAINER_MultiHashMap *map);
713 783
714 784
715/** 785/**
716 * Retrieve the next element from the hash map at the iterator's position. 786 * @ingroup hashmap
717 * If there are no elements left, GNUNET_NO is returned, and 'key' and 'value' 787 * Retrieve the next element from the hash map at the iterator's
718 * are not modified. 788 * position. If there are no elements left, #GNUNET_NO is returned,
719 * This operation is only allowed if no elements have been removed from the 789 * and @a key and @a value are not modified. This operation is only
720 * multihashmap since the creation of 'iter', and the map has not been destroyed. 790 * allowed if no elements have been removed from the multihashmap
791 * since the creation of @a iter, and the map has not been destroyed.
721 * Adding elements may result in repeating or skipping elements. 792 * Adding elements may result in repeating or skipping elements.
722 * 793 *
723 * @param iter the iterator to get the next element from 794 * @param iter the iterator to get the next element from
724 * @param key pointer to store the key in, can be NULL 795 * @param key pointer to store the key in, can be NULL
725 * @param value pointer to store the value in, can be NULL 796 * @param value pointer to store the value in, can be NULL
726 * @return GNUNET_YES we returned an element, 797 * @return #GNUNET_YES we returned an element,
727 * GNUNET_NO if we are out of elements 798 * #GNUNET_NO if we are out of elements
728 */ 799 */
729int 800int
730GNUNET_CONTAINER_multihashmap_iterator_next (struct GNUNET_CONTAINER_MultiHashMapIterator *iter, 801GNUNET_CONTAINER_multihashmap_iterator_next (struct GNUNET_CONTAINER_MultiHashMapIterator *iter,
@@ -732,6 +803,7 @@ GNUNET_CONTAINER_multihashmap_iterator_next (struct GNUNET_CONTAINER_MultiHashMa
732 803
733 804
734/** 805/**
806 * @ingroup hashmap
735 * Destroy a multihashmap iterator. 807 * Destroy a multihashmap iterator.
736 * 808 *
737 * @param iter the iterator to destroy 809 * @param iter the iterator to destroy
@@ -741,14 +813,15 @@ GNUNET_CONTAINER_multihashmap_iterator_destroy (struct GNUNET_CONTAINER_MultiHas
741 813
742 814
743/** 815/**
816 * @ingroup hashmap
744 * Iterate over all entries in the map that match a particular key. 817 * Iterate over all entries in the map that match a particular key.
745 * 818 *
746 * @param map the map 819 * @param map the map
747 * @param key key that the entries must correspond to 820 * @param key key that the entries must correspond to
748 * @param it function to call on each entry 821 * @param it function to call on each entry
749 * @param it_cls extra argument to it 822 * @param it_cls extra argument to @a it
750 * @return the number of key value pairs processed, 823 * @return the number of key value pairs processed,
751 * GNUNET_SYSERR if it aborted iteration 824 * #GNUNET_SYSERR if it aborted iteration
752 */ 825 */
753int 826int
754GNUNET_CONTAINER_multihashmap_get_multiple (const struct 827GNUNET_CONTAINER_multihashmap_get_multiple (const struct
@@ -760,20 +833,22 @@ GNUNET_CONTAINER_multihashmap_get_multiple (const struct
760/* Version of multihashmap with 32 bit keys */ 833/* Version of multihashmap with 32 bit keys */
761 834
762/** 835/**
836 * @ingroup hashmap
763 * Opaque handle for the 32-bit key HashMap. 837 * Opaque handle for the 32-bit key HashMap.
764 */ 838 */
765struct GNUNET_CONTAINER_MultiHashMap32; 839struct GNUNET_CONTAINER_MultiHashMap32;
766 840
767 841
768/** 842/**
843 * @ingroup hashmap
769 * Iterator over hash map entries. 844 * Iterator over hash map entries.
770 * 845 *
771 * @param cls closure 846 * @param cls closure
772 * @param key current key code 847 * @param key current key code
773 * @param value value in the hash map 848 * @param value value in the hash map
774 * @return GNUNET_YES if we should continue to 849 * @return #GNUNET_YES if we should continue to
775 * iterate, 850 * iterate,
776 * GNUNET_NO if not. 851 * #GNUNET_NO if not.
777 */ 852 */
778typedef int (*GNUNET_CONTAINER_HashMapIterator32) (void *cls, 853typedef int (*GNUNET_CONTAINER_HashMapIterator32) (void *cls,
779 uint32_t key, 854 uint32_t key,
@@ -781,6 +856,7 @@ typedef int (*GNUNET_CONTAINER_HashMapIterator32) (void *cls,
781 856
782 857
783/** 858/**
859 * @ingroup hashmap
784 * Create a 32-bit key multi hash map. 860 * Create a 32-bit key multi hash map.
785 * 861 *
786 * @param len initial size (map will grow as needed) 862 * @param len initial size (map will grow as needed)
@@ -791,6 +867,7 @@ GNUNET_CONTAINER_multihashmap32_create (unsigned int len);
791 867
792 868
793/** 869/**
870 * @ingroup hashmap
794 * Destroy a 32-bit key hash map. Will not free any values 871 * Destroy a 32-bit key hash map. Will not free any values
795 * stored in the hash map! 872 * stored in the hash map!
796 * 873 *
@@ -802,6 +879,7 @@ GNUNET_CONTAINER_multihashmap32_destroy (struct GNUNET_CONTAINER_MultiHashMap32
802 879
803 880
804/** 881/**
882 * @ingroup hashmap
805 * Get the number of key-value pairs in the map. 883 * Get the number of key-value pairs in the map.
806 * 884 *
807 * @param map the map 885 * @param map the map
@@ -813,6 +891,7 @@ GNUNET_CONTAINER_multihashmap32_size (const struct
813 891
814 892
815/** 893/**
894 * @ingroup hashmap
816 * Given a key find a value in the map matching the key. 895 * Given a key find a value in the map matching the key.
817 * 896 *
818 * @param map the map 897 * @param map the map
@@ -829,13 +908,14 @@ GNUNET_CONTAINER_multihashmap32_get (const struct
829 908
830 909
831/** 910/**
911 * @ingroup hashmap
832 * Iterate over all entries in the map. 912 * Iterate over all entries in the map.
833 * 913 *
834 * @param map the map 914 * @param map the map
835 * @param it function to call on each entry 915 * @param it function to call on each entry
836 * @param it_cls extra argument to it 916 * @param it_cls extra argument to @a it
837 * @return the number of key value pairs processed, 917 * @return the number of key value pairs processed,
838 * GNUNET_SYSERR if it aborted iteration 918 * #GNUNET_SYSERR if it aborted iteration
839 */ 919 */
840int 920int
841GNUNET_CONTAINER_multihashmap32_iterate (const struct 921GNUNET_CONTAINER_multihashmap32_iterate (const struct
@@ -845,6 +925,7 @@ GNUNET_CONTAINER_multihashmap32_iterate (const struct
845 925
846 926
847/** 927/**
928 * @ingroup hashmap
848 * Remove the given key-value pair from the map. Note that if the 929 * Remove the given key-value pair from the map. Note that if the
849 * key-value pair is in the map multiple times, only one of the pairs 930 * key-value pair is in the map multiple times, only one of the pairs
850 * will be removed. 931 * will be removed.
@@ -852,7 +933,7 @@ GNUNET_CONTAINER_multihashmap32_iterate (const struct
852 * @param map the map 933 * @param map the map
853 * @param key key of the key-value pair 934 * @param key key of the key-value pair
854 * @param value value of the key-value pair 935 * @param value value of the key-value pair
855 * @return GNUNET_YES on success, GNUNET_NO if the key-value pair 936 * @return #GNUNET_YES on success, #GNUNET_NO if the key-value pair
856 * is not in the map 937 * is not in the map
857 */ 938 */
858int 939int
@@ -863,6 +944,7 @@ GNUNET_CONTAINER_multihashmap32_remove (struct GNUNET_CONTAINER_MultiHashMap32
863 944
864 945
865/** 946/**
947 * @ingroup hashmap
866 * Remove all entries for the given key from the map. 948 * Remove all entries for the given key from the map.
867 * Note that the values would not be "freed". 949 * Note that the values would not be "freed".
868 * 950 *
@@ -878,13 +960,14 @@ GNUNET_CONTAINER_multihashmap32_remove_all (struct
878 960
879 961
880/** 962/**
963 * @ingroup hashmap
881 * Check if the map contains any value under the given 964 * Check if the map contains any value under the given
882 * key (including values that are NULL). 965 * key (including values that are NULL).
883 * 966 *
884 * @param map the map 967 * @param map the map
885 * @param key the key to test if a value exists for it 968 * @param key the key to test if a value exists for it
886 * @return GNUNET_YES if such a value exists, 969 * @return #GNUNET_YES if such a value exists,
887 * GNUNET_NO if not 970 * #GNUNET_NO if not
888 */ 971 */
889int 972int
890GNUNET_CONTAINER_multihashmap32_contains (const struct 973GNUNET_CONTAINER_multihashmap32_contains (const struct
@@ -893,14 +976,15 @@ GNUNET_CONTAINER_multihashmap32_contains (const struct
893 976
894 977
895/** 978/**
979 * @ingroup hashmap
896 * Check if the map contains the given value under the given 980 * Check if the map contains the given value under the given
897 * key. 981 * key.
898 * 982 *
899 * @param map the map 983 * @param map the map
900 * @param key the key to test if a value exists for it 984 * @param key the key to test if a value exists for it
901 * @param value value to test for 985 * @param value value to test for
902 * @return GNUNET_YES if such a value exists, 986 * @return #GNUNET_YES if such a value exists,
903 * GNUNET_NO if not 987 * #GNUNET_NO if not
904 */ 988 */
905int 989int
906GNUNET_CONTAINER_multihashmap32_contains_value (const struct 990GNUNET_CONTAINER_multihashmap32_contains_value (const struct
@@ -911,15 +995,16 @@ GNUNET_CONTAINER_multihashmap32_contains_value (const struct
911 995
912 996
913/** 997/**
998 * @ingroup hashmap
914 * Store a key-value pair in the map. 999 * Store a key-value pair in the map.
915 * 1000 *
916 * @param map the map 1001 * @param map the map
917 * @param key key to use 1002 * @param key key to use
918 * @param value value to use 1003 * @param value value to use
919 * @param opt options for put 1004 * @param opt options for put
920 * @return GNUNET_OK on success, 1005 * @return #GNUNET_OK on success,
921 * GNUNET_NO if a value was replaced (with REPLACE) 1006 * #GNUNET_NO if a value was replaced (with REPLACE)
922 * GNUNET_SYSERR if UNIQUE_ONLY was the option and the 1007 * #GNUNET_SYSERR if #GNUNET_CONTAINER_MULTIHASHMAPOPTION_UNIQUE_ONLY was the option and the
923 * value already exists 1008 * value already exists
924 */ 1009 */
925int 1010int
@@ -930,14 +1015,15 @@ GNUNET_CONTAINER_multihashmap32_put (struct GNUNET_CONTAINER_MultiHashMap32
930 1015
931 1016
932/** 1017/**
1018 * @ingroup hashmap
933 * Iterate over all entries in the map that match a particular key. 1019 * Iterate over all entries in the map that match a particular key.
934 * 1020 *
935 * @param map the map 1021 * @param map the map
936 * @param key key that the entries must correspond to 1022 * @param key key that the entries must correspond to
937 * @param it function to call on each entry 1023 * @param it function to call on each entry
938 * @param it_cls extra argument to it 1024 * @param it_cls extra argument to @a it
939 * @return the number of key value pairs processed, 1025 * @return the number of key value pairs processed,
940 * GNUNET_SYSERR if it aborted iteration 1026 * #GNUNET_SYSERR if it aborted iteration
941 */ 1027 */
942int 1028int
943GNUNET_CONTAINER_multihashmap32_get_multiple (const struct 1029GNUNET_CONTAINER_multihashmap32_get_multiple (const struct
@@ -953,6 +1039,7 @@ GNUNET_CONTAINER_multihashmap32_get_multiple (const struct
953/* To avoid mistakes: head->prev == tail->next == NULL */ 1039/* To avoid mistakes: head->prev == tail->next == NULL */
954 1040
955/** 1041/**
1042 * @ingroup dll
956 * Insert an element at the head of a DLL. Assumes that head, tail and 1043 * Insert an element at the head of a DLL. Assumes that head, tail and
957 * element are structs with prev and next fields. 1044 * element are structs with prev and next fields.
958 * 1045 *
@@ -973,6 +1060,7 @@ GNUNET_CONTAINER_multihashmap32_get_multiple (const struct
973 1060
974 1061
975/** 1062/**
1063 * @ingroup dll
976 * Insert an element at the tail of a DLL. Assumes that head, tail and 1064 * Insert an element at the tail of a DLL. Assumes that head, tail and
977 * element are structs with prev and next fields. 1065 * element are structs with prev and next fields.
978 * 1066 *
@@ -993,6 +1081,7 @@ GNUNET_CONTAINER_multihashmap32_get_multiple (const struct
993 1081
994 1082
995/** 1083/**
1084 * @ingroup dll
996 * Insert an element into a DLL after the given other element. Insert 1085 * Insert an element into a DLL after the given other element. Insert
997 * at the head if the other element is NULL. 1086 * at the head if the other element is NULL.
998 * 1087 *
@@ -1022,6 +1111,7 @@ GNUNET_CONTAINER_multihashmap32_get_multiple (const struct
1022 1111
1023 1112
1024/** 1113/**
1114 * @ingroup dll
1025 * Insert an element into a DLL before the given other element. Insert 1115 * Insert an element into a DLL before the given other element. Insert
1026 * at the tail if the other element is NULL. 1116 * at the tail if the other element is NULL.
1027 * 1117 *
@@ -1051,6 +1141,7 @@ GNUNET_CONTAINER_multihashmap32_get_multiple (const struct
1051 1141
1052 1142
1053/** 1143/**
1144 * @ingroup dll
1054 * Remove an element from a DLL. Assumes that head, tail and 1145 * Remove an element from a DLL. Assumes that head, tail and
1055 * element point to structs with prev and next fields. 1146 * element point to structs with prev and next fields.
1056 * 1147 *
@@ -1082,6 +1173,7 @@ GNUNET_CONTAINER_multihashmap32_get_multiple (const struct
1082 in multiple lists at the same time *********************** */ 1173 in multiple lists at the same time *********************** */
1083 1174
1084/** 1175/**
1176 * @ingroup dll
1085 * Insert an element at the head of a MDLL. Assumes that head, tail and 1177 * Insert an element at the head of a MDLL. Assumes that head, tail and
1086 * element are structs with prev and next fields. 1178 * element are structs with prev and next fields.
1087 * 1179 *
@@ -1103,6 +1195,7 @@ GNUNET_CONTAINER_multihashmap32_get_multiple (const struct
1103 1195
1104 1196
1105/** 1197/**
1198 * @ingroup dll
1106 * Insert an element at the tail of a MDLL. Assumes that head, tail and 1199 * Insert an element at the tail of a MDLL. Assumes that head, tail and
1107 * element are structs with prev and next fields. 1200 * element are structs with prev and next fields.
1108 * 1201 *
@@ -1124,6 +1217,7 @@ GNUNET_CONTAINER_multihashmap32_get_multiple (const struct
1124 1217
1125 1218
1126/** 1219/**
1220 * @ingroup dll
1127 * Insert an element into a MDLL after the given other element. Insert 1221 * Insert an element into a MDLL after the given other element. Insert
1128 * at the head if the other element is NULL. 1222 * at the head if the other element is NULL.
1129 * 1223 *
@@ -1154,6 +1248,7 @@ GNUNET_CONTAINER_multihashmap32_get_multiple (const struct
1154 1248
1155 1249
1156/** 1250/**
1251 * @ingroup dll
1157 * Insert an element into a MDLL before the given other element. Insert 1252 * Insert an element into a MDLL before the given other element. Insert
1158 * at the tail if the other element is NULL. 1253 * at the tail if the other element is NULL.
1159 * 1254 *
@@ -1184,6 +1279,7 @@ GNUNET_CONTAINER_multihashmap32_get_multiple (const struct
1184 1279
1185 1280
1186/** 1281/**
1282 * @ingroup dll
1187 * Remove an element from a MDLL. Assumes 1283 * Remove an element from a MDLL. Assumes
1188 * that head, tail and element are structs 1284 * that head, tail and element are structs
1189 * with prev and next fields. 1285 * with prev and next fields.
@@ -1213,23 +1309,26 @@ GNUNET_CONTAINER_multihashmap32_get_multiple (const struct
1213 1309
1214 1310
1215/** 1311/**
1312 * @ingroup heap
1216 * Cost by which elements in a heap can be ordered. 1313 * Cost by which elements in a heap can be ordered.
1217 */ 1314 */
1218typedef uint64_t GNUNET_CONTAINER_HeapCostType; 1315typedef uint64_t GNUNET_CONTAINER_HeapCostType;
1219 1316
1220 1317
1221/* 1318/**
1222 * Heap type, either max or min. Hopefully makes the 1319 * @ingroup heap
1223 * implementation more useful. 1320 * Heap type, either max or min.
1224 */ 1321 */
1225enum GNUNET_CONTAINER_HeapOrder 1322enum GNUNET_CONTAINER_HeapOrder
1226{ 1323{
1227 /** 1324 /**
1325 * @ingroup heap
1228 * Heap with the maximum cost at the root. 1326 * Heap with the maximum cost at the root.
1229 */ 1327 */
1230 GNUNET_CONTAINER_HEAP_ORDER_MAX, 1328 GNUNET_CONTAINER_HEAP_ORDER_MAX,
1231 1329
1232 /** 1330 /**
1331 * @ingroup heap
1233 * Heap with the minimum cost at the root. 1332 * Heap with the minimum cost at the root.
1234 */ 1333 */
1235 GNUNET_CONTAINER_HEAP_ORDER_MIN 1334 GNUNET_CONTAINER_HEAP_ORDER_MIN
@@ -1237,19 +1336,21 @@ enum GNUNET_CONTAINER_HeapOrder
1237 1336
1238 1337
1239/** 1338/**
1339 * @ingroup heap
1240 * Handle to a Heap. 1340 * Handle to a Heap.
1241 */ 1341 */
1242struct GNUNET_CONTAINER_Heap; 1342struct GNUNET_CONTAINER_Heap;
1243 1343
1244 1344
1245
1246/** 1345/**
1346 * @ingroup heap
1247 * Handle to a node in a heap. 1347 * Handle to a node in a heap.
1248 */ 1348 */
1249struct GNUNET_CONTAINER_HeapNode; 1349struct GNUNET_CONTAINER_HeapNode;
1250 1350
1251 1351
1252/** 1352/**
1353 * @ingroup heap
1253 * Create a new heap. 1354 * Create a new heap.
1254 * 1355 *
1255 * @param order how should the heap be sorted? 1356 * @param order how should the heap be sorted?
@@ -1260,6 +1361,7 @@ GNUNET_CONTAINER_heap_create (enum GNUNET_CONTAINER_HeapOrder order);
1260 1361
1261 1362
1262/** 1363/**
1364 * @ingroup heap
1263 * Destroys the heap. Only call on a heap that 1365 * Destroys the heap. Only call on a heap that
1264 * is already empty. 1366 * is already empty.
1265 * 1367 *
@@ -1270,6 +1372,7 @@ GNUNET_CONTAINER_heap_destroy (struct GNUNET_CONTAINER_Heap *heap);
1270 1372
1271 1373
1272/** 1374/**
1375 * @ingroup heap
1273 * Get element stored at root of heap. 1376 * Get element stored at root of heap.
1274 * 1377 *
1275 * @param heap heap to inspect 1378 * @param heap heap to inspect
@@ -1280,6 +1383,7 @@ GNUNET_CONTAINER_heap_peek (const struct GNUNET_CONTAINER_Heap *heap);
1280 1383
1281 1384
1282/** 1385/**
1386 * @ingroup heap
1283 * Get the current size of the heap 1387 * Get the current size of the heap
1284 * 1388 *
1285 * @param heap the heap to get the size of 1389 * @param heap the heap to get the size of
@@ -1290,6 +1394,7 @@ GNUNET_CONTAINER_heap_get_size (const struct GNUNET_CONTAINER_Heap *heap);
1290 1394
1291 1395
1292/** 1396/**
1397 * @ingroup heap
1293 * Get the current cost of the node 1398 * Get the current cost of the node
1294 * 1399 *
1295 * @param node the node to get the cost of 1400 * @param node the node to get the cost of
@@ -1300,14 +1405,15 @@ GNUNET_CONTAINER_heap_node_get_cost (const struct GNUNET_CONTAINER_HeapNode
1300 *node); 1405 *node);
1301 1406
1302/** 1407/**
1408 * @ingroup heap
1303 * Iterator for heap 1409 * Iterator for heap
1304 * 1410 *
1305 * @param cls closure 1411 * @param cls closure
1306 * @param node internal node of the heap 1412 * @param node internal node of the heap
1307 * @param element value stored at the node 1413 * @param element value stored at the node
1308 * @param cost cost associated with the node 1414 * @param cost cost associated with the node
1309 * @return GNUNET_YES if we should continue to iterate, 1415 * @return #GNUNET_YES if we should continue to iterate,
1310 * GNUNET_NO if not. 1416 * #GNUNET_NO if not.
1311 */ 1417 */
1312typedef int (*GNUNET_CONTAINER_HeapIterator) (void *cls, 1418typedef int (*GNUNET_CONTAINER_HeapIterator) (void *cls,
1313 struct GNUNET_CONTAINER_HeapNode * 1419 struct GNUNET_CONTAINER_HeapNode *
@@ -1317,11 +1423,12 @@ typedef int (*GNUNET_CONTAINER_HeapIterator) (void *cls,
1317 1423
1318 1424
1319/** 1425/**
1426 * @ingroup heap
1320 * Iterate over all entries in the heap. 1427 * Iterate over all entries in the heap.
1321 * 1428 *
1322 * @param heap the heap 1429 * @param heap the heap
1323 * @param iterator function to call on each entry 1430 * @param iterator function to call on each entry
1324 * @param iterator_cls closure for iterator 1431 * @param iterator_cls closure for @a iterator
1325 */ 1432 */
1326void 1433void
1327GNUNET_CONTAINER_heap_iterate (const struct GNUNET_CONTAINER_Heap *heap, 1434GNUNET_CONTAINER_heap_iterate (const struct GNUNET_CONTAINER_Heap *heap,
@@ -1329,6 +1436,7 @@ GNUNET_CONTAINER_heap_iterate (const struct GNUNET_CONTAINER_Heap *heap,
1329 void *iterator_cls); 1436 void *iterator_cls);
1330 1437
1331/** 1438/**
1439 * @ingroup heap
1332 * Perform a random walk of the tree. The walk is biased 1440 * Perform a random walk of the tree. The walk is biased
1333 * towards elements closer to the root of the tree (since 1441 * towards elements closer to the root of the tree (since
1334 * each walk starts at the root and ends at a random leaf). 1442 * each walk starts at the root and ends at a random leaf).
@@ -1344,6 +1452,7 @@ GNUNET_CONTAINER_heap_walk_get_next (struct GNUNET_CONTAINER_Heap *heap);
1344 1452
1345 1453
1346/** 1454/**
1455 * @ingroup heap
1347 * Inserts a new element into the heap. 1456 * Inserts a new element into the heap.
1348 * 1457 *
1349 * @param heap heap to modify 1458 * @param heap heap to modify
@@ -1357,6 +1466,7 @@ GNUNET_CONTAINER_heap_insert (struct GNUNET_CONTAINER_Heap *heap, void *element,
1357 1466
1358 1467
1359/** 1468/**
1469 * @ingroup heap
1360 * Remove root of the heap. 1470 * Remove root of the heap.
1361 * 1471 *
1362 * @param heap heap to modify 1472 * @param heap heap to modify
@@ -1367,6 +1477,7 @@ GNUNET_CONTAINER_heap_remove_root (struct GNUNET_CONTAINER_Heap *heap);
1367 1477
1368 1478
1369/** 1479/**
1480 * @ingroup heap
1370 * Removes a node from the heap. 1481 * Removes a node from the heap.
1371 * 1482 *
1372 * @param node node to remove 1483 * @param node node to remove
@@ -1377,6 +1488,7 @@ GNUNET_CONTAINER_heap_remove_node (struct GNUNET_CONTAINER_HeapNode *node);
1377 1488
1378 1489
1379/** 1490/**
1491 * @ingroup heap
1380 * Updates the cost of any node in the tree 1492 * Updates the cost of any node in the tree
1381 * 1493 *
1382 * @param heap heap to modify 1494 * @param heap heap to modify
diff --git a/src/include/gnunet_core_service.h b/src/include/gnunet_core_service.h
index dc64f189a..ea8391d4e 100644
--- a/src/include/gnunet_core_service.h
+++ b/src/include/gnunet_core_service.h
@@ -1,6 +1,6 @@
1/* 1/*
2 This file is part of GNUnet. 2 This file is part of GNUnet.
3 (C) 2009, 2010 Christian Grothoff (and other contributing authors) 3 (C) 2009-2013 Christian Grothoff (and other contributing authors)
4 4
5 GNUnet is free software; you can redistribute it and/or modify 5 GNUnet is free software; you can redistribute it and/or modify
6 it under the terms of the GNU General Public License as published 6 it under the terms of the GNU General Public License as published
@@ -23,6 +23,8 @@
23 * @brief core service; this is the main API for encrypted P2P 23 * @brief core service; this is the main API for encrypted P2P
24 * communications 24 * communications
25 * @author Christian Grothoff 25 * @author Christian Grothoff
26 * @defgroup core encrypted direct communication between peers
27 * @{
26 */ 28 */
27 29
28#ifndef GNUNET_CORE_SERVICE_H 30#ifndef GNUNET_CORE_SERVICE_H
@@ -58,8 +60,7 @@ struct GNUNET_CORE_Handle;
58 * @param peer peer identity this notification is about 60 * @param peer peer identity this notification is about
59 */ 61 */
60typedef void (*GNUNET_CORE_ConnectEventHandler) (void *cls, 62typedef void (*GNUNET_CORE_ConnectEventHandler) (void *cls,
61 const struct 63 const struct GNUNET_PeerIdentity *peer);
62 GNUNET_PeerIdentity * peer);
63 64
64 65
65/** 66/**
@@ -69,8 +70,7 @@ typedef void (*GNUNET_CORE_ConnectEventHandler) (void *cls,
69 * @param peer peer identity this notification is about 70 * @param peer peer identity this notification is about
70 */ 71 */
71typedef void (*GNUNET_CORE_DisconnectEventHandler) (void *cls, 72typedef void (*GNUNET_CORE_DisconnectEventHandler) (void *cls,
72 const struct 73 const struct GNUNET_PeerIdentity *peer);
73 GNUNET_PeerIdentity * peer);
74 74
75 75
76/** 76/**
@@ -133,8 +133,7 @@ struct GNUNET_CORE_MessageHandler
133 */ 133 */
134typedef void (*GNUNET_CORE_StartupCallback) (void *cls, 134typedef void (*GNUNET_CORE_StartupCallback) (void *cls,
135 struct GNUNET_CORE_Handle * server, 135 struct GNUNET_CORE_Handle * server,
136 const struct GNUNET_PeerIdentity * 136 const struct GNUNET_PeerIdentity *my_identity);
137 my_identity);
138 137
139 138
140/** 139/**
@@ -280,42 +279,6 @@ GNUNET_CORE_iterate_peers (const struct GNUNET_CONFIGURATION_Handle *cfg,
280 279
281 280
282/** 281/**
283 * Handle to cancel 'is_peer_connected' test.
284 */
285struct GNUNET_CORE_ConnectTestHandle;
286
287
288/**
289 * Check if the given peer is currently connected and return information
290 * about the session if so. This function is for special cirumstances
291 * (GNUNET_TESTING uses it), normal users of the CORE API are
292 * expected to track which peers are connected based on the
293 * connect/disconnect callbacks from GNUNET_CORE_connect. This
294 * function is NOT part of the 'versioned', 'official' API.
295 *
296 * @param cfg configuration to use
297 * @param peer the specific peer to check for
298 * @param peer_cb function to call with the peer information
299 * @param cb_cls closure for @a peer_cb
300 * @return handle to cancel the operation
301 */
302struct GNUNET_CORE_ConnectTestHandle *
303GNUNET_CORE_is_peer_connected (const struct GNUNET_CONFIGURATION_Handle *cfg,
304 const struct GNUNET_PeerIdentity *peer,
305 GNUNET_CORE_ConnectEventHandler peer_cb,
306 void *cb_cls);
307
308
309/**
310 * Abort 'is_connected' test operation.
311 *
312 * @param cth handle for operation to cancel
313 */
314void
315GNUNET_CORE_is_peer_connected_cancel (struct GNUNET_CORE_ConnectTestHandle *cth);
316
317
318/**
319 * Check if the given peer is currently connected. This function is for special 282 * Check if the given peer is currently connected. This function is for special
320 * cirumstances (GNUNET_TESTBED uses it), normal users of the CORE API are 283 * cirumstances (GNUNET_TESTBED uses it), normal users of the CORE API are
321 * expected to track which peers are connected based on the connect/disconnect 284 * expected to track which peers are connected based on the connect/disconnect
@@ -342,6 +305,8 @@ GNUNET_CORE_is_peer_connected_sync (const struct GNUNET_CORE_Handle *h,
342} 305}
343#endif 306#endif
344 307
308/** @} */ /* end of group core */
309
345/* ifndef GNUNET_CORE_SERVICE_H */ 310/* ifndef GNUNET_CORE_SERVICE_H */
346#endif 311#endif
347/* end of gnunet_core_service.h */ 312/* end of gnunet_core_service.h */
diff --git a/src/include/gnunet_crypto_lib.h b/src/include/gnunet_crypto_lib.h
index 7fb3d2ac9..4133360a2 100644
--- a/src/include/gnunet_crypto_lib.h
+++ b/src/include/gnunet_crypto_lib.h
@@ -55,23 +55,27 @@ extern "C"
55 55
56 56
57/** 57/**
58 * Desired quality level for cryptographic operations. 58 * Desired quality level for random numbers.
59 * @ingroup crypto
59 */ 60 */
60enum GNUNET_CRYPTO_Quality 61enum GNUNET_CRYPTO_Quality
61{ 62{
62 /** 63 /**
63 * No good quality of the operation is needed (i.e., 64 * No good quality of the operation is needed (i.e.,
64 * random numbers can be pseudo-random). 65 * random numbers can be pseudo-random).
66 * @ingroup crypto
65 */ 67 */
66 GNUNET_CRYPTO_QUALITY_WEAK, 68 GNUNET_CRYPTO_QUALITY_WEAK,
67 69
68 /** 70 /**
69 * High-quality operations are desired. 71 * High-quality operations are desired.
72 * @ingroup crypto
70 */ 73 */
71 GNUNET_CRYPTO_QUALITY_STRONG, 74 GNUNET_CRYPTO_QUALITY_STRONG,
72 75
73 /** 76 /**
74 * Randomness for IVs etc. is required. 77 * Randomness for IVs etc. is required.
78 * @ingroup crypto
75 */ 79 */
76 GNUNET_CRYPTO_QUALITY_NONCE 80 GNUNET_CRYPTO_QUALITY_NONCE
77}; 81};
diff --git a/src/include/gnunet_dht_service.h b/src/include/gnunet_dht_service.h
index 53a212dd3..e5c4c1ee4 100644
--- a/src/include/gnunet_dht_service.h
+++ b/src/include/gnunet_dht_service.h
@@ -1,6 +1,6 @@
1/* 1/*
2 This file is part of GNUnet 2 This file is part of GNUnet
3 (C) 2004, 2005, 2006, 2008, 2009, 2011 Christian Grothoff (and other contributing authors) 3 (C) 2004-2013 Christian Grothoff (and other contributing authors)
4 4
5 GNUnet is free software; you can redistribute it and/or modify 5 GNUnet is free software; you can redistribute it and/or modify
6 it under the terms of the GNU General Public License as published 6 it under the terms of the GNU General Public License as published
diff --git a/src/include/gnunet_disk_lib.h b/src/include/gnunet_disk_lib.h
index 5359e9d49..12d3345c5 100644
--- a/src/include/gnunet_disk_lib.h
+++ b/src/include/gnunet_disk_lib.h
@@ -4,7 +4,7 @@
4 4
5 GNUnet is free software; you can redistribute it and/or modify 5 GNUnet is free software; you can redistribute it and/or modify
6 it under the terms of the GNU General Public License as published 6 it under the terms of the GNU General Public License as published
7 by the Free Software Foundation; either version 2, or (at your 7 by the Free Software Foundation; either version 3, or (at your
8 option) any later version. 8 option) any later version.
9 9
10 GNUnet is distributed in the hope that it will be useful, but 10 GNUnet is distributed in the hope that it will be useful, but
diff --git a/src/include/gnunet_getopt_lib.h b/src/include/gnunet_getopt_lib.h
index ce54674d8..a6650fe03 100644
--- a/src/include/gnunet_getopt_lib.h
+++ b/src/include/gnunet_getopt_lib.h
@@ -1,10 +1,10 @@
1/* 1/*
2 This file is part of GNUnet. 2 This file is part of GNUnet.
3 (C) 2001, 2002, 2003, 2004, 2005, 2006, 2009, 2011 Christian Grothoff (and other contributing authors) 3 (C) 2001-2013 Christian Grothoff (and other contributing authors)
4 4
5 GNUnet is free software; you can redistribute it and/or modify 5 GNUnet is free software; you can redistribute it and/or modify
6 it under the terms of the GNU General Public License as published 6 it under the terms of the GNU General Public License as published
7 by the Free Software Foundation; either version 2, or (at your 7 by the Free Software Foundation; either version 3, or (at your
8 option) any later version. 8 option) any later version.
9 9
10 GNUnet is distributed in the hope that it will be useful, but 10 GNUnet is distributed in the hope that it will be useful, but
@@ -21,8 +21,9 @@
21/** 21/**
22 * @file include/gnunet_getopt_lib.h 22 * @file include/gnunet_getopt_lib.h
23 * @brief command line parsing and --help formatting 23 * @brief command line parsing and --help formatting
24 *
25 * @author Christian Grothoff 24 * @author Christian Grothoff
25 * @defgroup getopt command-line parsing
26 * @{
26 */ 27 */
27 28
28#ifndef GNUNET_GETOPT_LIB_H 29#ifndef GNUNET_GETOPT_LIB_H
@@ -83,7 +84,7 @@ struct GNUNET_GETOPT_CommandLineProcessorContext
83 * @param scls specific closure (for this processor) 84 * @param scls specific closure (for this processor)
84 * @param option long name of the option (i.e. "config" for --config) 85 * @param option long name of the option (i.e. "config" for --config)
85 * @param value argument, NULL if none was given 86 * @param value argument, NULL if none was given
86 * @return GNUNET_OK to continue processing other options, GNUNET_SYSERR to abort 87 * @return #GNUNET_OK to continue processing other options, #GNUNET_SYSERR to abort
87 */ 88 */
88typedef int (*GNUNET_GETOPT_CommandLineOptionProcessor) (struct 89typedef int (*GNUNET_GETOPT_CommandLineOptionProcessor) (struct
89 GNUNET_GETOPT_CommandLineProcessorContext 90 GNUNET_GETOPT_CommandLineProcessorContext
@@ -202,10 +203,10 @@ struct GNUNET_GETOPT_CommandLineOption
202 * 203 *
203 * @param binaryOptions Name of application with option summary 204 * @param binaryOptions Name of application with option summary
204 * @param allOptions defined options and handlers 205 * @param allOptions defined options and handlers
205 * @param argc number of arguments 206 * @param argc number of arguments in @a argv
206 * @param argv actual arguments 207 * @param argv actual arguments
207 * @return index into argv with first non-option 208 * @return index into argv with first non-option
208 * argument, or GNUNET_SYSERR on error 209 * argument, or #GNUNET_SYSERR on error
209 */ 210 */
210int 211int
211GNUNET_GETOPT_run (const char *binaryOptions, 212GNUNET_GETOPT_run (const char *binaryOptions,
@@ -224,7 +225,7 @@ GNUNET_GETOPT_run (const char *binaryOptions,
224 * @param scls additional closure (will point to the 'unsigned long long') 225 * @param scls additional closure (will point to the 'unsigned long long')
225 * @param option name of the option 226 * @param option name of the option
226 * @param value actual value of the option as a string. 227 * @param value actual value of the option as a string.
227 * @return GNUNET_OK if parsing the value worked 228 * @return #GNUNET_OK if parsing the value worked
228 */ 229 */
229int 230int
230GNUNET_GETOPT_set_ulong (struct GNUNET_GETOPT_CommandLineProcessorContext *ctx, 231GNUNET_GETOPT_set_ulong (struct GNUNET_GETOPT_CommandLineProcessorContext *ctx,
@@ -242,7 +243,7 @@ GNUNET_GETOPT_set_ulong (struct GNUNET_GETOPT_CommandLineProcessorContext *ctx,
242 * @param scls additional closure (will point to the 'struct GNUNET_TIME_Relative') 243 * @param scls additional closure (will point to the 'struct GNUNET_TIME_Relative')
243 * @param option name of the option 244 * @param option name of the option
244 * @param value actual value of the option as a string. 245 * @param value actual value of the option as a string.
245 * @return GNUNET_OK if parsing the value worked 246 * @return #GNUNET_OK if parsing the value worked
246 */ 247 */
247int 248int
248GNUNET_GETOPT_set_relative_time (struct GNUNET_GETOPT_CommandLineProcessorContext *ctx, 249GNUNET_GETOPT_set_relative_time (struct GNUNET_GETOPT_CommandLineProcessorContext *ctx,
@@ -260,7 +261,7 @@ GNUNET_GETOPT_set_relative_time (struct GNUNET_GETOPT_CommandLineProcessorContex
260 * @param scls additional closure (will point to the 'unsigned int') 261 * @param scls additional closure (will point to the 'unsigned int')
261 * @param option name of the option 262 * @param option name of the option
262 * @param value actual value of the option as a string. 263 * @param value actual value of the option as a string.
263 * @return GNUNET_OK if parsing the value worked 264 * @return #GNUNET_OK if parsing the value worked
264 */ 265 */
265int 266int
266GNUNET_GETOPT_set_uint (struct GNUNET_GETOPT_CommandLineProcessorContext *ctx, 267GNUNET_GETOPT_set_uint (struct GNUNET_GETOPT_CommandLineProcessorContext *ctx,
@@ -279,7 +280,7 @@ GNUNET_GETOPT_set_uint (struct GNUNET_GETOPT_CommandLineProcessorContext *ctx,
279 * @param scls additional closure (will point to the 'int') 280 * @param scls additional closure (will point to the 'int')
280 * @param option name of the option 281 * @param option name of the option
281 * @param value not used (NULL) 282 * @param value not used (NULL)
282 * @return GNUNET_OK 283 * @return #GNUNET_OK (always)
283 */ 284 */
284int 285int
285GNUNET_GETOPT_set_one (struct GNUNET_GETOPT_CommandLineProcessorContext *ctx, 286GNUNET_GETOPT_set_one (struct GNUNET_GETOPT_CommandLineProcessorContext *ctx,
@@ -298,7 +299,7 @@ GNUNET_GETOPT_set_one (struct GNUNET_GETOPT_CommandLineProcessorContext *ctx,
298 * which will be allocated) 299 * which will be allocated)
299 * @param option name of the option 300 * @param option name of the option
300 * @param value actual value of the option (a string) 301 * @param value actual value of the option (a string)
301 * @return GNUNET_OK 302 * @return #GNUNET_OK (always)
302 */ 303 */
303int 304int
304GNUNET_GETOPT_set_string (struct GNUNET_GETOPT_CommandLineProcessorContext *ctx, 305GNUNET_GETOPT_set_string (struct GNUNET_GETOPT_CommandLineProcessorContext *ctx,
@@ -317,7 +318,7 @@ GNUNET_GETOPT_set_string (struct GNUNET_GETOPT_CommandLineProcessorContext *ctx,
317 * which will be allocated) 318 * which will be allocated)
318 * @param option name of the option 319 * @param option name of the option
319 * @param value actual value of the option (a string) 320 * @param value actual value of the option (a string)
320 * @return GNUNET_OK 321 * @return #GNUNET_OK (always)
321 */ 322 */
322int 323int
323GNUNET_GETOPT_set_filename (struct GNUNET_GETOPT_CommandLineProcessorContext *ctx, 324GNUNET_GETOPT_set_filename (struct GNUNET_GETOPT_CommandLineProcessorContext *ctx,
@@ -335,7 +336,7 @@ GNUNET_GETOPT_set_filename (struct GNUNET_GETOPT_CommandLineProcessorContext *ct
335 * @param scls additional closure (will point to the 'int') 336 * @param scls additional closure (will point to the 'int')
336 * @param option name of the option 337 * @param option name of the option
337 * @param value not used (NULL) 338 * @param value not used (NULL)
338 * @return GNUNET_OK 339 * @return #GNUNET_OK (always)
339 */ 340 */
340int 341int
341GNUNET_GETOPT_increment_value (struct GNUNET_GETOPT_CommandLineProcessorContext 342GNUNET_GETOPT_increment_value (struct GNUNET_GETOPT_CommandLineProcessorContext
@@ -352,7 +353,7 @@ GNUNET_GETOPT_increment_value (struct GNUNET_GETOPT_CommandLineProcessorContext
352 * @param scls additional closure (points to about text) 353 * @param scls additional closure (points to about text)
353 * @param option name of the option 354 * @param option name of the option
354 * @param value not used (NULL) 355 * @param value not used (NULL)
355 * @return GNUNET_NO (do not continue, not an error) 356 * @return #GNUNET_NO (do not continue, not an error)
356 */ 357 */
357int 358int
358GNUNET_GETOPT_format_help_ (struct GNUNET_GETOPT_CommandLineProcessorContext 359GNUNET_GETOPT_format_help_ (struct GNUNET_GETOPT_CommandLineProcessorContext
@@ -366,7 +367,7 @@ GNUNET_GETOPT_format_help_ (struct GNUNET_GETOPT_CommandLineProcessorContext
366 * @param scls additional closure (points to version string) 367 * @param scls additional closure (points to version string)
367 * @param option name of the option 368 * @param option name of the option
368 * @param value not used (NULL) 369 * @param value not used (NULL)
369 * @return GNUNET_NO (do not continue, not an error) 370 * @return #GNUNET_NO (do not continue, not an error)
370 */ 371 */
371int 372int
372GNUNET_GETOPT_print_version_ (struct GNUNET_GETOPT_CommandLineProcessorContext 373GNUNET_GETOPT_print_version_ (struct GNUNET_GETOPT_CommandLineProcessorContext
@@ -380,6 +381,7 @@ GNUNET_GETOPT_print_version_ (struct GNUNET_GETOPT_CommandLineProcessorContext
380} 381}
381#endif 382#endif
382 383
384/** @} */ /* end of group getopt */
383 385
384/* ifndef GNUNET_GETOPT_LIB_H */ 386/* ifndef GNUNET_GETOPT_LIB_H */
385#endif 387#endif
diff --git a/src/include/gnunet_identity_service.h b/src/include/gnunet_identity_service.h
index 23dee600f..1d682cb1e 100644
--- a/src/include/gnunet_identity_service.h
+++ b/src/include/gnunet_identity_service.h
@@ -30,7 +30,10 @@
30 * manages the egos (private keys) of the local user; it does 30 * manages the egos (private keys) of the local user; it does
31 * NOT manage identities of other users (public keys). For giving 31 * NOT manage identities of other users (public keys). For giving
32 * names to other users and manage their public keys securely, we 32 * names to other users and manage their public keys securely, we
33 * use GADS/GNS. 33 * use GNS.
34 *
35 * @defgroup identity identity management service
36 * @{
34 */ 37 */
35#ifndef GNUNET_IDENTITY_SERVICE_H 38#ifndef GNUNET_IDENTITY_SERVICE_H
36#define GNUNET_IDENTITY_SERVICE_H 39#define GNUNET_IDENTITY_SERVICE_H
@@ -101,27 +104,27 @@ GNUNET_IDENTITY_ego_get_public_key (const struct GNUNET_IDENTITY_Ego *ego,
101 * Method called to inform about the egos of 104 * Method called to inform about the egos of
102 * this peer. 105 * this peer.
103 * 106 *
104 * When used with 'GNUNET_IDENTITY_connect', this function is 107 * When used with #GNUNET_IDENTITY_connect, this function is
105 * initially called for all egos and then again whenever a 108 * initially called for all egos and then again whenever a
106 * ego's name changes or if it is deleted. At the end of 109 * ego's name changes or if it is deleted. At the end of
107 * the initial pass over all egos, the function is once called 110 * the initial pass over all egos, the function is once called
108 * with 'NULL' for 'ego'. That does NOT mean that the callback won't 111 * with 'NULL' for @a ego. That does NOT mean that the callback won't
109 * be invoked in the future or that there was an error. 112 * be invoked in the future or that there was an error.
110 * 113 *
111 * When used with 'GNUNET_IDENTITY_create' or 'GNUNET_IDENTITY_get', 114 * When used with #GNUNET_IDENTITY_create or #GNUNET_IDENTITY_get,
112 * this function is only called ONCE, and 'NULL' being passed in 115 * this function is only called ONCE, and 'NULL' being passed in
113 * 'ego' does indicate an error (i.e. name is taken or no default 116 * @a ego does indicate an error (i.e. name is taken or no default
114 * value is known). If 'ego' is non-NULL and if '*ctx' 117 * value is known). If @a ego is non-NULL and if '*ctx'
115 * is set in those callbacks, the value WILL be passed to a subsequent 118 * is set in those callbacks, the value WILL be passed to a subsequent
116 * call to the identity callback of 'GNUNET_IDENTITY_connect' (if 119 * call to the identity callback of #GNUNET_IDENTITY_connect (if
117 * that one was not NULL). 120 * that one was not NULL).
118 * 121 *
119 * When an identity is renamed, this function is called with the 122 * When an identity is renamed, this function is called with the
120 * (known) ego but the NEW name. 123 * (known) @a ego but the NEW @a name.
121 * 124 *
122 * When an identity is deleted, this function is called with the 125 * When an identity is deleted, this function is called with the
123 * (known) ego and "NULL" for the 'name'. In this case, 126 * (known) ego and "NULL" for the @a name. In this case,
124 * the 'ego' is henceforth invalid (and the 'ctx' should also be 127 * the @a ego is henceforth invalid (and the @a ctx should also be
125 * cleaned up). 128 * cleaned up).
126 * 129 *
127 * @param cls closure 130 * @param cls closure
@@ -143,7 +146,7 @@ typedef void (*GNUNET_IDENTITY_Callback)(void *cls,
143 * 146 *
144 * @param cfg Configuration to contact the identity service. 147 * @param cfg Configuration to contact the identity service.
145 * @param cb function to call on all identity events, can be NULL 148 * @param cb function to call on all identity events, can be NULL
146 * @param cb_cls closure for 'cb' 149 * @param cb_cls closure for @a cb
147 * @return handle to communicate with identity service 150 * @return handle to communicate with identity service
148 */ 151 */
149struct GNUNET_IDENTITY_Handle * 152struct GNUNET_IDENTITY_Handle *
@@ -159,7 +162,7 @@ GNUNET_IDENTITY_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
159 * @param id identity service to query 162 * @param id identity service to query
160 * @param service_name for which service is an identity wanted 163 * @param service_name for which service is an identity wanted
161 * @param cb function to call with the result (will only be called once) 164 * @param cb function to call with the result (will only be called once)
162 * @param cb_cls closure for cb 165 * @param cb_cls closure for @a cb
163 * @return handle to abort the operation 166 * @return handle to abort the operation
164 */ 167 */
165struct GNUNET_IDENTITY_Operation * 168struct GNUNET_IDENTITY_Operation *
@@ -187,7 +190,7 @@ typedef void (*GNUNET_IDENTITY_Continuation)(void *cls,
187 * @param service_name for which service is an identity set 190 * @param service_name for which service is an identity set
188 * @param ego new default identity to be set for this service 191 * @param ego new default identity to be set for this service
189 * @param cont function to call once the operation finished 192 * @param cont function to call once the operation finished
190 * @param cont_cls closure for cont 193 * @param cont_cls closure for @a cont
191 * @return handle to abort the operation 194 * @return handle to abort the operation
192 */ 195 */
193struct GNUNET_IDENTITY_Operation * 196struct GNUNET_IDENTITY_Operation *
@@ -213,7 +216,7 @@ GNUNET_IDENTITY_disconnect (struct GNUNET_IDENTITY_Handle *h);
213 * @param id identity service to use 216 * @param id identity service to use
214 * @param name desired name 217 * @param name desired name
215 * @param cont function to call with the result (will only be called once) 218 * @param cont function to call with the result (will only be called once)
216 * @param cont_cls closure for cont 219 * @param cont_cls closure for @a cont
217 * @return handle to abort the operation 220 * @return handle to abort the operation
218 */ 221 */
219struct GNUNET_IDENTITY_Operation * 222struct GNUNET_IDENTITY_Operation *
@@ -230,7 +233,7 @@ GNUNET_IDENTITY_create (struct GNUNET_IDENTITY_Handle *id,
230 * @param old_name old name 233 * @param old_name old name
231 * @param new_name desired new name 234 * @param new_name desired new name
232 * @param cb function to call with the result (will only be called once) 235 * @param cb function to call with the result (will only be called once)
233 * @param cb_cls closure for cb 236 * @param cb_cls closure for @a cb
234 * @return handle to abort the operation 237 * @return handle to abort the operation
235 */ 238 */
236struct GNUNET_IDENTITY_Operation * 239struct GNUNET_IDENTITY_Operation *
@@ -247,7 +250,7 @@ GNUNET_IDENTITY_rename (struct GNUNET_IDENTITY_Handle *id,
247 * @param id identity service to use 250 * @param id identity service to use
248 * @param name name of the identity to delete 251 * @param name name of the identity to delete
249 * @param cb function to call with the result (will only be called once) 252 * @param cb function to call with the result (will only be called once)
250 * @param cb_cls closure for cb 253 * @param cb_cls closure for @a cb
251 * @return handle to abort the operation 254 * @return handle to abort the operation
252 */ 255 */
253struct GNUNET_IDENTITY_Operation * 256struct GNUNET_IDENTITY_Operation *
@@ -276,6 +279,8 @@ GNUNET_IDENTITY_cancel (struct GNUNET_IDENTITY_Operation *op);
276} 279}
277#endif 280#endif
278 281
282/** @} */ /* end of group identity */
283
279/* ifndef GNUNET_IDENTITY_SERVICE_H */ 284/* ifndef GNUNET_IDENTITY_SERVICE_H */
280#endif 285#endif
281/* end of gnunet_identity_service.h */ 286/* end of gnunet_identity_service.h */
diff --git a/src/include/gnunet_mq_lib.h b/src/include/gnunet_mq_lib.h
index a20588b4d..f88017fbe 100644
--- a/src/include/gnunet_mq_lib.h
+++ b/src/include/gnunet_mq_lib.h
@@ -1,10 +1,10 @@
1/* 1/*
2 This file is part of GNUnet. 2 This file is part of GNUnet.
3 (C) 2012 Christian Grothoff (and other contributing authors) 3 (C) 2012-2013 Christian Grothoff (and other contributing authors)
4 4
5 GNUnet is free software; you can redistribute it and/or modify 5 GNUnet is free software; you can redistribute it and/or modify
6 it under the terms of the GNU General Public License as published 6 it under the terms of the GNU General Public License as published
7 by the Free Software Foundation; either version 2, or (at your 7 by the Free Software Foundation; either version 3, or (at your
8 option) any later version. 8 option) any later version.
9 9
10 GNUnet is distributed in the hope that it will be useful, but 10 GNUnet is distributed in the hope that it will be useful, but
@@ -22,6 +22,8 @@
22 * @author Florian Dold 22 * @author Florian Dold
23 * @file include/gnunet_mq_lib.h 23 * @file include/gnunet_mq_lib.h
24 * @brief general purpose message queue 24 * @brief general purpose message queue
25 * @defgroup mq general purpose message queue
26 * @{
25 */ 27 */
26#ifndef GNUNET_MQ_H 28#ifndef GNUNET_MQ_H
27#define GNUNET_MQ_H 29#define GNUNET_MQ_H
@@ -93,7 +95,7 @@
93 * @param var pointer to a message struct, the type of the expression determines the base size, 95 * @param var pointer to a message struct, the type of the expression determines the base size,
94 * the space after the base size is the nested message 96 * the space after the base size is the nested message
95 * @return a 'struct GNUNET_MessageHeader *' that points at the nested message of the given message, 97 * @return a 'struct GNUNET_MessageHeader *' that points at the nested message of the given message,
96 * or NULL if the given message in 'var' does not have any space after the message struct 98 * or NULL if the given message in @a var does not have any space after the message struct
97 */ 99 */
98#define GNUNET_MQ_extract_nested_mh(var) GNUNET_MQ_extract_nested_mh_ ((struct GNUNET_MessageHeader *) (var), sizeof (*(var))) 100#define GNUNET_MQ_extract_nested_mh(var) GNUNET_MQ_extract_nested_mh_ ((struct GNUNET_MessageHeader *) (var), sizeof (*(var)))
99 101
@@ -140,10 +142,25 @@ struct GNUNET_MQ_Handle;
140 */ 142 */
141struct GNUNET_MQ_Envelope; 143struct GNUNET_MQ_Envelope;
142 144
145
146/**
147 * Error codes for the queue.
148 */
143enum GNUNET_MQ_Error 149enum GNUNET_MQ_Error
144{ 150{
151 /**
152 * FIXME: document!
153 */
145 GNUNET_MQ_ERROR_READ = 1, 154 GNUNET_MQ_ERROR_READ = 1,
155
156 /**
157 * FIXME: document!
158 */
146 GNUNET_MQ_ERROR_WRITE = 2, 159 GNUNET_MQ_ERROR_WRITE = 2,
160
161 /**
162 * FIXME: document!
163 */
147 GNUNET_MQ_ERROR_TIMEOUT = 4 164 GNUNET_MQ_ERROR_TIMEOUT = 4
148}; 165};
149 166
@@ -176,8 +193,8 @@ typedef void
176/** 193/**
177 * Signature of functions implementing the 194 * Signature of functions implementing the
178 * destruction of a message queue. 195 * destruction of a message queue.
179 * Implementations must not free 'mq', but should 196 * Implementations must not free @a mq, but should
180 * take care of 'impl_state'. 197 * take care of @a impl_state.
181 * 198 *
182 * @param mq the message queue to destroy 199 * @param mq the message queue to destroy
183 * @param impl_state state of the implementation 200 * @param impl_state state of the implementation
@@ -277,12 +294,14 @@ GNUNET_MQ_discard (struct GNUNET_MQ_Envelope *mqm);
277 * @param ev the envelope with the message to send. 294 * @param ev the envelope with the message to send.
278 */ 295 */
279void 296void
280GNUNET_MQ_send (struct GNUNET_MQ_Handle *mq, struct GNUNET_MQ_Envelope *ev); 297GNUNET_MQ_send (struct GNUNET_MQ_Handle *mq,
298 struct GNUNET_MQ_Envelope *ev);
281 299
282 300
283/** 301/**
284 * Cancel sending the message. Message must have been sent with GNUNET_MQ_send before. 302 * Cancel sending the message. Message must have been sent with
285 * May not be called after the notify sent callback has been called 303 * #GNUNET_MQ_send before. May not be called after the notify sent
304 * callback has been called
286 * 305 *
287 * @param ev queued envelope to cancel 306 * @param ev queued envelope to cancel
288 */ 307 */
@@ -340,7 +359,7 @@ GNUNET_MQ_queue_for_connection_client (struct GNUNET_CLIENT_Connection *connecti
340 359
341 360
342/** 361/**
343 * Create a message queue for a GNUNET_STREAM_Socket. 362 * Create a message queue for a GNUNET_SERVER_Client.
344 * 363 *
345 * @param client the client 364 * @param client the client
346 * @return the message queue 365 * @return the message queue
@@ -355,7 +374,7 @@ GNUNET_MQ_queue_for_server_client (struct GNUNET_SERVER_Client *client);
355 * @param send function the implements sending messages 374 * @param send function the implements sending messages
356 * @param destroy function that implements destroying the queue 375 * @param destroy function that implements destroying the queue
357 * @param cancel function that implements canceling a message 376 * @param cancel function that implements canceling a message
358 * @param impl_state for the queue, passed to 'send' and 'destroy' 377 * @param impl_state for the queue, passed to @a send, @a destroy and @a cancel
359 * @param handlers array of message handlers 378 * @param handlers array of message handlers
360 * @param error_handler handler for read and write errors 379 * @param error_handler handler for read and write errors
361 * @param cls closure for message handlers and error handler 380 * @param cls closure for message handlers and error handler
@@ -497,4 +516,6 @@ GNUNET_MQ_impl_state (struct GNUNET_MQ_Handle *mq);
497void 516void
498GNUNET_MQ_impl_send_commit (struct GNUNET_MQ_Handle *mq); 517GNUNET_MQ_impl_send_commit (struct GNUNET_MQ_Handle *mq);
499 518
519/** @} */ /* end of group mq */
520
500#endif 521#endif
diff --git a/src/include/gnunet_namestore_service.h b/src/include/gnunet_namestore_service.h
index 75e9224ef..1e459a850 100644
--- a/src/include/gnunet_namestore_service.h
+++ b/src/include/gnunet_namestore_service.h
@@ -147,6 +147,7 @@ enum GNUNET_NAMESTORE_RecordFlags
147 * This peer is the authority for this record; it must thus 147 * This peer is the authority for this record; it must thus
148 * not be deleted (other records can be deleted if we run 148 * not be deleted (other records can be deleted if we run
149 * out of space). 149 * out of space).
150 * @deprecated
150 */ 151 */
151 GNUNET_NAMESTORE_RF_AUTHORITY = 1, 152 GNUNET_NAMESTORE_RF_AUTHORITY = 1,
152 153
@@ -157,8 +158,8 @@ enum GNUNET_NAMESTORE_RecordFlags
157 GNUNET_NAMESTORE_RF_PRIVATE = 2, 158 GNUNET_NAMESTORE_RF_PRIVATE = 2,
158 159
159 /** 160 /**
160 * This record was added by the system 161 * This record was added automatically by the system
161 * and is pending user confimation 162 * and is pending user confimation.
162 */ 163 */
163 GNUNET_NAMESTORE_RF_PENDING = 4, 164 GNUNET_NAMESTORE_RF_PENDING = 4,
164 165
@@ -196,20 +197,16 @@ struct GNUNET_NAMESTORE_RecordData
196{ 197{
197 198
198 /** 199 /**
199 * Binary value stored in the DNS record. 200 * Binary value stored in the DNS record. Note: "data" must never
200 * FIXME: goofy API: sometimes 'data' is individually 201 * be individually 'malloc'ed, but instead always points into some
201 * 'malloc'ed, sometimes it points into some existing 202 * existing data area.
202 * data area (so sometimes this should be a 'void *',
203 * sometimes a 'const void *'). This is unclean. We
204 * should go over the code and make sure that 'data'
205 * is NEVER individually alloc'ed here but always points
206 * to some "other" location.
207 */ 203 */
208 const void *data; 204 const void *data;
209 205
210 /** 206 /**
211 * Expiration time for the DNS record. Can be relative 207 * Expiration time for the DNS record. Can be relative
212 * or absolute, depending on 'flags'. 208 * or absolute, depending on 'flags'. Measured in the same
209 * unit as GNUnet time (microseconds).
213 */ 210 */
214 uint64_t expiration_time; 211 uint64_t expiration_time;
215 212
diff --git a/src/include/gnunet_nse_service.h b/src/include/gnunet_nse_service.h
index a0c6016a4..9169c68ba 100644
--- a/src/include/gnunet_nse_service.h
+++ b/src/include/gnunet_nse_service.h
@@ -4,7 +4,7 @@
4 4
5 GNUnet is free software; you can redistribute it and/or modify 5 GNUnet is free software; you can redistribute it and/or modify
6 it under the terms of the GNU General Public License as published 6 it under the terms of the GNU General Public License as published
7 by the Free Software Foundation; either version 2, or (at your 7 by the Free Software Foundation; either version 3, or (at your
8 option) any later version. 8 option) any later version.
9 9
10 GNUnet is distributed in the hope that it will be useful, but 10 GNUnet is distributed in the hope that it will be useful, but
@@ -26,8 +26,9 @@
26 * @brief API to retrieve the current network size estimate, 26 * @brief API to retrieve the current network size estimate,
27 * also to register for notifications whenever a new 27 * also to register for notifications whenever a new
28 * network size estimate is calculated. 28 * network size estimate is calculated.
29 *
30 * @author Nathan Evans 29 * @author Nathan Evans
30 * @defgroup nse network size estimation service
31 * @{
31 */ 32 */
32 33
33#ifdef __cplusplus 34#ifdef __cplusplus
@@ -80,8 +81,7 @@ typedef void (*GNUNET_NSE_Callback) (void *cls,
80 * 81 *
81 * @param cfg the configuration to use 82 * @param cfg the configuration to use
82 * @param func funtion to call with network size estimate 83 * @param func funtion to call with network size estimate
83 * @param func_cls closure to pass for network size estimate callback 84 * @param func_cls closure to pass to @a func
84 *
85 * @return handle to use 85 * @return handle to use
86 */ 86 */
87struct GNUNET_NSE_Handle * 87struct GNUNET_NSE_Handle *
@@ -93,7 +93,6 @@ GNUNET_NSE_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
93 * Disconnect from network size estimation service 93 * Disconnect from network size estimation service
94 * 94 *
95 * @param h handle to destroy 95 * @param h handle to destroy
96 *
97 */ 96 */
98void 97void
99GNUNET_NSE_disconnect (struct GNUNET_NSE_Handle *h); 98GNUNET_NSE_disconnect (struct GNUNET_NSE_Handle *h);
@@ -106,4 +105,6 @@ GNUNET_NSE_disconnect (struct GNUNET_NSE_Handle *h);
106} 105}
107#endif 106#endif
108 107
108/** @} */ /* end of group nse */
109
109#endif /* GNUNET_NSE_SERVICE_H_ */ 110#endif /* GNUNET_NSE_SERVICE_H_ */
diff --git a/src/include/gnunet_program_lib.h b/src/include/gnunet_program_lib.h
index fa96ecf3c..cae1913a0 100644
--- a/src/include/gnunet_program_lib.h
+++ b/src/include/gnunet_program_lib.h
@@ -1,10 +1,10 @@
1/* 1/*
2 This file is part of GNUnet. 2 This file is part of GNUnet.
3 (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2009 Christian Grothoff (and other contributing authors) 3 (C) 2001-2013 Christian Grothoff (and other contributing authors)
4 4
5 GNUnet is free software; you can redistribute it and/or modify 5 GNUnet is free software; you can redistribute it and/or modify
6 it under the terms of the GNU General Public License as published 6 it under the terms of the GNU General Public License as published
7 by the Free Software Foundation; either version 2, or (at your 7 by the Free Software Foundation; either version 3, or (at your
8 option) any later version. 8 option) any later version.
9 9
10 GNUnet is distributed in the hope that it will be useful, but 10 GNUnet is distributed in the hope that it will be useful, but
@@ -22,6 +22,8 @@
22 * @file include/gnunet_program_lib.h 22 * @file include/gnunet_program_lib.h
23 * @brief functions related to starting programs 23 * @brief functions related to starting programs
24 * @author Christian Grothoff 24 * @author Christian Grothoff
25 * @defgroup program functions for writing command-line programs
26 * @{
25 */ 27 */
26 28
27#ifndef GNUNET_PROGRAM_LIB_H 29#ifndef GNUNET_PROGRAM_LIB_H
@@ -57,16 +59,16 @@ typedef void (*GNUNET_PROGRAM_Main) (void *cls, char *const *args,
57 * Run a standard GNUnet command startup sequence (initialize loggers 59 * Run a standard GNUnet command startup sequence (initialize loggers
58 * and configuration, parse options). 60 * and configuration, parse options).
59 * 61 *
60 * @param argc number of command line arguments 62 * @param argc number of command line arguments in @a argv
61 * @param argv command line arguments 63 * @param argv command line arguments
62 * @param binaryName our expected name 64 * @param binaryName our expected name
63 * @param binaryHelp help text for the program 65 * @param binaryHelp help text for the program
64 * @param options command line options 66 * @param options command line options
65 * @param task main function to run 67 * @param task main function to run
66 * @param task_cls closure for task 68 * @param task_cls closure for @a task
67 * @param run_without_scheduler GNUNET_NO start the scheduler, GNUNET_YES do not 69 * @param run_without_scheduler #GNUNET_NO start the scheduler,
68 * start the scheduler just run the main task 70 * #GNUNET_YES do not start the scheduler just run the main task
69 * @return GNUNET_SYSERR on error, GNUNET_OK on success 71 * @return #GNUNET_SYSERR on error, #GNUNET_OK on success
70 */ 72 */
71int 73int
72GNUNET_PROGRAM_run2 (int argc, char *const *argv, const char *binaryName, 74GNUNET_PROGRAM_run2 (int argc, char *const *argv, const char *binaryName,
@@ -85,8 +87,8 @@ GNUNET_PROGRAM_run2 (int argc, char *const *argv, const char *binaryName,
85 * @param binaryHelp helptext for "-h" option (about the app) 87 * @param binaryHelp helptext for "-h" option (about the app)
86 * @param options command line options 88 * @param options command line options
87 * @param task main function to run 89 * @param task main function to run
88 * @param task_cls closure for task 90 * @param task_cls closure for @a task
89 * @return GNUNET_SYSERR on error, GNUNET_OK on success 91 * @return #GNUNET_SYSERR on error, #GNUNET_OK on success
90 */ 92 */
91int 93int
92GNUNET_PROGRAM_run (int argc, char *const *argv, const char *binaryName, 94GNUNET_PROGRAM_run (int argc, char *const *argv, const char *binaryName,
@@ -103,6 +105,8 @@ GNUNET_PROGRAM_run (int argc, char *const *argv, const char *binaryName,
103} 105}
104#endif 106#endif
105 107
108/** @} */ /* end of group program */
109
106/* ifndef GNUNET_PROGRAM_LIB_H */ 110/* ifndef GNUNET_PROGRAM_LIB_H */
107#endif 111#endif
108/* end of gnunet_program_lib.h */ 112/* end of gnunet_program_lib.h */
diff --git a/src/include/gnunet_protocols.h b/src/include/gnunet_protocols.h
index 9020ce317..a62b286af 100644
--- a/src/include/gnunet_protocols.h
+++ b/src/include/gnunet_protocols.h
@@ -1,10 +1,10 @@
1/* 1/*
2 This file is part of GNUnet. 2 This file is part of GNUnet.
3 (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2009, 2010 Christian Grothoff (and other contributing authors) 3 (C) 2001-2013 Christian Grothoff (and other contributing authors)
4 4
5 GNUnet is free software; you can redistribute it and/or modify 5 GNUnet is free software; you can redistribute it and/or modify
6 it under the terms of the GNU General Public License as published 6 it under the terms of the GNU General Public License as published
7 by the Free Software Foundation; either version 2, or (at your 7 by the Free Software Foundation; either version 3, or (at your
8 option) any later version. 8 option) any later version.
9 9
10 GNUnet is distributed in the hope that it will be useful, but 10 GNUnet is distributed in the hope that it will be useful, but
@@ -345,11 +345,6 @@ extern "C"
345#define GNUNET_MESSAGE_TYPE_CORE_ITERATE_PEERS_END 79 345#define GNUNET_MESSAGE_TYPE_CORE_ITERATE_PEERS_END 79
346 346
347/** 347/**
348 * Check whether a given peer is currently connected to CORE.
349 */
350#define GNUNET_MESSAGE_TYPE_CORE_PEER_CONNECTED 80
351
352/**
353 * Encapsulation for an encrypted message between peers. 348 * Encapsulation for an encrypted message between peers.
354 */ 349 */
355#define GNUNET_MESSAGE_TYPE_CORE_ENCRYPTED_MESSAGE 82 350#define GNUNET_MESSAGE_TYPE_CORE_ENCRYPTED_MESSAGE 82
diff --git a/src/include/gnunet_resolver_service.h b/src/include/gnunet_resolver_service.h
index ae98bb8a6..31fd178ca 100644
--- a/src/include/gnunet_resolver_service.h
+++ b/src/include/gnunet_resolver_service.h
@@ -22,6 +22,8 @@
22 * @file include/gnunet_resolver_service.h 22 * @file include/gnunet_resolver_service.h
23 * @brief functions related to doing DNS lookups 23 * @brief functions related to doing DNS lookups
24 * @author Christian Grothoff 24 * @author Christian Grothoff
25 * @defgroup resolver asynchronous standard DNS lookups
26 * @{
25 */ 27 */
26 28
27#ifndef GNUNET_RESOLVER_SERVICE_H 29#ifndef GNUNET_RESOLVER_SERVICE_H
@@ -45,7 +47,7 @@ extern "C"
45 * 47 *
46 * @param cls closure 48 * @param cls closure
47 * @param addr one of the addresses of the host, NULL for the last address 49 * @param addr one of the addresses of the host, NULL for the last address
48 * @param addrlen length of the address 50 * @param addrlen length of @a addr
49 */ 51 */
50typedef void (*GNUNET_RESOLVER_AddressCallback) (void *cls, 52typedef void (*GNUNET_RESOLVER_AddressCallback) (void *cls,
51 const struct sockaddr *addr, 53 const struct sockaddr *addr,
@@ -80,7 +82,7 @@ GNUNET_RESOLVER_disconnect (void);
80 * @param hostname the hostname to resolve 82 * @param hostname the hostname to resolve
81 * @param af AF_INET or AF_INET6; use AF_UNSPEC for "any" 83 * @param af AF_INET or AF_INET6; use AF_UNSPEC for "any"
82 * @param callback function to call with addresses 84 * @param callback function to call with addresses
83 * @param callback_cls closure for callback 85 * @param callback_cls closure for @a callback
84 * @param timeout how long to try resolving 86 * @param timeout how long to try resolving
85 * @return handle that can be used to cancel the request, NULL on error 87 * @return handle that can be used to cancel the request, NULL on error
86 */ 88 */
@@ -96,7 +98,7 @@ GNUNET_RESOLVER_ip_get (const char *hostname, int af,
96 * 98 *
97 * @param af AF_INET or AF_INET6; use AF_UNSPEC for "any" 99 * @param af AF_INET or AF_INET6; use AF_UNSPEC for "any"
98 * @param callback function to call with addresses 100 * @param callback function to call with addresses
99 * @param cls closure for callback 101 * @param cls closure for @a callback
100 * @param timeout how long to try resolving 102 * @param timeout how long to try resolving
101 * @return handle that can be used to cancel the request, NULL on error 103 * @return handle that can be used to cancel the request, NULL on error
102 */ 104 */
@@ -130,11 +132,11 @@ GNUNET_RESOLVER_local_fqdn_get (void);
130 * Perform a reverse DNS lookup. 132 * Perform a reverse DNS lookup.
131 * 133 *
132 * @param sa host address 134 * @param sa host address
133 * @param salen length of host address 135 * @param salen length of @a sa
134 * @param do_resolve use GNUNET_NO to return numeric hostname 136 * @param do_resolve use #GNUNET_NO to return numeric hostname
135 * @param timeout how long to try resolving 137 * @param timeout how long to try resolving
136 * @param callback function to call with hostnames 138 * @param callback function to call with hostnames
137 * @param cls closure for callback 139 * @param cls closure for @a callback
138 * @return handle that can be used to cancel the request, NULL on error 140 * @return handle that can be used to cancel the request, NULL on error
139 */ 141 */
140struct GNUNET_RESOLVER_RequestHandle * 142struct GNUNET_RESOLVER_RequestHandle *
@@ -164,6 +166,8 @@ GNUNET_RESOLVER_request_cancel (struct GNUNET_RESOLVER_RequestHandle *rh);
164} 166}
165#endif 167#endif
166 168
169/** @} */ /* end of group resolver */
170
167/* ifndef GNUNET_RESOLVER_SERVICE_H */ 171/* ifndef GNUNET_RESOLVER_SERVICE_H */
168#endif 172#endif
169/* end of gnunet_resolver_service.h */ 173/* end of gnunet_resolver_service.h */
diff --git a/src/include/gnunet_server_lib.h b/src/include/gnunet_server_lib.h
index 468f5bf17..7b48b621c 100644
--- a/src/include/gnunet_server_lib.h
+++ b/src/include/gnunet_server_lib.h
@@ -21,8 +21,9 @@
21/** 21/**
22 * @file include/gnunet_server_lib.h 22 * @file include/gnunet_server_lib.h
23 * @brief library for building GNUnet network servers 23 * @brief library for building GNUnet network servers
24 *
25 * @author Christian Grothoff 24 * @author Christian Grothoff
25 * @defgroup server functions for a server that communicates with clients
26 * @{
26 */ 27 */
27 28
28#ifndef GNUNET_SERVER_LIB_H 29#ifndef GNUNET_SERVER_LIB_H
@@ -41,7 +42,10 @@ extern "C"
41 42
42 43
43/** 44/**
44 * Largest supported message. 45 * Largest supported message (to be precise, one byte more
46 * than the largest possible message, so tests involving
47 * this value should check for messages being smaller than
48 * this value).
45 */ 49 */
46#define GNUNET_SERVER_MAX_MESSAGE_SIZE 65536 50#define GNUNET_SERVER_MAX_MESSAGE_SIZE 65536
47 51
@@ -75,11 +79,9 @@ struct GNUNET_SERVER_TransmitHandle;
75 * @param message the actual message 79 * @param message the actual message
76 */ 80 */
77typedef void (*GNUNET_SERVER_MessageCallback) (void *cls, 81typedef void (*GNUNET_SERVER_MessageCallback) (void *cls,
78 struct GNUNET_SERVER_Client * 82 struct GNUNET_SERVER_Client *client,
79 client,
80 const struct GNUNET_MessageHeader 83 const struct GNUNET_MessageHeader
81 * message); 84 *message);
82
83 85
84 86
85/** 87/**
@@ -118,10 +120,10 @@ struct GNUNET_SERVER_MessageHandler
118 * Create a new server. 120 * Create a new server.
119 * 121 *
120 * @param access function for access control 122 * @param access function for access control
121 * @param access_cls closure for access 123 * @param access_cls closure for @a access
122 * @param lsocks NULL-terminated array of listen sockets 124 * @param lsocks NULL-terminated array of listen sockets
123 * @param idle_timeout after how long should we timeout idle connections? 125 * @param idle_timeout after how long should we timeout idle connections?
124 * @param require_found if YES, connections sending messages of unknown type 126 * @param require_found if #GNUNET_YES, connections sending messages of unknown type
125 * will be closed 127 * will be closed
126 * @return handle for the new server, NULL on error 128 * @return handle for the new server, NULL on error
127 * (typically, "port" already in use) 129 * (typically, "port" already in use)
@@ -137,11 +139,11 @@ GNUNET_SERVER_create_with_sockets (GNUNET_CONNECTION_AccessCheck access,
137 * Create a new server. 139 * Create a new server.
138 * 140 *
139 * @param access function for access control 141 * @param access function for access control
140 * @param access_cls closure for access 142 * @param access_cls closure for @a access
141 * @param serverAddr address toes listen on (including port), NULL terminated array 143 * @param serverAddr address toes listen on (including port), NULL terminated array
142 * @param socklen lengths of respective serverAddr 144 * @param socklen lengths of respective @a serverAddr
143 * @param idle_timeout after how long should we timeout idle connections? 145 * @param idle_timeout after how long should we timeout idle connections?
144 * @param require_found if YES, connections sending messages of unknown type 146 * @param require_found if #GNUNET_YES, connections sending messages of unknown type
145 * will be closed 147 * will be closed
146 * @return handle for the new server, NULL on error 148 * @return handle for the new server, NULL on error
147 * (typically, "port" already in use) 149 * (typically, "port" already in use)
@@ -156,6 +158,7 @@ GNUNET_SERVER_create (GNUNET_CONNECTION_AccessCheck access, void *access_cls,
156 158
157/** 159/**
158 * Suspend accepting connections from the listen socket temporarily. 160 * Suspend accepting connections from the listen socket temporarily.
161 * Resume activity using #GNUNET_SERVER_resume.
159 * 162 *
160 * @param server server to stop accepting connections. 163 * @param server server to stop accepting connections.
161 */ 164 */
@@ -173,8 +176,9 @@ GNUNET_SERVER_resume (struct GNUNET_SERVER_Handle *server);
173 176
174 177
175/** 178/**
176 * Stop the listen socket and get ready to shutdown the server 179 * Stop the listen socket and get ready to shutdown the server once
177 * once only 'monitor' clients are left. 180 * only clients marked using #GNUNET_SERVER_client_mark_monitor are
181 * left.
178 * 182 *
179 * @param server server to stop listening on 183 * @param server server to stop listening on
180 */ 184 */
@@ -219,10 +223,10 @@ GNUNET_SERVER_add_handlers (struct GNUNET_SERVER_Handle *server,
219 * @param timeout after how long should we give up (and call 223 * @param timeout after how long should we give up (and call
220 * notify with buf NULL and size 0)? 224 * notify with buf NULL and size 0)?
221 * @param callback function to call when space is available 225 * @param callback function to call when space is available
222 * @param callback_cls closure for callback 226 * @param callback_cls closure for @a callback
223 * @return non-NULL if the notify callback was queued; can be used 227 * @return non-NULL if the notify callback was queued; can be used
224 * to cancel the request using 228 * to cancel the request using
225 * GNUNET_SERVER_notify_transmit_ready_cancel. 229 * #GNUNET_SERVER_notify_transmit_ready_cancel.
226 * NULL if we are already going to notify someone else (busy) 230 * NULL if we are already going to notify someone else (busy)
227 */ 231 */
228struct GNUNET_SERVER_TransmitHandle * 232struct GNUNET_SERVER_TransmitHandle *
@@ -245,12 +249,12 @@ GNUNET_SERVER_notify_transmit_ready_cancel (struct GNUNET_SERVER_TransmitHandle
245/** 249/**
246 * Set the 'monitor' flag on this client. Clients which have been 250 * Set the 'monitor' flag on this client. Clients which have been
247 * marked as 'monitors' won't prevent the server from shutting down 251 * marked as 'monitors' won't prevent the server from shutting down
248 * once 'GNUNET_SERVER_stop_listening' has been invoked. The idea is 252 * once #GNUNET_SERVER_stop_listening has been invoked. The idea is
249 * that for "normal" clients we likely want to allow them to process 253 * that for "normal" clients we likely want to allow them to process
250 * their requests; however, monitor-clients are likely to 'never' 254 * their requests; however, monitor-clients are likely to 'never'
251 * disconnect during shutdown and thus will not be considered when 255 * disconnect during shutdown and thus will not be considered when
252 * determining if the server should continue to exist after 256 * determining if the server should continue to exist after
253 * 'GNUNET_SERVER_destroy' has been called. 257 * #GNUNET_SERVER_destroy has been called.
254 * 258 *
255 * @param client the client to set the 'monitor' flag on 259 * @param client the client to set the 'monitor' flag on
256 */ 260 */
@@ -259,8 +263,11 @@ GNUNET_SERVER_client_mark_monitor (struct GNUNET_SERVER_Client *client);
259 263
260 264
261/** 265/**
262 * Set the persistent flag on this client, used to setup client connection 266 * Set the persistent flag on this client, used to setup client
263 * to only be killed when the service it's connected to is actually dead. 267 * connection to only be killed when the process of the service it's
268 * connected to is actually dead. This API is used during shutdown
269 * signalling within ARM, and it is not expected that typical users
270 * of the API would need this function.
264 * 271 *
265 * @param client the client to set the persistent flag on 272 * @param client the client to set the persistent flag on
266 */ 273 */
@@ -271,17 +278,18 @@ GNUNET_SERVER_client_persist_ (struct GNUNET_SERVER_Client *client);
271/** 278/**
272 * Resume receiving from this client, we are done processing the 279 * Resume receiving from this client, we are done processing the
273 * current request. This function must be called from within each 280 * current request. This function must be called from within each
274 * GNUNET_SERVER_MessageCallback (or its respective continuations). 281 * #GNUNET_SERVER_MessageCallback (or its respective continuations).
275 * 282 *
276 * @param client client we were processing a message of 283 * @param client client we were processing a message of
277 * @param success GNUNET_OK to keep the connection open and 284 * @param success #GNUNET_OK to keep the connection open and
278 * continue to receive 285 * continue to receive
279 * GNUNET_NO to close the connection (normal behavior) 286 * #GNUNET_NO to close the connection (normal behavior)
280 * GNUNET_SYSERR to close the connection (signal 287 * #GNUNET_SYSERR to close the connection (signal
281 * serious error) 288 * serious error)
282 */ 289 */
283void 290void
284GNUNET_SERVER_receive_done (struct GNUNET_SERVER_Client *client, int success); 291GNUNET_SERVER_receive_done (struct GNUNET_SERVER_Client *client,
292 int success);
285 293
286 294
287/** 295/**
@@ -297,7 +305,6 @@ GNUNET_SERVER_client_set_timeout (struct GNUNET_SERVER_Client *client,
297 struct GNUNET_TIME_Relative timeout); 305 struct GNUNET_TIME_Relative timeout);
298 306
299 307
300
301/** 308/**
302 * Return user context associated with the given client. 309 * Return user context associated with the given client.
303 * Note: you should probably use the macro (call without the underscore). 310 * Note: you should probably use the macro (call without the underscore).
@@ -365,9 +372,9 @@ GNUNET_SERVER_disable_receive_done_warning (struct GNUNET_SERVER_Client
365 * @param sender the "pretended" sender of the message 372 * @param sender the "pretended" sender of the message
366 * can be NULL! 373 * can be NULL!
367 * @param message message to transmit 374 * @param message message to transmit
368 * @return GNUNET_OK if the message was OK and the 375 * @return #GNUNET_OK if the message was OK and the
369 * connection can stay open 376 * connection can stay open
370 * GNUNET_SYSERR if the connection to the 377 * #GNUNET_SYSERR if the connection to the
371 * client should be shut down 378 * client should be shut down
372 */ 379 */
373int 380int
@@ -386,7 +393,7 @@ GNUNET_SERVER_inject (struct GNUNET_SERVER_Handle *server,
386 * @param connection the connection to manage (client must 393 * @param connection the connection to manage (client must
387 * stop using this connection from now on) 394 * stop using this connection from now on)
388 * @return the client handle (client should call 395 * @return the client handle (client should call
389 * "client_drop" on the return value eventually) 396 * #GNUNET_SERVER_client_drop on the return value eventually)
390 */ 397 */
391struct GNUNET_SERVER_Client * 398struct GNUNET_SERVER_Client *
392GNUNET_SERVER_connect_socket (struct GNUNET_SERVER_Handle *server, 399GNUNET_SERVER_connect_socket (struct GNUNET_SERVER_Handle *server,
@@ -421,12 +428,12 @@ GNUNET_SERVER_client_drop (struct GNUNET_SERVER_Client *client);
421 * 428 *
422 * @param client the client to get the address for 429 * @param client the client to get the address for
423 * @param addr where to store the address 430 * @param addr where to store the address
424 * @param addrlen where to store the length of the address 431 * @param addrlen where to store the length of @a addr
425 * @return GNUNET_OK on success 432 * @return #GNUNET_OK on success
426 */ 433 */
427int 434int
428GNUNET_SERVER_client_get_address (struct GNUNET_SERVER_Client *client, 435GNUNET_SERVER_client_get_address (struct GNUNET_SERVER_Client *client,
429 void **addr, size_t * addrlen); 436 void **addr, size_t *addrlen);
430 437
431 438
432/** 439/**
@@ -438,8 +445,8 @@ GNUNET_SERVER_client_get_address (struct GNUNET_SERVER_Client *client,
438 * for the last call when the server is destroyed 445 * for the last call when the server is destroyed
439 */ 446 */
440typedef void (*GNUNET_SERVER_DisconnectCallback) (void *cls, 447typedef void (*GNUNET_SERVER_DisconnectCallback) (void *cls,
441 struct GNUNET_SERVER_Client * 448 struct GNUNET_SERVER_Client *client);
442 client); 449
443 450
444/** 451/**
445 * Functions with this signature are called whenever a client 452 * Functions with this signature are called whenever a client
@@ -449,8 +456,7 @@ typedef void (*GNUNET_SERVER_DisconnectCallback) (void *cls,
449 * @param client identification of the client 456 * @param client identification of the client
450 */ 457 */
451typedef void (*GNUNET_SERVER_ConnectCallback) (void *cls, 458typedef void (*GNUNET_SERVER_ConnectCallback) (void *cls,
452 struct GNUNET_SERVER_Client *client); 459 struct GNUNET_SERVER_Client *client);
453
454 460
455 461
456/** 462/**
@@ -465,7 +471,7 @@ typedef void (*GNUNET_SERVER_ConnectCallback) (void *cls,
465 * 471 *
466 * @param server the server manageing the clients 472 * @param server the server manageing the clients
467 * @param callback function to call on disconnect 473 * @param callback function to call on disconnect
468 * @param callback_cls closure for callback 474 * @param callback_cls closure for @a callback
469 */ 475 */
470void 476void
471GNUNET_SERVER_disconnect_notify (struct GNUNET_SERVER_Handle *server, 477GNUNET_SERVER_disconnect_notify (struct GNUNET_SERVER_Handle *server,
@@ -477,26 +483,31 @@ GNUNET_SERVER_disconnect_notify (struct GNUNET_SERVER_Handle *server,
477 * Ask the server to notify us whenever a client connects. 483 * Ask the server to notify us whenever a client connects.
478 * This function is called whenever the actual network connection 484 * This function is called whenever the actual network connection
479 * is opened. If the server is destroyed before this 485 * is opened. If the server is destroyed before this
480 * notification is explicitly cancelled, the 'callback' will 486 * notification is explicitly cancelled, the @a callback will
481 * once be called with a 'client' argument of NULL to indicate 487 * once be called with a 'client' argument of NULL to indicate
482 * that the server itself is now gone (and that the callback 488 * that the server itself is now gone (and that the callback
483 * won't be called anymore and also can no longer be cancelled). 489 * won't be called anymore and also can no longer be cancelled).
484 * 490 *
485 * @param server the server manageing the clients 491 * @param server the server manageing the clients
486 * @param callback function to call on sconnect 492 * @param callback function to call on sconnect
487 * @param callback_cls closure for callback 493 * @param callback_cls closure for @a callback
488 */ 494 */
489void 495void
490GNUNET_SERVER_connect_notify (struct GNUNET_SERVER_Handle *server, 496GNUNET_SERVER_connect_notify (struct GNUNET_SERVER_Handle *server,
491 GNUNET_SERVER_ConnectCallback callback, void *callback_cls); 497 GNUNET_SERVER_ConnectCallback callback,
498 void *callback_cls);
492 499
493 500
494/** 501/**
495 * Ask the server to stop notifying us whenever a client disconnects. 502 * Ask the server to stop notifying us whenever a client disconnects.
503 * Arguments must match exactly those given to
504 * #GNUNET_SERVER_disconnect_notify. It is not necessary to call this
505 * function during shutdown of the server; in fact, most applications
506 * will never use this function.
496 * 507 *
497 * @param server the server manageing the clients 508 * @param server the server manageing the clients
498 * @param callback function to call on disconnect 509 * @param callback function to call on disconnect
499 * @param callback_cls closure for callback 510 * @param callback_cls closure for @a callback
500 */ 511 */
501void 512void
502GNUNET_SERVER_disconnect_notify_cancel (struct GNUNET_SERVER_Handle *server, 513GNUNET_SERVER_disconnect_notify_cancel (struct GNUNET_SERVER_Handle *server,
@@ -506,21 +517,26 @@ GNUNET_SERVER_disconnect_notify_cancel (struct GNUNET_SERVER_Handle *server,
506 517
507/** 518/**
508 * Ask the server to stop notifying us whenever a client connects. 519 * Ask the server to stop notifying us whenever a client connects.
520 * Arguments must match exactly those given to
521 * #GNUNET_SERVER_connect_notify. It is not necessary to call this
522 * function during shutdown of the server; in fact, most applications
523 * will never use this function.
509 * 524 *
510 * @param server the server manageing the clients 525 * @param server the server manageing the clients
511 * @param callback function to call on connect 526 * @param callback function to call on connect
512 * @param callback_cls closure for callback 527 * @param callback_cls closure for @a callback
513 */ 528 */
514void 529void
515GNUNET_SERVER_connect_notify_cancel (struct GNUNET_SERVER_Handle *server, 530GNUNET_SERVER_connect_notify_cancel (struct GNUNET_SERVER_Handle *server,
516 GNUNET_SERVER_ConnectCallback callback, void *callback_cls); 531 GNUNET_SERVER_ConnectCallback callback,
532 void *callback_cls);
517 533
518 534
519/** 535/**
520 * Ask the server to disconnect from the given client. 536 * Ask the server to disconnect from the given client. This is the
521 * This is the same as returning GNUNET_SYSERR from a message 537 * same as passing #GNUNET_SYSERR to #GNUNET_SERVER_receive_done,
522 * handler, except that it allows dropping of a client even 538 * except that it allows dropping of a client even when not handling a
523 * when not handling a message from that client. 539 * message from that client.
524 * 540 *
525 * @param client the client to disconnect from 541 * @param client the client to disconnect from
526 */ 542 */
@@ -534,7 +550,7 @@ GNUNET_SERVER_client_disconnect (struct GNUNET_SERVER_Client *client);
534 * instead of potentially buffering multiple messages. 550 * instead of potentially buffering multiple messages.
535 * 551 *
536 * @param client handle to the client 552 * @param client handle to the client
537 * @return GNUNET_OK on success 553 * @return #GNUNET_OK on success
538 */ 554 */
539int 555int
540GNUNET_SERVER_client_disable_corking (struct GNUNET_SERVER_Client *client); 556GNUNET_SERVER_client_disable_corking (struct GNUNET_SERVER_Client *client);
@@ -549,8 +565,7 @@ struct GNUNET_SERVER_TransmitContext;
549 565
550 566
551/** 567/**
552 * Create a new transmission context for the 568 * Create a new transmission context for the given client.
553 * given client.
554 * 569 *
555 * @param client client to create the context for. 570 * @param client client to create the context for.
556 * @return NULL on error 571 * @return NULL on error
@@ -562,11 +577,11 @@ GNUNET_SERVER_transmit_context_create (struct GNUNET_SERVER_Client *client);
562/** 577/**
563 * Append a message to the transmission context. 578 * Append a message to the transmission context.
564 * All messages in the context will be sent by 579 * All messages in the context will be sent by
565 * the transmit_context_run method. 580 * the #GNUNET_SERVER_transmit_context_run method.
566 * 581 *
567 * @param tc context to use 582 * @param tc context to use
568 * @param data what to append to the result message 583 * @param data what to append to the result message
569 * @param length length of data 584 * @param length length of @a data
570 * @param type type of the message 585 * @param type type of the message
571 */ 586 */
572void 587void
@@ -594,7 +609,7 @@ GNUNET_SERVER_transmit_context_append_message (struct
594/** 609/**
595 * Execute a transmission context. If there is an error in the 610 * Execute a transmission context. If there is an error in the
596 * transmission, the receive_done method will be called with an error 611 * transmission, the receive_done method will be called with an error
597 * code (GNUNET_SYSERR), otherwise with GNUNET_OK. 612 * code (#GNUNET_SYSERR), otherwise with #GNUNET_OK.
598 * 613 *
599 * @param tc transmission context to use 614 * @param tc transmission context to use
600 * @param timeout when to time out and abort the transmission 615 * @param timeout when to time out and abort the transmission
@@ -606,14 +621,14 @@ GNUNET_SERVER_transmit_context_run (struct GNUNET_SERVER_TransmitContext *tc,
606 621
607/** 622/**
608 * Destroy a transmission context. This function must not be called 623 * Destroy a transmission context. This function must not be called
609 * after 'GNUNET_SERVER_transmit_context_run'. 624 * after #GNUNET_SERVER_transmit_context_run.
610 * 625 *
611 * @param tc transmission context to destroy 626 * @param tc transmission context to destroy
612 * @param success code to give to 'GNUNET_SERVER_receive_done' for 627 * @param success code to give to #GNUNET_SERVER_receive_done for
613 * the client: GNUNET_OK to keep the connection open and 628 * the client: #GNUNET_OK to keep the connection open and
614 * continue to receive 629 * continue to receive
615 * GNUNET_NO to close the connection (normal behavior) 630 * #GNUNET_NO to close the connection (normal behavior)
616 * GNUNET_SYSERR to close the connection (signal 631 * #GNUNET_SYSERR to close the connection (signal
617 * serious error) 632 * serious error)
618 */ 633 */
619void 634void
@@ -702,23 +717,23 @@ GNUNET_SERVER_notification_context_broadcast (struct
702 *msg, int can_drop); 717 *msg, int can_drop);
703 718
704 719
705
706/** 720/**
707 * Handle to a message stream tokenizer. 721 * Handle to a message stream tokenizer.
708 */ 722 */
709struct GNUNET_SERVER_MessageStreamTokenizer; 723struct GNUNET_SERVER_MessageStreamTokenizer;
710 724
725
711/** 726/**
712 * Functions with this signature are called whenever a 727 * Functions with this signature are called whenever a
713 * complete message is received by the tokenizer. 728 * complete message is received by the tokenizer.
714 * 729 *
715 * Do not call GNUNET_SERVER_mst_destroy in callback 730 * Do not call #GNUNET_SERVER_mst_destroy from within
731 * the scope of this callback.
716 * 732 *
717 * @param cls closure 733 * @param cls closure
718 * @param client identification of the client 734 * @param client identification of the client
719 * @param message the actual message 735 * @param message the actual message
720 * 736 * @return #GNUNET_OK on success, #GNUNET_SYSERR to stop further processing
721 * @return GNUNET_OK on success, GNUNET_SYSERR to stop further processing
722 */ 737 */
723typedef int (*GNUNET_SERVER_MessageTokenizerCallback) (void *cls, void *client, 738typedef int (*GNUNET_SERVER_MessageTokenizerCallback) (void *cls, void *client,
724 const struct 739 const struct
@@ -730,7 +745,7 @@ typedef int (*GNUNET_SERVER_MessageTokenizerCallback) (void *cls, void *client,
730 * Create a message stream tokenizer. 745 * Create a message stream tokenizer.
731 * 746 *
732 * @param cb function to call on completed messages 747 * @param cb function to call on completed messages
733 * @param cb_cls closure for cb 748 * @param cb_cls closure for @a cb
734 * @return handle to tokenizer 749 * @return handle to tokenizer
735 */ 750 */
736struct GNUNET_SERVER_MessageStreamTokenizer * 751struct GNUNET_SERVER_MessageStreamTokenizer *
@@ -746,13 +761,13 @@ GNUNET_SERVER_mst_create (GNUNET_SERVER_MessageTokenizerCallback cb,
746 * @param client_identity ID of client for which this is a buffer, 761 * @param client_identity ID of client for which this is a buffer,
747 * can be NULL (will be passed back to 'cb') 762 * can be NULL (will be passed back to 'cb')
748 * @param buf input data to add 763 * @param buf input data to add
749 * @param size number of bytes in buf 764 * @param size number of bytes in @a buf
750 * @param purge should any excess bytes in the buffer be discarded 765 * @param purge should any excess bytes in the buffer be discarded
751 * (i.e. for packet-based services like UDP) 766 * (i.e. for packet-based services like UDP)
752 * @param one_shot only call callback once, keep rest of message in buffer 767 * @param one_shot only call callback once, keep rest of message in buffer
753 * @return GNUNET_OK if we are done processing (need more data) 768 * @return #GNUNET_OK if we are done processing (need more data)
754 * GNUNET_NO if one_shot was set and we have another message ready 769 * #GNUNET_NO if one_shot was set and we have another message ready
755 * GNUNET_SYSERR if the data stream is corrupt 770 * #GNUNET_SYSERR if the data stream is corrupt
756 */ 771 */
757int 772int
758GNUNET_SERVER_mst_receive (struct GNUNET_SERVER_MessageStreamTokenizer *mst, 773GNUNET_SERVER_mst_receive (struct GNUNET_SERVER_MessageStreamTokenizer *mst,
@@ -779,6 +794,7 @@ GNUNET_SERVER_mst_destroy (struct GNUNET_SERVER_MessageStreamTokenizer *mst);
779typedef void* (*GNUNET_SERVER_MstCreateCallback) (void *cls, 794typedef void* (*GNUNET_SERVER_MstCreateCallback) (void *cls,
780 struct GNUNET_SERVER_Client *client); 795 struct GNUNET_SERVER_Client *client);
781 796
797
782/** 798/**
783 * Signature of a function to destroy a custom tokenizer. 799 * Signature of a function to destroy a custom tokenizer.
784 * 800 *
@@ -787,21 +803,22 @@ typedef void* (*GNUNET_SERVER_MstCreateCallback) (void *cls,
787 */ 803 */
788typedef void (*GNUNET_SERVER_MstDestroyCallback) (void *cls, void *mst); 804typedef void (*GNUNET_SERVER_MstDestroyCallback) (void *cls, void *mst);
789 805
806
790/** 807/**
791 * Signature of a function to receive data for a custom tokenizer. 808 * Signature of a function to receive data for a custom tokenizer.
792 * 809 *
793 * @param cls closure from 'GNUNET_SERVER_set_callbacks' 810 * @param cls closure from #GNUNET_SERVER_set_callbacks
794 * @param mst custom tokenizer handle 811 * @param mst custom tokenizer handle
795 * @param client_identity ID of client for which this is a buffer, 812 * @param client_identity ID of client for which this is a buffer,
796 * can be NULL (will be passed back to 'cb') 813 * can be NULL (will be passed back to 'cb')
797 * @param buf input data to add 814 * @param buf input data to add
798 * @param size number of bytes in buf 815 * @param size number of bytes in @a buf
799 * @param purge should any excess bytes in the buffer be discarded 816 * @param purge should any excess bytes in the buffer be discarded
800 * (i.e. for packet-based services like UDP) 817 * (i.e. for packet-based services like UDP)
801 * @param one_shot only call callback once, keep rest of message in buffer 818 * @param one_shot only call callback once, keep rest of message in buffer
802 * @return GNUNET_OK if we are done processing (need more data) 819 * @return #GNUNET_OK if we are done processing (need more data)
803 * GNUNET_NO if one_shot was set and we have another message ready 820 * #GNUNET_NO if one_shot was set and we have another message ready
804 * GNUNET_SYSERR if the data stream is corrupt 821 * #GNUNET_SYSERR if the data stream is corrupt
805 */ 822 */
806typedef int (*GNUNET_SERVER_MstReceiveCallback) (void *cls, void *mst, 823typedef int (*GNUNET_SERVER_MstReceiveCallback) (void *cls, void *mst,
807 struct GNUNET_SERVER_Client *client, 824 struct GNUNET_SERVER_Client *client,
@@ -817,7 +834,7 @@ typedef int (*GNUNET_SERVER_MstReceiveCallback) (void *cls, void *mst,
817 * @param create new tokenizer initialization function 834 * @param create new tokenizer initialization function
818 * @param destroy new tokenizer destruction function 835 * @param destroy new tokenizer destruction function
819 * @param receive new tokenizer receive function 836 * @param receive new tokenizer receive function
820 * @param cls closure for 'create', 'receive', 'destroy' 837 * @param cls closure for @a create, @a receive and @a destroy
821 */ 838 */
822void 839void
823GNUNET_SERVER_set_callbacks (struct GNUNET_SERVER_Handle *server, 840GNUNET_SERVER_set_callbacks (struct GNUNET_SERVER_Handle *server,
@@ -834,6 +851,7 @@ GNUNET_SERVER_set_callbacks (struct GNUNET_SERVER_Handle *server,
834} 851}
835#endif 852#endif
836 853
854/** @} */ /* end of group server */
837 855
838/* ifndef GNUNET_SERVER_LIB_H */ 856/* ifndef GNUNET_SERVER_LIB_H */
839#endif 857#endif
diff --git a/src/include/gnunet_service_lib.h b/src/include/gnunet_service_lib.h
index cc224ff16..2d7b3064f 100644
--- a/src/include/gnunet_service_lib.h
+++ b/src/include/gnunet_service_lib.h
@@ -1,10 +1,10 @@
1/* 1/*
2 This file is part of GNUnet. 2 This file is part of GNUnet.
3 (C) 2009 Christian Grothoff (and other contributing authors) 3 (C) 2009-2013 Christian Grothoff (and other contributing authors)
4 4
5 GNUnet is free software; you can redistribute it and/or modify 5 GNUnet is free software; you can redistribute it and/or modify
6 it under the terms of the GNU General Public License as published 6 it under the terms of the GNU General Public License as published
7 by the Free Software Foundation; either version 2, or (at your 7 by the Free Software Foundation; either version 3, or (at your
8 option) any later version. 8 option) any later version.
9 9
10 GNUnet is distributed in the hope that it will be useful, but 10 GNUnet is distributed in the hope that it will be useful, but
@@ -22,6 +22,8 @@
22 * @file include/gnunet_service_lib.h 22 * @file include/gnunet_service_lib.h
23 * @brief functions related to starting services 23 * @brief functions related to starting services
24 * @author Christian Grothoff 24 * @author Christian Grothoff
25 * @defgroup service generic functions for implementing service processes
26 * @{
25 */ 27 */
26 28
27#ifndef GNUNET_SERVICE_LIB_H 29#ifndef GNUNET_SERVICE_LIB_H
@@ -49,21 +51,21 @@ extern "C"
49 * addresses the server should bind to and listen on; the 51 * addresses the server should bind to and listen on; the
50 * array will be NULL-terminated (on success) 52 * array will be NULL-terminated (on success)
51 * @param addr_lens set (call by reference) to an array of the lengths 53 * @param addr_lens set (call by reference) to an array of the lengths
52 * of the respective 'struct sockaddr' struct in the 'addrs' 54 * of the respective 'struct sockaddr' struct in the @a addrs
53 * array (on success) 55 * array (on success)
54 * @return number of addresses found on success, 56 * @return number of addresses found on success,
55 * GNUNET_SYSERR if the configuration 57 * #GNUNET_SYSERR if the configuration
56 * did not specify reasonable finding information or 58 * did not specify reasonable finding information or
57 * if it specified a hostname that could not be resolved; 59 * if it specified a hostname that could not be resolved;
58 * GNUNET_NO if the number of addresses configured is 60 * #GNUNET_NO if the number of addresses configured is
59 * zero (in this case, '*addrs' and '*addr_lens' will be 61 * zero (in this case, '* @a addrs' and '* @a addr_lens' will be
60 * set to NULL). 62 * set to NULL).
61 */ 63 */
62int 64int
63GNUNET_SERVICE_get_server_addresses (const char *service_name, 65GNUNET_SERVICE_get_server_addresses (const char *service_name,
64 const struct GNUNET_CONFIGURATION_Handle 66 const struct GNUNET_CONFIGURATION_Handle
65 *cfg, struct sockaddr ***addrs, 67 *cfg, struct sockaddr ***addrs,
66 socklen_t ** addr_lens); 68 socklen_t **addr_lens);
67 69
68 70
69/** 71/**
@@ -75,9 +77,8 @@ GNUNET_SERVICE_get_server_addresses (const char *service_name,
75 * @param cfg configuration to use 77 * @param cfg configuration to use
76 */ 78 */
77typedef void (*GNUNET_SERVICE_Main) (void *cls, 79typedef void (*GNUNET_SERVICE_Main) (void *cls,
78 struct GNUNET_SERVER_Handle * server, 80 struct GNUNET_SERVER_Handle *server,
79 const struct GNUNET_CONFIGURATION_Handle * 81 const struct GNUNET_CONFIGURATION_Handle *cfg);
80 cfg);
81 82
82 83
83/** 84/**
@@ -108,19 +109,21 @@ enum GNUNET_SERVICE_Options
108 * Run a standard GNUnet service startup sequence (initialize loggers 109 * Run a standard GNUnet service startup sequence (initialize loggers
109 * and configuration, parse options). 110 * and configuration, parse options).
110 * 111 *
111 * @param argc number of command line arguments 112 * @param argc number of command line arguments in @a argv
112 * @param argv command line arguments 113 * @param argv command line arguments
113 * @param service_name our service name 114 * @param service_name our service name
114 * @param options service options 115 * @param options service options
115 * @param task main task of the service 116 * @param task main task of the service
116 * @param task_cls closure for task 117 * @param task_cls closure for @a task
117 * @return GNUNET_SYSERR on error, GNUNET_OK 118 * @return #GNUNET_SYSERR on error, #GNUNET_OK
118 * if we shutdown nicely 119 * if we shutdown nicely
119 */ 120 */
120int 121int
121GNUNET_SERVICE_run (int argc, char *const *argv, const char *service_name, 122GNUNET_SERVICE_run (int argc, char *const *argv,
123 const char *service_name,
122 enum GNUNET_SERVICE_Options options, 124 enum GNUNET_SERVICE_Options options,
123 GNUNET_SERVICE_Main task, void *task_cls); 125 GNUNET_SERVICE_Main task,
126 void *task_cls);
124 127
125 128
126/** 129/**
@@ -128,6 +131,7 @@ GNUNET_SERVICE_run (int argc, char *const *argv, const char *service_name,
128 */ 131 */
129struct GNUNET_SERVICE_Context; 132struct GNUNET_SERVICE_Context;
130 133
134
131/** 135/**
132 * Run a service startup sequence within an existing 136 * Run a service startup sequence within an existing
133 * initialized system. 137 * initialized system.
@@ -155,7 +159,7 @@ GNUNET_SERVICE_get_server (struct GNUNET_SERVICE_Context *ctx);
155 159
156 160
157/** 161/**
158 * Stop a service that was started with "GNUNET_SERVICE_start". 162 * Stop a service that was started with #GNUNET_SERVICE_start.
159 * 163 *
160 * @param sctx the service context returned from the start function 164 * @param sctx the service context returned from the start function
161 */ 165 */
@@ -170,6 +174,10 @@ GNUNET_SERVICE_stop (struct GNUNET_SERVICE_Context *sctx);
170} 174}
171#endif 175#endif
172 176
177
178/** @} */ /* end of group service */
179
180
173/* ifndef GNUNET_SERVICE_LIB_H */ 181/* ifndef GNUNET_SERVICE_LIB_H */
174#endif 182#endif
175/* end of gnunet_service_lib.h */ 183/* end of gnunet_service_lib.h */
diff --git a/src/include/gnunet_signal_lib.h b/src/include/gnunet_signal_lib.h
index 1597c76d0..04037b4ca 100644
--- a/src/include/gnunet_signal_lib.h
+++ b/src/include/gnunet_signal_lib.h
@@ -4,7 +4,7 @@
4 4
5 GNUnet is free software; you can redistribute it and/or modify 5 GNUnet is free software; you can redistribute it and/or modify
6 it under the terms of the GNU General Public License as published 6 it under the terms of the GNU General Public License as published
7 by the Free Software Foundation; either version 2, or (at your 7 by the Free Software Foundation; either version 3, or (at your
8 option) any later version. 8 option) any later version.
9 9
10 GNUnet is distributed in the hope that it will be useful, but 10 GNUnet is distributed in the hope that it will be useful, but
diff --git a/src/include/gnunet_statistics_service.h b/src/include/gnunet_statistics_service.h
index 5e41edc5b..c2fb46109 100644
--- a/src/include/gnunet_statistics_service.h
+++ b/src/include/gnunet_statistics_service.h
@@ -1,10 +1,10 @@
1/* 1/*
2 This file is part of GNUnet 2 This file is part of GNUnet
3 (C) 2009, 2010 Christian Grothoff (and other contributing authors) 3 (C) 2009-2013 Christian Grothoff (and other contributing authors)
4 4
5 GNUnet is free software; you can redistribute it and/or modify 5 GNUnet is free software; you can redistribute it and/or modify
6 it under the terms of the GNU General Public License as published 6 it under the terms of the GNU General Public License as published
7 by the Free Software Foundation; either version 2, or (at your 7 by the Free Software Foundation; either version 3, or (at your
8 option) any later version. 8 option) any later version.
9 9
10 GNUnet is distributed in the hope that it will be useful, but 10 GNUnet is distributed in the hope that it will be useful, but
@@ -24,6 +24,8 @@
24 * the operation of GNUnet; all statistical values 24 * the operation of GNUnet; all statistical values
25 * must be of type "unsigned long long". 25 * must be of type "unsigned long long".
26 * @author Christian Grothoff 26 * @author Christian Grothoff
27 * @defgroup statistics track statistics or provide access to statistics
28 * @{
27 */ 29 */
28 30
29#ifndef GNUNET_STATISTICS_SERVICE_H 31#ifndef GNUNET_STATISTICS_SERVICE_H
@@ -58,8 +60,8 @@ struct GNUNET_STATISTICS_Handle;
58 * @param subsystem name of subsystem that created the statistic 60 * @param subsystem name of subsystem that created the statistic
59 * @param name the name of the datum 61 * @param name the name of the datum
60 * @param value the current value 62 * @param value the current value
61 * @param is_persistent GNUNET_YES if the value is persistent, GNUNET_NO if not 63 * @param is_persistent #GNUNET_YES if the value is persistent, #GNUNET_NO if not
62 * @return GNUNET_OK to continue, GNUNET_SYSERR to abort iteration 64 * @return #GNUNET_OK to continue, #GNUNET_SYSERR to abort iteration
63 */ 65 */
64typedef int (*GNUNET_STATISTICS_Iterator) (void *cls, const char *subsystem, 66typedef int (*GNUNET_STATISTICS_Iterator) (void *cls, const char *subsystem,
65 const char *name, uint64_t value, 67 const char *name, uint64_t value,
@@ -82,7 +84,7 @@ GNUNET_STATISTICS_create (const char *subsystem,
82 * it). 84 * it).
83 * 85 *
84 * @param h statistics handle to destroy 86 * @param h statistics handle to destroy
85 * @param sync_first set to GNUNET_YES if pending SET requests should 87 * @param sync_first set to #GNUNET_YES if pending SET requests should
86 * be completed 88 * be completed
87 */ 89 */
88void 90void
@@ -96,8 +98,8 @@ GNUNET_STATISTICS_destroy (struct GNUNET_STATISTICS_Handle *h, int sync_first);
96 * @param subsystem limit to the specified subsystem, never NULL 98 * @param subsystem limit to the specified subsystem, never NULL
97 * @param name name of the statistic value, never NULL 99 * @param name name of the statistic value, never NULL
98 * @param proc function to call on each value 100 * @param proc function to call on each value
99 * @param proc_cls closure for proc 101 * @param proc_cls closure for @a proc
100 * @return GNUNET_OK on success, GNUNET_SYSERR on error 102 * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
101 */ 103 */
102int 104int
103GNUNET_STATISTICS_watch (struct GNUNET_STATISTICS_Handle *handle, 105GNUNET_STATISTICS_watch (struct GNUNET_STATISTICS_Handle *handle,
@@ -112,8 +114,8 @@ GNUNET_STATISTICS_watch (struct GNUNET_STATISTICS_Handle *handle,
112 * @param subsystem limit to the specified subsystem, never NULL 114 * @param subsystem limit to the specified subsystem, never NULL
113 * @param name name of the statistic value, never NULL 115 * @param name name of the statistic value, never NULL
114 * @param proc function to call on each value 116 * @param proc function to call on each value
115 * @param proc_cls closure for proc 117 * @param proc_cls closure for @a proc
116 * @return GNUNET_OK on success, GNUNET_SYSERR on error (no such watch) 118 * @return #GNUNET_OK on success, #GNUNET_SYSERR on error (no such watch)
117 */ 119 */
118int 120int
119GNUNET_STATISTICS_watch_cancel (struct GNUNET_STATISTICS_Handle *handle, 121GNUNET_STATISTICS_watch_cancel (struct GNUNET_STATISTICS_Handle *handle,
@@ -122,11 +124,12 @@ GNUNET_STATISTICS_watch_cancel (struct GNUNET_STATISTICS_Handle *handle,
122 124
123 125
124/** 126/**
125 * Continuation called by the "get_all" and "get" functions. 127 * Continuation called by the #GNUNET_STATISTICS_get_all
128 * and #GNUNET_STATISTICS_get functions.
126 * 129 *
127 * @param cls closure 130 * @param cls closure
128 * @param success GNUNET_OK if statistics were 131 * @param success #GNUNET_OK if statistics were
129 * successfully obtained, GNUNET_SYSERR if not. 132 * successfully obtained, #GNUNET_SYSERR if not.
130 */ 133 */
131typedef void (*GNUNET_STATISTICS_Callback) (void *cls, int success); 134typedef void (*GNUNET_STATISTICS_Callback) (void *cls, int success);
132 135
@@ -136,6 +139,7 @@ typedef void (*GNUNET_STATISTICS_Callback) (void *cls, int success);
136 */ 139 */
137struct GNUNET_STATISTICS_GetHandle; 140struct GNUNET_STATISTICS_GetHandle;
138 141
142
139/** 143/**
140 * Get statistic from the peer. 144 * Get statistic from the peer.
141 * 145 *
@@ -147,7 +151,7 @@ struct GNUNET_STATISTICS_GetHandle;
147 * @param cont continuation to call when done (can be NULL) 151 * @param cont continuation to call when done (can be NULL)
148 * This callback CANNOT destroy the statistics handle in the same call. 152 * This callback CANNOT destroy the statistics handle in the same call.
149 * @param proc function to call on each value 153 * @param proc function to call on each value
150 * @param cls closure for proc and cont 154 * @param cls closure for @a proc and @a cont
151 * @return NULL on error 155 * @return NULL on error
152 */ 156 */
153struct GNUNET_STATISTICS_GetHandle * 157struct GNUNET_STATISTICS_GetHandle *
@@ -159,7 +163,7 @@ GNUNET_STATISTICS_get (struct GNUNET_STATISTICS_Handle *handle,
159 163
160 164
161/** 165/**
162 * Cancel a 'get' request. Must be called before the 'cont' 166 * Cancel a #GNUNET_STATISICS_get request. Must be called before the 'cont'
163 * function is called. 167 * function is called.
164 * 168 *
165 * @param gh handle of the request to cancel 169 * @param gh handle of the request to cancel
@@ -181,6 +185,7 @@ void
181GNUNET_STATISTICS_set (struct GNUNET_STATISTICS_Handle *handle, 185GNUNET_STATISTICS_set (struct GNUNET_STATISTICS_Handle *handle,
182 const char *name, uint64_t value, int make_persistent); 186 const char *name, uint64_t value, int make_persistent);
183 187
188
184/** 189/**
185 * Set statistic value for the peer. Will always use our 190 * Set statistic value for the peer. Will always use our
186 * subsystem (the argument used when "handle" was created). 191 * subsystem (the argument used when "handle" was created).
@@ -203,4 +208,6 @@ GNUNET_STATISTICS_update (struct GNUNET_STATISTICS_Handle *handle,
203} 208}
204#endif 209#endif
205 210
211/** @} */ /* end of group statistics */
212
206#endif 213#endif
generated by cgit v1.2.3 (git 2.39.1) at 2024-04-30 21:58:40 +0000