diff options
author | Christian Grothoff <christian@grothoff.org> | 2013-08-14 23:05:42 +0000 |
---|---|---|
committer | Christian Grothoff <christian@grothoff.org> | 2013-08-14 23:05:42 +0000 |
commit | ca173048a26a418866163d14c9159b9ad712644b (patch) | |
tree | 7ec72935229086d494257d144dcb373b5ea858cd /src/include/gnunet_core_service.h | |
parent | 17d1146c625092753e1b29b7ce6f0dfb603fbd09 (diff) | |
download | gnunet-ca173048a26a418866163d14c9159b9ad712644b.tar.gz gnunet-ca173048a26a418866163d14c9159b9ad712644b.zip |
-doxygen
Diffstat (limited to 'src/include/gnunet_core_service.h')
-rw-r--r-- | src/include/gnunet_core_service.h | 50 |
1 files changed, 24 insertions, 26 deletions
diff --git a/src/include/gnunet_core_service.h b/src/include/gnunet_core_service.h index cec06fedd..dc64f189a 100644 --- a/src/include/gnunet_core_service.h +++ b/src/include/gnunet_core_service.h | |||
@@ -77,12 +77,12 @@ typedef void (*GNUNET_CORE_DisconnectEventHandler) (void *cls, | |||
77 | * Functions with this signature are called whenever a message is | 77 | * Functions with this signature are called whenever a message is |
78 | * received or transmitted. | 78 | * received or transmitted. |
79 | * | 79 | * |
80 | * @param cls closure (set from GNUNET_CORE_connect) | 80 | * @param cls closure (set from #GNUNET_CORE_connect) |
81 | * @param peer the other peer involved (sender or receiver, NULL | 81 | * @param peer the other peer involved (sender or receiver, NULL |
82 | * for loopback messages where we are both sender and receiver) | 82 | * for loopback messages where we are both sender and receiver) |
83 | * @param message the actual message | 83 | * @param message the actual message |
84 | * @return GNUNET_OK to keep the connection open, | 84 | * @return #GNUNET_OK to keep the connection open, |
85 | * GNUNET_SYSERR to close connection to the peer (signal serious error) | 85 | * #GNUNET_SYSERR to close connection to the peer (signal serious error) |
86 | */ | 86 | */ |
87 | typedef int (*GNUNET_CORE_MessageCallback) (void *cls, | 87 | typedef int (*GNUNET_CORE_MessageCallback) (void *cls, |
88 | const struct GNUNET_PeerIdentity * | 88 | const struct GNUNET_PeerIdentity * |
@@ -118,16 +118,17 @@ struct GNUNET_CORE_MessageHandler | |||
118 | 118 | ||
119 | 119 | ||
120 | /** | 120 | /** |
121 | * Function called after GNUNET_CORE_connect has succeeded (or failed | 121 | * Function called after #GNUNET_CORE_connect has succeeded (or failed |
122 | * for good). Note that the private key of the peer is intentionally | 122 | * for good). Note that the private key of the peer is intentionally |
123 | * not exposed here; if you need it, your process should try to read | 123 | * not exposed here; if you need it, your process should try to read |
124 | * the private key file directly (which should work if you are | 124 | * the private key file directly (which should work if you are |
125 | * authorized...). Implementations of this function must not call | 125 | * authorized...). Implementations of this function must not call |
126 | * GNUNET_CORE_disconnect (other than by scheduling a new task to | 126 | * #GNUNET_CORE_disconnect (other than by scheduling a new task to |
127 | * do this later). | 127 | * do this later). |
128 | * | 128 | * |
129 | * @param cls closure | 129 | * @param cls closure |
130 | * @param server handle to the server, NULL if we failed; TODO: consider removing this argument, it is redundant... | 130 | * @param server handle to the server, NULL if we failed; |
131 | * TODO: consider removing this argument, it is redundant... | ||
131 | * @param my_identity ID of this peer, NULL if we failed | 132 | * @param my_identity ID of this peer, NULL if we failed |
132 | */ | 133 | */ |
133 | typedef void (*GNUNET_CORE_StartupCallback) (void *cls, | 134 | typedef void (*GNUNET_CORE_StartupCallback) (void *cls, |
@@ -143,7 +144,7 @@ typedef void (*GNUNET_CORE_StartupCallback) (void *cls, | |||
143 | * specified event happens. The maximum number of queued | 144 | * specified event happens. The maximum number of queued |
144 | * notifications (queue length) is per client; the queue is shared | 145 | * notifications (queue length) is per client; the queue is shared |
145 | * across all types of notifications. So a slow client that registers | 146 | * across all types of notifications. So a slow client that registers |
146 | * for 'outbound_notify' also risks missing 'inbound_notify' messages. | 147 | * for @a outbound_notify also risks missing @a inbound_notify messages. |
147 | * Certain events (such as connect/disconnect notifications) are not | 148 | * Certain events (such as connect/disconnect notifications) are not |
148 | * subject to queue size limitations. | 149 | * subject to queue size limitations. |
149 | * | 150 | * |
@@ -157,7 +158,7 @@ typedef void (*GNUNET_CORE_StartupCallback) (void *cls, | |||
157 | * note that the core is allowed to drop notifications about inbound | 158 | * note that the core is allowed to drop notifications about inbound |
158 | * messages if the client does not process them fast enough (for this | 159 | * messages if the client does not process them fast enough (for this |
159 | * notification type, a bounded queue is used) | 160 | * notification type, a bounded queue is used) |
160 | * @param inbound_hdr_only set to GNUNET_YES if inbound_notify will only read the | 161 | * @param inbound_hdr_only set to #GNUNET_YES if @a inbound_notify will only read the |
161 | * GNUNET_MessageHeader and hence we do not need to give it the full message; | 162 | * GNUNET_MessageHeader and hence we do not need to give it the full message; |
162 | * can be used to improve efficiency, ignored if inbound_notify is NULL | 163 | * can be used to improve efficiency, ignored if inbound_notify is NULL |
163 | * note that the core is allowed to drop notifications about inbound | 164 | * note that the core is allowed to drop notifications about inbound |
@@ -167,7 +168,7 @@ typedef void (*GNUNET_CORE_StartupCallback) (void *cls, | |||
167 | * note that the core is allowed to drop notifications about outbound | 168 | * note that the core is allowed to drop notifications about outbound |
168 | * messages if the client does not process them fast enough (for this | 169 | * messages if the client does not process them fast enough (for this |
169 | * notification type, a bounded queue is used) | 170 | * notification type, a bounded queue is used) |
170 | * @param outbound_hdr_only set to GNUNET_YES if outbound_notify will only read the | 171 | * @param outbound_hdr_only set to #GNUNET_YES if @a outbound_notify will only read the |
171 | * GNUNET_MessageHeader and hence we do not need to give it the full message | 172 | * GNUNET_MessageHeader and hence we do not need to give it the full message |
172 | * can be used to improve efficiency, ignored if outbound_notify is NULL | 173 | * can be used to improve efficiency, ignored if outbound_notify is NULL |
173 | * note that the core is allowed to drop notifications about outbound | 174 | * note that the core is allowed to drop notifications about outbound |
@@ -177,7 +178,7 @@ typedef void (*GNUNET_CORE_StartupCallback) (void *cls, | |||
177 | * note that the core is allowed to drop notifications about inbound | 178 | * note that the core is allowed to drop notifications about inbound |
178 | * messages if the client does not process them fast enough (for this | 179 | * messages if the client does not process them fast enough (for this |
179 | * notification type, a bounded queue is used) | 180 | * notification type, a bounded queue is used) |
180 | * @return handle to the core service (only useful for disconnect until 'init' is called), | 181 | * @return handle to the core service (only useful for disconnect until @a init is called), |
181 | * NULL on error (in this case, init is never called) | 182 | * NULL on error (in this case, init is never called) |
182 | */ | 183 | */ |
183 | struct GNUNET_CORE_Handle * | 184 | struct GNUNET_CORE_Handle * |
@@ -195,7 +196,7 @@ GNUNET_CORE_connect (const struct GNUNET_CONFIGURATION_Handle *cfg, | |||
195 | 196 | ||
196 | /** | 197 | /** |
197 | * Disconnect from the core service. This function can only | 198 | * Disconnect from the core service. This function can only |
198 | * be called *after* all pending 'GNUNET_CORE_notify_transmit_ready' | 199 | * be called *after* all pending #GNUNET_CORE_notify_transmit_ready |
199 | * requests have been explicitly cancelled. | 200 | * requests have been explicitly cancelled. |
200 | * | 201 | * |
201 | * @param handle connection to core to disconnect | 202 | * @param handle connection to core to disconnect |
@@ -211,13 +212,13 @@ struct GNUNET_CORE_TransmitHandle; | |||
211 | 212 | ||
212 | 213 | ||
213 | /** | 214 | /** |
214 | * Ask the core to call "notify" once it is ready to transmit the | 215 | * Ask the core to call @a notify once it is ready to transmit the |
215 | * given number of bytes to the specified "target". Must only be | 216 | * given number of bytes to the specified @a target. Must only be |
216 | * called after a connection to the respective peer has been | 217 | * called after a connection to the respective peer has been |
217 | * established (and the client has been informed about this). You may | 218 | * established (and the client has been informed about this). You may |
218 | * have one request of this type pending for each connected peer at | 219 | * have one request of this type pending for each connected peer at |
219 | * any time. If a peer disconnects, the application MUST call | 220 | * any time. If a peer disconnects, the application MUST call |
220 | * "GNUNET_CORE_notify_transmit_ready_cancel" on the respective | 221 | * #GNUNET_CORE_notify_transmit_ready_cancel on the respective |
221 | * transmission request, if one such request is pending. | 222 | * transmission request, if one such request is pending. |
222 | * | 223 | * |
223 | * @param handle connection to core service | 224 | * @param handle connection to core service |
@@ -230,7 +231,7 @@ struct GNUNET_CORE_TransmitHandle; | |||
230 | * will be called with NULL on timeout; clients MUST cancel | 231 | * will be called with NULL on timeout; clients MUST cancel |
231 | * all pending transmission requests DURING the disconnect | 232 | * all pending transmission requests DURING the disconnect |
232 | * handler | 233 | * handler |
233 | * @param notify_cls closure for notify | 234 | * @param notify_cls closure for @a notify |
234 | * @return non-NULL if the notify callback was queued, | 235 | * @return non-NULL if the notify callback was queued, |
235 | * NULL if we can not even queue the request (request already pending); | 236 | * NULL if we can not even queue the request (request already pending); |
236 | * if NULL is returned, "notify" will NOT be called. | 237 | * if NULL is returned, "notify" will NOT be called. |
@@ -255,11 +256,8 @@ GNUNET_CORE_notify_transmit_ready_cancel (struct GNUNET_CORE_TransmitHandle | |||
255 | *th); | 256 | *th); |
256 | 257 | ||
257 | 258 | ||
258 | |||
259 | |||
260 | |||
261 | /** | 259 | /** |
262 | * Iterate over all connected peers. Calls peer_cb with each | 260 | * Iterate over all connected peers. Calls @a peer_cb with each |
263 | * connected peer, and then once with NULL to indicate that all peers | 261 | * connected peer, and then once with NULL to indicate that all peers |
264 | * have been handled. Normal users of the CORE API are not expected | 262 | * have been handled. Normal users of the CORE API are not expected |
265 | * to use this function. It is different in that it truly lists | 263 | * to use this function. It is different in that it truly lists |
@@ -272,8 +270,8 @@ GNUNET_CORE_notify_transmit_ready_cancel (struct GNUNET_CORE_TransmitHandle | |||
272 | * | 270 | * |
273 | * @param cfg configuration handle | 271 | * @param cfg configuration handle |
274 | * @param peer_cb function to call with the peer information | 272 | * @param peer_cb function to call with the peer information |
275 | * @param cb_cls closure for peer_cb | 273 | * @param cb_cls closure for @a peer_cb |
276 | * @return GNUNET_OK on success, GNUNET_SYSERR on errors | 274 | * @return #GNUNET_OK on success, #GNUNET_SYSERR on errors |
277 | */ | 275 | */ |
278 | int | 276 | int |
279 | GNUNET_CORE_iterate_peers (const struct GNUNET_CONFIGURATION_Handle *cfg, | 277 | GNUNET_CORE_iterate_peers (const struct GNUNET_CONFIGURATION_Handle *cfg, |
@@ -298,7 +296,7 @@ struct GNUNET_CORE_ConnectTestHandle; | |||
298 | * @param cfg configuration to use | 296 | * @param cfg configuration to use |
299 | * @param peer the specific peer to check for | 297 | * @param peer the specific peer to check for |
300 | * @param peer_cb function to call with the peer information | 298 | * @param peer_cb function to call with the peer information |
301 | * @param cb_cls closure for peer_cb | 299 | * @param cb_cls closure for @a peer_cb |
302 | * @return handle to cancel the operation | 300 | * @return handle to cancel the operation |
303 | */ | 301 | */ |
304 | struct GNUNET_CORE_ConnectTestHandle * | 302 | struct GNUNET_CORE_ConnectTestHandle * |
@@ -321,16 +319,16 @@ GNUNET_CORE_is_peer_connected_cancel (struct GNUNET_CORE_ConnectTestHandle *cth) | |||
321 | * Check if the given peer is currently connected. This function is for special | 319 | * Check if the given peer is currently connected. This function is for special |
322 | * cirumstances (GNUNET_TESTBED uses it), normal users of the CORE API are | 320 | * cirumstances (GNUNET_TESTBED uses it), normal users of the CORE API are |
323 | * expected to track which peers are connected based on the connect/disconnect | 321 | * expected to track which peers are connected based on the connect/disconnect |
324 | * callbacks from GNUNET_CORE_connect. This function is NOT part of the | 322 | * callbacks from #GNUNET_CORE_connect. This function is NOT part of the |
325 | * 'versioned', 'official' API. The difference between this function and the | 323 | * 'versioned', 'official' API. The difference between this function and the |
326 | * function GNUNET_CORE_is_peer_connected() is that this one returns | 324 | * function #GNUNET_CORE_is_peer_connected is that this one returns |
327 | * synchronously after looking in the CORE API cache. The function | 325 | * synchronously after looking in the CORE API cache. The function |
328 | * GNUNET_CORE_is_peer_connected() sends a message to the CORE service and hence | 326 | * #GNUNET_CORE_is_peer_connected sends a message to the CORE service and hence |
329 | * its response is given asynchronously. | 327 | * its response is given asynchronously. |
330 | * | 328 | * |
331 | * @param h the core handle | 329 | * @param h the core handle |
332 | * @param pid the identity of the peer to check if it has been connected to us | 330 | * @param pid the identity of the peer to check if it has been connected to us |
333 | * @return GNUNET_YES if the peer is connected to us; GNUNET_NO if not | 331 | * @return #GNUNET_YES if the peer is connected to us; #GNUNET_NO if not |
334 | */ | 332 | */ |
335 | int | 333 | int |
336 | GNUNET_CORE_is_peer_connected_sync (const struct GNUNET_CORE_Handle *h, | 334 | GNUNET_CORE_is_peer_connected_sync (const struct GNUNET_CORE_Handle *h, |