src/include/gnunet_connection_lib.h

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