diff options
Diffstat (limited to 'src/include/gnunet_connection_lib.h')
-rw-r--r-- | src/include/gnunet_connection_lib.h | 400 |
1 files changed, 0 insertions, 400 deletions
diff --git a/src/include/gnunet_connection_lib.h b/src/include/gnunet_connection_lib.h deleted file mode 100644 index e9dd95d1b..000000000 --- a/src/include/gnunet_connection_lib.h +++ /dev/null | |||
@@ -1,400 +0,0 @@ | |||
1 | /* | ||
2 | This file is part of GNUnet. | ||
3 | Copyright (C) 2009 GNUnet e.V. | ||
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., 51 Franklin Street, Fifth Floor, | ||
18 | Boston, MA 02110-1301, USA. | ||
19 | */ | ||
20 | |||
21 | /** | ||
22 | * @author Christian Grothoff | ||
23 | * | ||
24 | * @file include/gnunet_connection_lib.h | ||
25 | * Basic, low-level TCP networking interface | ||
26 | * | ||
27 | * @defgroup connection Connection library | ||
28 | * Basic, low-level TCP networking interface | ||
29 | * @{ | ||
30 | */ | ||
31 | #ifndef GNUNET_CONNECTION_LIB_H | ||
32 | #define GNUNET_CONNECTION_LIB_H | ||
33 | |||
34 | #ifdef __cplusplus | ||
35 | extern "C" | ||
36 | { | ||
37 | #if 0 /* keep Emacsens' auto-indent happy */ | ||
38 | } | ||
39 | #endif | ||
40 | #endif | ||
41 | |||
42 | #include "gnunet_network_lib.h" | ||
43 | #include "gnunet_scheduler_lib.h" | ||
44 | #include "gnunet_time_lib.h" | ||
45 | |||
46 | /** | ||
47 | * Timeout we use on TCP connect before trying another | ||
48 | * result from the DNS resolver. Actual value used | ||
49 | * is this value divided by the number of address families. | ||
50 | * Default is 5s. | ||
51 | */ | ||
52 | #define GNUNET_CONNECTION_CONNECT_RETRY_TIMEOUT GNUNET_TIME_relative_multiply (GNUNET_TIME_UNIT_SECONDS, 5) | ||
53 | |||
54 | /** | ||
55 | * @brief handle for a network connection | ||
56 | */ | ||
57 | struct GNUNET_CONNECTION_Handle; | ||
58 | |||
59 | |||
60 | /** | ||
61 | * Credentials for UNIX domain sockets. | ||
62 | */ | ||
63 | struct GNUNET_CONNECTION_Credentials | ||
64 | { | ||
65 | /** | ||
66 | * UID of the other end of the connection. | ||
67 | */ | ||
68 | uid_t uid; | ||
69 | |||
70 | /** | ||
71 | * GID of the other end of the connection. | ||
72 | */ | ||
73 | gid_t gid; | ||
74 | }; | ||
75 | |||
76 | |||
77 | /** | ||
78 | * Function to call for access control checks. | ||
79 | * | ||
80 | * @param cls closure | ||
81 | * @param ucred credentials, if available, otherwise NULL | ||
82 | * @param addr address | ||
83 | * @param addrlen length of address | ||
84 | * @return GNUNET_YES to allow, GNUNET_NO to deny, GNUNET_SYSERR | ||
85 | * for unknown address family (will be denied). | ||
86 | */ | ||
87 | typedef int (*GNUNET_CONNECTION_AccessCheck) (void *cls, | ||
88 | const struct | ||
89 | GNUNET_CONNECTION_Credentials * | ||
90 | ucred, | ||
91 | const struct sockaddr * addr, | ||
92 | socklen_t addrlen); | ||
93 | |||
94 | |||
95 | /** | ||
96 | * Callback function for data received from the network. Note that | ||
97 | * both "available" and "err" would be 0 if the read simply timed out. | ||
98 | * | ||
99 | * @param cls closure | ||
100 | * @param buf pointer to received data | ||
101 | * @param available number of bytes availabe in "buf", | ||
102 | * possibly 0 (on errors) | ||
103 | * @param addr address of the sender | ||
104 | * @param addrlen size of addr | ||
105 | * @param errCode value of errno (on errors receiving) | ||
106 | */ | ||
107 | typedef void (*GNUNET_CONNECTION_Receiver) (void *cls, const void *buf, | ||
108 | size_t available, | ||
109 | const struct sockaddr * addr, | ||
110 | socklen_t addrlen, int errCode); | ||
111 | |||
112 | /** | ||
113 | * Set the persist option on this connection handle. Indicates | ||
114 | * that the underlying socket or fd should never really be closed. | ||
115 | * Used for indicating process death. | ||
116 | * | ||
117 | * @param connection the connection to set persistent | ||
118 | */ | ||
119 | void | ||
120 | GNUNET_CONNECTION_persist_ (struct GNUNET_CONNECTION_Handle *connection); | ||
121 | |||
122 | /** | ||
123 | * Disable the "CORK" feature for communication with the given socket, | ||
124 | * forcing the OS to immediately flush the buffer on transmission | ||
125 | * instead of potentially buffering multiple messages. Essentially | ||
126 | * reduces the OS send buffers to zero. | ||
127 | * Used to make sure that the last messages sent through the connection | ||
128 | * reach the other side before the process is terminated. | ||
129 | * | ||
130 | * @param connection the connection to make flushing and blocking | ||
131 | * @return #GNUNET_OK on success | ||
132 | */ | ||
133 | int | ||
134 | GNUNET_CONNECTION_disable_corking (struct GNUNET_CONNECTION_Handle *connection); | ||
135 | |||
136 | |||
137 | /** | ||
138 | * Create a connection handle by (asynchronously) connecting to a host. | ||
139 | * This function returns immediately, even if the connection has not | ||
140 | * yet been established. This function only creates TCP connections. | ||
141 | * | ||
142 | * @param s socket to connect | ||
143 | * @param serv_addr server address | ||
144 | * @param addrlen length of server address | ||
145 | * @return the connection handle | ||
146 | */ | ||
147 | struct GNUNET_CONNECTION_Handle * | ||
148 | GNUNET_CONNECTION_connect_socket (struct GNUNET_NETWORK_Handle *s, | ||
149 | const struct sockaddr *serv_addr, | ||
150 | socklen_t addrlen); | ||
151 | |||
152 | |||
153 | /** | ||
154 | * Create a connection handle by boxing an existing OS socket. The OS | ||
155 | * socket should henceforth be no longer used directly. | ||
156 | * #GNUNET_CONNECTION_destroy() will close it. | ||
157 | * | ||
158 | * @param osSocket existing socket to box | ||
159 | * @return the boxed socket handle | ||
160 | */ | ||
161 | struct GNUNET_CONNECTION_Handle * | ||
162 | GNUNET_CONNECTION_create_from_existing (struct GNUNET_NETWORK_Handle *osSocket); | ||
163 | |||
164 | |||
165 | /** | ||
166 | * Create a connection handle by accepting on a listen socket. This | ||
167 | * function may block if the listen socket has no connection ready. | ||
168 | * | ||
169 | * @param access_cb function to use to check if access is allowed | ||
170 | * @param access_cb_cls closure for @a access_cb | ||
171 | * @param lsock listen socket | ||
172 | * @return the connection handle, NULL on error (for example, access refused) | ||
173 | */ | ||
174 | struct GNUNET_CONNECTION_Handle * | ||
175 | GNUNET_CONNECTION_create_from_accept (GNUNET_CONNECTION_AccessCheck access_cb, | ||
176 | void *access_cb_cls, | ||
177 | struct GNUNET_NETWORK_Handle *lsock); | ||
178 | |||
179 | |||
180 | /** | ||
181 | * Create a connection handle by (asynchronously) connecting to a host. | ||
182 | * This function returns immediately, even if the connection has not | ||
183 | * yet been established. This function only creates TCP connections. | ||
184 | * | ||
185 | * @param cfg configuration to use | ||
186 | * @param hostname name of the host to connect to | ||
187 | * @param port port to connect to | ||
188 | * @return the connection handle | ||
189 | */ | ||
190 | struct GNUNET_CONNECTION_Handle * | ||
191 | GNUNET_CONNECTION_create_from_connect (const struct GNUNET_CONFIGURATION_Handle | ||
192 | *cfg, const char *hostname, | ||
193 | uint16_t port); | ||
194 | |||
195 | |||
196 | /** | ||
197 | * Create a connection handle by connecting to a UNIX domain service. | ||
198 | * This function returns immediately, even if the connection has not | ||
199 | * yet been established. This function only creates UNIX connections. | ||
200 | * | ||
201 | * @param cfg configuration to use | ||
202 | * @param unixpath path to connect to) | ||
203 | * @return the connection handle, NULL on systems without UNIX support | ||
204 | */ | ||
205 | struct GNUNET_CONNECTION_Handle * | ||
206 | GNUNET_CONNECTION_create_from_connect_to_unixpath (const struct | ||
207 | GNUNET_CONFIGURATION_Handle | ||
208 | *cfg, const char *unixpath); | ||
209 | |||
210 | |||
211 | |||
212 | |||
213 | /** | ||
214 | * Create a connection handle by (asynchronously) connecting to a host. | ||
215 | * This function returns immediately, even if the connection has not | ||
216 | * yet been established. This function only creates TCP connections. | ||
217 | * | ||
218 | * @param af_family address family to use | ||
219 | * @param serv_addr server address | ||
220 | * @param addrlen length of server address | ||
221 | * @return the connection handle | ||
222 | */ | ||
223 | struct GNUNET_CONNECTION_Handle * | ||
224 | GNUNET_CONNECTION_create_from_sockaddr (int af_family, | ||
225 | const struct sockaddr *serv_addr, | ||
226 | socklen_t addrlen); | ||
227 | |||
228 | /** | ||
229 | * Check if connection is valid (no fatal errors have happened so far). | ||
230 | * Note that a connection that is still trying to connect is considered | ||
231 | * valid. | ||
232 | * | ||
233 | * @param connection handle to check | ||
234 | * @return GNUNET_YES if valid, GNUNET_NO otherwise | ||
235 | */ | ||
236 | int | ||
237 | GNUNET_CONNECTION_check (struct GNUNET_CONNECTION_Handle *connection); | ||
238 | |||
239 | |||
240 | /** | ||
241 | * Obtain the network address of the other party. | ||
242 | * | ||
243 | * @param connection the client to get the address for | ||
244 | * @param addr where to store the address | ||
245 | * @param addrlen where to store the length of the address | ||
246 | * @return GNUNET_OK on success | ||
247 | */ | ||
248 | int | ||
249 | GNUNET_CONNECTION_get_address (struct GNUNET_CONNECTION_Handle *connection, | ||
250 | void **addr, size_t * addrlen); | ||
251 | |||
252 | |||
253 | /** | ||
254 | * Close the connection and free associated resources. There must | ||
255 | * not be any pending requests for reading or writing to the | ||
256 | * connection at this time. | ||
257 | * | ||
258 | * @param connection connection to destroy | ||
259 | */ | ||
260 | void | ||
261 | GNUNET_CONNECTION_destroy (struct GNUNET_CONNECTION_Handle *connection); | ||
262 | |||
263 | |||
264 | /** | ||
265 | * Receive data from the given connection. Note that this function will | ||
266 | * call "receiver" asynchronously using the scheduler. It will | ||
267 | * "immediately" return. Note that there MUST only be one active | ||
268 | * receive call per connection at any given point in time (so do not | ||
269 | * call receive again until the receiver callback has been invoked). | ||
270 | * | ||
271 | * @param connection connection handle | ||
272 | * @param max maximum number of bytes to read | ||
273 | * @param timeout maximum amount of time to wait | ||
274 | * @param receiver function to call with received data | ||
275 | * @param receiver_cls closure for receiver | ||
276 | */ | ||
277 | void | ||
278 | GNUNET_CONNECTION_receive (struct GNUNET_CONNECTION_Handle *connection, size_t max, | ||
279 | struct GNUNET_TIME_Relative timeout, | ||
280 | GNUNET_CONNECTION_Receiver receiver, | ||
281 | void *receiver_cls); | ||
282 | |||
283 | |||
284 | /** | ||
285 | * Cancel receive job on the given connection. Note that the | ||
286 | * receiver callback must not have been called yet in order | ||
287 | * for the cancellation to be valid. | ||
288 | * | ||
289 | * @param connection connection handle | ||
290 | * @return closure of the original receiver callback closure | ||
291 | */ | ||
292 | void * | ||
293 | GNUNET_CONNECTION_receive_cancel (struct GNUNET_CONNECTION_Handle *connection); | ||
294 | |||
295 | |||
296 | /** | ||
297 | * Function called to notify a client about the connection begin ready | ||
298 | * to queue more data. @a buf will be NULL and @a size zero if the | ||
299 | * connection was closed for writing in the meantime. | ||
300 | * | ||
301 | * @param cls closure | ||
302 | * @param size number of bytes available in @a buf | ||
303 | * @param buf where the callee should write the message | ||
304 | * @return number of bytes written to @a buf | ||
305 | */ | ||
306 | typedef size_t | ||
307 | (*GNUNET_CONNECTION_TransmitReadyNotify) (void *cls, | ||
308 | size_t size, | ||
309 | void *buf); | ||
310 | |||
311 | |||
312 | /** | ||
313 | * Opaque handle that can be used to cancel | ||
314 | * a transmit-ready notification. | ||
315 | */ | ||
316 | struct GNUNET_CONNECTION_TransmitHandle; | ||
317 | |||
318 | /** | ||
319 | * Ask the connection to call us once the specified number of bytes | ||
320 | * are free in the transmission buffer. Will never call the @a notify | ||
321 | * callback in this task, but always first go into the scheduler. Note that | ||
322 | * this function will abort if "size" is greater than | ||
323 | * #GNUNET_SERVER_MAX_MESSAGE_SIZE. | ||
324 | * | ||
325 | * Note that "notify" will be called either when enough | ||
326 | * buffer space is available OR when the connection is destroyed. | ||
327 | * The size parameter given to notify is guaranteed to be | ||
328 | * larger or equal to size if the buffer is ready, or zero | ||
329 | * if the connection was destroyed (or at least closed for | ||
330 | * writing). Finally, any time before 'notify' is called, a | ||
331 | * client may call "notify_transmit_ready_cancel" to cancel | ||
332 | * the transmission request. | ||
333 | * | ||
334 | * Only one transmission request can be scheduled at the same | ||
335 | * time. Notify will be run with the same scheduler priority | ||
336 | * as that of the caller. | ||
337 | * | ||
338 | * @param connection connection | ||
339 | * @param size number of bytes to send | ||
340 | * @param timeout after how long should we give up (and call | ||
341 | * notify with buf NULL and size 0)? | ||
342 | * @param notify function to call when buffer space is available | ||
343 | * @param notify_cls closure for notify | ||
344 | * @return non-NULL if the notify callback was queued, | ||
345 | * NULL if we are already going to notify someone else (busy) | ||
346 | */ | ||
347 | struct GNUNET_CONNECTION_TransmitHandle * | ||
348 | GNUNET_CONNECTION_notify_transmit_ready (struct GNUNET_CONNECTION_Handle *connection, | ||
349 | size_t size, | ||
350 | struct GNUNET_TIME_Relative timeout, | ||
351 | GNUNET_CONNECTION_TransmitReadyNotify | ||
352 | notify, void *notify_cls); | ||
353 | |||
354 | |||
355 | /** | ||
356 | * Cancel the specified transmission-ready | ||
357 | * notification. | ||
358 | * | ||
359 | * @param th handle for notification to cancel | ||
360 | */ | ||
361 | void | ||
362 | GNUNET_CONNECTION_notify_transmit_ready_cancel (struct | ||
363 | GNUNET_CONNECTION_TransmitHandle | ||
364 | *th); | ||
365 | |||
366 | |||
367 | /** | ||
368 | * Create a connection to be proxied using a given connection. | ||
369 | * | ||
370 | * @param cph connection to proxy server | ||
371 | * @return connection to be proxied | ||
372 | */ | ||
373 | struct GNUNET_CONNECTION_Handle * | ||
374 | GNUNET_CONNECTION_create_proxied_from_handshake (struct GNUNET_CONNECTION_Handle *cph); | ||
375 | |||
376 | |||
377 | /** | ||
378 | * Activate proxied connection and destroy initial proxy handshake connection. | ||
379 | * There must not be any pending requests for reading or writing to the | ||
380 | * proxy hadshake connection at this time. | ||
381 | * | ||
382 | * @param proxied connection connection to proxy server | ||
383 | */ | ||
384 | void | ||
385 | GNUNET_CONNECTION_acivate_proxied (struct GNUNET_CONNECTION_Handle *proxied); | ||
386 | |||
387 | |||
388 | #if 0 /* keep Emacsens' auto-indent happy */ | ||
389 | { | ||
390 | #endif | ||
391 | #ifdef __cplusplus | ||
392 | } | ||
393 | #endif | ||
394 | |||
395 | /* ifndef GNUNET_CONNECTION_LIB_H */ | ||
396 | #endif | ||
397 | |||
398 | /** @} */ /* end of group */ | ||
399 | |||
400 | /* end of gnunet_connection_lib.h */ | ||