Changeset b10460a in mainline for uspace/lib/nettl/src/amap.c


Ignore:
Timestamp:
2015-08-07T21:39:00Z (10 years ago)
Author:
Jiri Svoboda <jiri@…>
Branches:
lfn, master, serial, ticket/834-toolchain-update, topic/msim-upgrade, topic/simplify-dev-export
Children:
b688fd8
Parents:
6accc5cf
Message:

Add missing docblocks in network code.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • uspace/lib/nettl/src/amap.c

    r6accc5cf rb10460a  
    3636 * Manages allocations of endpoints / endpoint pairs (corresponding to
    3737 * UDP associations, TCP listeners and TCP connections)
     38 *
     39 * An association map contains different types of entries, based on which
     40 * set of attributes (key) they specify. In order from most specific to the
     41 * least specific one:
     42 *
     43 *  - repla (remote endpoint, local address)
     44 *  - laddr (local address)
     45 *  - llink (local link)
     46 *  - unspec (unspecified)
     47 *
     48 * In the unspecified case only the local port is known and the entry matches
     49 * all remote and local addresses.
    3850 */
    3951
    … …  
    4759#include <stdlib.h>
    4860
     61/** Create association map.
     62 *
     63 * @param rmap Place to store pointer to new association map
     64 * @return EOk on success, ENOMEM if out of memory
     65 */
    4966int amap_create(amap_t **rmap)
    5067{
    … …  
    7390}
    7491
     92/** Destroy association map.
     93 *
     94 * @param map Association map
     95 */
    7596void amap_destroy(amap_t *map)
    7697{
    … …  
    79100}
    80101
    81 /** Find exact repla */
     102/** Find exact repla.
     103 *
     104 * Find repla (remote endpoint, local address) entry by exact match.
     105 *
     106 * @param map Association map
     107 * @param rep Remote endpoint
     108 * @param la  Local address
     109 * @param rrepla Place to store pointer to repla
     110 *
     111 * @return EOK on success, ENOENT if not found
     112 */
    82113static int amap_repla_find(amap_t *map, inet_ep_t *rep, inet_addr_t *la,
    83114    amap_repla_t **rrepla)
    … …  
    113144}
    114145
     146/** Insert repla.
     147 *
     148 * Insert new repla (remote endpoint, local address) entry to association map.
     149 *
     150 * @param amap   Association map
     151 * @param rep    Remote endpoint
     152 * @param la     Local address
     153 * @param rrepla Place to store pointer to new repla
     154 *
     155 * @return EOK on success, ENOMEM if out of memory
     156 */
    115157static int amap_repla_insert(amap_t *map, inet_ep_t *rep, inet_addr_t *la,
    116158    amap_repla_t **rrepla)
    … …  
    139181}
    140182
     183/** Remove repla from association map.
     184 *
     185 * Remove repla (remote endpoint, local address) from association map.
     186 *
     187 * @param map   Association map
     188 * @param repla Repla
     189 */
    141190static void amap_repla_remove(amap_t *map, amap_repla_t *repla)
    142191{
    … …  
    146195}
    147196
    148 /** Find exact laddr */
     197/** Find exact laddr.
     198 *
     199 * Find laddr (local address) entry by exact match.
     200 *
     201 * @param map    Association map
     202 * @param addr   Address
     203 * @param rladdr Place to store pointer to laddr entry
     204 *
     205 * @return EOK on success, ENOENT if not found.
     206 */
    149207static int amap_laddr_find(amap_t *map, inet_addr_t *addr,
    150208    amap_laddr_t **rladdr)
    … …  
    161219}
    162220
     221/** Insert laddr.
     222 *
     223 * Insert new laddr (local address) entry to association map.
     224 *
     225 * @param addr   Local address
     226 * @param rladdr Place to store pointer to new laddr
     227 *
     228 * @return EOK on success, ENOMEM if out of memory
     229 */
    163230static int amap_laddr_insert(amap_t *map, inet_addr_t *addr,
    164231    amap_laddr_t **rladdr)
    … …  
    186253}
    187254
     255/** Remove laddr from association map.
     256 *
     257 * Remove laddr (local address) entry from association map.
     258 *
     259 * @param map   Association map
     260 * @param laddr Laddr entry
     261 */
    188262static void amap_laddr_remove(amap_t *map, amap_laddr_t *laddr)
    189263{
    … …  
    193267}
    194268
    195 /** Find exact llink */
     269/** Find exact llink.
     270 *
     271 * Find llink (local link) entry by exact match.
     272 *
     273 * @param map     Association map
     274 * @param link_id Local link ID
     275 * @param rllink  Place to store pointer to llink entry
     276 *
     277 * @return EOK on success, ENOENT if not found.
     278 */
    196279static int amap_llink_find(amap_t *map, sysarg_t link_id,
    197280    amap_llink_t **rllink)
    … …  
    208291}
    209292
     293/** Insert llink.
     294 *
     295 * Insert new llink (local link) entry to association map.
     296 *
     297 * @param link_id Local link
     298 * @param rllink  Place to store pointer to new llink
     299 *
     300 * @return EOK on success, ENOMEM if out of memory
     301 */
    210302static int amap_llink_insert(amap_t *map, sysarg_t link_id,
    211303    amap_llink_t **rllink)
    … …  
    233325}
    234326
     327/** Remove llink from association map.
     328 *
     329 * Remove llink (local link) entry from association map.
     330 *
     331 * @param map   Association map
     332 * @param llink Llink entry
     333 */
    235334static void amap_llink_remove(amap_t *map, amap_llink_t *llink)
    236335{
    … …  
    240339}
    241340
     341/** Insert endpoint pair into map with repla as key.
     342 *
     343 * If local port number is not specified, it is allocated.
     344 *
     345 * @param map Association map
     346 * @param epp Endpoint pair, possibly with local port inet_port_any
     347 * @param arg arg User value
     348 * @param flags Flags
     349 * @param aepp Place to store actual endpoint pair, possibly with allocated port
     350 *
     351 * @return EOK on success, EEXISTS if conflicting epp exists,
     352 *         ENOMEM if out of memory
     353 */
    242354static int amap_insert_repla(amap_t *map, inet_ep2_t *epp, void *arg,
    243355    amap_flags_t flags, inet_ep2_t *aepp)
    … …  
    272384}
    273385
     386/** Insert endpoint pair into map with laddr as key.
     387 *
     388 * If local port number is not specified, it is allocated.
     389 *
     390 * @param map Association map
     391 * @param epp Endpoint pair, possibly with local port inet_port_any
     392 * @param arg arg User value
     393 * @param flags Flags
     394 * @param aepp Place to store actual endpoint pair, possibly with allocated port
     395 *
     396 * @return EOK on success, EEXISTS if conflicting epp exists,
     397 *         ENOMEM if out of memory
     398 */
    274399static int amap_insert_laddr(amap_t *map, inet_ep2_t *epp, void *arg,
    275400    amap_flags_t flags, inet_ep2_t *aepp)
    … …  
    303428}
    304429
     430/** Insert endpoint pair into map with llink as key.
     431 *
     432 * If local port number is not specified, it is allocated.
     433 *
     434 * @param map Association map
     435 * @param epp Endpoint pair, possibly with local port inet_port_any
     436 * @param arg arg User value
     437 * @param flags Flags
     438 * @param aepp Place to store actual endpoint pair, possibly with allocated port
     439 *
     440 * @return EOK on success, EEXISTS if conflicting epp exists,
     441 *         ENOMEM if out of memory
     442 */
    305443static int amap_insert_llink(amap_t *map, inet_ep2_t *epp, void *arg,
    306444    amap_flags_t flags, inet_ep2_t *aepp)
    … …  
    334472}
    335473
     474/** Insert endpoint pair into map with unspec as key.
     475 *
     476 * If local port number is not specified, it is allocated.
     477 *
     478 * @param map Association map
     479 * @param epp Endpoint pair, possibly with local port inet_port_any
     480 * @param arg arg User value
     481 * @param flags Flags
     482 * @param aepp Place to store actual endpoint pair, possibly with allocated port
     483 *
     484 * @return EOK on success, EEXISTS if conflicting epp exists,
     485 *         ENOMEM if out of memory
     486 */
    336487static int amap_insert_unspec(amap_t *map, inet_ep2_t *epp, void *arg,
    337488    amap_flags_t flags, inet_ep2_t *aepp)
    … …  
    417568}
    418569
     570/** Remove endpoint pair using repla as key from map.
     571 *
     572 * The endpoint pair must be present in the map, otherwise behavior
     573 * is unspecified.
     574 *
     575 * @param map Association map
     576 * @param epp Endpoint pair
     577 */
    419578static void amap_remove_repla(amap_t *map, inet_ep2_t *epp)
    420579{
    … …  
    434593}
    435594
     595/** Remove endpoint pair using laddr as key from map.
     596 *
     597 * The endpoint pair must be present in the map, otherwise behavior
     598 * is unspecified.
     599 *
     600 * @param map Association map
     601 * @param epp Endpoint pair
     602 */
    436603static void amap_remove_laddr(amap_t *map, inet_ep2_t *epp)
    437604{
    … …  
    451618}
    452619
     620/** Remove endpoint pair using llink as key from map.
     621 *
     622 * The endpoint pair must be present in the map, otherwise behavior
     623 * is unspecified.
     624 *
     625 * @param map Association map
     626 * @param epp Endpoint pair
     627 */
    453628static void amap_remove_llink(amap_t *map, inet_ep2_t *epp)
    454629{
    … …  
    468643}
    469644
     645/** Remove endpoint pair using unspec as key from map.
     646 *
     647 * The endpoint pair must be present in the map, otherwise behavior
     648 * is unspecified.
     649 *
     650 * @param map Association map
     651 * @param epp Endpoint pair
     652 */
    470653static void amap_remove_unspec(amap_t *map, inet_ep2_t *epp)
    471654{
    … …  
    473656}
    474657
     658/** Remove endpoint pair from map.
     659 *
     660 * The endpoint pair must be present in the map, otherwise behavior
     661 * is unspecified.
     662 *
     663 * @param map Association map
     664 * @param epp Endpoint pair
     665 */
    475666void amap_remove(amap_t *map, inet_ep2_t *epp)
    476667{
Note: See TracChangeset for help on using the changeset viewer.