src/include/gnunet_dv_service.h

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (C) 2013, 2016 GNUnet e.V.
   4
   5      GNUnet is free software: you can redistribute it and/or modify it
   6      under the terms of the GNU Affero General Public License as published
   7      by the Free Software Foundation, either version 3 of the License,
   8      or (at your 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      Affero General Public License for more details.
  14
  15      You should have received a copy of the GNU Affero General Public License
  16      along with this program.  If not, see <http://www.gnu.org/licenses/>.
  17 */
  18
  19 /**
  20  * @author Christian Grothoff
  21  *
  22  * @file
  23  * DV service API (should only be used by the DV plugin)
  24  *
  25  * @defgroup dv  DV service
  26  * Distance Vector routing
  27  *
  28  * The DV service API should only be used by the DV plugin.
  29  * @{
  30  */
  31 #ifndef GNUNET_SERVICE_DV_H
  32 #define GNUNET_SERVICE_DV_H
  33
  34 #include "gnunet_util_lib.h"
  35 #include "gnunet_ats_service.h"
  36
  37 /**
  38  * Signature of a function to be called if DV
  39  * starts to be able to talk to a peer.
  40  *
  41  * @param cls closure
  42  * @param peer newly connected peer
  43  * @param distance distance to the peer
  44  * @param network the peer is located in
  45  */
  46 typedef void
  47 (*GNUNET_DV_ConnectCallback)(void *cls,
  48                              const struct GNUNET_PeerIdentity *peer,
  49                              uint32_t distance,
  50                              enum GNUNET_ATS_Network_Type network);
  51
  52
  53 /**
  54  * Signature of a function to be called if DV
  55  * distance to a peer is changed.
  56  *
  57  * @param cls closure
  58  * @param peer connected peer
  59  * @param distance new distance to the peer
  60  * @param network this network will be used to reach the next hop
  61  */
  62 typedef void
  63 (*GNUNET_DV_DistanceChangedCallback)(void *cls,
  64                                      const struct GNUNET_PeerIdentity *peer,
  65                                      uint32_t distance,
  66                                      enum GNUNET_ATS_Network_Type network);
  67
  68
  69 /**
  70  * Signature of a function to be called if DV
  71  * is no longer able to talk to a peer.
  72  *
  73  * @param cls closure
  74  * @param peer peer that disconnected
  75  */
  76 typedef void
  77 (*GNUNET_DV_DisconnectCallback)(void *cls,
  78                                 const struct GNUNET_PeerIdentity *peer);
  79
  80
  81 /**
  82  * Signature of a function to be called if DV
  83  * receives a message for this peer.
  84  *
  85  * @param cls closure
  86  * @param sender sender of the message
  87  * @param distance how far did the message travel
  88  * @param msg actual message payload
  89  */
  90 typedef void
  91 (*GNUNET_DV_MessageReceivedCallback)(void *cls,
  92                                      const struct GNUNET_PeerIdentity *sender,
  93                                      uint32_t distance,
  94                                      const struct GNUNET_MessageHeader *msg);
  95
  96
  97 /**
  98  * Signature of a function called once the delivery of a
  99  * message has been successful.
 100  *
 101  * @param cls closure
 102  */
 103 typedef void
 104 (*GNUNET_DV_MessageSentCallback)(void *cls);
 105
 106
 107 /**
 108  * Handle to the DV service.
 109  */
 110 struct GNUNET_DV_ServiceHandle;
 111
 112
 113 /**
 114  * Connect to the DV service.
 115  *
 116  * @param cfg configuration
 117  * @param cls closure for callbacks
 118  * @param connect_cb function to call on connects
 119  * @param distance_cb function to call if distances change
 120  * @param disconnect_cb function to call on disconnects
 121  * @param message_cb function to call if we receive messages
 122  * @return handle to access the service
 123  */
 124 struct GNUNET_DV_ServiceHandle *
 125 GNUNET_DV_service_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
 126                            void *cls,
 127                            GNUNET_DV_ConnectCallback connect_cb,
 128                            GNUNET_DV_DistanceChangedCallback distance_cb,
 129                            GNUNET_DV_DisconnectCallback disconnect_cb,
 130                            GNUNET_DV_MessageReceivedCallback message_cb);
 131
 132
 133 /**
 134  * Disconnect from DV service.
 135  *
 136  * @param sh service handle
 137  */
 138 void
 139 GNUNET_DV_service_disconnect (struct GNUNET_DV_ServiceHandle *sh);
 140
 141
 142 /**
 143  * Handle for a send operation.
 144  */
 145 struct GNUNET_DV_TransmitHandle;
 146
 147
 148 /**
 149  * Send a message via DV service.
 150  *
 151  * @param sh service handle
 152  * @param target intended recpient
 153  * @param msg message payload
 154  * @return handle to cancel the operation
 155  */
 156 void
 157 GNUNET_DV_send (struct GNUNET_DV_ServiceHandle *sh,
 158                 const struct GNUNET_PeerIdentity *target,
 159                 const struct GNUNET_MessageHeader *msg);
 160
 161
 162 #endif
 163
 164 /** @} */  /* end of group */