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
   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.
   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      General Public License for more details.
  14
  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.
  19 */
  20
  21 /**
  22  * @file rps/gnunet-service-rps_custommap.h
  23  * @brief utilities for managing (information about) peers
  24  * @author Julius Bünger
  25  */
  26 #include "gnunet_util_lib.h"
  27 #include <inttypes.h>
  28
  29
  30 /**
  31  * Peer map to store peers with specialised use-cases (push_list, pull_list,
  32  * view, ...)
  33  *
  34  * It is aimed for use as unordered list-like structures that can be indexed.
  35  * Main use-case:
  36  *
  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]);
  44  *
  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
  52  */
  53 struct CustomPeerMap;
  54
  55
  56 /**
  57  * Create an empty peermap.
  58  *
  59  * @param len the initial length for the internal maps
  60  *
  61  * @return the newly created custom peer map
  62  */
  63 struct CustomPeerMap *
  64 CustomPeerMap_create (unsigned int len);
  65
  66 /**
  67  * Get the size of the custom peer map
  68  *
  69  * @param c_peer_map the custom peer map to look in
  70  *
  71  * @return size of the map
  72  */
  73 int
  74 CustomPeerMap_size (const struct CustomPeerMap *c_peer_map);
  75
  76 /**
  77  * Insert peer into the custom peer map
  78  *
  79  * @param c_peer_map the custom peer map to insert peer
  80  * @param peer the peer to insert
  81  *
  82  * @return GNUNET_OK if map did not contain peer previously
  83  *         GNUNET_NO if map did contain peer previously
  84  */
  85 int
  86 CustomPeerMap_put (const struct CustomPeerMap *c_peer_map,
  87                    const struct GNUNET_PeerIdentity *peer);
  88
  89 /**
  90  * Check whether custom peer map contains a peer
  91  *
  92  * @param c_peer_map the custom peer map to look in
  93  * @param peer the peer to check for
  94  *
  95  * @return GNUNET_OK if map contains peer
  96  *         GNUNET_NO  otherwise
  97  */
  98 int
  99 CustomPeerMap_contains_peer (const struct CustomPeerMap *c_peer_map,
 100                              const struct GNUNET_PeerIdentity *peer);
 101
 102 /**
 103  * Remove peer from custom peer map
 104  *
 105  * @param c_peer_map the custom peer map to remove the peer from
 106  * @param peer the peer to remove
 107  *
 108  * @return GNUNET_OK if map contained peer and removed it successfully
 109  *         GNUNET_NO if map does not contain peer
 110  */
 111 int
 112 CustomPeerMap_remove_peer (const struct CustomPeerMap *c_peer_map,
 113                            const struct GNUNET_PeerIdentity *peer);
 114
 115 /**
 116  * Get a peer by index
 117  *
 118  * @param c_peer_map the custom peer map to look in
 119  * @param index the index of the peer to get
 120  *
 121  * @return peer to the corresponding index.
 122  *         if this index is not known, return NULL
 123  */
 124 struct GNUNET_PeerIdentity *
 125 CustomPeerMap_get_peer_by_index (const struct CustomPeerMap *c_peer_map,
 126                                  uint32_t index);
 127
 128 /**
 129  * Remove peer from custom peer map by index
 130  *
 131  * @param c_peer_map the custom peer map to remove the peer from
 132  * @param index the index of the peer to remove
 133  *
 134  * @return GNUNET_OK if map contained peer and removed it successfully
 135  *         GNUNET_NO if map does not contain (index of) peer
 136  */
 137 int
 138 CustomPeerMap_remove_peer_by_index (const struct CustomPeerMap *c_peer_map,
 139                                     uint32_t index);
 140
 141 /**
 142  * Clear the custom peer map
 143  *
 144  * @param c_peer_map the custom peer map to look in
 145  *
 146  * @return size of the map
 147  */
 148 void
 149 CustomPeerMap_clear (const struct CustomPeerMap *c_peer_map);
 150
 151 /**
 152  * Destroy peermap.
 153  *
 154  * @param c_peer_map the map to destroy
 155  */
 156 void
 157 CustomPeerMap_destroy (struct CustomPeerMap *c_peer_map);
 158
 159 /* end of gnunet-service-rps_custommap.h */