src/rps/gnunet-service-rps_sampler_elem.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_sampler_elem.h
  23  * @brief sampler element implementation
  24  * @author Julius Bünger
  25  */
  26
  27 #ifndef RPS_SAMPLER_ELEM_H
  28 #define RPS_SAMPLER_ELEM_H
  29 #include <inttypes.h>
  30
  31
  32 /***********************************************************************
  33  * WARNING: This section needs to be reviewed regarding the use of
  34  * functions providing (pseudo)randomness!
  35  ***********************************************************************/
  36
  37 /**
  38  * Used to indicate whether a sampler element is empty.
  39  */
  40 enum RPS_SamplerEmpty
  41 {
  42   NOT_EMPTY = 0x0,
  43   EMPTY = 0x1
  44 };
  45
  46 /**
  47  * A sampler element sampling one PeerID at a time.
  48  */
  49 struct RPS_SamplerElement
  50 {
  51   /**
  52    * Min-wise linear permutation used by this sampler.
  53    *
  54    * This is an key later used by a hmac.
  55    */
  56   struct GNUNET_CRYPTO_AuthKey auth_key;
  57
  58   /**
  59    * The PeerID this sampler currently samples.
  60    */
  61   struct GNUNET_PeerIdentity peer_id;
  62
  63   /**
  64    * The according hash value of this PeerID.
  65    */
  66   struct GNUNET_HashCode peer_id_hash;
  67
  68
  69   /**
  70    * Time of last request.
  71    */
  72   struct GNUNET_TIME_Absolute last_client_request;
  73
  74   /**
  75    * Flag that indicates that we are not holding a valid PeerID right now.
  76    */
  77   enum RPS_SamplerEmpty is_empty;
  78
  79   /**
  80    * 'Birth'
  81    */
  82   struct GNUNET_TIME_Absolute birth;
  83
  84   /**
  85    * How many times a PeerID was put in this sampler.
  86    */
  87   uint32_t num_peers;
  88
  89   /**
  90    * How many times this sampler changed the peer_id.
  91    */
  92   uint32_t num_change;
  93
  94   /**
  95    * The file name this sampler element should log to
  96    */
  97   char *file_name;
  98 };
  99
 100
 101 /**
 102  * Reinitialise a previously initialised sampler element.
 103  *
 104  * @param sampler pointer to the memory that keeps the value.
 105  */
 106 void
 107 RPS_sampler_elem_reinit (struct RPS_SamplerElement *sampler_el);
 108
 109
 110 /**
 111  * Create a sampler element and initialise it.
 112  *
 113  * In this implementation this means choosing an auth_key for later use in
 114  * a hmac at random.
 115  *
 116  * @return a newly created RPS_SamplerElement which currently holds no id.
 117  */
 118 struct RPS_SamplerElement *
 119 RPS_sampler_elem_create (void);
 120
 121
 122 /**
 123  * Destroy a sampler element.
 124  *
 125  * @param sampler_elem the element to destroy
 126  */
 127 void
 128 RPS_sampler_elem_destroy (struct RPS_SamplerElement *sampler_elem);
 129
 130
 131 /**
 132  * Input an PeerID into the given sampler element.
 133  *
 134  * @param sampler the sampler the @a s_elem belongs to.
 135  *                Needed to know the
 136  */
 137 void
 138 RPS_sampler_elem_next (struct RPS_SamplerElement *s_elem,
 139                        const struct GNUNET_PeerIdentity *new_ID);
 140
 141 /**
 142  * Initialise the min-wise independent function of the given sampler element.
 143  *
 144  * @param s_elem the sampler element
 145  * @param auth_key the key to use
 146  */
 147 void
 148 RPS_sampler_elem_set (struct RPS_SamplerElement *s_elem,
 149                       struct GNUNET_CRYPTO_AuthKey auth_key);
 150
 151
 152 #endif /* RPS_SAMPLER_ELEM_H */
 153 /* end of gnunet-service-rps.c */