2 This file is part of GNUnet.
5 GNUnet is free software: you can redistribute it and/or modify it
6 under the terms of the GNU General Public License as published
7 by the Free Software Foundation, either version 3 of the License,
8 or (at your option) any later version.
10 GNUnet is distributed in the hope that it will be useful, but
11 WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 Affero General Public License for more details.
17 * @file rps/gnunet-service-rps_custommap.h
18 * @brief utilities for managing (information about) peers
19 * @author Julius Bünger
21 #include "gnunet_util_lib.h"
26 * Peer map to store peers with specialised use-cases (push_list, pull_list,
29 * It is aimed for use as unordered list-like structures that can be indexed.
32 * permut = GNUNET_CRYPTO_random_permute (GNUNET_CRYPTO_QUALITY_STRONG,
33 * CustomPeerMap_size (peer_map));
34 * for (i = 0; i < some_border; i++)
35 * some_array[i] = *CustomPeerMap_get_peer_by_index (peer_map, permut[i]);
36 * for (i = some_border; i < CustomPeerMap_size (peer_map); i++)
37 * other_array[i-some_border] =
38 * *CustomPeerMap_get_peer_by_index (peer_map, permut[i]);
40 * This list is expected to
41 * - be altered in small steps frequently
42 * - be cleared regularily
43 * - often being queried whether a peer is contained
44 * - alter indices of peers
45 * - contain continous indices 0 <= i < len
46 * - not contain duplicate peers
52 * Create an empty peermap.
54 * @param len the initial length for the internal maps
56 * @return the newly created custom peer map
58 struct CustomPeerMap *
59 CustomPeerMap_create (unsigned int len);
62 * Get the size of the custom peer map
64 * @param c_peer_map the custom peer map to look in
66 * @return size of the map
69 CustomPeerMap_size (const struct CustomPeerMap *c_peer_map);
72 * Insert peer into the custom peer map
74 * @param c_peer_map the custom peer map to insert peer
75 * @param peer the peer to insert
77 * @return GNUNET_OK if map did not contain peer previously
78 * GNUNET_NO if map did contain peer previously
81 CustomPeerMap_put (const struct CustomPeerMap *c_peer_map,
82 const struct GNUNET_PeerIdentity *peer);
85 * Check whether custom peer map contains a peer
87 * @param c_peer_map the custom peer map to look in
88 * @param peer the peer to check for
90 * @return GNUNET_OK if map contains peer
94 CustomPeerMap_contains_peer (const struct CustomPeerMap *c_peer_map,
95 const struct GNUNET_PeerIdentity *peer);
98 * Remove peer from custom peer map
100 * @param c_peer_map the custom peer map to remove the peer from
101 * @param peer the peer to remove
103 * @return GNUNET_OK if map contained peer and removed it successfully
104 * GNUNET_NO if map does not contain peer
107 CustomPeerMap_remove_peer (const struct CustomPeerMap *c_peer_map,
108 const struct GNUNET_PeerIdentity *peer);
111 * Get a peer by index
113 * @param c_peer_map the custom peer map to look in
114 * @param index the index of the peer to get
116 * @return peer to the corresponding index.
117 * if this index is not known, return NULL
119 struct GNUNET_PeerIdentity *
120 CustomPeerMap_get_peer_by_index (const struct CustomPeerMap *c_peer_map,
124 * Remove peer from custom peer map by index
126 * @param c_peer_map the custom peer map to remove the peer from
127 * @param index the index of the peer to remove
129 * @return GNUNET_OK if map contained peer and removed it successfully
130 * GNUNET_NO if map does not contain (index of) peer
133 CustomPeerMap_remove_peer_by_index (const struct CustomPeerMap *c_peer_map,
137 * Clear the custom peer map
139 * @param c_peer_map the custom peer map to look in
141 * @return size of the map
144 CustomPeerMap_clear (const struct CustomPeerMap *c_peer_map);
149 * @param c_peer_map the map to destroy
152 CustomPeerMap_destroy (struct CustomPeerMap *c_peer_map);
154 /* end of gnunet-service-rps_custommap.h */