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
   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
  25  * DV service API (should only be used by the DV plugin)
  26  *
  27  * @defgroup dv  DV service
  28  * Distance Vector routing
  29  *
  30  * The DV service API should only be used by the DV plugin.
  31  * @{
  32  */
  33 #ifndef GNUNET_SERVICE_DV_H
  34 #define GNUNET_SERVICE_DV_H
  35
  36 #include "gnunet_util_lib.h"
  37 #include "gnunet_ats_service.h"
  38
  39 /**
  40  * Signature of a function to be called if DV
  41  * starts to be able to talk to a peer.
  42  *
  43  * @param cls closure
  44  * @param peer newly connected peer
  45  * @param distance distance to the peer
  46  * @param network the peer is located in
  47  */
  48 typedef void
  49 (*GNUNET_DV_ConnectCallback)(void *cls,
  50                              const struct GNUNET_PeerIdentity *peer,
  51                              uint32_t distance,
  52                              enum GNUNET_ATS_Network_Type network);
  53
  54
  55 /**
  56  * Signature of a function to be called if DV
  57  * distance to a peer is changed.
  58  *
  59  * @param cls closure
  60  * @param peer connected peer
  61  * @param distance new distance to the peer
  62  * @param network this network will be used to reach the next hop
  63  */
  64 typedef void
  65 (*GNUNET_DV_DistanceChangedCallback)(void *cls,
  66                                      const struct GNUNET_PeerIdentity *peer,
  67                                      uint32_t distance,
  68                                      enum GNUNET_ATS_Network_Type network);
  69
  70
  71 /**
  72  * Signature of a function to be called if DV
  73  * is no longer able to talk to a peer.
  74  *
  75  * @param cls closure
  76  * @param peer peer that disconnected
  77  */
  78 typedef void
  79 (*GNUNET_DV_DisconnectCallback)(void *cls,
  80                                 const struct GNUNET_PeerIdentity *peer);
  81
  82
  83 /**
  84  * Signature of a function to be called if DV
  85  * receives a message for this peer.
  86  *
  87  * @param cls closure
  88  * @param sender sender of the message
  89  * @param distance how far did the message travel
  90  * @param msg actual message payload
  91  */
  92 typedef void
  93 (*GNUNET_DV_MessageReceivedCallback)(void *cls,
  94                                      const struct GNUNET_PeerIdentity *sender,
  95                                      uint32_t distance,
  96                                      const struct GNUNET_MessageHeader *msg);
  97
  98
  99 /**
 100  * Signature of a function called once the delivery of a
 101  * message has been successful.
 102  *
 103  * @param cls closure
 104  */
 105 typedef void
 106 (*GNUNET_DV_MessageSentCallback)(void *cls);
 107
 108
 109 /**
 110  * Handle to the DV service.
 111  */
 112 struct GNUNET_DV_ServiceHandle;
 113
 114
 115 /**
 116  * Connect to the DV service.
 117  *
 118  * @param cfg configuration
 119  * @param cls closure for callbacks
 120  * @param connect_cb function to call on connects
 121  * @param distance_cb function to call if distances change
 122  * @param disconnect_cb function to call on disconnects
 123  * @param message_cb function to call if we receive messages
 124  * @return handle to access the service
 125  */
 126 struct GNUNET_DV_ServiceHandle *
 127 GNUNET_DV_service_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
 128                            void *cls,
 129                            GNUNET_DV_ConnectCallback connect_cb,
 130                            GNUNET_DV_DistanceChangedCallback distance_cb,
 131                            GNUNET_DV_DisconnectCallback disconnect_cb,
 132                            GNUNET_DV_MessageReceivedCallback message_cb);
 133
 134
 135 /**
 136  * Disconnect from DV service.
 137  *
 138  * @param sh service handle
 139  */
 140 void
 141 GNUNET_DV_service_disconnect (struct GNUNET_DV_ServiceHandle *sh);
 142
 143
 144 /**
 145  * Handle for a send operation.
 146  */
 147 struct GNUNET_DV_TransmitHandle;
 148
 149
 150 /**
 151  * Send a message via DV service.
 152  *
 153  * @param sh service handle
 154  * @param target intended recpient
 155  * @param msg message payload
 156  * @return handle to cancel the operation
 157  */
 158 void
 159 GNUNET_DV_send (struct GNUNET_DV_ServiceHandle *sh,
 160                 const struct GNUNET_PeerIdentity *target,
 161                 const struct GNUNET_MessageHeader *msg);
 162
 163
 164 #endif
 165
 166 /** @} */  /* end of group */