src/include/gnunet_connection_lib.h

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (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 3, 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., 51 Franklin Street, Fifth Floor,
  18      Boston, MA 02110-1301, 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 connection the connection to set persistent
 113  */
 114 void
 115 GNUNET_CONNECTION_persist_ (struct GNUNET_CONNECTION_Handle *connection);
 116
 117 /**
 118  * Disable the "CORK" feature for communication with the given socket,
 119  * forcing the OS to immediately flush the buffer on transmission
 120  * instead of potentially buffering multiple messages.  Essentially
 121  * reduces the OS send buffers to zero.
 122  * Used to make sure that the last messages sent through the connection
 123  * reach the other side before the process is terminated.
 124  *
 125  * @param connection the connection to make flushing and blocking
 126  * @return #GNUNET_OK on success
 127  */
 128 int
 129 GNUNET_CONNECTION_disable_corking (struct GNUNET_CONNECTION_Handle *connection);
 130
 131
 132 /**
 133  * Create a connection handle by (asynchronously) connecting to a host.
 134  * This function returns immediately, even if the connection has not
 135  * yet been established.  This function only creates TCP connections.
 136  *
 137  * @param s socket to connect
 138  * @param serv_addr server address
 139  * @param addrlen length of server address
 140  * @return the connection handle
 141  */
 142 struct GNUNET_CONNECTION_Handle *
 143 GNUNET_CONNECTION_connect_socket (struct GNUNET_NETWORK_Handle *s,
 144                                   const struct sockaddr *serv_addr,
 145                                   socklen_t addrlen);
 146
 147
 148 /**
 149  * Create a connection handle by boxing an existing OS socket.  The OS
 150  * socket should henceforth be no longer used directly.
 151  * #GNUNET_CONNECTION_destroy() will close it.
 152  *
 153  * @param osSocket existing socket to box
 154  * @return the boxed socket handle
 155  */
 156 struct GNUNET_CONNECTION_Handle *
 157 GNUNET_CONNECTION_create_from_existing (struct GNUNET_NETWORK_Handle *osSocket);
 158
 159
 160 /**
 161  * Create a connection handle by accepting on a listen socket.  This
 162  * function may block if the listen socket has no connection ready.
 163  *
 164  * @param access_cb function to use to check if access is allowed
 165  * @param access_cb_cls closure for @a access_cb
 166  * @param lsock listen socket
 167  * @return the connection handle, NULL on error (for example, access refused)
 168  */
 169 struct GNUNET_CONNECTION_Handle *
 170 GNUNET_CONNECTION_create_from_accept (GNUNET_CONNECTION_AccessCheck access_cb,
 171                                       void *access_cb_cls,
 172                                       struct GNUNET_NETWORK_Handle *lsock);
 173
 174
 175 /**
 176  * Create a connection handle by (asynchronously) connecting to a host.
 177  * This function returns immediately, even if the connection has not
 178  * yet been established.  This function only creates TCP connections.
 179  *
 180  * @param cfg configuration to use
 181  * @param hostname name of the host to connect to
 182  * @param port port to connect to
 183  * @return the connection handle
 184  */
 185 struct GNUNET_CONNECTION_Handle *
 186 GNUNET_CONNECTION_create_from_connect (const struct GNUNET_CONFIGURATION_Handle
 187                                        *cfg, const char *hostname,
 188                                        uint16_t port);
 189
 190
 191 /**
 192  * Create a connection handle by connecting to a UNIX domain service.
 193  * This function returns immediately, even if the connection has not
 194  * yet been established.  This function only creates UNIX connections.
 195  *
 196  * @param cfg configuration to use
 197  * @param unixpath path to connect to)
 198  * @return the connection handle, NULL on systems without UNIX support
 199  */
 200 struct GNUNET_CONNECTION_Handle *
 201 GNUNET_CONNECTION_create_from_connect_to_unixpath (const struct
 202                                                    GNUNET_CONFIGURATION_Handle
 203                                                    *cfg, const char *unixpath);
 204
 205
 206
 207
 208 /**
 209  * Create a connection handle by (asynchronously) connecting to a host.
 210  * This function returns immediately, even if the connection has not
 211  * yet been established.  This function only creates TCP connections.
 212  *
 213  * @param af_family address family to use
 214  * @param serv_addr server address
 215  * @param addrlen length of server address
 216  * @return the connection handle
 217  */
 218 struct GNUNET_CONNECTION_Handle *
 219 GNUNET_CONNECTION_create_from_sockaddr (int af_family,
 220                                         const struct sockaddr *serv_addr,
 221                                         socklen_t addrlen);
 222
 223 /**
 224  * Check if connection is valid (no fatal errors have happened so far).
 225  * Note that a connection that is still trying to connect is considered
 226  * valid.
 227  *
 228  * @param connection handle to check
 229  * @return GNUNET_YES if valid, GNUNET_NO otherwise
 230  */
 231 int
 232 GNUNET_CONNECTION_check (struct GNUNET_CONNECTION_Handle *connection);
 233
 234
 235 /**
 236  * Obtain the network address of the other party.
 237  *
 238  * @param connection the client to get the address for
 239  * @param addr where to store the address
 240  * @param addrlen where to store the length of the address
 241  * @return GNUNET_OK on success
 242  */
 243 int
 244 GNUNET_CONNECTION_get_address (struct GNUNET_CONNECTION_Handle *connection,
 245                                void **addr, size_t * addrlen);
 246
 247
 248 /**
 249  * Close the connection and free associated resources.  There must
 250  * not be any pending requests for reading or writing to the
 251  * connection at this time.
 252  *
 253  * @param connection connection to destroy
 254  */
 255 void
 256 GNUNET_CONNECTION_destroy (struct GNUNET_CONNECTION_Handle *connection);
 257
 258
 259 /**
 260  * Receive data from the given connection.  Note that this function will
 261  * call "receiver" asynchronously using the scheduler.  It will
 262  * "immediately" return.  Note that there MUST only be one active
 263  * receive call per connection at any given point in time (so do not
 264  * call receive again until the receiver callback has been invoked).
 265  *
 266  * @param connection connection handle
 267  * @param max maximum number of bytes to read
 268  * @param timeout maximum amount of time to wait
 269  * @param receiver function to call with received data
 270  * @param receiver_cls closure for receiver
 271  */
 272 void
 273 GNUNET_CONNECTION_receive (struct GNUNET_CONNECTION_Handle *connection, size_t max,
 274                            struct GNUNET_TIME_Relative timeout,
 275                            GNUNET_CONNECTION_Receiver receiver,
 276                            void *receiver_cls);
 277
 278
 279 /**
 280  * Cancel receive job on the given connection.  Note that the
 281  * receiver callback must not have been called yet in order
 282  * for the cancellation to be valid.
 283  *
 284  * @param connection connection handle
 285  * @return closure of the original receiver callback closure
 286  */
 287 void *
 288 GNUNET_CONNECTION_receive_cancel (struct GNUNET_CONNECTION_Handle *connection);
 289
 290
 291 /**
 292  * Function called to notify a client about the connection begin ready
 293  * to queue more data.  @a buf will be NULL and @a size zero if the
 294  * connection was closed for writing in the meantime.
 295  *
 296  * @param cls closure
 297  * @param size number of bytes available in @a buf
 298  * @param buf where the callee should write the message
 299  * @return number of bytes written to @a buf
 300  */
 301 typedef size_t
 302 (*GNUNET_CONNECTION_TransmitReadyNotify) (void *cls,
 303                                           size_t size,
 304                                           void *buf);
 305
 306
 307 /**
 308  * Opaque handle that can be used to cancel
 309  * a transmit-ready notification.
 310  */
 311 struct GNUNET_CONNECTION_TransmitHandle;
 312
 313 /**
 314  * Ask the connection to call us once the specified number of bytes
 315  * are free in the transmission buffer.  Will never call the @a notify
 316  * callback in this task, but always first go into the scheduler.  Note that
 317  * this function will abort if "size" is greater than
 318  * #GNUNET_SERVER_MAX_MESSAGE_SIZE.
 319  *
 320  * Note that "notify" will be called either when enough
 321  * buffer space is available OR when the connection is destroyed.
 322  * The size parameter given to notify is guaranteed to be
 323  * larger or equal to size if the buffer is ready, or zero
 324  * if the connection was destroyed (or at least closed for
 325  * writing).  Finally, any time before 'notify' is called, a
 326  * client may call "notify_transmit_ready_cancel" to cancel
 327  * the transmission request.
 328  *
 329  * Only one transmission request can be scheduled at the same
 330  * time.  Notify will be run with the same scheduler priority
 331  * as that of the caller.
 332  *
 333  * @param connection connection
 334  * @param size number of bytes to send
 335  * @param timeout after how long should we give up (and call
 336  *        notify with buf NULL and size 0)?
 337  * @param notify function to call when buffer space is available
 338  * @param notify_cls closure for notify
 339  * @return non-NULL if the notify callback was queued,
 340  *         NULL if we are already going to notify someone else (busy)
 341  */
 342 struct GNUNET_CONNECTION_TransmitHandle *
 343 GNUNET_CONNECTION_notify_transmit_ready (struct GNUNET_CONNECTION_Handle *connection,
 344                                          size_t size,
 345                                          struct GNUNET_TIME_Relative timeout,
 346                                          GNUNET_CONNECTION_TransmitReadyNotify
 347                                          notify, void *notify_cls);
 348
 349
 350 /**
 351  * Cancel the specified transmission-ready
 352  * notification.
 353  *
 354  * @param th handle for notification to cancel
 355  */
 356 void
 357 GNUNET_CONNECTION_notify_transmit_ready_cancel (struct
 358                                                 GNUNET_CONNECTION_TransmitHandle
 359                                                 *th);
 360
 361
 362 /**
 363  * Create a connection to be proxied using a given connection.
 364  *
 365  * @param cph connection to proxy server
 366  * @return connection to be proxied
 367  */
 368 struct GNUNET_CONNECTION_Handle *
 369 GNUNET_CONNECTION_create_proxied_from_handshake (struct GNUNET_CONNECTION_Handle *cph);
 370
 371
 372 /**
 373  * Activate proxied connection and destroy initial proxy handshake connection.
 374  * There must not be any pending requests for reading or writing to the
 375  * proxy hadshake connection at this time.
 376  *
 377  * @param proxied connection connection to proxy server
 378  */
 379 void
 380 GNUNET_CONNECTION_acivate_proxied (struct GNUNET_CONNECTION_Handle *proxied);
 381
 382
 383 #if 0                           /* keep Emacsens' auto-indent happy */
 384 {
 385 #endif
 386 #ifdef __cplusplus
 387 }
 388 #endif
 389
 390
 391 /* ifndef GNUNET_CONNECTION_LIB_H */
 392 #endif
 393 /* end of gnunet_connection_lib.h */