diff options
author | Christian Grothoff <christian@grothoff.org> | 2013-08-29 22:31:07 +0000 |
---|---|---|
committer | Christian Grothoff <christian@grothoff.org> | 2013-08-29 22:31:07 +0000 |
commit | 9fc4769028236bb2c83b956e1afcba3e5257f936 (patch) | |
tree | df8cdcd654a91558ee9a057393629c6bd51c38ab /src/include/gnunet_network_lib.h | |
parent | fcff7aaef106e5bd78e340ba9540667614d5a202 (diff) | |
download | gnunet-9fc4769028236bb2c83b956e1afcba3e5257f936.tar.gz gnunet-9fc4769028236bb2c83b956e1afcba3e5257f936.zip |
-fix u/clarify/improve util/network code doxygen documentation
Diffstat (limited to 'src/include/gnunet_network_lib.h')
-rw-r--r-- | src/include/gnunet_network_lib.h | 59 |
1 files changed, 36 insertions, 23 deletions
diff --git a/src/include/gnunet_network_lib.h b/src/include/gnunet_network_lib.h index 1e9703e9f..c5c72379a 100644 --- a/src/include/gnunet_network_lib.h +++ b/src/include/gnunet_network_lib.h | |||
@@ -1,6 +1,6 @@ | |||
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 |
@@ -74,7 +74,7 @@ struct GNUNET_NETWORK_FDSet | |||
74 | * Test if the given protocol family is supported by this system. | 74 | * Test if the given protocol family is supported by this system. |
75 | * | 75 | * |
76 | * @param pf protocol family to test (PF_INET, PF_INET6, PF_UNIX) | 76 | * @param pf protocol family to test (PF_INET, PF_INET6, PF_UNIX) |
77 | * @return GNUNET_OK if the PF is supported | 77 | * @return #GNUNET_OK if the PF is supported |
78 | */ | 78 | */ |
79 | int | 79 | int |
80 | GNUNET_NETWORK_test_pf (int pf); | 80 | GNUNET_NETWORK_test_pf (int pf); |
@@ -106,7 +106,7 @@ GNUNET_NETWORK_shorten_unixpath (char *unixpath); | |||
106 | struct GNUNET_NETWORK_Handle * | 106 | struct GNUNET_NETWORK_Handle * |
107 | GNUNET_NETWORK_socket_accept (const struct GNUNET_NETWORK_Handle *desc, | 107 | GNUNET_NETWORK_socket_accept (const struct GNUNET_NETWORK_Handle *desc, |
108 | struct sockaddr *address, | 108 | struct sockaddr *address, |
109 | socklen_t * address_len); | 109 | socklen_t *address_len); |
110 | 110 | ||
111 | 111 | ||
112 | /** | 112 | /** |
@@ -124,7 +124,7 @@ GNUNET_NETWORK_socket_box_native (SOCKTYPE fd); | |||
124 | * | 124 | * |
125 | * @param fd socket | 125 | * @param fd socket |
126 | * @param doBlock blocking mode | 126 | * @param doBlock blocking mode |
127 | * @return GNUNET_OK on success, GNUNET_SYSERR on error | 127 | * @return #GNUNET_OK on success, #GNUNET_SYSERR on error |
128 | */ | 128 | */ |
129 | int | 129 | int |
130 | GNUNET_NETWORK_socket_set_blocking (struct GNUNET_NETWORK_Handle *fd, | 130 | GNUNET_NETWORK_socket_set_blocking (struct GNUNET_NETWORK_Handle *fd, |
@@ -138,13 +138,13 @@ GNUNET_NETWORK_socket_set_blocking (struct GNUNET_NETWORK_Handle *fd, | |||
138 | 138 | ||
139 | 139 | ||
140 | /** | 140 | /** |
141 | * Bind to a connected socket | 141 | * Bind a socket to a particular address. |
142 | * | 142 | * |
143 | * @param desc socket to bind | 143 | * @param desc socket to bind |
144 | * @param address address to be bound | 144 | * @param address address to be bound |
145 | * @param address_len length of address | 145 | * @param address_len length of address |
146 | * @param flags flags affecting bind behaviour | 146 | * @param flags flags affecting bind behaviour |
147 | * @return GNUNET_OK on success, GNUNET_SYSERR otherwise | 147 | * @return #GNUNET_OK on success, #GNUNET_SYSERR otherwise |
148 | */ | 148 | */ |
149 | int | 149 | int |
150 | GNUNET_NETWORK_socket_bind (struct GNUNET_NETWORK_Handle *desc, | 150 | GNUNET_NETWORK_socket_bind (struct GNUNET_NETWORK_Handle *desc, |
@@ -163,12 +163,12 @@ GNUNET_NETWORK_socket_close (struct GNUNET_NETWORK_Handle *desc); | |||
163 | 163 | ||
164 | 164 | ||
165 | /** | 165 | /** |
166 | * Connect a socket | 166 | * Connect a socket to some remote address. |
167 | * | 167 | * |
168 | * @param desc socket to connect | 168 | * @param desc socket to connect |
169 | * @param address peer address | 169 | * @param address peer address |
170 | * @param address_len of address | 170 | * @param address_len of address |
171 | * @return GNUNET_OK on success, GNUNET_SYSERR otherwise | 171 | * @return #GNUNET_OK on success, #GNUNET_SYSERR otherwise |
172 | */ | 172 | */ |
173 | int | 173 | int |
174 | GNUNET_NETWORK_socket_connect (const struct GNUNET_NETWORK_Handle *desc, | 174 | GNUNET_NETWORK_socket_connect (const struct GNUNET_NETWORK_Handle *desc, |
@@ -184,7 +184,7 @@ GNUNET_NETWORK_socket_connect (const struct GNUNET_NETWORK_Handle *desc, | |||
184 | * @param optname identifier of the option | 184 | * @param optname identifier of the option |
185 | * @param optval options | 185 | * @param optval options |
186 | * @param optlen length of optval | 186 | * @param optlen length of optval |
187 | * @return GNUNET_OK on success, GNUNET_SYSERR otherwise | 187 | * @return #GNUNET_OK on success, #GNUNET_SYSERR otherwise |
188 | */ | 188 | */ |
189 | int | 189 | int |
190 | GNUNET_NETWORK_socket_getsockopt (const struct GNUNET_NETWORK_Handle *desc, | 190 | GNUNET_NETWORK_socket_getsockopt (const struct GNUNET_NETWORK_Handle *desc, |
@@ -197,7 +197,7 @@ GNUNET_NETWORK_socket_getsockopt (const struct GNUNET_NETWORK_Handle *desc, | |||
197 | * | 197 | * |
198 | * @param desc socket to start listening on | 198 | * @param desc socket to start listening on |
199 | * @param backlog length of the listen queue | 199 | * @param backlog length of the listen queue |
200 | * @return GNUNET_OK on success, GNUNET_SYSERR otherwise | 200 | * @return #GNUNET_OK on success, #GNUNET_SYSERR otherwise |
201 | */ | 201 | */ |
202 | int | 202 | int |
203 | GNUNET_NETWORK_socket_listen (const struct GNUNET_NETWORK_Handle *desc, | 203 | GNUNET_NETWORK_socket_listen (const struct GNUNET_NETWORK_Handle *desc, |
@@ -206,7 +206,9 @@ GNUNET_NETWORK_socket_listen (const struct GNUNET_NETWORK_Handle *desc, | |||
206 | 206 | ||
207 | /** | 207 | /** |
208 | * How much data is available to be read on this descriptor? | 208 | * How much data is available to be read on this descriptor? |
209 | * | ||
209 | * @param desc socket | 210 | * @param desc socket |
211 | * @returns #GNUNET_NO if no data is available, or on error! | ||
210 | */ | 212 | */ |
211 | ssize_t | 213 | ssize_t |
212 | GNUNET_NETWORK_socket_recvfrom_amount (const struct GNUNET_NETWORK_Handle | 214 | GNUNET_NETWORK_socket_recvfrom_amount (const struct GNUNET_NETWORK_Handle |
@@ -214,7 +216,8 @@ GNUNET_NETWORK_socket_recvfrom_amount (const struct GNUNET_NETWORK_Handle | |||
214 | 216 | ||
215 | 217 | ||
216 | /** | 218 | /** |
217 | * Read data from a connected socket (always non-blocking). | 219 | * Read data from a socket (always non-blocking). |
220 | * | ||
218 | * @param desc socket | 221 | * @param desc socket |
219 | * @param buffer buffer | 222 | * @param buffer buffer |
220 | * @param length length of buffer | 223 | * @param length length of buffer |
@@ -247,7 +250,7 @@ GNUNET_NETWORK_socket_recv (const struct GNUNET_NETWORK_Handle *desc, | |||
247 | * @param wfds set of sockets to be checked for writability | 250 | * @param wfds set of sockets to be checked for writability |
248 | * @param efds set of sockets to be checked for exceptions | 251 | * @param efds set of sockets to be checked for exceptions |
249 | * @param timeout relative value when to return | 252 | * @param timeout relative value when to return |
250 | * @return number of selected sockets, GNUNET_SYSERR on error | 253 | * @return number of selected sockets, #GNUNET_SYSERR on error |
251 | */ | 254 | */ |
252 | int | 255 | int |
253 | GNUNET_NETWORK_socket_select (struct GNUNET_NETWORK_FDSet *rfds, | 256 | GNUNET_NETWORK_socket_select (struct GNUNET_NETWORK_FDSet *rfds, |
@@ -262,7 +265,7 @@ GNUNET_NETWORK_socket_select (struct GNUNET_NETWORK_FDSet *rfds, | |||
262 | * @param desc socket | 265 | * @param desc socket |
263 | * @param buffer data to send | 266 | * @param buffer data to send |
264 | * @param length size of the buffer | 267 | * @param length size of the buffer |
265 | * @return number of bytes sent, GNUNET_SYSERR on error | 268 | * @return number of bytes sent, #GNUNET_SYSERR on error |
266 | */ | 269 | */ |
267 | ssize_t | 270 | ssize_t |
268 | GNUNET_NETWORK_socket_send (const struct GNUNET_NETWORK_Handle *desc, | 271 | GNUNET_NETWORK_socket_send (const struct GNUNET_NETWORK_Handle *desc, |
@@ -278,7 +281,7 @@ GNUNET_NETWORK_socket_send (const struct GNUNET_NETWORK_Handle *desc, | |||
278 | * @param length size of the data | 281 | * @param length size of the data |
279 | * @param dest_addr destination address | 282 | * @param dest_addr destination address |
280 | * @param dest_len length of address | 283 | * @param dest_len length of address |
281 | * @return number of bytes sent, GNUNET_SYSERR on error | 284 | * @return number of bytes sent, #GNUNET_SYSERR on error |
282 | */ | 285 | */ |
283 | ssize_t | 286 | ssize_t |
284 | GNUNET_NETWORK_socket_sendto (const struct GNUNET_NETWORK_Handle *desc, | 287 | GNUNET_NETWORK_socket_sendto (const struct GNUNET_NETWORK_Handle *desc, |
@@ -295,7 +298,7 @@ GNUNET_NETWORK_socket_sendto (const struct GNUNET_NETWORK_Handle *desc, | |||
295 | * @param option_name option identifier | 298 | * @param option_name option identifier |
296 | * @param option_value value to set | 299 | * @param option_value value to set |
297 | * @param option_len size of option_value | 300 | * @param option_len size of option_value |
298 | * @return GNUNET_OK on success, GNUNET_SYSERR otherwise | 301 | * @return #GNUNET_OK on success, #GNUNET_SYSERR otherwise |
299 | */ | 302 | */ |
300 | int | 303 | int |
301 | GNUNET_NETWORK_socket_setsockopt (struct GNUNET_NETWORK_Handle *fd, int level, | 304 | GNUNET_NETWORK_socket_setsockopt (struct GNUNET_NETWORK_Handle *fd, int level, |
@@ -308,7 +311,7 @@ GNUNET_NETWORK_socket_setsockopt (struct GNUNET_NETWORK_Handle *fd, int level, | |||
308 | * | 311 | * |
309 | * @param desc socket | 312 | * @param desc socket |
310 | * @param how type of shutdown | 313 | * @param how type of shutdown |
311 | * @return GNUNET_OK on success, GNUNET_SYSERR otherwise | 314 | * @return #GNUNET_OK on success, #GNUNET_SYSERR otherwise |
312 | */ | 315 | */ |
313 | int | 316 | int |
314 | GNUNET_NETWORK_socket_shutdown (struct GNUNET_NETWORK_Handle *desc, int how); | 317 | GNUNET_NETWORK_socket_shutdown (struct GNUNET_NETWORK_Handle *desc, int how); |
@@ -321,7 +324,7 @@ GNUNET_NETWORK_socket_shutdown (struct GNUNET_NETWORK_Handle *desc, int how); | |||
321 | * reduces the OS send buffers to zero. | 324 | * reduces the OS send buffers to zero. |
322 | * | 325 | * |
323 | * @param desc socket | 326 | * @param desc socket |
324 | * @return GNUNET_OK on success, GNUNET_SYSERR otherwise | 327 | * @return #GNUNET_OK on success, #GNUNET_SYSERR otherwise |
325 | */ | 328 | */ |
326 | int | 329 | int |
327 | GNUNET_NETWORK_socket_disable_corking (struct GNUNET_NETWORK_Handle *desc); | 330 | GNUNET_NETWORK_socket_disable_corking (struct GNUNET_NETWORK_Handle *desc); |
@@ -352,6 +355,7 @@ GNUNET_NETWORK_fdset_zero (struct GNUNET_NETWORK_FDSet *fds); | |||
352 | 355 | ||
353 | /** | 356 | /** |
354 | * Add a socket to the FD set | 357 | * Add a socket to the FD set |
358 | * | ||
355 | * @param fds fd set | 359 | * @param fds fd set |
356 | * @param desc socket to add | 360 | * @param desc socket to add |
357 | */ | 361 | */ |
@@ -363,6 +367,7 @@ GNUNET_NETWORK_fdset_set (struct GNUNET_NETWORK_FDSet *fds, | |||
363 | #if WINDOWS | 367 | #if WINDOWS |
364 | /** | 368 | /** |
365 | * Add a W32 file handle to the fd set | 369 | * Add a W32 file handle to the fd set |
370 | * | ||
366 | * @param fds fd set | 371 | * @param fds fd set |
367 | * @param h the file handle to add | 372 | * @param h the file handle to add |
368 | */ | 373 | */ |
@@ -374,9 +379,10 @@ GNUNET_NETWORK_fdset_handle_set_native_w32_handle (struct GNUNET_NETWORK_FDSet | |||
374 | 379 | ||
375 | /** | 380 | /** |
376 | * Check whether a socket is part of the fd set | 381 | * Check whether a socket is part of the fd set |
382 | * | ||
377 | * @param fds fd set | 383 | * @param fds fd set |
378 | * @param desc socket | 384 | * @param desc socket |
379 | * @return GNUNET_YES if the socket is in the set | 385 | * @return #GNUNET_YES if the socket is in the set |
380 | */ | 386 | */ |
381 | int | 387 | int |
382 | GNUNET_NETWORK_fdset_isset (const struct GNUNET_NETWORK_FDSet *fds, | 388 | GNUNET_NETWORK_fdset_isset (const struct GNUNET_NETWORK_FDSet *fds, |
@@ -384,7 +390,8 @@ GNUNET_NETWORK_fdset_isset (const struct GNUNET_NETWORK_FDSet *fds, | |||
384 | 390 | ||
385 | 391 | ||
386 | /** | 392 | /** |
387 | * Add one fd set to another | 393 | * Add one fd set to another (computes the union). |
394 | * | ||
388 | * @param dst the fd set to add to | 395 | * @param dst the fd set to add to |
389 | * @param src the fd set to add from | 396 | * @param src the fd set to add from |
390 | */ | 397 | */ |
@@ -395,6 +402,7 @@ GNUNET_NETWORK_fdset_add (struct GNUNET_NETWORK_FDSet *dst, | |||
395 | 402 | ||
396 | /** | 403 | /** |
397 | * Copy one fd set to another | 404 | * Copy one fd set to another |
405 | * | ||
398 | * @param to destination | 406 | * @param to destination |
399 | * @param from source | 407 | * @param from source |
400 | */ | 408 | */ |
@@ -434,14 +442,15 @@ GNUNET_NETWORK_get_addrlen (struct GNUNET_NETWORK_Handle *desc); | |||
434 | 442 | ||
435 | 443 | ||
436 | /** | 444 | /** |
437 | * Copy a native fd set | 445 | * Copy a native fd set into the GNUnet representation. |
446 | * | ||
438 | * @param to destination | 447 | * @param to destination |
439 | * @param from native source set | 448 | * @param from native source set |
440 | * @param nfds the biggest socket number in from + 1 | 449 | * @param nfds the biggest socket number in from + 1 |
441 | */ | 450 | */ |
442 | void | 451 | void |
443 | GNUNET_NETWORK_fdset_copy_native (struct GNUNET_NETWORK_FDSet *to, | 452 | GNUNET_NETWORK_fdset_copy_native (struct GNUNET_NETWORK_FDSet *to, |
444 | const fd_set * from, int nfds); | 453 | const fd_set *from, int nfds); |
445 | 454 | ||
446 | 455 | ||
447 | /** | 456 | /** |
@@ -468,6 +477,7 @@ GNUNET_NETWORK_fdset_test_native (const struct GNUNET_NETWORK_FDSet *to, | |||
468 | 477 | ||
469 | /** | 478 | /** |
470 | * Add a file handle to the fd set | 479 | * Add a file handle to the fd set |
480 | * | ||
471 | * @param fds fd set | 481 | * @param fds fd set |
472 | * @param h the file handle to add | 482 | * @param h the file handle to add |
473 | */ | 483 | */ |
@@ -480,7 +490,7 @@ GNUNET_NETWORK_fdset_handle_set (struct GNUNET_NETWORK_FDSet *fds, | |||
480 | * Check if a file handle is part of an fd set | 490 | * Check if a file handle is part of an fd set |
481 | * @param fds fd set | 491 | * @param fds fd set |
482 | * @param h file handle | 492 | * @param h file handle |
483 | * @return GNUNET_YES if the file handle is part of the set | 493 | * @return #GNUNET_YES if the file handle is part of the set |
484 | */ | 494 | */ |
485 | int | 495 | int |
486 | GNUNET_NETWORK_fdset_handle_isset (const struct GNUNET_NETWORK_FDSet *fds, | 496 | GNUNET_NETWORK_fdset_handle_isset (const struct GNUNET_NETWORK_FDSet *fds, |
@@ -489,9 +499,10 @@ GNUNET_NETWORK_fdset_handle_isset (const struct GNUNET_NETWORK_FDSet *fds, | |||
489 | 499 | ||
490 | /** | 500 | /** |
491 | * Checks if two fd sets overlap | 501 | * Checks if two fd sets overlap |
502 | * | ||
492 | * @param fds1 first fd set | 503 | * @param fds1 first fd set |
493 | * @param fds2 second fd set | 504 | * @param fds2 second fd set |
494 | * @return GNUNET_YES if they do overlap, GNUNET_NO otherwise | 505 | * @return #GNUNET_YES if they do overlap, #GNUNET_NO otherwise |
495 | */ | 506 | */ |
496 | int | 507 | int |
497 | GNUNET_NETWORK_fdset_overlap (const struct GNUNET_NETWORK_FDSet *fds1, | 508 | GNUNET_NETWORK_fdset_overlap (const struct GNUNET_NETWORK_FDSet *fds1, |
@@ -500,6 +511,7 @@ GNUNET_NETWORK_fdset_overlap (const struct GNUNET_NETWORK_FDSet *fds1, | |||
500 | 511 | ||
501 | /** | 512 | /** |
502 | * Creates an fd set | 513 | * Creates an fd set |
514 | * | ||
503 | * @return a new fd set | 515 | * @return a new fd set |
504 | */ | 516 | */ |
505 | struct GNUNET_NETWORK_FDSet * | 517 | struct GNUNET_NETWORK_FDSet * |
@@ -508,6 +520,7 @@ GNUNET_NETWORK_fdset_create (void); | |||
508 | 520 | ||
509 | /** | 521 | /** |
510 | * Releases the associated memory of an fd set | 522 | * Releases the associated memory of an fd set |
523 | * | ||
511 | * @param fds fd set | 524 | * @param fds fd set |
512 | */ | 525 | */ |
513 | void | 526 | void |