src/include/gnunet_network_lib.h

   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 */