src/include/gnunet_dv_service.h

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (C) 2013 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 (*GNUNET_DV_ConnectCallback)(void *cls,
  49                                           const struct GNUNET_PeerIdentity *peer,
  50                                           uint32_t distance,
  51                                           enum GNUNET_ATS_Network_Type network);
  52
  53
  54 /**
  55  * Signature of a function to be called if DV
  56  * distance to a peer is changed.
  57  *
  58  * @param cls closure
  59  * @param peer connected peer
  60  * @param distance new distance to the peer
  61  * @param network this network will be used to reach the next hop
  62  */
  63 typedef void (*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 (*GNUNET_DV_DisconnectCallback)(void *cls,
  77                                              const struct GNUNET_PeerIdentity *peer);
  78
  79
  80 /**
  81  * Signature of a function to be called if DV
  82  * receives a message for this peer.
  83  *
  84  * @param cls closure
  85  * @param sender sender of the message
  86  * @param distance how far did the message travel
  87  * @param msg actual message payload
  88  */
  89 typedef void (*GNUNET_DV_MessageReceivedCallback)(void *cls,
  90                                                   const struct GNUNET_PeerIdentity *sender,
  91                                                   uint32_t distance,
  92                                                   const struct GNUNET_MessageHeader *msg);
  93
  94
  95 /**
  96  * Signature of a function called once the delivery of a
  97  * message has been successful.
  98  *
  99  * @param cls closure
 100  * @param ok GNUNET_OK on success, GNUNET_SYSERR on error
 101  */
 102 typedef void (*GNUNET_DV_MessageSentCallback)(void *cls,
 103                                               int ok);
 104
 105
 106 /**
 107  * Handle to the DV service.
 108  */
 109 struct GNUNET_DV_ServiceHandle;
 110
 111
 112 /**
 113  * Connect to the DV service.
 114  *
 115  * @param cfg configuration
 116  * @param cls closure for callbacks
 117  * @param connect_cb function to call on connects
 118  * @param distance_cb function to call if distances change
 119  * @param disconnect_cb function to call on disconnects
 120  * @param message_cb function to call if we receive messages
 121  * @return handle to access the service
 122  */
 123 struct GNUNET_DV_ServiceHandle *
 124 GNUNET_DV_service_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
 125                            void *cls,
 126                            GNUNET_DV_ConnectCallback connect_cb,
 127                            GNUNET_DV_DistanceChangedCallback distance_cb,
 128                            GNUNET_DV_DisconnectCallback disconnect_cb,
 129                            GNUNET_DV_MessageReceivedCallback message_cb);
 130
 131
 132 /**
 133  * Disconnect from DV service.
 134  *
 135  * @param sh service handle
 136  */
 137 void
 138 GNUNET_DV_service_disconnect (struct GNUNET_DV_ServiceHandle *sh);
 139
 140
 141 /**
 142  * Handle for a send operation.
 143  */
 144 struct GNUNET_DV_TransmitHandle;
 145
 146
 147 /**
 148  * Send a message via DV service.
 149  *
 150  * @param sh service handle
 151  * @param target intended recpient
 152  * @param msg message payload
 153  * @param cb function to invoke when done
 154  * @param cb_cls closure for 'cb'
 155  * @return handle to cancel the operation
 156  */
 157 struct GNUNET_DV_TransmitHandle *
 158 GNUNET_DV_send (struct GNUNET_DV_ServiceHandle *sh,
 159                 const struct GNUNET_PeerIdentity *target,
 160                 const struct GNUNET_MessageHeader *msg,
 161                 GNUNET_DV_MessageSentCallback cb,
 162                 void *cb_cls);
 163
 164
 165 /**
 166  * Abort send operation (naturally, the message may have
 167  * already been transmitted; this only stops the 'cb'
 168  * from being called again).
 169  *
 170  * @param th send operation to cancel
 171  */
 172 void
 173 GNUNET_DV_send_cancel (struct GNUNET_DV_TransmitHandle *th);
 174
 175
 176 #endif
 177
 178 /** @} */  /* end of group */