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