aboutsummaryrefslogtreecommitdiff
path: root/src/include/gnunet_ats_service.h
diff options
context:
space:
mode:
Diffstat (limited to 'src/include/gnunet_ats_service.h')
-rw-r--r--src/include/gnunet_ats_service.h205
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 */
112enum GNUNET_ATS_Property 105struct 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 149struct 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
188GNUNET_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 */
208struct 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};
220GNUNET_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 */
232const char * 200void
233GNUNET_ATS_print_property_type (enum GNUNET_ATS_Property type); 201GNUNET_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 */
211void
212GNUNET_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 */
368typedef void 349typedef 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 *
434GNUNET_ATS_address_add (struct GNUNET_ATS_SchedulingHandle *sh, 414GNUNET_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 */
483void 461void
484GNUNET_ATS_address_update (struct GNUNET_ATS_AddressRecord *ar, 462GNUNET_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 */
521typedef void 497typedef 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 */
710void 679void
711GNUNET_ATS_performance_change_preference (struct GNUNET_ATS_PerformanceHandle *ph, 680GNUNET_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 */
733void 702void
734GNUNET_ATS_performance_give_feedback (struct GNUNET_ATS_PerformanceHandle *ph, 703GNUNET_ATS_performance_give_feedback (struct GNUNET_ATS_PerformanceHandle *ph,