src/fs/gnunet-service-fs_cp.h

   1 /*
   2      This file is part of GNUnet.
   3      (C) 2011 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  * @file fs/gnunet-service-fs_cp.h
  23  * @brief API to handle 'connected peers'
  24  * @author Christian Grothoff
  25  */
  26 #ifndef GNUNET_SERVICE_FS_CP_H
  27 #define GNUNET_SERVICE_FS_CP_H
  28
  29 #include "gnunet-service-fs.h"
  30
  31
  32 /**
  33  * A peer connected to us.  Setup the connected peer
  34  * records.
  35  *
  36  * @param peer identity of peer that connected
  37  * @param atsi performance data for the connection
  38  * @return handle to connected peer entry
  39  */
  40 struct GSF_ConnectedPeer *
  41 GSF_peer_connect_handler_ (const struct GNUNET_PeerIdentity *peer,
  42                            const struct GNUNET_TRANSPORT_ATS_Information *atsi);
  43
  44
  45 /**
  46  * Function called to get a message for transmission.
  47  *
  48  * @param cls closure
  49  * @param buf_size number of bytes available in buf
  50  * @param buf where to copy the message, NULL on error (peer disconnect)
  51  * @return number of bytes copied to 'buf', can be 0 (without indicating an error)
  52  */
  53 typedef size_t (*GSF_GetMessageCallback)(void *cls,
  54                                          size_t buf_size,
  55                                          void *buf);
  56
  57
  58 /**
  59  * Transmit a message to the given peer as soon as possible.
  60  * If the peer disconnects before the transmission can happen,
  61  * the callback is invoked with a 'NULL' buffer.
  62  *
  63  * @param peer target peer
  64  * @param size number of bytes we would like to send to the peer
  65  * @param gmc function to call to get the message
  66  * @param gmc_cls closure for gmc
  67  */
  68 void
  69 GSF_peer_transmit_ (struct GSF_ConnectedPeer *peer,
  70                     size_t size,
  71                     GSF_GetMessageCallback gmc,
  72                     void *gmc_cls);
  73
  74
  75 /**
  76  * Method called whenever a given peer has a status change.
  77  *
  78  * @param cls closure
  79  * @param peer peer identity this notification is about
  80  * @param bandwidth_in available amount of inbound bandwidth
  81  * @param bandwidth_out available amount of outbound bandwidth
  82  * @param timeout absolute time when this peer will time out
  83  *        unless we see some further activity from it
  84  * @param atsi status information
  85  */
  86 void
  87 GSF_peer_status_handler_ (void *cls,
  88                           const struct GNUNET_PeerIdentity *peer,
  89                           struct GNUNET_BANDWIDTH_Value32NBO bandwidth_in,
  90                           struct GNUNET_BANDWIDTH_Value32NBO bandwidth_out,
  91                           struct GNUNET_TIME_Absolute timeout,
  92                           const struct GNUNET_TRANSPORT_ATS_Information *atsi);
  93
  94
  95 /**
  96  * A peer disconnected from us.  Tear down the connected peer
  97  * record.
  98  *
  99  * @param cls unused
 100  * @param peer identity of peer that connected
 101  */
 102 void
 103 GSF_peer_disconnect_handler_ (void *cls,
 104                               const struct GNUNET_PeerIdentity *peer);
 105
 106
 107 /**
 108  * Signature of function called on a connected peer.
 109  *
 110  * @param cls closure
 111  * @param peer identity of the peer
 112  * @param cp handle to the connected peer record
 113  */
 114 typedef void (*GSF_ConnectedPeerIterator)(void *cls,
 115                                           const struct GNUNET_PeerIdentity *peer,
 116                                           struct GSF_ConnectedPeer *cp);
 117
 118
 119 /**
 120  * Iterate over all connected peers.
 121  *
 122  * @param it function to call for each peer
 123  * @param it_cls closure for it
 124  */
 125 void
 126 GSF_iterate_connected_peers_ (GSF_ConnectedPeerIterator it,
 127                               void *it_cls);
 128
 129
 130 /**
 131  * Register callback to invoke on peer disconnect.
 132  *
 133  * @param cp peer to monitor
 134  * @param it function to call on disconnect
 135  * @param it_cls closure for it
 136  */
 137 void
 138 GSF_connected_peer_register_disconnect_callback_ (struct GSF_ConnectedPeer *cp,
 139                                                   GSF_ConnectedPeerIterator it,
 140                                                   void *it_cls);
 141
 142
 143 /**
 144  * Unregister callback to invoke on peer disconnect.
 145  *
 146  * @param cp peer to stop monitoring
 147  * @param it function to no longer call on disconnect
 148  * @param it_cls closure for it
 149  */
 150 void
 151 GSF_connected_peer_unregister_disconnect_callback_ (struct GSF_ConnectedPeer *cp,
 152                                                     GSF_ConnectedPeerIterator it,
 153                                                     void *it_cls);
 154
 155
 156 /**
 157  * Signature of function called on a reservation success.
 158  *
 159  * @param cls closure
 160  * @param cp handle to the connected peer record
 161  */
 162 typedef void (*GSF_PeerReserveCallback)(void *cls,
 163                                         struct GSF_ConnectedPeer *cp);
 164
 165
 166 /**
 167  * Try to reserve bandwidth (to receive data FROM the given peer).
 168  * This function must only be called ONCE per connected peer at a
 169  * time; it can be called again after the 'rc' callback was invoked.
 170  * If the peer disconnects, the request is (silently!) ignored (and
 171  * the requester is responsible to register for notification about the
 172  * peer disconnect if any special action needs to be taken in this
 173  * case).
 174  *
 175  * @param cp peer to reserve bandwidth from
 176  * @param size number of bytes to reserve
 177  * @param rc function to call upon reservation success
 178  * @param rc_cls closure for rc
 179  */
 180 void
 181 GSF_connected_peer_reserve_ (struct GSF_ConnectedPeer *cp,
 182                              size_t size,
 183                              GSF_PeerReserveCallback rc,
 184                              void *rc_cls);
 185
 186
 187 #endif
 188 /* end of gnunet-service-fs_cp.h */