src/include/gnunet_peerinfo_service.h

   1 /*
   2      This file is part of GNUnet
   3      Copyright (C) 2009, 2010 GNUnet e.V.
   4
   5      GNUnet is free software: you can redistribute it and/or modify it
   6      under the terms of the GNU Affero 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      You should have received a copy of the GNU Affero General Public License
  16      along with this program.  If not, see <http://www.gnu.org/licenses/>.
  17 */
  18 /**
  19  * @author Christian Grothoff
  20  *
  21  * @file
  22  * Maintain the list of currently known hosts
  23  *
  24  * @defgroup peerinfo  Peer Info service
  25  * Maintain the list of currently known hosts.
  26  *
  27  * Holds an in-memory structure of data/hosts.
  28  *
  29  * @see [Documentation](https://gnunet.org/gnunets-peerinfo-subsystem)
  30  *
  31  * @{
  32  */
  33
  34 #ifndef GNUNET_PEERINFO_SERVICE_H
  35 #define GNUNET_PEERINFO_SERVICE_H
  36
  37 #include "gnunet_common.h"
  38 #include "gnunet_configuration_lib.h"
  39 #include "gnunet_crypto_lib.h"
  40 #include "gnunet_hello_lib.h"
  41
  42 #ifdef __cplusplus
  43 extern "C"
  44 {
  45 #if 0                           /* keep Emacsens' auto-indent happy */
  46 }
  47 #endif
  48 #endif
  49
  50
  51 /**
  52  * Handle to the peerinfo service.
  53  */
  54 struct GNUNET_PEERINFO_Handle;
  55
  56
  57 /**
  58  * Connect to the peerinfo service.
  59  *
  60  * @param cfg configuration to use
  61  * @return NULL on error (configuration related, actual connection
  62  *         etablishment may happen asynchronously).
  63  */
  64 struct GNUNET_PEERINFO_Handle *
  65 GNUNET_PEERINFO_connect (const struct GNUNET_CONFIGURATION_Handle *cfg);
  66
  67
  68 /**
  69  * Disconnect from the peerinfo service.  Note that all iterators must
  70  * have completed or have been cancelled by the time this function is
  71  * called (otherwise, calling this function is a serious error).
  72  * Furthermore, if #GNUNET_PEERINFO_add_peer() operations are still
  73  * pending, they will be cancelled silently on disconnect.
  74  *
  75  * @param h handle to disconnect
  76  */
  77 void
  78 GNUNET_PEERINFO_disconnect (struct GNUNET_PEERINFO_Handle *h);
  79
  80
  81 /**
  82  * Add a host to the persistent list.  This method operates in
  83  * semi-reliable mode: if the transmission is not completed by
  84  * the time #GNUNET_PEERINFO_disconnect() is called, it will be
  85  * aborted.  Furthermore, if a second HELLO is added for the
  86  * same peer before the first one was transmitted, PEERINFO may
  87  * merge the two HELLOs prior to transmission to the service.
  88  *
  89  * @param h handle to the peerinfo service
  90  * @param hello the verified (!) HELLO message
  91  * @param cont continuation to call when done, NULL is allowed
  92  * @param cont_cls closure for @a cont
  93  * @return handle to cancel add operation; all pending
  94  *         'add' operations will be cancelled automatically
  95  *        on disconnect, so it is not necessary to keep this
  96  *        handle (unless @a cont is non-NULL and at some point
  97  *        calling @a cont must be prevented)
  98  */
  99 struct GNUNET_MQ_Envelope *
 100 GNUNET_PEERINFO_add_peer (struct GNUNET_PEERINFO_Handle *h,
 101                           const struct GNUNET_HELLO_Message *hello,
 102                           GNUNET_SCHEDULER_TaskCallback cont,
 103                           void *cont_cls);
 104
 105
 106 /**
 107  * Type of an iterator over the hosts.  Note that each
 108  * host will be called with each available protocol.
 109  *
 110  * @param cls closure
 111  * @param peer id of the peer, NULL for last call
 112  * @param hello hello message for the peer (can be NULL)
 113  * @param error message
 114  */
 115 typedef void
 116 (*GNUNET_PEERINFO_Processor) (void *cls,
 117                               const struct GNUNET_PeerIdentity *peer,
 118                               const struct GNUNET_HELLO_Message *hello,
 119                               const char *err_msg);
 120
 121
 122 /**
 123  * Handle for cancellation of iteration over peers.
 124  */
 125 struct GNUNET_PEERINFO_IteratorContext;
 126
 127
 128 /**
 129  * Call a method for each known matching host.  The callback method
 130  * will be invoked once for each matching host and then finally once
 131  * with a NULL pointer.  After that final invocation, the iterator
 132  * context must no longer be used.
 133  *
 134  * Instead of calling this function with `peer == NULL` it is often
 135  * better to use #GNUNET_PEERINFO_notify().
 136  *
 137  * @param h handle to the peerinfo service
 138  * @param include_friend_only include HELLO messages for friends only
 139  * @param peer restrict iteration to this peer only (can be NULL)
 140  * @param timeout how long to wait until timing out
 141  * @param callback the method to call for each peer
 142  * @param callback_cls closure for @a callback
 143  * @return iterator context
 144  */
 145 struct GNUNET_PEERINFO_IteratorContext *
 146 GNUNET_PEERINFO_iterate (struct GNUNET_PEERINFO_Handle *h,
 147                          int include_friend_only,
 148                          const struct GNUNET_PeerIdentity *peer,
 149                          GNUNET_PEERINFO_Processor callback,
 150                          void *callback_cls);
 151
 152
 153 /**
 154  * Cancel an iteration over peer information.
 155  *
 156  * @param ic context of the iterator to cancel
 157  */
 158 void
 159 GNUNET_PEERINFO_iterate_cancel (struct GNUNET_PEERINFO_IteratorContext *ic);
 160
 161
 162 /**
 163  * Handle for notifications about changes to the set of known peers.
 164  */
 165 struct GNUNET_PEERINFO_NotifyContext;
 166
 167
 168 /**
 169  * Call a method whenever our known information about peers
 170  * changes.  Initially calls the given function for all known
 171  * peers and then only signals changes.
 172  *
 173  * If @a include_friend_only is set to #GNUNET_YES peerinfo will include HELLO
 174  * messages which are intended for friend to friend mode and which do not
 175  * have to be gossiped. Otherwise these messages are skipped.
 176  *
 177  * @param cfg configuration to use
 178  * @param include_friend_only include HELLO messages for friends only
 179  * @param callback the method to call for each peer
 180  * @param callback_cls closure for @a callback
 181  * @return NULL on error
 182  */
 183 struct GNUNET_PEERINFO_NotifyContext *
 184 GNUNET_PEERINFO_notify (const struct GNUNET_CONFIGURATION_Handle *cfg,
 185                         int include_friend_only,
 186                         GNUNET_PEERINFO_Processor callback,
 187                         void *callback_cls);
 188
 189
 190 /**
 191  * Stop notifying about changes.
 192  *
 193  * @param nc context to stop notifying
 194  */
 195 void
 196 GNUNET_PEERINFO_notify_cancel (struct GNUNET_PEERINFO_NotifyContext *nc);
 197
 198
 199 #if 0                           /* keep Emacsens' auto-indent happy */
 200 {
 201 #endif
 202 #ifdef __cplusplus
 203 }
 204 #endif
 205
 206 #endif
 207
 208 /** @} */  /* end of group */