2 This file is part of GNUnet.
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
7 by the Free Software Foundation; either version 3, or (at your
8 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 General Public License for more details.
15 You should have received a copy of the GNU General Public License
16 along with GNUnet; see the file COPYING. If not, write to the
17 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
18 Boston, MA 02110-1301, USA.
22 * @file rps/gnunet-service-rps_custommap.h
23 * @brief utilities for managing (information about) peers
24 * @author Julius Bünger
26 #include "gnunet_util_lib.h"
31 * Peer map to store peers with specialised use-cases (push_list, pull_list,
34 * It is aimed for use as unordered list-like structures that can be indexed.
37 * permut = GNUNET_CRYPTO_random_permute (GNUNET_CRYPTO_QUALITY_STRONG,
38 * CustomPeerMap_size (peer_map));
39 * for (i = 0; i < some_border; i++)
40 * some_array[i] = *CustomPeerMap_get_peer_by_index (peer_map, permut[i]);
41 * for (i = some_border; i < CustomPeerMap_size (peer_map); i++)
42 * other_array[i-some_border] =
43 * *CustomPeerMap_get_peer_by_index (peer_map, permut[i]);
45 * This list is expected to
46 * - be altered in small steps frequently
47 * - be cleared regularily
48 * - often being queried whether a peer is contained
49 * - alter indices of peers
50 * - contain continous indices 0 <= i < len
51 * - not contain duplicate peers
57 * Create an empty peermap.
59 * @param len the initial length for the internal maps
61 * @return the newly created custom peer map
63 struct CustomPeerMap *
64 CustomPeerMap_create (unsigned int len);
67 * Get the size of the custom peer map
69 * @param c_peer_map the custom peer map to look in
71 * @return size of the map
74 CustomPeerMap_size (const struct CustomPeerMap *c_peer_map);
77 * Insert peer into the custom peer map
79 * @param c_peer_map the custom peer map to insert peer
80 * @param peer the peer to insert
82 * @return GNUNET_OK if map did not contain peer previously
83 * GNUNET_NO if map did contain peer previously
86 CustomPeerMap_put (const struct CustomPeerMap *c_peer_map,
87 const struct GNUNET_PeerIdentity *peer);
90 * Check whether custom peer map contains a peer
92 * @param c_peer_map the custom peer map to look in
93 * @param peer the peer to check for
95 * @return GNUNET_OK if map contains peer
99 CustomPeerMap_contains_peer (const struct CustomPeerMap *c_peer_map,
100 const struct GNUNET_PeerIdentity *peer);
103 * Remove peer from custom peer map
105 * @param c_peer_map the custom peer map to remove the peer from
106 * @param peer the peer to remove
108 * @return GNUNET_OK if map contained peer and removed it successfully
109 * GNUNET_NO if map does not contain peer
112 CustomPeerMap_remove_peer (const struct CustomPeerMap *c_peer_map,
113 const struct GNUNET_PeerIdentity *peer);
116 * Get a peer by index
118 * @param c_peer_map the custom peer map to look in
119 * @param index the index of the peer to get
121 * @return peer to the corresponding index.
122 * if this index is not known, return NULL
124 struct GNUNET_PeerIdentity *
125 CustomPeerMap_get_peer_by_index (const struct CustomPeerMap *c_peer_map,
129 * Remove peer from custom peer map by index
131 * @param c_peer_map the custom peer map to remove the peer from
132 * @param index the index of the peer to remove
134 * @return GNUNET_OK if map contained peer and removed it successfully
135 * GNUNET_NO if map does not contain (index of) peer
138 CustomPeerMap_remove_peer_by_index (const struct CustomPeerMap *c_peer_map,
142 * Clear the custom peer map
144 * @param c_peer_map the custom peer map to look in
146 * @return size of the map
149 CustomPeerMap_clear (const struct CustomPeerMap *c_peer_map);
154 * @param c_peer_map the map to destroy
157 CustomPeerMap_destroy (struct CustomPeerMap *c_peer_map);
159 /* end of gnunet-service-rps_custommap.h */