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