diff options
Diffstat (limited to 'src/include/gnunet_ats_service.h')
-rw-r--r-- | src/include/gnunet_ats_service.h | 631 |
1 files changed, 0 insertions, 631 deletions
diff --git a/src/include/gnunet_ats_service.h b/src/include/gnunet_ats_service.h deleted file mode 100644 index ce149875a..000000000 --- a/src/include/gnunet_ats_service.h +++ /dev/null | |||
@@ -1,631 +0,0 @@ | |||
1 | /* | ||
2 | This file is part of GNUnet. | ||
3 | Copyright (C) 2010-2015 GNUnet e.V. | ||
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 | * @addtogroup Backbone | ||
22 | * @{ | ||
23 | * | ||
24 | * @file | ||
25 | * Automatic transport selection and outbound bandwidth determination | ||
26 | * | ||
27 | * @author Christian Grothoff | ||
28 | * @author Matthias Wachs | ||
29 | * | ||
30 | * @defgroup ats ATS service | ||
31 | * Automatic Transport Selection and outbound bandwidth determination | ||
32 | * | ||
33 | * @see [Documentation](https://gnunet.org/ats-subsystem) | ||
34 | * | ||
35 | * @{ | ||
36 | */ | ||
37 | #ifndef GNUNET_ATS_SERVICE_H | ||
38 | #define GNUNET_ATS_SERVICE_H | ||
39 | |||
40 | |||
41 | #include "gnunet_constants.h" | ||
42 | #include "gnunet_util_lib.h" | ||
43 | #include "gnunet_hello_lib.h" | ||
44 | |||
45 | |||
46 | /** | ||
47 | * Default bandwidth assigned to a network : 64 KB/s | ||
48 | */ | ||
49 | #define GNUNET_ATS_DefaultBandwidth 65536 | ||
50 | |||
51 | /** | ||
52 | * Undefined value for an `enum GNUNET_ATS_Property` | ||
53 | */ | ||
54 | #define GNUNET_ATS_VALUE_UNDEFINED UINT32_MAX | ||
55 | |||
56 | /** | ||
57 | * String representation for GNUNET_ATS_VALUE_UNDEFINED | ||
58 | */ | ||
59 | #define GNUNET_ATS_VALUE_UNDEFINED_STR "undefined" | ||
60 | |||
61 | /** | ||
62 | * Maximum bandwidth assigned to a network : 4095 MB/s | ||
63 | */ | ||
64 | #define GNUNET_ATS_MaxBandwidth UINT32_MAX | ||
65 | |||
66 | /** | ||
67 | * Textual equivalent for GNUNET_ATS_MaxBandwidth | ||
68 | */ | ||
69 | #define GNUNET_ATS_MaxBandwidthString "unlimited" | ||
70 | |||
71 | |||
72 | /** | ||
73 | * ATS performance characteristics for an address. | ||
74 | */ | ||
75 | struct GNUNET_ATS_Properties | ||
76 | { | ||
77 | /** | ||
78 | * Delay. Time between when the time packet is sent and the packet | ||
79 | * arrives. FOREVER if we did not measure yet. | ||
80 | */ | ||
81 | struct GNUNET_TIME_Relative delay; | ||
82 | |||
83 | /** | ||
84 | * Actual traffic on this connection from this peer to the other peer. | ||
85 | * Includes transport overhead. | ||
86 | * | ||
87 | * Unit: [bytes/second] | ||
88 | */ | ||
89 | uint32_t utilization_out; | ||
90 | |||
91 | /** | ||
92 | * Actual traffic on this connection from the other peer to this peer. | ||
93 | * Includes transport overhead. | ||
94 | * | ||
95 | * Unit: [bytes/second] | ||
96 | */ | ||
97 | uint32_t utilization_in; | ||
98 | |||
99 | /** | ||
100 | * Distance on network layer (required for distance-vector routing) | ||
101 | * in hops. Zero for direct connections (e.g. plain TCP/UDP). | ||
102 | */ | ||
103 | unsigned int distance; | ||
104 | |||
105 | /** | ||
106 | * Which network scope does the respective address belong to? | ||
107 | * This property does not change. | ||
108 | */ | ||
109 | enum GNUNET_NetworkType scope; | ||
110 | }; | ||
111 | |||
112 | |||
113 | /** | ||
114 | * ATS performance characteristics for an address in | ||
115 | * network byte order (for IPC). | ||
116 | */ | ||
117 | struct GNUNET_ATS_PropertiesNBO | ||
118 | { | ||
119 | /** | ||
120 | * Actual traffic on this connection from this peer to the other peer. | ||
121 | * Includes transport overhead. | ||
122 | * | ||
123 | * Unit: [bytes/second] | ||
124 | */ | ||
125 | uint32_t utilization_out GNUNET_PACKED; | ||
126 | |||
127 | /** | ||
128 | * Actual traffic on this connection from the other peer to this peer. | ||
129 | * Includes transport overhead. | ||
130 | * | ||
131 | * Unit: [bytes/second] | ||
132 | */ | ||
133 | uint32_t utilization_in GNUNET_PACKED; | ||
134 | |||
135 | /** | ||
136 | * Which network scope does the respective address belong to? | ||
137 | * This property does not change. | ||
138 | */ | ||
139 | uint32_t scope GNUNET_PACKED; | ||
140 | |||
141 | /** | ||
142 | * Distance on network layer (required for distance-vector routing) | ||
143 | * in hops. Zero for direct connections (e.g. plain TCP/UDP). | ||
144 | */ | ||
145 | uint32_t distance GNUNET_PACKED; | ||
146 | |||
147 | /** | ||
148 | * Delay. Time between when the time packet is sent and the packet | ||
149 | * arrives. FOREVER if we did not measure yet. | ||
150 | */ | ||
151 | struct GNUNET_TIME_RelativeNBO delay; | ||
152 | }; | ||
153 | |||
154 | |||
155 | /* ********************* LAN Characterization library ************************ */ | ||
156 | /* Note: these functions do not really communicate with the ATS service */ | ||
157 | |||
158 | |||
159 | /** | ||
160 | * Convert ATS properties from host to network byte order. | ||
161 | * | ||
162 | * @param nbo[out] value written | ||
163 | * @param hbo value read | ||
164 | */ | ||
165 | void | ||
166 | GNUNET_ATS_properties_hton (struct GNUNET_ATS_PropertiesNBO *nbo, | ||
167 | const struct GNUNET_ATS_Properties *hbo); | ||
168 | |||
169 | |||
170 | /** | ||
171 | * Convert ATS properties from network to host byte order. | ||
172 | * | ||
173 | * @param hbo[out] value written | ||
174 | * @param nbo value read | ||
175 | */ | ||
176 | void | ||
177 | GNUNET_ATS_properties_ntoh (struct GNUNET_ATS_Properties *hbo, | ||
178 | const struct GNUNET_ATS_PropertiesNBO *nbo); | ||
179 | |||
180 | |||
181 | /* ********************Connection Suggestion API ***************************** */ | ||
182 | |||
183 | /** | ||
184 | * Handle to the ATS subsystem for making suggestions about | ||
185 | * connections the peer would like to have. | ||
186 | */ | ||
187 | struct GNUNET_ATS_ConnectivityHandle; | ||
188 | |||
189 | /** | ||
190 | * Handle for address suggestion requests. | ||
191 | */ | ||
192 | struct GNUNET_ATS_ConnectivitySuggestHandle; | ||
193 | |||
194 | |||
195 | /** | ||
196 | * Initialize the ATS connectivity suggestion client handle. | ||
197 | * | ||
198 | * @param cfg configuration to use | ||
199 | * @return ats connectivity handle, NULL on error | ||
200 | */ | ||
201 | struct GNUNET_ATS_ConnectivityHandle * | ||
202 | GNUNET_ATS_connectivity_init (const struct GNUNET_CONFIGURATION_Handle *cfg); | ||
203 | |||
204 | |||
205 | /** | ||
206 | * Shutdown ATS connectivity suggestion client. | ||
207 | * | ||
208 | * @param ch handle to destroy | ||
209 | */ | ||
210 | void | ||
211 | GNUNET_ATS_connectivity_done (struct GNUNET_ATS_ConnectivityHandle *ch); | ||
212 | |||
213 | |||
214 | /** | ||
215 | * We would like to establish a new connection with a peer. ATS | ||
216 | * should suggest a good address to begin with. | ||
217 | * | ||
218 | * @param ch handle | ||
219 | * @param peer identity of the peer we need an address for | ||
220 | * @param strength how urgent is the need for such a suggestion | ||
221 | * @return suggestion handle, NULL if request is already pending | ||
222 | */ | ||
223 | struct GNUNET_ATS_ConnectivitySuggestHandle * | ||
224 | GNUNET_ATS_connectivity_suggest (struct GNUNET_ATS_ConnectivityHandle *ch, | ||
225 | const struct GNUNET_PeerIdentity *peer, | ||
226 | uint32_t strength); | ||
227 | |||
228 | |||
229 | /** | ||
230 | * We no longer care about being connected to a peer. | ||
231 | * | ||
232 | * @param sh handle to stop | ||
233 | */ | ||
234 | void | ||
235 | GNUNET_ATS_connectivity_suggest_cancel (struct | ||
236 | GNUNET_ATS_ConnectivitySuggestHandle *sh); | ||
237 | |||
238 | |||
239 | /* ******************************** Scheduling API ***************************** */ | ||
240 | |||
241 | /** | ||
242 | * Handle to the ATS subsystem for bandwidth/transport scheduling information. | ||
243 | */ | ||
244 | struct GNUNET_ATS_SchedulingHandle; | ||
245 | |||
246 | /** | ||
247 | * Opaque session handle, defined by plugins. Contents not known to ATS. | ||
248 | */ | ||
249 | struct GNUNET_ATS_Session; | ||
250 | |||
251 | |||
252 | /** | ||
253 | * Signature of a function called by ATS with the current bandwidth | ||
254 | * and address preferences as determined by ATS. If our connection | ||
255 | * to ATS dies and thus all suggestions become invalid, this function | ||
256 | * is called ONCE with all arguments (except @a cls) being NULL/0. | ||
257 | * | ||
258 | * @param cls closure | ||
259 | * @param peer for which we suggest an address, NULL if ATS connection died | ||
260 | * @param address suggested address (including peer identity of the peer), | ||
261 | * may be NULL to signal disconnect from peer | ||
262 | * @param session session to use, NULL to establish a new outgoing session | ||
263 | * @param bandwidth_out assigned outbound bandwidth for the connection, | ||
264 | * 0 to signal disconnect | ||
265 | * @param bandwidth_in assigned inbound bandwidth for the connection, | ||
266 | * 0 to signal disconnect | ||
267 | */ | ||
268 | typedef void | ||
269 | (*GNUNET_ATS_AddressSuggestionCallback) (void *cls, | ||
270 | const struct GNUNET_PeerIdentity *peer, | ||
271 | const struct | ||
272 | GNUNET_HELLO_Address *address, | ||
273 | struct GNUNET_ATS_Session *session, | ||
274 | struct GNUNET_BANDWIDTH_Value32NBO | ||
275 | bandwidth_out, | ||
276 | struct GNUNET_BANDWIDTH_Value32NBO | ||
277 | bandwidth_in); | ||
278 | |||
279 | |||
280 | /** | ||
281 | * Initialize the ATS scheduling subsystem. | ||
282 | * | ||
283 | * @param cfg configuration to use | ||
284 | * @param suggest_cb notification to call whenever the suggestation changed | ||
285 | * @param suggest_cb_cls closure for @a suggest_cb | ||
286 | * @return ats context | ||
287 | */ | ||
288 | struct GNUNET_ATS_SchedulingHandle * | ||
289 | GNUNET_ATS_scheduling_init (const struct GNUNET_CONFIGURATION_Handle *cfg, | ||
290 | GNUNET_ATS_AddressSuggestionCallback suggest_cb, | ||
291 | void *suggest_cb_cls); | ||
292 | |||
293 | |||
294 | /** | ||
295 | * Client is done with ATS scheduling, release resources. | ||
296 | * | ||
297 | * @param sh handle to release | ||
298 | */ | ||
299 | void | ||
300 | GNUNET_ATS_scheduling_done (struct GNUNET_ATS_SchedulingHandle *sh); | ||
301 | |||
302 | |||
303 | /** | ||
304 | * Handle used within ATS to track an address. | ||
305 | */ | ||
306 | struct GNUNET_ATS_AddressRecord; | ||
307 | |||
308 | |||
309 | /** | ||
310 | * We have a new address ATS should know. Addresses have to be added with this | ||
311 | * function before they can be: updated, set in use and destroyed | ||
312 | * | ||
313 | * @param sh handle | ||
314 | * @param address the address | ||
315 | * @param session session handle (if available, e.g for incoming connections) | ||
316 | * @param prop performance data for the address | ||
317 | * @return handle to the address representation inside ATS, NULL | ||
318 | * on error (i.e. ATS knows this exact address already, or | ||
319 | * address is invalid) | ||
320 | */ | ||
321 | struct GNUNET_ATS_AddressRecord * | ||
322 | GNUNET_ATS_address_add (struct GNUNET_ATS_SchedulingHandle *sh, | ||
323 | const struct GNUNET_HELLO_Address *address, | ||
324 | struct GNUNET_ATS_Session *session, | ||
325 | const struct GNUNET_ATS_Properties *prop); | ||
326 | |||
327 | |||
328 | /** | ||
329 | * An address was used to initiate a session. | ||
330 | * | ||
331 | * @param ar address record to update information for | ||
332 | * @param session session handle | ||
333 | */ | ||
334 | void | ||
335 | GNUNET_ATS_address_add_session (struct GNUNET_ATS_AddressRecord *ar, | ||
336 | struct GNUNET_ATS_Session *session); | ||
337 | |||
338 | |||
339 | /** | ||
340 | * A @a session was destroyed, disassociate it from the given address | ||
341 | * record. If this was an incoming address, destroys the address as | ||
342 | * well. | ||
343 | * | ||
344 | * @param ar address record to update information for | ||
345 | * @param session session handle | ||
346 | * @return #GNUNET_YES if the @a ar was destroyed because | ||
347 | * it was an incoming address, | ||
348 | * #GNUNET_NO if the @a ar was kept because we can | ||
349 | * use it still to establish a new session | ||
350 | */ | ||
351 | int | ||
352 | GNUNET_ATS_address_del_session (struct GNUNET_ATS_AddressRecord *ar, | ||
353 | struct GNUNET_ATS_Session *session); | ||
354 | |||
355 | |||
356 | /** | ||
357 | * We have updated performance statistics for a given address. Note | ||
358 | * that this function can be called for addresses that are currently | ||
359 | * in use as well as addresses that are valid but not actively in use. | ||
360 | * Furthermore, the peer may not even be connected to us right now (@a | ||
361 | * session value of NULL used to signal disconnect, or somehow we | ||
362 | * otherwise got updated on @a ats information). Based on the | ||
363 | * information provided, ATS may update bandwidth assignments and | ||
364 | * suggest to switch addresses. | ||
365 | * | ||
366 | * @param ar address record to update information for | ||
367 | * @param prop performance data for the address | ||
368 | */ | ||
369 | void | ||
370 | GNUNET_ATS_address_update (struct GNUNET_ATS_AddressRecord *ar, | ||
371 | const struct GNUNET_ATS_Properties *prop); | ||
372 | |||
373 | |||
374 | /** | ||
375 | * An address got destroyed, stop using it as a valid address. | ||
376 | * | ||
377 | * @param ar address record to destroy, its validation has | ||
378 | * expired and ATS may no longer use it | ||
379 | */ | ||
380 | void | ||
381 | GNUNET_ATS_address_destroy (struct GNUNET_ATS_AddressRecord *ar); | ||
382 | |||
383 | |||
384 | /* ******************************** Performance API ***************************** */ | ||
385 | |||
386 | /** | ||
387 | * ATS Handle to obtain and/or modify performance information. | ||
388 | */ | ||
389 | struct GNUNET_ATS_PerformanceHandle; | ||
390 | |||
391 | /** | ||
392 | * Signature of a function that is called with QoS information about an address. | ||
393 | * | ||
394 | * @param cls closure | ||
395 | * @param address the address, NULL if ATS service was disconnected or | ||
396 | * when the iteration is completed in the case of | ||
397 | * #GNUNET_ATS_performance_list_addresses() | ||
398 | * @param address_active #GNUNET_YES if this address is actively used | ||
399 | * to maintain a connection to a peer; | ||
400 | * #GNUNET_NO if the address is not actively used; | ||
401 | * #GNUNET_SYSERR if this address is no longer available for ATS | ||
402 | * @param bandwidth_out assigned outbound bandwidth for the connection | ||
403 | * @param bandwidth_in assigned inbound bandwidth for the connection | ||
404 | * @param prop performance data for the address | ||
405 | */ | ||
406 | typedef void | ||
407 | (*GNUNET_ATS_AddressInformationCallback) (void *cls, | ||
408 | const struct | ||
409 | GNUNET_HELLO_Address *address, | ||
410 | int address_active, | ||
411 | struct GNUNET_BANDWIDTH_Value32NBO | ||
412 | bandwidth_out, | ||
413 | struct GNUNET_BANDWIDTH_Value32NBO | ||
414 | bandwidth_in, | ||
415 | const struct | ||
416 | GNUNET_ATS_Properties *prop); | ||
417 | |||
418 | |||
419 | /** | ||
420 | * Handle for an address listing operation | ||
421 | */ | ||
422 | struct GNUNET_ATS_AddressListHandle; | ||
423 | |||
424 | |||
425 | /** | ||
426 | * Get handle to access performance API of the ATS subsystem. | ||
427 | * | ||
428 | * @param cfg configuration to use | ||
429 | * @param addr_info_cb callback called when performance characteristics for | ||
430 | * an address change | ||
431 | * @param addr_info_cb_cls closure for @a addr_info_cb | ||
432 | * @return ats performance context | ||
433 | */ | ||
434 | struct GNUNET_ATS_PerformanceHandle * | ||
435 | GNUNET_ATS_performance_init (const struct GNUNET_CONFIGURATION_Handle *cfg, | ||
436 | GNUNET_ATS_AddressInformationCallback addr_info_cb, | ||
437 | void *addr_info_cb_cls); | ||
438 | |||
439 | |||
440 | /** | ||
441 | * Get information about addresses known to the ATS subsystem. | ||
442 | * | ||
443 | * @param ph the performance handle to use | ||
444 | * @param peer peer idm can be NULL for all peers | ||
445 | * @param all #GNUNET_YES to get information about all addresses or #GNUNET_NO to | ||
446 | * get only address currently used | ||
447 | * @param infocb callback to call with the addresses, | ||
448 | * will callback with address == NULL when done | ||
449 | * @param infocb_cls closure for @a infocb | ||
450 | * @return handle to abort the operation | ||
451 | */ | ||
452 | struct GNUNET_ATS_AddressListHandle * | ||
453 | GNUNET_ATS_performance_list_addresses (struct GNUNET_ATS_PerformanceHandle *ph, | ||
454 | const struct GNUNET_PeerIdentity *peer, | ||
455 | int all, | ||
456 | GNUNET_ATS_AddressInformationCallback | ||
457 | infocb, | ||
458 | void *infocb_cls); | ||
459 | |||
460 | |||
461 | /** | ||
462 | * Cancel a pending address listing operation | ||
463 | * | ||
464 | * @param alh the `struct GNUNET_ATS_AddressListHandle` handle to cancel | ||
465 | */ | ||
466 | void | ||
467 | GNUNET_ATS_performance_list_addresses_cancel (struct | ||
468 | GNUNET_ATS_AddressListHandle *alh); | ||
469 | |||
470 | |||
471 | /** | ||
472 | * Client is done using the ATS performance subsystem, release resources. | ||
473 | * | ||
474 | * @param ph handle | ||
475 | */ | ||
476 | void | ||
477 | GNUNET_ATS_performance_done (struct GNUNET_ATS_PerformanceHandle *ph); | ||
478 | |||
479 | |||
480 | /** | ||
481 | * Function called with reservation result. | ||
482 | * | ||
483 | * @param cls closure | ||
484 | * @param peer identifies the peer | ||
485 | * @param amount set to the amount that was actually reserved or unreserved; | ||
486 | * either the full requested amount or zero (no partial reservations) | ||
487 | * @param res_delay if the reservation could not be satisfied (amount was 0), how | ||
488 | * long should the client wait until re-trying? | ||
489 | */ | ||
490 | typedef void | ||
491 | (*GNUNET_ATS_ReservationCallback) (void *cls, | ||
492 | const struct GNUNET_PeerIdentity *peer, | ||
493 | int32_t amount, | ||
494 | struct GNUNET_TIME_Relative res_delay); | ||
495 | |||
496 | |||
497 | /** | ||
498 | * Context that can be used to cancel a peer information request. | ||
499 | */ | ||
500 | struct GNUNET_ATS_ReservationContext; | ||
501 | |||
502 | |||
503 | /** | ||
504 | * Reserve inbound bandwidth from the given peer. ATS will look at | ||
505 | * the current amount of traffic we receive from the peer and ensure | ||
506 | * that the peer could add 'amount' of data to its stream. | ||
507 | * | ||
508 | * @param ph performance handle | ||
509 | * @param peer identifies the peer | ||
510 | * @param amount reserve N bytes for receiving, negative | ||
511 | * amounts can be used to undo a (recent) reservation; | ||
512 | * @param rcb function to call with the resulting reservation information | ||
513 | * @param rcb_cls closure for @a rcb | ||
514 | * @return NULL on error | ||
515 | * @deprecated will be replaced soon | ||
516 | */ | ||
517 | struct GNUNET_ATS_ReservationContext * | ||
518 | GNUNET_ATS_reserve_bandwidth (struct GNUNET_ATS_PerformanceHandle *ph, | ||
519 | const struct GNUNET_PeerIdentity *peer, | ||
520 | int32_t amount, | ||
521 | GNUNET_ATS_ReservationCallback rcb, | ||
522 | void *rcb_cls); | ||
523 | |||
524 | |||
525 | /** | ||
526 | * Cancel request for reserving bandwidth. | ||
527 | * | ||
528 | * @param rc context returned by the original #GNUNET_ATS_reserve_bandwidth() call | ||
529 | */ | ||
530 | void | ||
531 | GNUNET_ATS_reserve_bandwidth_cancel (struct GNUNET_ATS_ReservationContext *rc); | ||
532 | |||
533 | |||
534 | /** | ||
535 | * ATS preference types as array initializer | ||
536 | */ | ||
537 | #define GNUNET_ATS_PreferenceType { GNUNET_ATS_PREFERENCE_BANDWIDTH, \ | ||
538 | GNUNET_ATS_PREFERENCE_LATENCY, \ | ||
539 | GNUNET_ATS_PREFERENCE_END } | ||
540 | |||
541 | /** | ||
542 | * ATS preference types as string array initializer | ||
543 | */ | ||
544 | #define GNUNET_ATS_PreferenceTypeString { "BANDWIDTH", "LATENCY", "END" } | ||
545 | |||
546 | /** | ||
547 | * Enum defining all known preference categories. | ||
548 | */ | ||
549 | enum GNUNET_ATS_PreferenceKind | ||
550 | { | ||
551 | /** | ||
552 | * Change the peer's bandwidth value (value per byte of bandwidth in | ||
553 | * the goal function) to the given amount. The argument is followed | ||
554 | * by a double value giving the desired value (can be negative). | ||
555 | * Preference changes are forgotten if peers disconnect. | ||
556 | */ | ||
557 | GNUNET_ATS_PREFERENCE_BANDWIDTH = 0, | ||
558 | |||
559 | /** | ||
560 | * Change the peer's latency value to the given amount. The | ||
561 | * argument is followed by a double value giving the desired value | ||
562 | * (can be negative). The absolute score in the goal function is | ||
563 | * the inverse of the latency in microseconds (minimum: 1 | ||
564 | * microsecond) multiplied by the latency preferences. | ||
565 | */ | ||
566 | GNUNET_ATS_PREFERENCE_LATENCY = 1, | ||
567 | |||
568 | /** | ||
569 | * End of preference list. | ||
570 | */ | ||
571 | GNUNET_ATS_PREFERENCE_END = 2 | ||
572 | }; | ||
573 | |||
574 | |||
575 | /** | ||
576 | * Convert an `enum GNUNET_ATS_PreferenceType` to a string | ||
577 | * | ||
578 | * @param type the preference type | ||
579 | * @return a string or NULL if invalid | ||
580 | */ | ||
581 | const char * | ||
582 | GNUNET_ATS_print_preference_type (enum GNUNET_ATS_PreferenceKind type); | ||
583 | |||
584 | |||
585 | /** | ||
586 | * Change preferences for the given peer. Preference changes are | ||
587 | * forgotten if peers disconnect. | ||
588 | * | ||
589 | * @param ph performance handle | ||
590 | * @param peer identifies the peer | ||
591 | * @param ... #GNUNET_ATS_PREFERENCE_END-terminated specification of the | ||
592 | * desired changes | ||
593 | */ | ||
594 | void | ||
595 | GNUNET_ATS_performance_change_preference (struct | ||
596 | GNUNET_ATS_PerformanceHandle *ph, | ||
597 | const struct | ||
598 | GNUNET_PeerIdentity *peer, | ||
599 | ...); | ||
600 | |||
601 | |||
602 | /** | ||
603 | * Application feedback on how good preference requirements are fulfilled | ||
604 | * for the preferences included in the given time scope [now - scope .. now] | ||
605 | * | ||
606 | * An application notifies ATS if (and only if) it has feedback information | ||
607 | * for specific properties. This values are valid until the feedback scores are | ||
608 | * updated by the application. | ||
609 | * | ||
610 | * If the application has no feedback for this preference kind the application | ||
611 | * will not explicitly call for this property and will not include it in this | ||
612 | * function call. | ||
613 | * | ||
614 | * @param ph performance handle | ||
615 | * @param scope the time interval this valid for: [now - scope .. now] | ||
616 | * @param peer identifies the peer | ||
617 | * @param ... #GNUNET_ATS_PREFERENCE_END-terminated specification of the desired changes | ||
618 | */ | ||
619 | void | ||
620 | GNUNET_ATS_performance_give_feedback (struct GNUNET_ATS_PerformanceHandle *ph, | ||
621 | const struct GNUNET_PeerIdentity *peer, | ||
622 | const struct GNUNET_TIME_Relative scope, | ||
623 | ...); | ||
624 | |||
625 | #endif | ||
626 | |||
627 | /** @} */ /* end of group */ | ||
628 | |||
629 | /** @} */ /* end of Backbone addition */ | ||
630 | |||
631 | /* end of file gnunet-service-transport_ats.h */ | ||