diff options
author | Christian Grothoff <christian@grothoff.org> | 2011-08-12 10:54:28 +0000 |
---|---|---|
committer | Christian Grothoff <christian@grothoff.org> | 2011-08-12 10:54:28 +0000 |
commit | 3d016df6e9f16a224637ae1f525acdcbbce9fbed (patch) | |
tree | c198a1c8a918412d018f446d98ee553a3a1dac68 /src/include/gnunet_ats_service.h | |
parent | 180f2e637029d045e3c72dc3e13fddb1f9f30141 (diff) | |
download | gnunet-3d016df6e9f16a224637ae1f525acdcbbce9fbed.tar.gz gnunet-3d016df6e9f16a224637ae1f525acdcbbce9fbed.zip |
initial ATS service refactoring
Diffstat (limited to 'src/include/gnunet_ats_service.h')
-rw-r--r-- | src/include/gnunet_ats_service.h | 230 |
1 files changed, 230 insertions, 0 deletions
diff --git a/src/include/gnunet_ats_service.h b/src/include/gnunet_ats_service.h new file mode 100644 index 000000000..da54b24be --- /dev/null +++ b/src/include/gnunet_ats_service.h | |||
@@ -0,0 +1,230 @@ | |||
1 | /* | ||
2 | This file is part of GNUnet. | ||
3 | (C) 2010,2011 Christian Grothoff (and other contributing authors) | ||
4 | |||
5 | GNUnet is free software; you can redistribute it and/or modify | ||
6 | it under the terms of the GNU General Public License as published | ||
7 | by the Free Software Foundation; either version 3, or (at your | ||
8 | 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 | General Public License for more details. | ||
14 | |||
15 | You should have received a copy of the GNU General Public License | ||
16 | along with GNUnet; see the file COPYING. If not, write to the | ||
17 | Free Software Foundation, Inc., 59 Temple Place - Suite 330, | ||
18 | Boston, MA 02111-1307, USA. | ||
19 | */ | ||
20 | /** | ||
21 | * @file include/gnunet_ats_service.h | ||
22 | * @brief automatic transport selection and outbound bandwidth determination | ||
23 | * @author Christian Grothoff | ||
24 | * @author Matthias Wachs | ||
25 | * | ||
26 | * TODO: | ||
27 | * - move GNUNET_TRANSPORT_ATS* in here and rename... | ||
28 | * - extend API to express communication preferences to ATS | ||
29 | * (to be called DIRECTLY from apps, not from transport/core!) | ||
30 | */ | ||
31 | #ifndef GNUNET_ATS_SERVICE_H | ||
32 | #define GNUNET_ATS_SERVICE_H | ||
33 | |||
34 | #include "gnunet_constants.h" | ||
35 | #include "gnunet_util_lib.h" | ||
36 | #include "gnunet_transport_service.h" | ||
37 | #include "gnunet_transport_plugin.h" | ||
38 | |||
39 | |||
40 | /** | ||
41 | * Handle to the ATS subsystem. | ||
42 | */ | ||
43 | struct GNUNET_ATS_Handle; | ||
44 | |||
45 | |||
46 | /** | ||
47 | * Signature of a function called by ATS to notify the callee that the | ||
48 | * assigned bandwidth or address for a given peer was changed. If the | ||
49 | * callback is called with address/bandwidth assignments of zero, the | ||
50 | * ATS disconnect function will still be called once the disconnect | ||
51 | * actually happened. | ||
52 | * | ||
53 | * @param cls closure | ||
54 | * @param peer identity of the peer | ||
55 | * @param plugin_name name of the transport plugin, NULL to disconnect | ||
56 | * @param session session to use (if available) | ||
57 | * @param plugin_addr address to use (if available) | ||
58 | * @param plugin_addr_len number of bytes in addr | ||
59 | * @param bandwidth assigned outbound bandwidth for the connection | ||
60 | */ | ||
61 | typedef void (*GNUNET_TRANSPORT_ATS_AllocationNotification)(void *cls, | ||
62 | const struct GNUNET_PeerIdentity *peer, | ||
63 | const char *plugin_name, | ||
64 | struct Session *session, | ||
65 | const void *plugin_addr, | ||
66 | size_t plugin_addr_len, | ||
67 | struct GNUNET_BANDWIDTH_Value32NBO bandwidth); | ||
68 | |||
69 | |||
70 | /** | ||
71 | * Initialize the ATS subsystem. | ||
72 | * | ||
73 | * @param cfg configuration to use | ||
74 | * @param alloc_cb notification to call whenever the allocation changed | ||
75 | * @param alloc_cb_cls closure for 'alloc_cb' | ||
76 | * @return ats context | ||
77 | */ | ||
78 | struct GNUNET_ATS_Handle * | ||
79 | GNUNET_ATS_init (const struct GNUNET_CONFIGURATION_Handle *cfg, | ||
80 | GNUNET_TRANSPORT_ATS_AllocationNotification alloc_cb, | ||
81 | void *alloc_cb_cls); | ||
82 | |||
83 | |||
84 | /** | ||
85 | * Shutdown the ATS subsystem. | ||
86 | * | ||
87 | * @param atc handle | ||
88 | */ | ||
89 | void | ||
90 | GNUNET_ATS_shutdown (struct GNUNET_ATS_Handle *atc); | ||
91 | |||
92 | |||
93 | /** | ||
94 | * Signature of a function that takes an address suggestion | ||
95 | * | ||
96 | * @param cls closure | ||
97 | * @param public_key public key of the peer | ||
98 | * @param peer identity of the new peer | ||
99 | * @param plugin_name name of the plugin, NULL if we have no suggestion | ||
100 | * @param plugin_addr suggested address, NULL if we have no suggestion | ||
101 | * @param plugin_addr_len number of bytes in plugin_addr | ||
102 | * @param ats performance data for the address (as far as known) | ||
103 | * @param ats_count number of performance records in 'ats' | ||
104 | */ | ||
105 | typedef void (*GNUNET_ATS_AddressSuggestionCallback)(void *cls, | ||
106 | const struct GNUNET_CRYPTO_RsaPublicKeyBinaryEncoded *public_key, | ||
107 | const struct GNUNET_PeerIdentity *peer, | ||
108 | const char *plugin_name, | ||
109 | const void *plugin_addr, | ||
110 | size_t plugin_addr_len, | ||
111 | const struct GNUNET_TRANSPORT_ATS_Information *ats, | ||
112 | uint32_t ats_count); | ||
113 | |||
114 | |||
115 | /** | ||
116 | * Handle to cancel suggestion request. | ||
117 | */ | ||
118 | struct GNUNET_ATS_SuggestionContext; | ||
119 | |||
120 | |||
121 | /** | ||
122 | * We would like to establish a new connection with a peer. | ||
123 | * ATS should suggest a good address to begin with. | ||
124 | * | ||
125 | * @param atc handle | ||
126 | * @param peer identity of the new peer | ||
127 | * @param cb function to call with the address | ||
128 | * @param cb_cls closure for cb | ||
129 | */ | ||
130 | struct GNUNET_ATS_SuggestionContext * | ||
131 | GNUNET_ATS_suggest_address (struct GNUNET_ATS_Handle *atc, | ||
132 | const struct GNUNET_PeerIdentity *peer, | ||
133 | GNUNET_ATS_AddressSuggestionCallback cb, | ||
134 | void *cb_cls); | ||
135 | |||
136 | |||
137 | /** | ||
138 | * Cancel suggestion request. | ||
139 | * | ||
140 | * @param asc handle of the request to cancel | ||
141 | */ | ||
142 | void | ||
143 | GNUNET_ATS_suggest_address_cancel (struct GNUNET_ATS_SuggestionContext *asc); | ||
144 | |||
145 | |||
146 | /** | ||
147 | * We established a new connection with a peer (for example, because | ||
148 | * core asked for it or because the other peer connected to us). | ||
149 | * Calculate bandwidth assignments including the new peer. | ||
150 | * | ||
151 | * @param atc handle | ||
152 | * @param public_key public key of the peer | ||
153 | * @param peer identity of the new peer | ||
154 | * @param plugin_name name of the currently used transport plugin | ||
155 | * @param session session in use (if available) | ||
156 | * @param plugin_addr address in use (if available) | ||
157 | * @param plugin_addr_len number of bytes in plugin_addr | ||
158 | * @param ats performance data for the connection | ||
159 | * @param ats_count number of performance records in 'ats' | ||
160 | */ | ||
161 | void | ||
162 | GNUNET_ATS_peer_connect (struct GNUNET_ATS_Handle *atc, | ||
163 | const struct GNUNET_CRYPTO_RsaPublicKeyBinaryEncoded *public_key, | ||
164 | const struct GNUNET_PeerIdentity *peer, | ||
165 | const char *plugin_name, | ||
166 | struct Session *session, | ||
167 | const void *plugin_addr, | ||
168 | size_t plugin_addr_len, | ||
169 | const struct GNUNET_TRANSPORT_ATS_Information *ats, | ||
170 | uint32_t ats_count); | ||
171 | |||
172 | |||
173 | /** | ||
174 | * We disconnected from the given peer (for example, because ats, core | ||
175 | * or blacklist asked for it or because the other peer disconnected). | ||
176 | * Calculate bandwidth assignments without the peer. | ||
177 | * | ||
178 | * @param atc handle | ||
179 | * @param peer identity of the peer | ||
180 | */ | ||
181 | void | ||
182 | GNUNET_ATS_peer_disconnect (struct GNUNET_ATS_Handle *atc, | ||
183 | const struct GNUNET_PeerIdentity *peer); | ||
184 | |||
185 | |||
186 | /** | ||
187 | * A session got destroyed, stop including it as a valid address. | ||
188 | * | ||
189 | * @param atc handle | ||
190 | * @param peer identity of the peer | ||
191 | * @param session session handle that is no longer valid | ||
192 | */ | ||
193 | void | ||
194 | GNUNET_ATS_session_destroyed (struct GNUNET_ATS_Handle *atc, | ||
195 | const struct GNUNET_PeerIdentity *peer, | ||
196 | const struct Session *session); | ||
197 | |||
198 | |||
199 | /** | ||
200 | * We have updated performance statistics for a given address. Note | ||
201 | * that this function can be called for addresses that are currently | ||
202 | * in use as well as addresses that are valid but not actively in use. | ||
203 | * Furthermore, the peer may not even be connected to us right now (in | ||
204 | * which case the call may be ignored or the information may be stored | ||
205 | * for later use). Update bandwidth assignments. | ||
206 | * | ||
207 | * @param atc handle | ||
208 | * @param public_key public key of the peer | ||
209 | * @param peer identity of the new peer | ||
210 | * @param plugin_name name of the transport plugin | ||
211 | * @param session session handle (if available) | ||
212 | * @param plugin_addr address (if available) | ||
213 | * @param plugin_addr_len number of bytes in plugin_addr | ||
214 | * @param ats performance data for the address | ||
215 | * @param ats_count number of performance records in 'ats' | ||
216 | */ | ||
217 | void | ||
218 | GNUNET_ATS_address_update (struct GNUNET_ATS_Handle *atc, | ||
219 | const struct GNUNET_CRYPTO_RsaPublicKeyBinaryEncoded *public_key, | ||
220 | const struct GNUNET_PeerIdentity *peer, | ||
221 | const char *plugin_name, | ||
222 | struct Session *session, | ||
223 | const void *plugin_addr, | ||
224 | size_t plugin_addr_len, | ||
225 | const struct GNUNET_TRANSPORT_ATS_Information *ats, | ||
226 | uint32_t ats_count); | ||
227 | |||
228 | |||
229 | #endif | ||
230 | /* end of file gnunet-service-transport_ats.h */ | ||