src/cadet/gnunet-service-cadet_peer.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., 51 Franklin Street, Fifth Floor,
  18      Boston, MA 02110-1301, USA.
  19 */
  20
  21 /**
  22  * @file cadet/gnunet-service-cadet_peer.h
  23  * @brief cadet service; dealing with remote peers
  24  * @author Bartlomiej Polot
  25  *
  26  * All functions in this file should use the prefix GMP (Gnunet Cadet Peer)
  27  */
  28
  29 #ifndef GNUNET_SERVICE_CADET_PEER_H
  30 #define GNUNET_SERVICE_CADET_PEER_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 "platform.h"
  41 #include "gnunet_util_lib.h"
  42
  43 /**
  44  * Struct containing all information regarding a given peer
  45  */
  46 struct CadetPeer;
  47
  48 /**
  49  * Struct containing info about a queued transmission to this peer
  50  */
  51 struct CadetPeerQueue;
  52
  53 #include "gnunet-service-cadet_connection.h"
  54
  55
  56 /**
  57  * Callback called when a queued message is sent.
  58  *
  59  * @param cls Closure.
  60  * @param c Connection this message was on.
  61  * @param sent Was it really sent? (Could have been canceled)
  62  * @param type Type of message sent.
  63  * @param pid Packet ID, or 0 if not applicable (create, destroy, etc).
  64  * @param fwd Was this a FWD going message?
  65  * @param size Size of the message.
  66  * @param wait Time spent waiting for core (only the time for THIS message)
  67  * @return #GNUNET_YES if connection was destroyed, #GNUNET_NO otherwise.
  68  */
  69 typedef int
  70 (*GCP_sent) (void *cls,
  71              struct CadetConnection *c, int sent,
  72              uint16_t type, uint32_t pid, int fwd, size_t size,
  73              struct GNUNET_TIME_Relative wait);
  74
  75
  76 /******************************************************************************/
  77 /********************************    API    ***********************************/
  78 /******************************************************************************/
  79
  80 /**
  81  * Initialize peer subsystem.
  82  *
  83  * @param c Configuration.
  84  */
  85 void
  86 GCP_init (const struct GNUNET_CONFIGURATION_Handle *c);
  87
  88 /**
  89  * Shut down the peer subsystem.
  90  */
  91 void
  92 GCP_shutdown (void);
  93
  94
  95 /**
  96  * Retrieve the CadetPeer stucture associated with the peer, create one
  97  * and insert it in the appropriate structures if the peer is not known yet.
  98  *
  99  * @param peer_id Full identity of the peer.
 100  *
 101  * @return Existing or newly created peer structure.
 102  */
 103 struct CadetPeer *
 104 GCP_get (const struct GNUNET_PeerIdentity *peer_id);
 105
 106
 107 /**
 108  * Retrieve the CadetPeer stucture associated with the peer, create one
 109  * and insert it in the appropriate structures if the peer is not known yet.
 110  *
 111  * @param peer Short identity of the peer.
 112  *
 113  * @return Existing or newly created peer structure.
 114  */
 115 struct CadetPeer *
 116 GCP_get_short (const GNUNET_PEER_Id peer);
 117
 118 /**
 119  * Try to establish a new connection to this peer (in its tunnel).
 120  * If the peer doesn't have any path to it yet, try to get one.
 121  * If the peer already has some path, send a CREATE CONNECTION towards it.
 122  *
 123  * @param peer Peer to connect to.
 124  */
 125 void
 126 GCP_connect (struct CadetPeer *peer);
 127
 128 /**
 129  * Free a transmission that was already queued with all resources
 130  * associated to the request.
 131  *
 132  * If connection was marked to be destroyed, and this was the last queued
 133  * message on it, the connection will be free'd as a result.
 134  *
 135  * @param queue Queue handler to cancel.
 136  * @param clear_cls Is it necessary to free associated cls?
 137  * @param sent Was it really sent? (Could have been canceled)
 138  * @param pid PID, if relevant (was sent and was a payload message).
 139  *
 140  * @return #GNUNET_YES if connection was destroyed as a result,
 141  *         #GNUNET_NO otherwise.
 142  */
 143 int
 144 GCP_queue_destroy (struct CadetPeerQueue *queue, int clear_cls,
 145                    int sent, uint32_t pid);
 146
 147 /**
 148  * @brief Queue and pass message to core when possible.
 149  *
 150  * @param peer Peer towards which to queue the message.
 151  * @param cls Closure (@c type dependant). It will be used by queue_send to
 152  *            build the message to be sent if not already prebuilt.
 153  * @param type Type of the message, 0 for a raw message.
 154  * @param size Size of the message.
 155  * @param c Connection this message belongs to (cannot be NULL).
 156  * @param fwd Is this a message going root->dest? (FWD ACK are NOT FWD!)
 157  * @param cont Continuation to be called once CORE has taken the message.
 158  * @param cont_cls Closure for @c cont.
 159  *
 160  * @return Handle to cancel the message before it is sent. Once cont is called
 161  *         message has been sent and therefore the handle is no longer valid.
 162  */
 163 struct CadetPeerQueue *
 164 GCP_queue_add (struct CadetPeer *peer, void *cls, uint16_t type,
 165                uint16_t payload_type, uint32_t payload_id,
 166                size_t size, struct CadetConnection *c, int fwd,
 167                GCP_sent cont, void *cont_cls);
 168
 169 /**
 170  * Cancel all queued messages to a peer that belong to a certain connection.
 171  *
 172  * @param peer Peer towards whom to cancel.
 173  * @param c Connection whose queued messages to cancel. Might be destroyed by
 174  *          the sent continuation call.
 175  */
 176 void
 177 GCP_queue_cancel (struct CadetPeer *peer, struct CadetConnection *c);
 178
 179 /**
 180  * Get the first message for a connection and unqueue it.
 181  *
 182  * Only tunnel (or higher) level messages are unqueued. Connection specific
 183  * messages are silently destroyed upon encounter.
 184  *
 185  * @param peer Neighboring peer.
 186  * @param c Connection.
 187  * @param destroyed[in/out] Was the connection destroyed as a result?.
 188  *                          Can NOT be NULL.
 189  *
 190  *
 191  * @return First message for this connection.
 192  */
 193 struct GNUNET_MessageHeader *
 194 GCP_connection_pop (struct CadetPeer *peer,
 195                     struct CadetConnection *c,
 196                     int *destroyed);
 197
 198 /**
 199  * Unlock a possibly locked queue for a connection.
 200  *
 201  * If there is a message that can be sent on this connection, call core for it.
 202  * Otherwise (if core transmit is already called or there is no sendable
 203  * message) do nothing.
 204  *
 205  * @param peer Peer who keeps the queue.
 206  * @param c Connection whose messages to unlock.
 207  */
 208 void
 209 GCP_queue_unlock (struct CadetPeer *peer, struct CadetConnection *c);
 210
 211 /**
 212  * Set tunnel.
 213  *
 214  * @param peer Peer.
 215  * @param t Tunnel.
 216  */
 217 void
 218 GCP_set_tunnel (struct CadetPeer *peer, struct CadetTunnel *t);
 219
 220
 221 /**
 222  * Check whether there is a direct (core level)  connection to peer.
 223  *
 224  * @param peer Peer to check.
 225  *
 226  * @return #GNUNET_YES if there is a direct connection.
 227  */
 228 int
 229 GCP_is_neighbor (const struct CadetPeer *peer);
 230
 231
 232 /**
 233  * Create and initialize a new tunnel towards a peer, in case it has none.
 234  *
 235  * Does not generate any traffic, just creates the local data structures.
 236  *
 237  * @param peer Peer towards which to create the tunnel.
 238  */
 239 void
 240 GCP_add_tunnel (struct CadetPeer *peer);
 241
 242
 243 /**
 244  * Add a connection to a neighboring peer.
 245  *
 246  * Store that the peer is the first hop of the connection in one
 247  * direction and that on peer disconnect the connection must be
 248  * notified and destroyed, for it will no longer be valid.
 249  *
 250  * @param peer Peer to add connection to.
 251  * @param c Connection to add.
 252  * @param pred #GNUNET_YES if we are predecessor, #GNUNET_NO if we are successor
 253  */
 254 void
 255 GCP_add_connection (struct CadetPeer *peer,
 256                     struct CadetConnection *c,
 257                     int pred);
 258
 259
 260 /**
 261  * Add the path to the peer and update the path used to reach it in case this
 262  * is the shortest.
 263  *
 264  * @param peer Destination peer to add the path to.
 265  * @param path New path to add. Last peer must be the peer in arg 1.
 266  *             Path will be either used of freed if already known.
 267  * @param trusted Do we trust that this path is real?
 268  *
 269  * @return path if path was taken, pointer to existing duplicate if exists
 270  *         NULL on error.
 271  */
 272 struct CadetPeerPath *
 273 GCP_add_path (struct CadetPeer *peer,
 274               struct CadetPeerPath *p,
 275               int trusted);
 276
 277
 278 /**
 279  * Add the path to the origin peer and update the path used to reach it in case
 280  * this is the shortest.
 281  * The path is given in peer_info -> destination, therefore we turn the path
 282  * upside down first.
 283  *
 284  * @param peer Peer to add the path to, being the origin of the path.
 285  * @param path New path to add after being inversed.
 286  *             Path will be either used or freed.
 287  * @param trusted Do we trust that this path is real?
 288  *
 289  * @return path if path was taken, pointer to existing duplicate if exists
 290  *         NULL on error.
 291  */
 292 struct CadetPeerPath *
 293 GCP_add_path_to_origin (struct CadetPeer *peer,
 294                         struct CadetPeerPath *path,
 295                         int trusted);
 296
 297 /**
 298  * Adds a path to the info of all the peers in the path
 299  *
 300  * @param p Path to process.
 301  * @param confirmed Whether we know if the path works or not.
 302  */
 303 void
 304 GCP_add_path_to_all (const struct CadetPeerPath *p, int confirmed);
 305
 306
 307 /**
 308  * Remove any path to the peer that has the extact same peers as the one given.
 309  *
 310  * @param peer Peer to remove the path from.
 311  * @param path Path to remove. Is always destroyed .
 312  */
 313 void
 314 GCP_remove_path (struct CadetPeer *peer,
 315                  struct CadetPeerPath *path);
 316
 317
 318 /**
 319  * Check that we are aware of a connection from a neighboring peer.
 320  *
 321  * @param peer Peer to the connection is with
 322  * @param c Connection that should be in the map with this peer.
 323  */
 324 void
 325 GCP_check_connection (const struct CadetPeer *peer,
 326                       const struct CadetConnection *c);
 327
 328
 329 /**
 330  * Remove a connection from a neighboring peer.
 331  *
 332  * @param peer Peer to remove connection from.
 333  * @param c Connection to remove.
 334  */
 335 void
 336 GCP_remove_connection (struct CadetPeer *peer,
 337                        const struct CadetConnection *c);
 338
 339
 340 /**
 341  * Start the DHT search for new paths towards the peer: we don't have
 342  * enough good connections.
 343  *
 344  * @param peer Destination peer.
 345  */
 346 void
 347 GCP_start_search (struct CadetPeer *peer);
 348
 349
 350 /**
 351  * Stop the DHT search for new paths towards the peer: we already have
 352  * enough good connections.
 353  *
 354  * @param peer Destination peer.
 355  */
 356 void
 357 GCP_stop_search (struct CadetPeer *peer);
 358
 359
 360 /**
 361  * Get the Full ID of a peer.
 362  *
 363  * @param peer Peer to get from.
 364  *
 365  * @return Full ID of peer.
 366  */
 367 const struct GNUNET_PeerIdentity *
 368 GCP_get_id (const struct CadetPeer *peer);
 369
 370
 371 /**
 372  * Get the Short ID of a peer.
 373  *
 374  * @param peer Peer to get from.
 375  *
 376  * @return Short ID of peer.
 377  */
 378 GNUNET_PEER_Id
 379 GCP_get_short_id (const struct CadetPeer *peer);
 380
 381
 382 /**
 383  * Get the tunnel towards a peer.
 384  *
 385  * @param peer Peer to get from.
 386  *
 387  * @return Tunnel towards peer.
 388  */
 389 struct CadetTunnel *
 390 GCP_get_tunnel (const struct CadetPeer *peer);
 391
 392
 393 /**
 394  * Set the hello message.
 395  *
 396  * @param peer Peer whose message to set.
 397  * @param hello Hello message.
 398  */
 399 void
 400 GCP_set_hello (struct CadetPeer *peer,
 401                const struct GNUNET_HELLO_Message *hello);
 402
 403
 404 /**
 405  * Get the hello message.
 406  *
 407  * @param peer Peer whose message to get.
 408  *
 409  * @return Hello message.
 410  */
 411 struct GNUNET_HELLO_Message *
 412 GCP_get_hello (struct CadetPeer *peer);
 413
 414
 415 /**
 416  * Try to connect to a peer on TRANSPORT level.
 417  *
 418  * @param peer Peer to whom to connect.
 419  */
 420 void
 421 GCP_try_connect (struct CadetPeer *peer);
 422
 423 /**
 424  * Notify a peer that a link between two other peers is broken. If any path
 425  * used that link, eliminate it.
 426  *
 427  * @param peer Peer affected by the change.
 428  * @param peer1 Peer whose link is broken.
 429  * @param peer2 Peer whose link is broken.
 430  */
 431 void
 432 GCP_notify_broken_link (struct CadetPeer *peer,
 433                         struct GNUNET_PeerIdentity *peer1,
 434                         struct GNUNET_PeerIdentity *peer2);
 435
 436
 437 /**
 438  * Count the number of known paths toward the peer.
 439  *
 440  * @param peer Peer to get path info.
 441  *
 442  * @return Number of known paths.
 443  */
 444 unsigned int
 445 GCP_count_paths (const struct CadetPeer *peer);
 446
 447
 448 /**
 449  * Iterate all known peers.
 450  *
 451  * @param iter Iterator.
 452  * @param cls Closure for @c iter.
 453  */
 454 void
 455 GCP_iterate_all (GNUNET_CONTAINER_PeerMapIterator iter, void *cls);
 456
 457
 458 /**
 459  * Get the static string for a peer ID.
 460  *
 461  * @param peer Peer.
 462  *
 463  * @return Static string for it's ID.
 464  */
 465 const char *
 466 GCP_2s (const struct CadetPeer *peer);
 467
 468
 469 /**
 470  * Log all kinds of info about a peer.
 471  *
 472  * @param peer Peer.
 473  */
 474 void
 475 GCP_debug (const struct CadetPeer *p,
 476            enum GNUNET_ErrorType level);
 477
 478
 479 #if 0                           /* keep Emacsens' auto-indent happy */
 480 {
 481 #endif
 482 #ifdef __cplusplus
 483 }
 484 #endif
 485
 486 /* ifndef GNUNET_CADET_SERVICE_PEER_H */
 487 #endif
 488 /* end of gnunet-cadet-service_peer.h */