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