gnunet_rps_service.h (7599B)
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 SPDX-License-Identifier: AGPL3.0-or-later 19 */ 20 21 /** 22 * @addtogroup Backbone 23 * @{ 24 * 25 * @author Julius Bünger 26 * 27 * @file 28 * API to the rps service 29 * 30 * @defgroup rps RPS service 31 * Random Peer Sampling 32 * @{ 33 */ 34 #ifndef GNUNET_RPS_SERVICE_H 35 #define GNUNET_RPS_SERVICE_H 36 37 #ifdef __cplusplus 38 extern "C" 39 { 40 #if 0 /* keep Emacsens' auto-indent happy */ 41 } 42 #endif 43 #endif 44 45 /** 46 * Version of the rps API. 47 */ 48 #define GNUNET_RPS_VERSION 0x00000000 49 50 /** 51 * Handle for the random peer sampling service 52 */ 53 struct GNUNET_RPS_Handle; 54 55 /** 56 * Handle for one request to the rps service 57 */ 58 struct GNUNET_RPS_Request_Handle; 59 60 /** 61 * Callback called when requested random peers are available. 62 * 63 * @param cls the closure given with the request 64 * @param num_peers the number of peers returned 65 * @param peers array with num_peers PeerIDs 66 */ 67 typedef void (*GNUNET_RPS_NotifyReadyCB) (void *cls, 68 uint64_t num_peers, 69 const struct 70 GNUNET_PeerIdentity *peers); 71 72 73 /** 74 * Callback called when requested random peer with additional information is 75 * available. 76 * 77 * @param cls the closure given with the request 78 * @param peer The Peer ID 79 * @param probability The probability with which all elements have been observed 80 * @param num_observed Number of IDs this sampler has observed 81 */ 82 typedef void (*GNUNET_RPS_NotifyReadySingleInfoCB) (void *cls, 83 const struct 84 GNUNET_PeerIdentity *peer, 85 double probability, 86 uint32_t num_observed); 87 88 89 /** 90 * Connect to the rps service 91 * 92 * @param cfg configuration to use 93 * @return handle to the rps service 94 */ 95 struct GNUNET_RPS_Handle * 96 GNUNET_RPS_connect (const struct GNUNET_CONFIGURATION_Handle *cfg); 97 98 99 /** 100 * @brief Start a sub with the given shared value 101 * 102 * @param h Handle to rps 103 * @param shared_value The shared value that defines the members of the sub (-group) 104 */ 105 void 106 GNUNET_RPS_sub_start (struct GNUNET_RPS_Handle *h, 107 const char *shared_value); 108 109 110 /** 111 * @brief Stop a sub with the given shared value 112 * 113 * @param h Handle to rps 114 * @param shared_value The shared value that defines the members of the sub (-group) 115 */ 116 void 117 GNUNET_RPS_sub_stop (struct GNUNET_RPS_Handle *h, 118 const char *shared_value); 119 120 121 /** 122 * Request n random peers. 123 * 124 * This does exactly the same as GNUNET_RPS_request_peers_single_call 125 * but needs a GNUNET_RPS_Handle. 126 * This exists only for other parts of GNUnet that expect having to 127 * (dis)connect from/to a service. 128 * 129 * @param h handle to the rps service 130 * @param n number of random peers to return 131 * @param ready_cb the callback to be called when the peers are available 132 * @param cls a closure that will be given to the callback 133 * @return handle to this request 134 */ 135 struct GNUNET_RPS_Request_Handle * 136 GNUNET_RPS_request_peers (struct GNUNET_RPS_Handle *h, uint32_t n, 137 GNUNET_RPS_NotifyReadyCB ready_cb, 138 void *cls); 139 140 141 /** 142 * Request one random peer, getting additional information. 143 * 144 * @param rps_handle handle to the rps service 145 * @param ready_cb the callback called when the peers are available 146 * @param cls closure given to the callback 147 * @return a handle to cancel this request 148 */ 149 struct GNUNET_RPS_Request_Handle_Single_Info * 150 GNUNET_RPS_request_peer_info (struct GNUNET_RPS_Handle *rps_handle, 151 GNUNET_RPS_NotifyReadySingleInfoCB ready_cb, 152 void *cls); 153 154 155 /** 156 * Seed rps service with peerIDs. 157 * 158 * @param h handle to the rps service 159 * @param n number of peers to seed 160 * @param ids the ids of the peers seeded 161 */ 162 void 163 GNUNET_RPS_seed_ids (struct GNUNET_RPS_Handle *h, uint32_t n, 164 const struct GNUNET_PeerIdentity *ids); 165 166 /** 167 * Cancel an issued request. 168 * 169 * @param rh handle of the pending request to be canceled 170 */ 171 void 172 GNUNET_RPS_request_cancel (struct GNUNET_RPS_Request_Handle *rh); 173 174 175 /** 176 * Cancel an issued single info request. 177 * 178 * @param rhs request handle of request to cancel 179 */ 180 void 181 GNUNET_RPS_request_single_info_cancel ( 182 struct GNUNET_RPS_Request_Handle_Single_Info *rhs); 183 184 185 #if ENABLE_MALICIOUS 186 /** 187 * Turn RPS service to act malicious. 188 * 189 * @param h handle to the rps service 190 * @param type which type of malicious peer to turn to. 191 * 0 Don't act malicious at all 192 * 1 Try to maximise representation 193 * 2 Try to partition the network 194 * (isolate one peer from the rest) 195 * @param n number of @a ids 196 * @param ids the ids of the malicious peers 197 * if @type is 2 the last id is the id of the 198 * peer to be isolated from the rest 199 */ 200 void 201 GNUNET_RPS_act_malicious (struct GNUNET_RPS_Handle *h, 202 uint32_t type, 203 uint32_t num_peers, 204 const struct GNUNET_PeerIdentity *ids, 205 const struct GNUNET_PeerIdentity *target_peer); 206 207 #endif /* ENABLE_MALICIOUS */ 208 209 /* Get internals for debugging/profiling purposes */ 210 211 /** 212 * Request updates of view 213 * 214 * @param rps_handle handle to the rps service 215 * @param num_req_peers number of peers we want to receive 216 * (0 for infinite updates) 217 * @param cls a closure that will be given to the callback 218 * @param ready_cb the callback called when the peers are available 219 */ 220 void 221 GNUNET_RPS_view_request (struct GNUNET_RPS_Handle *rps_handle, 222 uint32_t num_updates, 223 GNUNET_RPS_NotifyReadyCB view_update_cb, 224 void *cls); 225 226 227 /** 228 * Request biased stream of peers that are being put into the sampler 229 * 230 * @param rps_handle handle to the rps service 231 * @param cls a closure that will be given to the callback 232 * @param ready_cb the callback called when the peers are available 233 */ 234 struct GNUNET_RPS_StreamRequestHandle * 235 GNUNET_RPS_stream_request (struct GNUNET_RPS_Handle *rps_handle, 236 GNUNET_RPS_NotifyReadyCB stream_input_cb, 237 void *cls); 238 239 240 /** 241 * @brief Cancel a specific request for updates from the biased peer stream 242 * 243 * @param srh The request handle to cancel 244 */ 245 void 246 GNUNET_RPS_stream_cancel (struct GNUNET_RPS_StreamRequestHandle *srh); 247 248 249 /** 250 * Disconnect from the rps service 251 * 252 * @param h the handle to the rps service 253 */ 254 void 255 GNUNET_RPS_disconnect (struct GNUNET_RPS_Handle *h); 256 257 258 #if 0 /* keep Emacsens' auto-indent happy */ 259 { 260 #endif 261 #ifdef __cplusplus 262 } 263 #endif 264 265 #endif 266 267 /** @} */ /* end of group */ 268 269 /** @} */ /* end of group addition */