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