src/include/gnunet_connection_lib.h

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