diff options
Diffstat (limited to 'src/include/gnunet_ats_service.h')
-rw-r--r-- | src/include/gnunet_ats_service.h | 205 |
1 files changed, 87 insertions, 118 deletions
diff --git a/src/include/gnunet_ats_service.h b/src/include/gnunet_ats_service.h index 437984402..8b28f5dc7 100644 --- a/src/include/gnunet_ats_service.h +++ b/src/include/gnunet_ats_service.h | |||
@@ -100,137 +100,118 @@ enum GNUNET_ATS_Network_Type | |||
100 | 100 | ||
101 | 101 | ||
102 | /** | 102 | /** |
103 | * Enum defining all known property types for ATS Enum values are used | 103 | * ATS performance characteristics for an address. |
104 | * in the GNUNET_ATS_Information struct as | ||
105 | * (key,value)-pairs. | ||
106 | * | ||
107 | * Cost are always stored in uint32_t, so all units used to define costs | ||
108 | * have to be normalized to fit in uint32_t [0 .. UINT32_MAX-1] | ||
109 | * | ||
110 | * UINT32_MAX is reserved for uninitialized values #GNUNET_ATS_VALUE_UNDEFINED | ||
111 | */ | 104 | */ |
112 | enum GNUNET_ATS_Property | 105 | struct GNUNET_ATS_Properties |
113 | { | 106 | { |
114 | 107 | ||
115 | /** | 108 | /** |
116 | * End of the array. | ||
117 | * @deprecated | ||
118 | */ | ||
119 | GNUNET_ATS_ARRAY_TERMINATOR = 0, | ||
120 | |||
121 | /** | ||
122 | * Actual traffic on this connection from this peer to the other peer. | 109 | * Actual traffic on this connection from this peer to the other peer. |
123 | * Includes transport overhead | 110 | * Includes transport overhead. |
124 | * | 111 | * |
125 | * Unit: [bytes/second] | 112 | * Unit: [bytes/second] |
126 | */ | 113 | */ |
127 | GNUNET_ATS_UTILIZATION_OUT = 1, | 114 | uint32_t utilization_out; |
128 | 115 | ||
129 | /** | 116 | /** |
130 | * Actual traffic on this connection from the other peer to this peer. | 117 | * Actual traffic on this connection from the other peer to this peer. |
131 | * Includes transport overhead | 118 | * Includes transport overhead. |
132 | * | 119 | * |
133 | * Unit: [bytes/second] | 120 | * Unit: [bytes/second] |
134 | */ | 121 | */ |
135 | GNUNET_ATS_UTILIZATION_IN = 2, | 122 | uint32_t utilization_in; |
136 | 123 | ||
137 | /** | 124 | /** |
138 | * Is this address located in WAN, LAN or a loopback address | 125 | * Which network scope does the respective address belong to? |
139 | * Value is element of GNUNET_ATS_Network_Type | 126 | * This property does not change. |
140 | */ | 127 | */ |
141 | GNUNET_ATS_NETWORK_TYPE = 3, | 128 | enum GNUNET_ATS_Network_Type scope; |
142 | 129 | ||
143 | /** | 130 | /** |
144 | * Delay | 131 | * Distance on network layer (required for distance-vector routing) |
145 | * Time between when the time packet is sent and the packet arrives | 132 | * in hops. Zero for direct connections (i.e. plain TCP/UDP). |
146 | * | ||
147 | * Unit: [microseconds] | ||
148 | * | ||
149 | * Examples: | ||
150 | * | ||
151 | * LAN : 1 | ||
152 | * WLAN : 2 | ||
153 | * Dialup: 500 | ||
154 | */ | 133 | */ |
155 | GNUNET_ATS_QUALITY_NET_DELAY = 4, | 134 | unsigned int distance; |
156 | 135 | ||
157 | /** | 136 | /** |
158 | * Distance on network layer (required for distance-vector routing). | 137 | * Delay. Time between when the time packet is sent and the packet |
159 | * | 138 | * arrives. FOREVER if we did not measure yet. |
160 | * Unit: [DV-hops] | ||
161 | */ | 139 | */ |
162 | GNUNET_ATS_QUALITY_NET_DISTANCE = 5 | 140 | struct GNUNET_TIME_Relative delay; |
163 | |||
164 | /** | ||
165 | * Number of property types supported by ATS | ||
166 | */ | ||
167 | #define GNUNET_ATS_PropertyCount 6 | ||
168 | |||
169 | 141 | ||
170 | }; | 142 | }; |
171 | 143 | ||
172 | 144 | ||
173 | /** | 145 | /** |
174 | * Number of ATS quality properties | 146 | * ATS performance characteristics for an address in |
147 | * network byte order (for IPC). | ||
175 | */ | 148 | */ |
176 | #define GNUNET_ATS_QualityPropertiesCount 2 | 149 | struct GNUNET_ATS_PropertiesNBO |
150 | { | ||
177 | 151 | ||
178 | /** | 152 | /** |
179 | * ATS quality properties as array initializer | 153 | * Actual traffic on this connection from this peer to the other peer. |
180 | */ | 154 | * Includes transport overhead. |
181 | #define GNUNET_ATS_QualityProperties { GNUNET_ATS_QUALITY_NET_DELAY, GNUNET_ATS_QUALITY_NET_DISTANCE } | 155 | * |
156 | * Unit: [bytes/second] | ||
157 | */ | ||
158 | uint32_t utilization_out GNUNET_PACKED; | ||
182 | 159 | ||
183 | /** | 160 | /** |
184 | * ATS quality properties as string array initializer | 161 | * Actual traffic on this connection from the other peer to this peer. |
185 | */ | 162 | * Includes transport overhead. |
186 | #define GNUNET_ATS_QualityPropertiesString {"Delay", "Distance"} | 163 | * |
164 | * Unit: [bytes/second] | ||
165 | */ | ||
166 | uint32_t utilization_in GNUNET_PACKED; | ||
187 | 167 | ||
188 | GNUNET_NETWORK_STRUCT_BEGIN | 168 | /** |
169 | * Which network scope does the respective address belong to? | ||
170 | * This property does not change. | ||
171 | */ | ||
172 | uint32_t scope GNUNET_PACKED; | ||
189 | 173 | ||
190 | /** | ||
191 | * struct used to communicate the transport's properties like cost and | ||
192 | * quality of service as well as high-level constraints on resource | ||
193 | * consumption. | ||
194 | * | ||
195 | * +---+ | ||
196 | * +-----------+ Constraints | | Plugin properties +---------+ | ||
197 | * | Highlevel |------------> |ATS| <------------------|Transport| | ||
198 | * | Component | ATS struct | | ATS struct | Plugin | | ||
199 | * +-----------+ | | +---------+ | ||
200 | * +---+ | ||
201 | * | ||
202 | * This structure will be used by transport plugins to communicate | ||
203 | * costs to ATS or by higher level components to tell ATS their | ||
204 | * constraints. Always a pair of (GNUNET_ATS_Property, | ||
205 | * uint32_t value). Value is always uint32_t, so all units used to | ||
206 | * define costs have to be normalized to fit uint32_t. | ||
207 | */ | ||
208 | struct GNUNET_ATS_Information | ||
209 | { | ||
210 | /** | 174 | /** |
211 | * ATS property type, in network byte order. | 175 | * Distance on network layer (required for distance-vector routing) |
176 | * in hops. Zero for direct connections (i.e. plain TCP/UDP). | ||
212 | */ | 177 | */ |
213 | uint32_t type GNUNET_PACKED; | 178 | uint32_t distance GNUNET_PACKED; |
214 | 179 | ||
215 | /** | 180 | /** |
216 | * ATS property value, in network byte order. | 181 | * Delay. Time between when the time packet is sent and the packet |
182 | * arrives. FOREVER if we did not measure yet. | ||
217 | */ | 183 | */ |
218 | uint32_t value GNUNET_PACKED; | 184 | struct GNUNET_TIME_RelativeNBO delay; |
185 | |||
219 | }; | 186 | }; |
220 | GNUNET_NETWORK_STRUCT_END | 187 | |
221 | 188 | ||
222 | 189 | ||
223 | /* ********************* LAN Characterization library ************************ */ | 190 | /* ********************* LAN Characterization library ************************ */ |
224 | /* Note: these functions do not really communicate with the ATS service */ | 191 | /* Note: these functions do not really communicate with the ATS service */ |
225 | 192 | ||
193 | |||
226 | /** | 194 | /** |
227 | * Convert a ATS property to a string | 195 | * Convert ATS properties from host to network byte order. |
228 | * | 196 | * |
229 | * @param type the property type | 197 | * @param nbo[OUT] value written |
230 | * @return a string or NULL if invalid | 198 | * @param hbo value read |
231 | */ | 199 | */ |
232 | const char * | 200 | void |
233 | GNUNET_ATS_print_property_type (enum GNUNET_ATS_Property type); | 201 | GNUNET_ATS_properties_hton (struct GNUNET_ATS_PropertiesNBO *nbo, |
202 | const struct GNUNET_ATS_Properties *hbo); | ||
203 | |||
204 | |||
205 | /** | ||
206 | * Convert ATS properties from network to host byte order. | ||
207 | * | ||
208 | * @param hbo[OUT] value written | ||
209 | * @param nbo value read | ||
210 | */ | ||
211 | void | ||
212 | GNUNET_ATS_properties_ntoh (struct GNUNET_ATS_Properties *hbo, | ||
213 | const struct GNUNET_ATS_PropertiesNBO *nbo); | ||
214 | |||
234 | 215 | ||
235 | 216 | ||
236 | /** | 217 | /** |
@@ -367,11 +348,11 @@ struct Session; | |||
367 | */ | 348 | */ |
368 | typedef void | 349 | typedef void |
369 | (*GNUNET_ATS_AddressSuggestionCallback) (void *cls, | 350 | (*GNUNET_ATS_AddressSuggestionCallback) (void *cls, |
370 | const struct GNUNET_PeerIdentity *peer, | 351 | const struct GNUNET_PeerIdentity *peer, |
371 | const struct GNUNET_HELLO_Address *address, | 352 | const struct GNUNET_HELLO_Address *address, |
372 | struct Session *session, | 353 | struct Session *session, |
373 | struct GNUNET_BANDWIDTH_Value32NBO bandwidth_out, | 354 | struct GNUNET_BANDWIDTH_Value32NBO bandwidth_out, |
374 | struct GNUNET_BANDWIDTH_Value32NBO bandwidth_in); | 355 | struct GNUNET_BANDWIDTH_Value32NBO bandwidth_in); |
375 | 356 | ||
376 | 357 | ||
377 | /** | 358 | /** |
@@ -424,8 +405,7 @@ struct GNUNET_ATS_AddressRecord; | |||
424 | * @param sh handle | 405 | * @param sh handle |
425 | * @param address the address | 406 | * @param address the address |
426 | * @param session session handle (if available, i.e. for incoming connections) | 407 | * @param session session handle (if available, i.e. for incoming connections) |
427 | * @param ats performance data for the address | 408 | * @param prop performance data for the address |
428 | * @param ats_count number of performance records in @a ats | ||
429 | * @return handle to the address representation inside ATS, NULL | 409 | * @return handle to the address representation inside ATS, NULL |
430 | * on error (i.e. ATS knows this exact address already, or | 410 | * on error (i.e. ATS knows this exact address already, or |
431 | * address is invalid) | 411 | * address is invalid) |
@@ -434,8 +414,7 @@ struct GNUNET_ATS_AddressRecord * | |||
434 | GNUNET_ATS_address_add (struct GNUNET_ATS_SchedulingHandle *sh, | 414 | GNUNET_ATS_address_add (struct GNUNET_ATS_SchedulingHandle *sh, |
435 | const struct GNUNET_HELLO_Address *address, | 415 | const struct GNUNET_HELLO_Address *address, |
436 | struct Session *session, | 416 | struct Session *session, |
437 | const struct GNUNET_ATS_Information *ats, | 417 | const struct GNUNET_ATS_Properties *prop); |
438 | uint32_t ats_count); | ||
439 | 418 | ||
440 | 419 | ||
441 | /** | 420 | /** |
@@ -477,13 +456,11 @@ GNUNET_ATS_address_del_session (struct GNUNET_ATS_AddressRecord *ar, | |||
477 | * suggest to switch addresses. | 456 | * suggest to switch addresses. |
478 | * | 457 | * |
479 | * @param ar address record to update information for | 458 | * @param ar address record to update information for |
480 | * @param ats performance data for the address | 459 | * @param prop performance data for the address |
481 | * @param ats_count number of performance records in @a ats | ||
482 | */ | 460 | */ |
483 | void | 461 | void |
484 | GNUNET_ATS_address_update (struct GNUNET_ATS_AddressRecord *ar, | 462 | GNUNET_ATS_address_update (struct GNUNET_ATS_AddressRecord *ar, |
485 | const struct GNUNET_ATS_Information *ats, | 463 | const struct GNUNET_ATS_Properties *prop); |
486 | uint32_t ats_count); | ||
487 | 464 | ||
488 | 465 | ||
489 | /** | 466 | /** |
@@ -515,8 +492,7 @@ struct GNUNET_ATS_PerformanceHandle; | |||
515 | * #GNUNET_SYSERR if this address is no longer available for ATS | 492 | * #GNUNET_SYSERR if this address is no longer available for ATS |
516 | * @param bandwidth_out assigned outbound bandwidth for the connection | 493 | * @param bandwidth_out assigned outbound bandwidth for the connection |
517 | * @param bandwidth_in assigned inbound bandwidth for the connection | 494 | * @param bandwidth_in assigned inbound bandwidth for the connection |
518 | * @param ats performance data for the address (as far as known) | 495 | * @param prop performance data for the address |
519 | * @param ats_count number of performance records in @a ats | ||
520 | */ | 496 | */ |
521 | typedef void | 497 | typedef void |
522 | (*GNUNET_ATS_AddressInformationCallback) (void *cls, | 498 | (*GNUNET_ATS_AddressInformationCallback) (void *cls, |
@@ -524,8 +500,7 @@ typedef void | |||
524 | int address_active, | 500 | int address_active, |
525 | struct GNUNET_BANDWIDTH_Value32NBO bandwidth_out, | 501 | struct GNUNET_BANDWIDTH_Value32NBO bandwidth_out, |
526 | struct GNUNET_BANDWIDTH_Value32NBO bandwidth_in, | 502 | struct GNUNET_BANDWIDTH_Value32NBO bandwidth_in, |
527 | const struct GNUNET_ATS_Information *ats, | 503 | const struct GNUNET_ATS_Properties *prop); |
528 | uint32_t ats_count); | ||
529 | 504 | ||
530 | 505 | ||
531 | /** | 506 | /** |
@@ -650,7 +625,7 @@ GNUNET_ATS_reserve_bandwidth_cancel (struct GNUNET_ATS_ReservationContext *rc); | |||
650 | /** | 625 | /** |
651 | * ATS preference types as string array initializer | 626 | * ATS preference types as string array initializer |
652 | */ | 627 | */ |
653 | #define GNUNET_ATS_PreferenceTypeString {"END", "BANDWIDTH", "LATENCY"} | 628 | #define GNUNET_ATS_PreferenceTypeString {"BANDWIDTH", "LATENCY", "END" } |
654 | 629 | ||
655 | /** | 630 | /** |
656 | * Enum defining all known preference categories. | 631 | * Enum defining all known preference categories. |
@@ -659,17 +634,12 @@ enum GNUNET_ATS_PreferenceKind | |||
659 | { | 634 | { |
660 | 635 | ||
661 | /** | 636 | /** |
662 | * End of preference list. | ||
663 | */ | ||
664 | GNUNET_ATS_PREFERENCE_END = 0, | ||
665 | |||
666 | /** | ||
667 | * Change the peer's bandwidth value (value per byte of bandwidth in | 637 | * Change the peer's bandwidth value (value per byte of bandwidth in |
668 | * the goal function) to the given amount. The argument is followed | 638 | * the goal function) to the given amount. The argument is followed |
669 | * by a double value giving the desired value (can be negative). | 639 | * by a double value giving the desired value (can be negative). |
670 | * Preference changes are forgotten if peers disconnect. | 640 | * Preference changes are forgotten if peers disconnect. |
671 | */ | 641 | */ |
672 | GNUNET_ATS_PREFERENCE_BANDWIDTH = 1, | 642 | GNUNET_ATS_PREFERENCE_BANDWIDTH = 0, |
673 | 643 | ||
674 | /** | 644 | /** |
675 | * Change the peer's latency value to the given amount. The | 645 | * Change the peer's latency value to the given amount. The |
@@ -678,13 +648,12 @@ enum GNUNET_ATS_PreferenceKind | |||
678 | * the inverse of the latency in microseconds (minimum: 1 | 648 | * the inverse of the latency in microseconds (minimum: 1 |
679 | * microsecond) multiplied by the latency preferences. | 649 | * microsecond) multiplied by the latency preferences. |
680 | */ | 650 | */ |
681 | GNUNET_ATS_PREFERENCE_LATENCY = 2 | 651 | GNUNET_ATS_PREFERENCE_LATENCY = 1, |
682 | |||
683 | /** | ||
684 | * Number of preference types supported by ATS | ||
685 | */ | ||
686 | #define GNUNET_ATS_PreferenceCount 3 | ||
687 | 652 | ||
653 | /** | ||
654 | * End of preference list. | ||
655 | */ | ||
656 | GNUNET_ATS_PREFERENCE_END = 2 | ||
688 | 657 | ||
689 | }; | 658 | }; |
690 | 659 | ||
@@ -703,9 +672,9 @@ GNUNET_ATS_print_preference_type (enum GNUNET_ATS_PreferenceKind type); | |||
703 | * Change preferences for the given peer. Preference changes are forgotten if peers | 672 | * Change preferences for the given peer. Preference changes are forgotten if peers |
704 | * disconnect. | 673 | * disconnect. |
705 | * | 674 | * |
706 | * @param ph performance handle | 675 | * @param ph performance handle @param peer identifies the peer |
707 | * @param peer identifies the peer | 676 | * @param ... #GNUNET_ATS_PREFERENCE_END-terminated specification of the |
708 | * @param ... 0-terminated specification of the desired changes | 677 | * desired changes |
709 | */ | 678 | */ |
710 | void | 679 | void |
711 | GNUNET_ATS_performance_change_preference (struct GNUNET_ATS_PerformanceHandle *ph, | 680 | GNUNET_ATS_performance_change_preference (struct GNUNET_ATS_PerformanceHandle *ph, |
@@ -728,7 +697,7 @@ GNUNET_ATS_performance_change_preference (struct GNUNET_ATS_PerformanceHandle *p | |||
728 | * @param ph performance handle | 697 | * @param ph performance handle |
729 | * @param scope the time interval this valid for: [now - scope .. now] | 698 | * @param scope the time interval this valid for: [now - scope .. now] |
730 | * @param peer identifies the peer | 699 | * @param peer identifies the peer |
731 | * @param ... 0-terminated specification of the desired changes | 700 | * @param ... #GNUNET_ATS_PREFERENCE_END-terminated specification of the desired changes |
732 | */ | 701 | */ |
733 | void | 702 | void |
734 | GNUNET_ATS_performance_give_feedback (struct GNUNET_ATS_PerformanceHandle *ph, | 703 | GNUNET_ATS_performance_give_feedback (struct GNUNET_ATS_PerformanceHandle *ph, |