src/include/gnunet_connection_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_connection_lib.h
  23  * @brief basic, low-level TCP networking interface
  24  * @author Christian Grothoff
  25  */
  26 #ifndef GNUNET_CONNECTION_LIB_H
  27 #define GNUNET_CONNECTION_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_network_lib.h"
  38 #include "gnunet_scheduler_lib.h"
  39 #include "gnunet_time_lib.h"
  40
  41 /**
  42  * Timeout we use on TCP connect before trying another
  43  * result from the DNS resolver.  Actual value used
  44  * is this value divided by the number of address families.
  45  * Default is 5s.
  46  */
  47 #define GNUNET_CONNECTION_CONNECT_RETRY_TIMEOUT GNUNET_TIME_relative_multiply (GNUNET_TIME_UNIT_SECONDS, 5)
  48
  49 /**
  50  * @brief handle for a network connection
  51  */
  52 struct GNUNET_CONNECTION_Handle;
  53
  54
  55 /**
  56  * Function to call for access control checks.
  57  *
  58  * @param cls closure
  59  * @param addr address
  60  * @param addrlen length of address
  61  * @return GNUNET_YES to allow, GNUNET_NO to deny, GNUNET_SYSERR
  62  *   for unknown address family (will be denied).
  63  */
  64 typedef int (*GNUNET_CONNECTION_AccessCheck) (void *cls,
  65                                            const struct sockaddr * addr,
  66                                            socklen_t addrlen);
  67
  68
  69 /**
  70  * Callback function for data received from the network.  Note that
  71  * both "available" and "err" would be 0 if the read simply timed out.
  72  *
  73  * @param cls closure
  74  * @param buf pointer to received data
  75  * @param available number of bytes availabe in "buf",
  76  *        possibly 0 (on errors)
  77  * @param addr address of the sender
  78  * @param addrlen size of addr
  79  * @param errCode value of errno (on errors receiving)
  80  */
  81 typedef void (*GNUNET_CONNECTION_Receiver) (void *cls,
  82                                          const void *buf,
  83                                          size_t available,
  84                                          const struct sockaddr * addr,
  85                                          socklen_t addrlen, int errCode);
  86
  87 /**
  88  * Set the persist option on this connection handle.  Indicates
  89  * that the underlying socket or fd should never really be closed.
  90  * Used for indicating process death.
  91  *
  92  * @param sock the connection to set persistent
  93  */
  94 void
  95 GNUNET_CONNECTION_persist_(struct GNUNET_CONNECTION_Handle *sock);
  96
  97 /**
  98  * Create a socket handle by boxing an existing OS socket.  The OS
  99  * socket should henceforth be no longer used directly.
 100  * GNUNET_socket_destroy will close it.
 101  *
 102  * @param sched scheduler to use
 103  * @param osSocket existing socket to box
 104  * @param maxbuf maximum write buffer size for the socket (use
 105  *        0 for sockets that need no write buffers, such as listen sockets)
 106  * @return the boxed socket handle
 107  */
 108 struct GNUNET_CONNECTION_Handle
 109   *GNUNET_CONNECTION_create_from_existing (struct
 110                                                    GNUNET_SCHEDULER_Handle
 111                                                    *sched,
 112                                                    struct
 113                                                    GNUNET_NETWORK_Handle
 114                                                    *osSocket, size_t maxbuf);
 115
 116
 117 /**
 118  * Create a socket handle by accepting on a listen socket.  This
 119  * function may block if the listen socket has no connection ready.
 120  *
 121  * @param sched scheduler to use
 122  * @param access function to use to check if access is allowed
 123  * @param access_cls closure for access
 124  * @param lsock listen socket
 125  * @param maxbuf maximum write buffer size for the socket (use
 126  *        0 for sockets that need no write buffers, such as listen sockets)
 127  * @return the socket handle, NULL on error (for example, access refused)
 128  */
 129 struct GNUNET_CONNECTION_Handle
 130   *GNUNET_CONNECTION_create_from_accept (struct
 131                                                  GNUNET_SCHEDULER_Handle
 132                                                  *sched,
 133                                                  GNUNET_CONNECTION_AccessCheck
 134                                                  access, void *access_cls,
 135                                                  struct
 136                                                  GNUNET_NETWORK_Handle
 137                                                  *lsock, size_t maxbuf);
 138
 139
 140 /**
 141  * Create a socket handle by (asynchronously) connecting to a host.
 142  * This function returns immediately, even if the connection has not
 143  * yet been established.  This function only creates TCP connections.
 144  *
 145  * @param sched scheduler to use
 146  * @param cfg configuration to use
 147  * @param hostname name of the host to connect to
 148  * @param port port to connect to
 149  * @param maxbuf maximum write buffer size for the socket (use
 150  *        0 for sockets that need no write buffers, such as listen sockets)
 151  * @return the socket handle
 152  */
 153 struct GNUNET_CONNECTION_Handle
 154   *GNUNET_CONNECTION_create_from_connect (struct GNUNET_SCHEDULER_Handle *sched,
 155                                           const struct GNUNET_CONFIGURATION_Handle *cfg,
 156                                           const char *hostname,
 157                                           uint16_t port,
 158                                           size_t maxbuf);
 159
 160
 161 /**
 162  * Create a socket handle by connecting to a UNIX domain service.
 163  * This function returns immediately, even if the connection has not
 164  * yet been established.  This function only creates UNIX connections.
 165  *
 166  * @param sched scheduler to use
 167  * @param cfg configuration to use
 168  * @param unixpath path to connect to
 169  * @param maxbuf maximum write buffer size for the socket (use
 170  *        0 for sockets that need no write buffers, such as listen sockets)
 171  * @return the socket handle, NULL on systems without UNIX support
 172  */
 173 struct GNUNET_CONNECTION_Handle *
 174 GNUNET_CONNECTION_create_from_connect_to_unixpath (struct GNUNET_SCHEDULER_Handle *sched,
 175                                                    const struct
 176                                                    GNUNET_CONFIGURATION_Handle *cfg,
 177                                                    const char *unixpath,
 178                                                    size_t maxbuf);
 179
 180
 181
 182
 183 /**
 184  * Create a socket handle by (asynchronously) connecting to a host.
 185  * This function returns immediately, even if the connection has not
 186  * yet been established.  This function only creates TCP connections.
 187  *
 188  * @param sched scheduler to use
 189  * @param af_family address family to use
 190  * @param serv_addr server address
 191  * @param addrlen length of server address
 192  * @param maxbuf maximum write buffer size for the socket (use
 193  *        0 for sockets that need no write buffers, such as listen sockets)
 194  * @return the socket handle
 195  */
 196 struct GNUNET_CONNECTION_Handle
 197   *GNUNET_CONNECTION_create_from_sockaddr (struct
 198                                                    GNUNET_SCHEDULER_Handle
 199                                                    *sched, int af_family,
 200                                                    const struct sockaddr
 201                                                    *serv_addr,
 202                                                    socklen_t addrlen,
 203                                                    size_t maxbuf);
 204
 205 /**
 206  * Check if socket is valid (no fatal errors have happened so far).
 207  * Note that a socket that is still trying to connect is considered
 208  * valid.
 209  *
 210  * @param sock socket to check
 211  * @return GNUNET_YES if valid, GNUNET_NO otherwise
 212  */
 213 int GNUNET_CONNECTION_check (struct GNUNET_CONNECTION_Handle
 214                                      *sock);
 215
 216
 217 /**
 218  * Obtain the network address of the other party.
 219  *
 220  * @param sock the client to get the address for
 221  * @param addr where to store the address
 222  * @param addrlen where to store the length of the address
 223  * @return GNUNET_OK on success
 224  */
 225 int GNUNET_CONNECTION_get_address (struct
 226                                            GNUNET_CONNECTION_Handle
 227                                            *sock, void **addr,
 228                                            size_t * addrlen);
 229
 230
 231 /**
 232  * Close the socket and free associated resources. Pending
 233  * transmissions may be completed or dropped depending on the
 234  * arguments.   If a receive call is pending and should
 235  * NOT be completed, 'GNUNET_CONNECTION_receive_cancel'
 236  * should be called explicitly first.
 237  *
 238  * @param sock socket to destroy
 239  * @param finish_pending_write should pending writes be completed or aborted?
 240  *        (this applies to transmissions where the data has already been
 241  *        read from the application; all other transmissions should be
 242  *        aborted using 'GNUNET_CONNECTION_notify_transmit_ready_cancel').
 243  */
 244 void
 245 GNUNET_CONNECTION_destroy (struct GNUNET_CONNECTION_Handle *sock,
 246                            int finish_pending_write);
 247
 248
 249 /**
 250  * Receive data from the given socket.  Note that this function will
 251  * call "receiver" asynchronously using the scheduler.  It will
 252  * "immediately" return.  Note that there MUST only be one active
 253  * receive call per socket at any given point in time (so do not
 254  * call receive again until the receiver callback has been invoked).
 255  *
 256  * @param sock socket handle
 257  * @param max maximum number of bytes to read
 258  * @param timeout maximum amount of time to wait
 259  * @param receiver function to call with received data
 260  * @param receiver_cls closure for receiver
 261  */
 262 void
 263 GNUNET_CONNECTION_receive (struct GNUNET_CONNECTION_Handle
 264                                    *sock, size_t max,
 265                                    struct GNUNET_TIME_Relative timeout,
 266                                    GNUNET_CONNECTION_Receiver receiver,
 267                                    void *receiver_cls);
 268
 269
 270 /**
 271  * Cancel receive job on the given socket.  Note that the
 272  * receiver callback must not have been called yet in order
 273  * for the cancellation to be valid.
 274  *
 275  * @param sock socket handle
 276  * @return closure of the original receiver callback closure
 277  */
 278 void *GNUNET_CONNECTION_receive_cancel (struct
 279                                         GNUNET_CONNECTION_Handle
 280                                         *sock);
 281
 282
 283 /**
 284  * Function called to notify a client about the socket
 285  * begin ready to queue more data.  "buf" will be
 286  * NULL and "size" zero if the socket was closed for
 287  * writing in the meantime.
 288  *
 289  * @param cls closure
 290  * @param size number of bytes available in buf
 291  * @param buf where the callee should write the message
 292  * @return number of bytes written to buf
 293  */
 294 typedef size_t (*GNUNET_CONNECTION_TransmitReadyNotify) (void *cls,
 295                                                          size_t size, void *buf);
 296
 297
 298 /**
 299  * Opaque handle that can be used to cancel
 300  * a transmit-ready notification.
 301  */
 302 struct GNUNET_CONNECTION_TransmitHandle;
 303
 304 /**
 305  * Ask the socket to call us once the specified number of bytes
 306  * are free in the transmission buffer.  May call the notify
 307  * method immediately if enough space is available.  Note that
 308  * this function will abort if "size" is greater than
 309  * "maxbuf" (as specified when the socket handle was created).
 310  *
 311  * Note that "notify" will be called either when enough
 312  * buffer space is available OR when the socket is destroyed.
 313  * The size parameter given to notify is guaranteed to be
 314  * larger or equal to size if the buffer is ready, or zero
 315  * if the socket was destroyed (or at least closed for
 316  * writing).  Finally, any time before 'notify' is called, a
 317  * client may call "notify_transmit_ready_cancel" to cancel
 318  * the transmission request.
 319  *
 320  * Only one transmission request can be scheduled at the same
 321  * time.  Notify will be run with the same scheduler priority
 322  * as that of the caller.
 323  *
 324  * @param sock socket
 325  * @param size number of bytes to send
 326  * @param timeout after how long should we give up (and call
 327  *        notify with buf NULL and size 0)?
 328  * @param notify function to call when buffer space is available
 329  * @param notify_cls closure for notify
 330  * @return non-NULL if the notify callback was queued,
 331  *         NULL if we are already going to notify someone else (busy)
 332  */
 333 struct GNUNET_CONNECTION_TransmitHandle
 334   *GNUNET_CONNECTION_notify_transmit_ready (struct
 335                                                     GNUNET_CONNECTION_Handle
 336                                                     *sock, size_t size,
 337                                                     struct
 338                                                     GNUNET_TIME_Relative
 339                                                     timeout,
 340                                                     GNUNET_CONNECTION_TransmitReadyNotify
 341                                                     notify, void *notify_cls);
 342
 343
 344 /**
 345  * Cancel the specified transmission-ready
 346  * notification.
 347  *
 348  * @param h handle for notification to cancel
 349  */
 350 void
 351 GNUNET_CONNECTION_notify_transmit_ready_cancel (struct
 352                                                         GNUNET_CONNECTION_TransmitHandle
 353                                                         *h);
 354
 355
 356 /**
 357  * Configure this connection to ignore shutdown signals.
 358  *
 359  * @param sock socket handle
 360  * @param do_ignore GNUNET_YES to ignore, GNUNET_NO to restore default
 361  */
 362 void
 363 GNUNET_CONNECTION_ignore_shutdown (struct GNUNET_CONNECTION_Handle *sock,
 364                                    int do_ignore);
 365
 366
 367 #if 0                           /* keep Emacsens' auto-indent happy */
 368 {
 369 #endif
 370 #ifdef __cplusplus
 371 }
 372 #endif
 373
 374
 375 /* ifndef GNUNET_CONNECTION_LIB_H */
 376 #endif
 377 /* end of gnunet_connection_lib.h */