diff options
Diffstat (limited to 'src/include/gnunet_network_lib.h')
-rw-r--r-- | src/include/gnunet_network_lib.h | 308 |
1 files changed, 308 insertions, 0 deletions
diff --git a/src/include/gnunet_network_lib.h b/src/include/gnunet_network_lib.h new file mode 100644 index 000000000..8731eacec --- /dev/null +++ b/src/include/gnunet_network_lib.h | |||
@@ -0,0 +1,308 @@ | |||
1 | /* | ||
2 | This file is part of GNUnet. | ||
3 | (C) 2009 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 2, 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 | /** | ||
22 | * @file include/gnunet_network_lib.h | ||
23 | * @brief basic, low-level TCP networking interface | ||
24 | * @author Christian Grothoff | ||
25 | */ | ||
26 | #ifndef GNUNET_NETWORK_LIB_H | ||
27 | #define GNUNET_NETWORK_LIB_H | ||
28 | |||
29 | #ifdef __cplusplus | ||
30 | extern "C" | ||
31 | { | ||
32 | #if 0 /* keep Emacsens' auto-indent happy */ | ||
33 | } | ||
34 | #endif | ||
35 | #endif | ||
36 | |||
37 | #include "gnunet_scheduler_lib.h" | ||
38 | #include "gnunet_time_lib.h" | ||
39 | |||
40 | /** | ||
41 | * Timeout we use on TCP connect before trying another | ||
42 | * result from the DNS resolver. 5s. | ||
43 | */ | ||
44 | #define GNUNET_NETWORK_CONNECT_RETRY_TIMEOUT GNUNET_TIME_relative_multiply (GNUNET_TIME_UNIT_SECONDS, 5) | ||
45 | |||
46 | /** | ||
47 | * @brief handle for a network socket | ||
48 | */ | ||
49 | struct GNUNET_NETWORK_SocketHandle; | ||
50 | |||
51 | |||
52 | /** | ||
53 | * Function to call for access control checks. | ||
54 | * | ||
55 | * @param cls closure | ||
56 | * @param addr address | ||
57 | * @param addrlen length of address | ||
58 | * @return GNUNET_YES to allow, GNUNET_NO to deny, GNUNET_SYSERR | ||
59 | * for unknown address family (will be denied). | ||
60 | */ | ||
61 | typedef int (*GNUNET_NETWORK_AccessCheck) (void *cls, | ||
62 | const struct sockaddr * addr, | ||
63 | socklen_t addrlen); | ||
64 | |||
65 | |||
66 | /** | ||
67 | * Callback function for data received from the network. Note that | ||
68 | * both "available" and "err" would be 0 if the read simply timed out. | ||
69 | * | ||
70 | * @param cls closure | ||
71 | * @param buf pointer to received data | ||
72 | * @param available number of bytes availabe in "buf", | ||
73 | * possibly 0 (on errors) | ||
74 | * @param addr address of the sender | ||
75 | * @param addrlen size of addr | ||
76 | * @param errCode value of errno (on errors receiving) | ||
77 | */ | ||
78 | typedef void (*GNUNET_NETWORK_Receiver) (void *cls, | ||
79 | const void *buf, | ||
80 | size_t available, | ||
81 | const struct sockaddr * addr, | ||
82 | socklen_t addrlen, int errCode); | ||
83 | |||
84 | |||
85 | /** | ||
86 | * Create a socket handle by boxing an existing OS socket. The OS | ||
87 | * socket should henceforth be no longer used directly. | ||
88 | * GNUNET_socket_destroy will close it. | ||
89 | * | ||
90 | * @param sched scheduler to use | ||
91 | * @param osSocket existing socket to box | ||
92 | * @param maxbuf maximum write buffer size for the socket (use | ||
93 | * 0 for sockets that need no write buffers, such as listen sockets) | ||
94 | * @return the boxed socket handle | ||
95 | */ | ||
96 | struct GNUNET_NETWORK_SocketHandle | ||
97 | *GNUNET_NETWORK_socket_create_from_existing (struct GNUNET_SCHEDULER_Handle | ||
98 | *sched, int osSocket, | ||
99 | size_t maxbuf); | ||
100 | |||
101 | |||
102 | /** | ||
103 | * Create a socket handle by accepting on a listen socket. This | ||
104 | * function may block if the listen socket has no connection ready. | ||
105 | * | ||
106 | * @param sched scheduler to use | ||
107 | * @param access function to use to check if access is allowed | ||
108 | * @param access_cls closure for access | ||
109 | * @param lsock listen socket | ||
110 | * @param maxbuf maximum write buffer size for the socket (use | ||
111 | * 0 for sockets that need no write buffers, such as listen sockets) | ||
112 | * @return the socket handle, NULL on error (for example, access refused) | ||
113 | */ | ||
114 | struct GNUNET_NETWORK_SocketHandle | ||
115 | *GNUNET_NETWORK_socket_create_from_accept (struct GNUNET_SCHEDULER_Handle | ||
116 | *sched, | ||
117 | GNUNET_NETWORK_AccessCheck | ||
118 | access, void *access_cls, | ||
119 | int lsock, size_t maxbuf); | ||
120 | |||
121 | |||
122 | /** | ||
123 | * Create a socket handle by (asynchronously) connecting to a host. | ||
124 | * This function returns immediately, even if the connection has not | ||
125 | * yet been established. This function only creates TCP connections. | ||
126 | * | ||
127 | * @param sched scheduler to use | ||
128 | * @param hostname name of the host to connect to | ||
129 | * @param port port to connect to | ||
130 | * @param maxbuf maximum write buffer size for the socket (use | ||
131 | * 0 for sockets that need no write buffers, such as listen sockets) | ||
132 | * @return the socket handle | ||
133 | */ | ||
134 | struct GNUNET_NETWORK_SocketHandle | ||
135 | *GNUNET_NETWORK_socket_create_from_connect (struct GNUNET_SCHEDULER_Handle | ||
136 | *sched, const char *hostname, | ||
137 | uint16_t port, size_t maxbuf); | ||
138 | |||
139 | |||
140 | |||
141 | /** | ||
142 | * Create a socket handle by (asynchronously) connecting to a host. | ||
143 | * This function returns immediately, even if the connection has not | ||
144 | * yet been established. This function only creates TCP connections. | ||
145 | * | ||
146 | * @param sched scheduler to use | ||
147 | * @param af_family address family to use | ||
148 | * @param serv_addr server address | ||
149 | * @param addrlen length of server address | ||
150 | * @param maxbuf maximum write buffer size for the socket (use | ||
151 | * 0 for sockets that need no write buffers, such as listen sockets) | ||
152 | * @return the socket handle | ||
153 | */ | ||
154 | struct GNUNET_NETWORK_SocketHandle | ||
155 | *GNUNET_NETWORK_socket_create_from_sockaddr (struct GNUNET_SCHEDULER_Handle | ||
156 | *sched, int af_family, | ||
157 | const struct sockaddr | ||
158 | *serv_addr, socklen_t addrlen, | ||
159 | size_t maxbuf); | ||
160 | |||
161 | /** | ||
162 | * Check if socket is valid (no fatal errors have happened so far). | ||
163 | * Note that a socket that is still trying to connect is considered | ||
164 | * valid. | ||
165 | * | ||
166 | * @param sock socket to check | ||
167 | * @return GNUNET_YES if valid, GNUNET_NO otherwise | ||
168 | */ | ||
169 | int GNUNET_NETWORK_socket_check (struct GNUNET_NETWORK_SocketHandle *sock); | ||
170 | |||
171 | |||
172 | /** | ||
173 | * Obtain the network address of the other party. | ||
174 | * | ||
175 | * @param sock the client to get the address for | ||
176 | * @param addr where to store the address | ||
177 | * @param addrlen where to store the length of the address | ||
178 | * @return GNUNET_OK on success | ||
179 | */ | ||
180 | int GNUNET_NETWORK_socket_get_address (struct GNUNET_NETWORK_SocketHandle | ||
181 | *sock, void **addr, size_t * addrlen); | ||
182 | |||
183 | /** | ||
184 | * Close the socket and free associated resources. Pending | ||
185 | * transmissions are simply dropped. A pending receive call will be | ||
186 | * called with an error code of "EPIPE". | ||
187 | * | ||
188 | * @param sock socket to destroy | ||
189 | */ | ||
190 | void GNUNET_NETWORK_socket_destroy (struct GNUNET_NETWORK_SocketHandle *sock); | ||
191 | |||
192 | |||
193 | /** | ||
194 | * Receive data from the given socket. Note that this function will | ||
195 | * call "receiver" asynchronously using the scheduler. It will | ||
196 | * "immediately" return. Note that there MUST only be one active | ||
197 | * receive call per socket at any given point in time (so do not | ||
198 | * call receive again until the receiver callback has been invoked). | ||
199 | * | ||
200 | * @param sock socket handle | ||
201 | * @param max maximum number of bytes to read | ||
202 | * @param timeout maximum amount of time to wait | ||
203 | * @param receiver function to call with received data | ||
204 | * @param receiver_cls closure for receiver | ||
205 | * @return scheduler task ID used for receiving, GNUNET_SCHEDULER_NO_PREREQUISITE_TASK on error | ||
206 | */ | ||
207 | GNUNET_SCHEDULER_TaskIdentifier | ||
208 | GNUNET_NETWORK_receive (struct GNUNET_NETWORK_SocketHandle *sock, | ||
209 | size_t max, | ||
210 | struct GNUNET_TIME_Relative timeout, | ||
211 | GNUNET_NETWORK_Receiver receiver, void *receiver_cls); | ||
212 | |||
213 | |||
214 | /** | ||
215 | * Cancel receive job on the given socket. Note that the | ||
216 | * receiver callback must not have been called yet in order | ||
217 | * for the cancellation to be valid. | ||
218 | * | ||
219 | * @param sock socket handle | ||
220 | * @param task task identifier returned from the receive call | ||
221 | * @return closure of the original receiver callback | ||
222 | */ | ||
223 | void *GNUNET_NETWORK_receive_cancel (struct GNUNET_NETWORK_SocketHandle *sock, | ||
224 | GNUNET_SCHEDULER_TaskIdentifier task); | ||
225 | |||
226 | |||
227 | /** | ||
228 | * Function called to notify a client about the socket | ||
229 | * begin ready to queue more data. "buf" will be | ||
230 | * NULL and "size" zero if the socket was closed for | ||
231 | * writing in the meantime. | ||
232 | * | ||
233 | * @param cls closure | ||
234 | * @param size number of bytes available in buf | ||
235 | * @param buf where the callee should write the message | ||
236 | * @return number of bytes written to buf | ||
237 | */ | ||
238 | typedef size_t (*GNUNET_NETWORK_TransmitReadyNotify) (void *cls, | ||
239 | size_t size, void *buf); | ||
240 | |||
241 | |||
242 | /** | ||
243 | * Opaque handle that can be used to cancel | ||
244 | * a transmit-ready notification. | ||
245 | */ | ||
246 | struct GNUNET_NETWORK_TransmitHandle; | ||
247 | |||
248 | /** | ||
249 | * Ask the socket to call us once the specified number of bytes | ||
250 | * are free in the transmission buffer. May call the notify | ||
251 | * method immediately if enough space is available. Note that | ||
252 | * this function will abort if "size" is greater than | ||
253 | * "maxbuf" (as specified when the socket handle was created). | ||
254 | * | ||
255 | * Note that "notify" will be called either when enough | ||
256 | * buffer space is available OR when the socket is destroyed. | ||
257 | * The size parameter given to notify is guaranteed to be | ||
258 | * larger or equal to size if the buffer is ready, or zero | ||
259 | * if the socket was destroyed (or at least closed for | ||
260 | * writing). Finally, any time before 'notify' is called, a | ||
261 | * client may call "notify_transmit_ready_cancel" to cancel | ||
262 | * the transmission request. | ||
263 | * | ||
264 | * Only one transmission request can be scheduled at the same | ||
265 | * time. Notify will be run with the same scheduler priority | ||
266 | * as that of the caller. | ||
267 | * | ||
268 | * @param sock socket | ||
269 | * @param size number of bytes to send | ||
270 | * @param timeout after how long should we give up (and call | ||
271 | * notify with buf NULL and size 0)? | ||
272 | * @param notify function to call when buffer space is available | ||
273 | * @param notify_cls closure for notify | ||
274 | * @return non-NULL if the notify callback was queued, | ||
275 | * NULL if we are already going to notify someone else (busy) | ||
276 | */ | ||
277 | struct GNUNET_NETWORK_TransmitHandle | ||
278 | *GNUNET_NETWORK_notify_transmit_ready (struct GNUNET_NETWORK_SocketHandle | ||
279 | *sock, size_t size, | ||
280 | struct GNUNET_TIME_Relative timeout, | ||
281 | GNUNET_NETWORK_TransmitReadyNotify | ||
282 | notify, void *notify_cls); | ||
283 | |||
284 | |||
285 | /** | ||
286 | * Cancel the specified transmission-ready | ||
287 | * notification. | ||
288 | * | ||
289 | * @param h handle for notification to cancel | ||
290 | */ | ||
291 | void | ||
292 | GNUNET_NETWORK_notify_transmit_ready_cancel (struct | ||
293 | GNUNET_NETWORK_TransmitHandle | ||
294 | *h); | ||
295 | |||
296 | |||
297 | |||
298 | #if 0 /* keep Emacsens' auto-indent happy */ | ||
299 | { | ||
300 | #endif | ||
301 | #ifdef __cplusplus | ||
302 | } | ||
303 | #endif | ||
304 | |||
305 | |||
306 | /* ifndef GNUNET_NETWORK_LIB_H */ | ||
307 | #endif | ||
308 | /* end of gnunet_network_lib.h */ | ||