src/cadet/gnunet-service-cadet_connection.h

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (C) 2013 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., 59 Temple Place - Suite 330,
  18      Boston, MA 02111-1307, USA.
  19 */
  20
  21 /**
  22  * @file cadet/gnunet-service-cadet_connection.h
  23  * @brief cadet service; dealing with connections
  24  * @author Bartlomiej Polot
  25  *
  26  * All functions in this file should use the prefix GMC (Gnunet Cadet Connection)
  27  */
  28
  29 #ifndef GNUNET_SERVICE_CADET_CONNECTION_H
  30 #define GNUNET_SERVICE_CADET_CONNECTION_H
  31
  32 #ifdef __cplusplus
  33 extern "C"
  34 {
  35 #if 0                           /* keep Emacsens' auto-indent happy */
  36 }
  37 #endif
  38 #endif
  39
  40 #include "gnunet_util_lib.h"
  41
  42
  43 /**
  44  * All the states a connection can be in.
  45  */
  46 enum CadetConnectionState
  47 {
  48   /**
  49    * Uninitialized status, should never appear in operation.
  50    */
  51   CADET_CONNECTION_NEW,
  52
  53   /**
  54    * Connection create message sent, waiting for ACK.
  55    */
  56   CADET_CONNECTION_SENT,
  57
  58   /**
  59    * Connection ACK sent, waiting for ACK.
  60    */
  61   CADET_CONNECTION_ACK,
  62
  63   /**
  64    * Connection confirmed, ready to carry traffic.
  65    */
  66   CADET_CONNECTION_READY,
  67
  68   /**
  69    * Connection to be destroyed, just waiting to empty queues.
  70    */
  71   CADET_CONNECTION_DESTROYED,
  72
  73   /**
  74    * Connection to be destroyed because of a distant peer, same as DESTROYED.
  75    */
  76   CADET_CONNECTION_BROKEN,
  77 };
  78
  79
  80 /**
  81  * Struct containing all information regarding a connection to a peer.
  82  */
  83 struct CadetConnection;
  84
  85 /**
  86  * Handle for messages queued but not yet sent.
  87  */
  88 struct CadetConnectionQueue;
  89
  90 #include "cadet_path.h"
  91 #include "gnunet-service-cadet_channel.h"
  92 #include "gnunet-service-cadet_peer.h"
  93
  94
  95
  96 /**
  97  * Callback called when a queued message is sent.
  98  *
  99  * @param cls Closure.
 100  * @param c Connection this message was on.
 101  * @param type Type of message sent.
 102  * @param fwd Was this a FWD going message?
 103  * @param size Size of the message.
 104  */
 105 typedef void (*GCC_sent) (void *cls,
 106                           struct CadetConnection *c,
 107                           struct CadetConnectionQueue *q,
 108                           uint16_t type, int fwd, size_t size);
 109
 110 /**
 111  * Core handler for connection creation.
 112  *
 113  * @param cls Closure (unused).
 114  * @param peer Sender (neighbor).
 115  * @param message Message.
 116  *
 117  * @return GNUNET_OK to keep the connection open,
 118  *         GNUNET_SYSERR to close it (signal serious error)
 119  */
 120 int
 121 GCC_handle_create (void *cls, const struct GNUNET_PeerIdentity *peer,
 122                    const struct GNUNET_MessageHeader *message);
 123
 124 /**
 125  * Core handler for path confirmations.
 126  *
 127  * @param cls closure
 128  * @param message message
 129  * @param peer peer identity this notification is about
 130  *
 131  * @return GNUNET_OK to keep the connection open,
 132  *         GNUNET_SYSERR to close it (signal serious error)
 133  */
 134 int
 135 GCC_handle_confirm (void *cls, const struct GNUNET_PeerIdentity *peer,
 136                     const struct GNUNET_MessageHeader *message);
 137
 138 /**
 139  * Core handler for notifications of broken paths
 140  *
 141  * @param cls Closure (unused).
 142  * @param id Peer identity of sending neighbor.
 143  * @param message Message.
 144  *
 145  * @return GNUNET_OK to keep the connection open,
 146  *         GNUNET_SYSERR to close it (signal serious error)
 147  */
 148 int
 149 GCC_handle_broken (void* cls,
 150                    const struct GNUNET_PeerIdentity* id,
 151                    const struct GNUNET_MessageHeader* message);
 152
 153 /**
 154  * Core handler for tunnel destruction
 155  *
 156  * @param cls Closure (unused).
 157  * @param peer Peer identity of sending neighbor.
 158  * @param message Message.
 159  *
 160  * @return GNUNET_OK to keep the connection open,
 161  *         GNUNET_SYSERR to close it (signal serious error)
 162  */
 163 int
 164 GCC_handle_destroy (void *cls, const struct GNUNET_PeerIdentity *peer,
 165                     const struct GNUNET_MessageHeader *message);
 166
 167 /**
 168  * Core handler for encrypted cadet network traffic (channel mgmt, data).
 169  *
 170  * @param cls Closure (unused).
 171  * @param message Message received.
 172  * @param peer Peer who sent the message.
 173  *
 174  * @return GNUNET_OK to keep the connection open,
 175  *         GNUNET_SYSERR to close it (signal serious error)
 176  */
 177 int
 178 GCC_handle_encrypted (void *cls, const struct GNUNET_PeerIdentity *peer,
 179                       const struct GNUNET_MessageHeader *message);
 180
 181 /**
 182  * Core handler for key exchange traffic (ephemeral key, ping, pong).
 183  *
 184  * @param cls Closure (unused).
 185  * @param message Message received.
 186  * @param peer Peer who sent the message.
 187  *
 188  * @return GNUNET_OK to keep the connection open,
 189  *         GNUNET_SYSERR to close it (signal serious error)
 190  */
 191 int
 192 GCC_handle_kx (void *cls, const struct GNUNET_PeerIdentity *peer,
 193                const struct GNUNET_MessageHeader *message);
 194
 195 /**
 196  * Core handler for cadet network traffic point-to-point acks.
 197  *
 198  * @param cls closure
 199  * @param message message
 200  * @param peer peer identity this notification is about
 201  *
 202  * @return GNUNET_OK to keep the connection open,
 203  *         GNUNET_SYSERR to close it (signal serious error)
 204  */
 205 int
 206 GCC_handle_ack (void *cls, const struct GNUNET_PeerIdentity *peer,
 207                 const struct GNUNET_MessageHeader *message);
 208
 209 /**
 210  * Core handler for cadet network traffic point-to-point ack polls.
 211  *
 212  * @param cls closure
 213  * @param message message
 214  * @param peer peer identity this notification is about
 215  *
 216  * @return GNUNET_OK to keep the connection open,
 217  *         GNUNET_SYSERR to close it (signal serious error)
 218  */
 219 int
 220 GCC_handle_poll (void *cls, const struct GNUNET_PeerIdentity *peer,
 221                  const struct GNUNET_MessageHeader *message);
 222
 223 /**
 224  * Core handler for cadet keepalives.
 225  *
 226  * @param cls closure
 227  * @param message message
 228  * @param peer peer identity this notification is about
 229  * @return GNUNET_OK to keep the connection open,
 230  *         GNUNET_SYSERR to close it (signal serious error)
 231  *
 232  * TODO: Check who we got this from, to validate route.
 233  */
 234 int
 235 GCC_handle_keepalive (void *cls, const struct GNUNET_PeerIdentity *peer,
 236                       const struct GNUNET_MessageHeader *message);
 237
 238 /**
 239  * Send an ACK on the appropriate connection/channel, depending on
 240  * the direction and the position of the peer.
 241  *
 242  * @param c Which connection to send the hop-by-hop ACK.
 243  * @param fwd Is this a fwd ACK? (will go dest->root).
 244  * @param force Send the ACK even if suboptimal (e.g. requested by POLL).
 245  */
 246 void
 247 GCC_send_ack (struct CadetConnection *c, int fwd, int force);
 248
 249 /**
 250  * Initialize the connections subsystem
 251  *
 252  * @param c Configuration handle.
 253  */
 254 void
 255 GCC_init (const struct GNUNET_CONFIGURATION_Handle *c);
 256
 257 /**
 258  * Shut down the connections subsystem.
 259  */
 260 void
 261 GCC_shutdown (void);
 262
 263 /**
 264  * Create a connection.
 265  *
 266  * @param cid Connection ID (either created locally or imposed remotely).
 267  * @param t Tunnel this connection belongs to (or NULL);
 268  * @param path Path this connection has to use (copy is made).
 269  * @param own_pos Own position in the @c path path.
 270  *
 271  * @return Newly created connection, NULL in case of error (own id not in path).
 272  */
 273 struct CadetConnection *
 274 GCC_new (const struct GNUNET_CADET_Hash *cid,
 275          struct CadetTunnel *t,
 276          struct CadetPeerPath *path,
 277          unsigned int own_pos);
 278
 279 /**
 280  * Connection is no longer needed: destroy it.
 281  *
 282  * Cancels all pending traffic (including possible DESTROY messages), all
 283  * maintenance tasks and removes the connection from neighbor peers and tunnel.
 284  *
 285  * @param c Connection to destroy.
 286  */
 287 void
 288 GCC_destroy (struct CadetConnection *c);
 289
 290 /**
 291  * Get the connection ID.
 292  *
 293  * @param c Connection to get the ID from.
 294  *
 295  * @return ID of the connection.
 296  */
 297 const struct GNUNET_CADET_Hash *
 298 GCC_get_id (const struct CadetConnection *c);
 299
 300
 301 /**
 302  * Get a hash for the connection ID.
 303  *
 304  * @param c Connection to get the hash.
 305  *
 306  * @return Hash expanded from the ID of the connection.
 307  */
 308 const struct GNUNET_HashCode *
 309 GCC_get_h (const struct CadetConnection *c);
 310
 311
 312 /**
 313  * Get the connection path.
 314  *
 315  * @param c Connection to get the path from.
 316  *
 317  * @return path used by the connection.
 318  */
 319 const struct CadetPeerPath *
 320 GCC_get_path (const struct CadetConnection *c);
 321
 322 /**
 323  * Get the connection state.
 324  *
 325  * @param c Connection to get the state from.
 326  *
 327  * @return state of the connection.
 328  */
 329 enum CadetConnectionState
 330 GCC_get_state (const struct CadetConnection *c);
 331
 332 /**
 333  * Get the connection tunnel.
 334  *
 335  * @param c Connection to get the tunnel from.
 336  *
 337  * @return tunnel of the connection.
 338  */
 339 struct CadetTunnel *
 340 GCC_get_tunnel (const struct CadetConnection *c);
 341
 342 /**
 343  * Get free buffer space in a connection.
 344  *
 345  * @param c Connection.
 346  * @param fwd Is query about FWD traffic?
 347  *
 348  * @return Free buffer space [0 - max_msgs_queue/max_connections]
 349  */
 350 unsigned int
 351 GCC_get_buffer (struct CadetConnection *c, int fwd);
 352
 353 /**
 354  * Get how many messages have we allowed to send to us from a direction.
 355  *
 356  * @param c Connection.
 357  * @param fwd Are we asking about traffic from FWD (BCK messages)?
 358  *
 359  * @return last_ack_sent - last_pid_recv
 360  */
 361 unsigned int
 362 GCC_get_allowed (struct CadetConnection *c, int fwd);
 363
 364 /**
 365  * Get messages queued in a connection.
 366  *
 367  * @param c Connection.
 368  * @param fwd Is query about FWD traffic?
 369  *
 370  * @return Number of messages queued.
 371  */
 372 unsigned int
 373 GCC_get_qn (struct CadetConnection *c, int fwd);
 374
 375 /**
 376  * Get next PID to use.
 377  *
 378  * @param c Connection.
 379  * @param fwd Is query about FWD traffic?
 380  *
 381  * @return Last PID used + 1.
 382  */
 383 unsigned int
 384 GCC_get_pid (struct CadetConnection *c, int fwd);
 385
 386 /**
 387  * Allow the connection to advertise a buffer of the given size.
 388  *
 389  * The connection will send an @c fwd ACK message (so: in direction !fwd)
 390  * allowing up to last_pid_recv + buffer.
 391  *
 392  * @param c Connection.
 393  * @param buffer How many more messages the connection can accept.
 394  * @param fwd Is this about FWD traffic? (The ack will go dest->root).
 395  */
 396 void
 397 GCC_allow (struct CadetConnection *c, unsigned int buffer, int fwd);
 398
 399 /**
 400  * Send FWD keepalive packets for a connection.
 401  *
 402  * @param cls Closure (connection for which to send the keepalive).
 403  * @param tc Notification context.
 404  */
 405 void
 406 GCC_fwd_keepalive (void *cls, const struct GNUNET_SCHEDULER_TaskContext *tc);
 407
 408 /**
 409  * Send BCK keepalive packets for a connection.
 410  *
 411  * @param cls Closure (connection for which to send the keepalive).
 412  * @param tc Notification context.
 413  */
 414 void
 415 GCC_bck_keepalive (void *cls, const struct GNUNET_SCHEDULER_TaskContext *tc);
 416
 417
 418 /**
 419  * Notify other peers on a connection of a broken link. Mark connections
 420  * to destroy after all traffic has been sent.
 421  *
 422  * @param c Connection on which there has been a disconnection.
 423  * @param peer Peer that disconnected.
 424  */
 425 void
 426 GCC_notify_broken (struct CadetConnection *c,
 427                    struct CadetPeer *peer);
 428
 429 /**
 430  * Is this peer the first one on the connection?
 431  *
 432  * @param c Connection.
 433  * @param fwd Is this about fwd traffic?
 434  *
 435  * @return #GNUNET_YES if origin, #GNUNET_NO if relay/terminal.
 436  */
 437 int
 438 GCC_is_origin (struct CadetConnection *c, int fwd);
 439
 440 /**
 441  * Is this peer the last one on the connection?
 442  *
 443  * @param c Connection.
 444  * @param fwd Is this about fwd traffic?
 445  *            Note that the ROOT is the terminal for BCK traffic!
 446  *
 447  * @return #GNUNET_YES if terminal, #GNUNET_NO if relay/origin.
 448  */
 449 int
 450 GCC_is_terminal (struct CadetConnection *c, int fwd);
 451
 452 /**
 453  * See if we are allowed to send by the next hop in the given direction.
 454  *
 455  * @param c Connection.
 456  * @param fwd Is this about fwd traffic?
 457  *
 458  * @return #GNUNET_YES in case it's OK to send.
 459  */
 460 int
 461 GCC_is_sendable (struct CadetConnection *c, int fwd);
 462
 463 /**
 464  * Check if this connection is a direct one (never trim a direct connection).
 465  *
 466  * @param c Connection.
 467  *
 468  * @return #GNUNET_YES in case it's a direct connection, #GNUNET_NO otherwise.
 469  */
 470 int
 471 GCC_is_direct (struct CadetConnection *c);
 472
 473 /**
 474  * Cancel a previously sent message while it's in the queue.
 475  *
 476  * ONLY can be called before the continuation given to the send function
 477  * is called. Once the continuation is called, the message is no longer in the
 478  * queue.
 479  *
 480  * @param q Handle to the queue.
 481  */
 482 void
 483 GCC_cancel (struct CadetConnectionQueue *q);
 484
 485 /**
 486  * Sends an already built message on a connection, properly registering
 487  * all used resources.
 488  *
 489  * @param message Message to send. Function makes a copy of it.
 490  *                If message is not hop-by-hop, decrements TTL of copy.
 491  * @param payload_type Type of payload, in case the message is encrypted.
 492  * @param c Connection on which this message is transmitted.
 493  * @param fwd Is this a fwd message?
 494  * @param force Force the connection to accept the message (buffer overfill).
 495  * @param cont Continuation called once message is sent. Can be NULL.
 496  * @param cont_cls Closure for @c cont.
 497  *
 498  * @return Handle to cancel the message before it's sent.
 499  *         NULL on error or if @c cont is NULL.
 500  *         Invalid on @c cont call.
 501  */
 502 struct CadetConnectionQueue *
 503 GCC_send_prebuilt_message (const struct GNUNET_MessageHeader *message,
 504                            uint16_t payload_type, uint32_t payload_id,
 505                            struct CadetConnection *c, int fwd, int force,
 506                            GCC_sent cont, void *cont_cls);
 507
 508 /**
 509  * Sends a CREATE CONNECTION message for a path to a peer.
 510  * Changes the connection and tunnel states if necessary.
 511  *
 512  * @param connection Connection to create.
 513  */
 514 void
 515 GCC_send_create (struct CadetConnection *connection);
 516
 517 /**
 518  * Send a message to all peers in this connection that the connection
 519  * is no longer valid.
 520  *
 521  * If some peer should not receive the message, it should be zero'ed out
 522  * before calling this function.
 523  *
 524  * @param c The connection whose peers to notify.
 525  */
 526 void
 527 GCC_send_destroy (struct CadetConnection *c);
 528
 529 /**
 530  * @brief Start a polling timer for the connection.
 531  *
 532  * When a neighbor does not accept more traffic on the connection it could be
 533  * caused by a simple congestion or by a lost ACK. Polling enables to check
 534  * for the lastest ACK status for a connection.
 535  *
 536  * @param c Connection.
 537  * @param fwd Should we poll in the FWD direction?
 538  */
 539 void
 540 GCC_start_poll (struct CadetConnection *c, int fwd);
 541
 542
 543 /**
 544  * @brief Stop polling a connection for ACKs.
 545  *
 546  * Once we have enough ACKs for future traffic, polls are no longer necessary.
 547  *
 548  * @param c Connection.
 549  * @param fwd Should we stop the poll in the FWD direction?
 550  */
 551 void
 552 GCC_stop_poll (struct CadetConnection *c, int fwd);
 553
 554 /**
 555  * Get a (static) string for a connection.
 556  *
 557  * @param c Connection.
 558  */
 559 const char *
 560 GCC_2s (const struct CadetConnection *c);
 561
 562 /**
 563  * Log all possible info about the connection state.
 564  *
 565  * @param c Connection to debug.
 566  * @param level Debug level to use.
 567  */
 568 void
 569 GCC_debug (const struct CadetConnection *c, enum GNUNET_ErrorType level);
 570
 571 #if 0                           /* keep Emacsens' auto-indent happy */
 572 {
 573 #endif
 574 #ifdef __cplusplus
 575 }
 576 #endif
 577
 578 /* ifndef GNUNET_SERVICE_CADET_CONNECTION_H */
 579 #endif
 580 /* end of gnunet-service-cadet_connection.h */