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