src/include/gnunet_dv_service.h

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