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