diff options
author | Nils Durner <durner@gnunet.org> | 2009-08-23 22:11:49 +0000 |
---|---|---|
committer | Nils Durner <durner@gnunet.org> | 2009-08-23 22:11:49 +0000 |
commit | 2518cfc0a86865ebe4d0550e0013ed52a494231b (patch) | |
tree | e9a130b782597e18bcff24a9fdab6e5c6aae1f9c /src/include/gnunet_network_lib.h | |
parent | 2ae973618f3b51fa9bbf5532eaa1352cafc24ecc (diff) | |
download | gnunet-2518cfc0a86865ebe4d0550e0013ed52a494231b.tar.gz gnunet-2518cfc0a86865ebe4d0550e0013ed52a494231b.zip |
low level network API
Diffstat (limited to 'src/include/gnunet_network_lib.h')
-rw-r--r-- | src/include/gnunet_network_lib.h | 293 |
1 files changed, 64 insertions, 229 deletions
diff --git a/src/include/gnunet_network_lib.h b/src/include/gnunet_network_lib.h index 68ca346e5..baba3aba8 100644 --- a/src/include/gnunet_network_lib.h +++ b/src/include/gnunet_network_lib.h | |||
@@ -20,11 +20,12 @@ | |||
20 | 20 | ||
21 | /** | 21 | /** |
22 | * @file include/gnunet_network_lib.h | 22 | * @file include/gnunet_network_lib.h |
23 | * @brief basic, low-level TCP networking interface | 23 | * @brief basic low-level networking interface |
24 | * @author Christian Grothoff | 24 | * @author Nils Durner |
25 | */ | 25 | */ |
26 | #ifndef GNUNET_NETWORK_LIB_H | 26 | |
27 | #define GNUNET_NETWORK_LIB_H | 27 | #ifndef GNUNET_NETWORK_LIB_H_ |
28 | #define GNUNET_NETWORK_LIB_H_ | ||
28 | 29 | ||
29 | #ifdef __cplusplus | 30 | #ifdef __cplusplus |
30 | extern "C" | 31 | extern "C" |
@@ -34,265 +35,102 @@ extern "C" | |||
34 | #endif | 35 | #endif |
35 | #endif | 36 | #endif |
36 | 37 | ||
37 | #include "gnunet_scheduler_lib.h" | ||
38 | #include "gnunet_time_lib.h" | 38 | #include "gnunet_time_lib.h" |
39 | 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 | 40 | ||
46 | /** | 41 | /** |
47 | * @brief handle for a network connection | 42 | * @brief handle to a socket |
48 | */ | 43 | */ |
49 | struct GNUNET_NETWORK_ConnectionHandle; | 44 | struct GNUNET_NETWORK_Descriptor; |
50 | |||
51 | 45 | ||
52 | /** | 46 | /** |
53 | * Function to call for access control checks. | 47 | * @brief collection of IO descriptors |
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 | */ | 48 | */ |
61 | typedef int (*GNUNET_NETWORK_AccessCheck) (void *cls, | 49 | struct GNUNET_NETWORK_FDSet; |
62 | const struct sockaddr * addr, | ||
63 | socklen_t addrlen); | ||
64 | 50 | ||
51 | struct GNUNET_DISK_FileHandle; | ||
65 | 52 | ||
66 | /** | 53 | struct GNUNET_NETWORK_Descriptor *GNUNET_NETWORK_socket_accept (const struct GNUNET_NETWORK_Descriptor *desc, |
67 | * Callback function for data received from the network. Note that | 54 | struct sockaddr *address, |
68 | * both "available" and "err" would be 0 if the read simply timed out. | 55 | socklen_t *address_len); |
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 | 56 | ||
57 | int GNUNET_NETWORK_socket_bind (struct GNUNET_NETWORK_Descriptor *desc, | ||
58 | const struct sockaddr *address, socklen_t address_len); | ||
84 | 59 | ||
85 | /** | 60 | int GNUNET_NETWORK_socket_close (struct GNUNET_NETWORK_Descriptor *desc); |
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_ConnectionHandle | ||
97 | *GNUNET_NETWORK_connection_create_from_existing (struct GNUNET_SCHEDULER_Handle | ||
98 | *sched, int osSocket, | ||
99 | size_t maxbuf); | ||
100 | 61 | ||
62 | int GNUNET_NETWORK_socket_connect (const struct GNUNET_NETWORK_Descriptor *desc, | ||
63 | const struct sockaddr *address, socklen_t address_len); | ||
101 | 64 | ||
102 | /** | 65 | int GNUNET_NETWORK_socket_getsockopt(const struct GNUNET_NETWORK_Descriptor *desc, int level, int optname, |
103 | * Create a socket handle by accepting on a listen socket. This | 66 | void *optval, socklen_t *optlen); |
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_ConnectionHandle | ||
115 | *GNUNET_NETWORK_connection_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 | 67 | ||
68 | int GNUNET_NETWORK_socket_listen (const struct GNUNET_NETWORK_Descriptor *desc, int backlog); | ||
121 | 69 | ||
122 | /** | 70 | ssize_t GNUNET_NETWORK_socket_read (const struct GNUNET_NETWORK_Descriptor *desc, void *buf, |
123 | * Create a socket handle by (asynchronously) connecting to a host. | 71 | size_t nbyte); |
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_ConnectionHandle | ||
135 | *GNUNET_NETWORK_connection_create_from_connect (struct GNUNET_SCHEDULER_Handle | ||
136 | *sched, const char *hostname, | ||
137 | uint16_t port, size_t maxbuf); | ||
138 | 72 | ||
73 | ssize_t GNUNET_NETWORK_socket_recv (const struct GNUNET_NETWORK_Descriptor *desc, void *buffer, | ||
74 | size_t length, int flags); | ||
139 | 75 | ||
76 | int GNUNET_NETWORK_socket_select (struct GNUNET_NETWORK_FDSet *rfds, | ||
77 | struct GNUNET_NETWORK_FDSet *wfds, struct GNUNET_NETWORK_FDSet *efds, | ||
78 | struct GNUNET_TIME_Relative timeout); | ||
140 | 79 | ||
141 | /** | 80 | /** |
142 | * Create a socket handle by (asynchronously) connecting to a host. | 81 | * Set if a socket should use blocking or non-blocking IO. |
143 | * This function returns immediately, even if the connection has not | ||
144 | * yet been established. This function only creates TCP connections. | ||
145 | * | 82 | * |
146 | * @param sched scheduler to use | 83 | * @return GNUNET_OK on success, GNUNET_SYSERR on error |
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 | */ | 84 | */ |
154 | struct GNUNET_NETWORK_ConnectionHandle | 85 | int GNUNET_NETWORK_socket_set_blocking (struct GNUNET_NETWORK_Descriptor *fd, int doBlock); |
155 | *GNUNET_NETWORK_connection_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 | 86 | ||
161 | /** | 87 | ssize_t GNUNET_NETWORK_socket_send (const struct GNUNET_NETWORK_Descriptor *desc, |
162 | * Check if socket is valid (no fatal errors have happened so far). | 88 | const void *buffer, size_t length, int flags); |
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_connection_check (struct GNUNET_NETWORK_ConnectionHandle *sock); | ||
170 | 89 | ||
90 | ssize_t GNUNET_NETWORK_socket_sendto (const struct GNUNET_NETWORK_Descriptor *desc, | ||
91 | const void *message, size_t length, int flags, | ||
92 | const struct sockaddr *dest_addr, | ||
93 | socklen_t dest_len); | ||
171 | 94 | ||
172 | /** | 95 | int GNUNET_NETWORK_socket_setsockopt(struct GNUNET_NETWORK_Descriptor *fd, int level, int option_name, |
173 | * Obtain the network address of the other party. | 96 | const void *option_value, socklen_t option_len); |
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_connection_get_address (struct GNUNET_NETWORK_ConnectionHandle | ||
181 | *sock, void **addr, size_t * addrlen); | ||
182 | 97 | ||
183 | /** | 98 | int GNUNET_NETWORK_socket_shutdown (struct GNUNET_NETWORK_Descriptor *desc, int how); |
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_connection_destroy (struct GNUNET_NETWORK_ConnectionHandle *sock); | ||
191 | 99 | ||
100 | struct GNUNET_NETWORK_Descriptor *GNUNET_NETWORK_socket_socket (int domain, int type, int protocol); | ||
192 | 101 | ||
193 | /** | 102 | ssize_t GNUNET_NETWORK_socket_write (const struct GNUNET_NETWORK_Descriptor *desc, |
194 | * Receive data from the given socket. Note that this function will | 103 | const void *buf, size_t nbyte); |
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_TASK on error | ||
206 | */ | ||
207 | GNUNET_SCHEDULER_TaskIdentifier | ||
208 | GNUNET_NETWORK_connection_receive (struct GNUNET_NETWORK_ConnectionHandle *sock, | ||
209 | size_t max, | ||
210 | struct GNUNET_TIME_Relative timeout, | ||
211 | GNUNET_NETWORK_Receiver receiver, void *receiver_cls); | ||
212 | 104 | ||
213 | 105 | ||
214 | /** | 106 | void GNUNET_NETWORK_fdset_zero(struct GNUNET_NETWORK_FDSet *fds); |
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_connection_receive_cancel (struct GNUNET_NETWORK_ConnectionHandle *sock, | ||
224 | GNUNET_SCHEDULER_TaskIdentifier task); | ||
225 | 107 | ||
108 | void GNUNET_NETWORK_fdset_set(struct GNUNET_NETWORK_FDSet *fds, | ||
109 | const struct GNUNET_NETWORK_Descriptor *desc); | ||
226 | 110 | ||
227 | /** | 111 | int GNUNET_NETWORK_fdset_isset(const struct GNUNET_NETWORK_FDSet *fds, |
228 | * Function called to notify a client about the socket | 112 | const struct GNUNET_NETWORK_Descriptor *desc); |
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 | 113 | ||
114 | void GNUNET_NETWORK_fdset_add (struct GNUNET_NETWORK_FDSet *dst, | ||
115 | const struct GNUNET_NETWORK_FDSet *src); | ||
241 | 116 | ||
242 | /** | 117 | void GNUNET_NETWORK_fdset_copy(struct GNUNET_NETWORK_FDSet *to, |
243 | * Opaque handle that can be used to cancel | 118 | const struct GNUNET_NETWORK_FDSet *from); |
244 | * a transmit-ready notification. | ||
245 | */ | ||
246 | struct GNUNET_NETWORK_TransmitHandle; | ||
247 | 119 | ||
248 | /** | 120 | void GNUNET_NETWORK_fdset_copy_native (struct GNUNET_NETWORK_FDSet *to, const fd_set *from, |
249 | * Ask the socket to call us once the specified number of bytes | 121 | int nfds); |
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_connection_notify_transmit_ready (struct GNUNET_NETWORK_ConnectionHandle | ||
279 | *sock, size_t size, | ||
280 | struct GNUNET_TIME_Relative timeout, | ||
281 | GNUNET_NETWORK_TransmitReadyNotify | ||
282 | notify, void *notify_cls); | ||
283 | 122 | ||
123 | void GNUNET_NETWORK_fdset_handle_set (struct GNUNET_NETWORK_FDSet *fds, | ||
124 | const struct GNUNET_DISK_FileHandle *h); | ||
284 | 125 | ||
285 | /** | 126 | int GNUNET_NETWORK_fdset_handle_isset (const struct GNUNET_NETWORK_FDSet *fds, |
286 | * Cancel the specified transmission-ready | 127 | const struct GNUNET_DISK_FileHandle *h); |
287 | * notification. | 128 | |
288 | * | 129 | int GNUNET_NETWORK_fdset_overlap (const struct GNUNET_NETWORK_FDSet *fds1, const struct GNUNET_NETWORK_FDSet *fds2); |
289 | * @param h handle for notification to cancel | ||
290 | */ | ||
291 | void | ||
292 | GNUNET_NETWORK_connection_notify_transmit_ready_cancel (struct | ||
293 | GNUNET_NETWORK_TransmitHandle | ||
294 | *h); | ||
295 | 130 | ||
131 | struct GNUNET_NETWORK_FDSet *GNUNET_NETWORK_fdset_create (); | ||
132 | |||
133 | void GNUNET_NETWORK_fdset_destroy (struct GNUNET_NETWORK_FDSet *fds); | ||
296 | 134 | ||
297 | 135 | ||
298 | #if 0 /* keep Emacsens' auto-indent happy */ | 136 | #if 0 /* keep Emacsens' auto-indent happy */ |
@@ -302,7 +140,4 @@ GNUNET_NETWORK_connection_notify_transmit_ready_cancel (struct | |||
302 | } | 140 | } |
303 | #endif | 141 | #endif |
304 | 142 | ||
305 | 143 | #endif /* GNUNET_NETWORK_LIB_H_ */ | |
306 | /* ifndef GNUNET_NETWORK_LIB_H */ | ||
307 | #endif | ||
308 | /* end of gnunet_network_lib.h */ | ||