src/rps/gnunet-service-rps_custommap.h

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (C)
   4
   5      GNUnet is free software: you can redistribute it and/or modify it
   6      under the terms of the GNU Affero 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.
   9
  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.
  14
  15      You should have received a copy of the GNU Affero General Public License
  16      along with this program.  If not, see <http://www.gnu.org/licenses/>.
  17 */
  18
  19 /**
  20  * @file rps/gnunet-service-rps_custommap.h
  21  * @brief utilities for managing (information about) peers
  22  * @author Julius Bünger
  23  */
  24 #include "gnunet_util_lib.h"
  25 #include <inttypes.h>
  26
  27
  28 /**
  29  * Peer map to store peers with specialised use-cases (push_list, pull_list,
  30  * view, ...)
  31  *
  32  * It is aimed for use as unordered list-like structures that can be indexed.
  33  * Main use-case:
  34  *
  35  *  permut = GNUNET_CRYPTO_random_permute (GNUNET_CRYPTO_QUALITY_STRONG,
  36  *                                         CustomPeerMap_size (peer_map));
  37  *  for (i = 0; i < some_border; i++)
  38  *    some_array[i] = *CustomPeerMap_get_peer_by_index (peer_map, permut[i]);
  39  *  for (i = some_border; i < CustomPeerMap_size (peer_map); i++)
  40  *    other_array[i-some_border] =
  41  *      *CustomPeerMap_get_peer_by_index (peer_map, permut[i]);
  42  *
  43  * This list is expected to
  44  * - be altered in small steps frequently
  45  * - be cleared regularily
  46  * - often being queried whether a peer is contained
  47  * - alter indices of peers
  48  * - contain continous indices 0 <= i < len
  49  * - not contain duplicate peers
  50  */
  51 struct CustomPeerMap;
  52
  53
  54 /**
  55  * Create an empty peermap.
  56  *
  57  * @param len the initial length for the internal maps
  58  *
  59  * @return the newly created custom peer map
  60  */
  61 struct CustomPeerMap *
  62 CustomPeerMap_create (unsigned int len);
  63
  64 /**
  65  * Get the size of the custom peer map
  66  *
  67  * @param c_peer_map the custom peer map to look in
  68  *
  69  * @return size of the map
  70  */
  71 int
  72 CustomPeerMap_size (const struct CustomPeerMap *c_peer_map);
  73
  74 /**
  75  * Insert peer into the custom peer map
  76  *
  77  * @param c_peer_map the custom peer map to insert peer
  78  * @param peer the peer to insert
  79  *
  80  * @return GNUNET_OK if map did not contain peer previously
  81  *         GNUNET_NO if map did contain peer previously
  82  */
  83 int
  84 CustomPeerMap_put (const struct CustomPeerMap *c_peer_map,
  85                    const struct GNUNET_PeerIdentity *peer);
  86
  87 /**
  88  * Check whether custom peer map contains a peer
  89  *
  90  * @param c_peer_map the custom peer map to look in
  91  * @param peer the peer to check for
  92  *
  93  * @return GNUNET_OK if map contains peer
  94  *         GNUNET_NO  otherwise
  95  */
  96 int
  97 CustomPeerMap_contains_peer (const struct CustomPeerMap *c_peer_map,
  98                              const struct GNUNET_PeerIdentity *peer);
  99
 100 /**
 101  * Remove peer from custom peer map
 102  *
 103  * @param c_peer_map the custom peer map to remove the peer from
 104  * @param peer the peer to remove
 105  *
 106  * @return GNUNET_OK if map contained peer and removed it successfully
 107  *         GNUNET_NO if map does not contain peer
 108  */
 109 int
 110 CustomPeerMap_remove_peer (const struct CustomPeerMap *c_peer_map,
 111                            const struct GNUNET_PeerIdentity *peer);
 112
 113 /**
 114  * Get a peer by index
 115  *
 116  * @param c_peer_map the custom peer map to look in
 117  * @param index the index of the peer to get
 118  *
 119  * @return peer to the corresponding index.
 120  *         if this index is not known, return NULL
 121  */
 122 struct GNUNET_PeerIdentity *
 123 CustomPeerMap_get_peer_by_index (const struct CustomPeerMap *c_peer_map,
 124                                  uint32_t index);
 125
 126 /**
 127  * Remove peer from custom peer map by index
 128  *
 129  * @param c_peer_map the custom peer map to remove the peer from
 130  * @param index the index of the peer to remove
 131  *
 132  * @return GNUNET_OK if map contained peer and removed it successfully
 133  *         GNUNET_NO if map does not contain (index of) peer
 134  */
 135 int
 136 CustomPeerMap_remove_peer_by_index (const struct CustomPeerMap *c_peer_map,
 137                                     uint32_t index);
 138
 139 /**
 140  * Clear the custom peer map
 141  *
 142  * @param c_peer_map the custom peer map to look in
 143  *
 144  * @return size of the map
 145  */
 146 void
 147 CustomPeerMap_clear (const struct CustomPeerMap *c_peer_map);
 148
 149 /**
 150  * Destroy peermap.
 151  *
 152  * @param c_peer_map the map to destroy
 153  */
 154 void
 155 CustomPeerMap_destroy (struct CustomPeerMap *c_peer_map);
 156
 157 /* end of gnunet-service-rps_custommap.h */