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