X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=src%2Finclude%2Fgnunet_peerinfo_service.h;h=6fc48f806b809830fc9bc7770479c382aa5af1bf;hb=200d05b44a96d6fec00e28736038c838c679f650;hp=463131e6a81b7b3bcd97f4af4e816de6f2c20478;hpb=bb4e48f94a3daba7b0294ce8760a231b0601fa11;p=oweals%2Fgnunet.git diff --git a/src/include/gnunet_peerinfo_service.h b/src/include/gnunet_peerinfo_service.h index 463131e6a..6fc48f806 100644 --- a/src/include/gnunet_peerinfo_service.h +++ b/src/include/gnunet_peerinfo_service.h @@ -1,28 +1,36 @@ /* This file is part of GNUnet - (C) 2009 Christian Grothoff (and other contributing authors) + Copyright (C) 2009, 2010 GNUnet e.V. - GNUnet is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published - by the Free Software Foundation; either version 2, or (at your - option) any later version. + GNUnet is free software: you can redistribute it and/or modify it + under the terms of the GNU Affero General Public License as published + by the Free Software Foundation, either version 3 of the License, + or (at your option) any later version. GNUnet is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - General Public License for more details. + Affero General Public License for more details. + + You should have received a copy of the GNU Affero General Public License + along with this program. If not, see . - You should have received a copy of the GNU General Public License - along with GNUnet; see the file COPYING. If not, write to the - Free Software Foundation, Inc., 59 Temple Place - Suite 330, - Boston, MA 02111-1307, USA. + SPDX-License-Identifier: AGPL3.0-or-later */ /** - * @file include/gnunet_peerinfo_service.h - * @brief Code to maintain the list of currently known hosts - * (in memory structure of data/hosts) and their trust ratings - * (in memory structure of data/trust) * @author Christian Grothoff + * + * @file + * Maintain the list of currently known hosts + * + * @defgroup peerinfo Peer Info service + * Maintain the list of currently known hosts. + * + * Holds an in-memory structure of data/hosts. + * + * @see [Documentation](https://gnunet.org/gnunets-peerinfo-subsystem) + * + * @{ */ #ifndef GNUNET_PEERINFO_SERVICE_H @@ -43,18 +51,59 @@ extern "C" /** - * Add a host to the persistent list. + * Handle to the peerinfo service. + */ +struct GNUNET_PEERINFO_Handle; + + +/** + * Connect to the peerinfo service. * * @param cfg configuration to use - * @param sched scheduler to use - * @param peer identity of the peer - * @param hello the verified (!) HELLO message + * @return NULL on error (configuration related, actual connection + * etablishment may happen asynchronously). + */ +struct GNUNET_PEERINFO_Handle * +GNUNET_PEERINFO_connect (const struct GNUNET_CONFIGURATION_Handle *cfg); + + +/** + * Disconnect from the peerinfo service. Note that all iterators must + * have completed or have been cancelled by the time this function is + * called (otherwise, calling this function is a serious error). + * Furthermore, if #GNUNET_PEERINFO_add_peer() operations are still + * pending, they will be cancelled silently on disconnect. + * + * @param h handle to disconnect */ void -GNUNET_PEERINFO_add_peer (const struct GNUNET_CONFIGURATION_Handle *cfg, - struct GNUNET_SCHEDULER_Handle *sched, - const struct GNUNET_PeerIdentity *peer, - const struct GNUNET_HELLO_Message *hello); +GNUNET_PEERINFO_disconnect (struct GNUNET_PEERINFO_Handle *h); + + +/** + * Add a host to the persistent list. This method operates in + * semi-reliable mode: if the transmission is not completed by + * the time #GNUNET_PEERINFO_disconnect() is called, it will be + * aborted. Furthermore, if a second HELLO is added for the + * same peer before the first one was transmitted, PEERINFO may + * merge the two HELLOs prior to transmission to the service. + * + * @param h handle to the peerinfo service + * @param hello the verified (!) HELLO message + * @param cont continuation to call when done, NULL is allowed + * @param cont_cls closure for @a cont + * @return handle to cancel add operation; all pending + * 'add' operations will be cancelled automatically + * on disconnect, so it is not necessary to keep this + * handle (unless @a cont is non-NULL and at some point + * calling @a cont must be prevented) + */ +struct GNUNET_MQ_Envelope * +GNUNET_PEERINFO_add_peer (struct GNUNET_PEERINFO_Handle *h, + const struct GNUNET_HELLO_Message *hello, + GNUNET_SCHEDULER_TaskCallback cont, + void *cont_cls); + /** * Type of an iterator over the hosts. Note that each @@ -63,42 +112,55 @@ GNUNET_PEERINFO_add_peer (const struct GNUNET_CONFIGURATION_Handle *cfg, * @param cls closure * @param peer id of the peer, NULL for last call * @param hello hello message for the peer (can be NULL) - * @param trust amount of trust we have in the peer + * @param error message */ typedef void - (*GNUNET_PEERINFO_Processor) (void *cls, - const struct GNUNET_PeerIdentity * peer, - const struct GNUNET_HELLO_Message * hello, - uint32_t trust); +(*GNUNET_PEERINFO_Processor) (void *cls, + const struct GNUNET_PeerIdentity *peer, + const struct GNUNET_HELLO_Message *hello, + const char *err_msg); + + +/** + * Handle for cancellation of iteration over peers. + */ +struct GNUNET_PEERINFO_IteratorContext; /** - * Call a method for each known matching host and change - * its trust value. The method will be invoked once for - * each host and then finally once with a NULL pointer. - * Note that the last call can be triggered by timeout or - * by simply being done; however, the trust argument will - * be set to zero if we are done, 1 if we timed out and - * 2 for fatal error. + * Call a method for each known matching host. The callback method + * will be invoked once for each matching host and then finally once + * with a NULL pointer. After that final invocation, the iterator + * context must no longer be used. * - * @param cfg configuration to use - * @param sched scheduler to use + * Instead of calling this function with `peer == NULL` it is often + * better to use #GNUNET_PEERINFO_notify(). + * + * @param h handle to the peerinfo service + * @param include_friend_only include HELLO messages for friends only * @param peer restrict iteration to this peer only (can be NULL) - * @param trust_delta how much to change the trust in all matching peers * @param timeout how long to wait until timing out * @param callback the method to call for each peer - * @param callback_cls closure for callback + * @param callback_cls closure for @a callback + * @return iterator context */ -void -GNUNET_PEERINFO_for_all (const struct GNUNET_CONFIGURATION_Handle *cfg, - struct GNUNET_SCHEDULER_Handle *sched, +struct GNUNET_PEERINFO_IteratorContext * +GNUNET_PEERINFO_iterate (struct GNUNET_PEERINFO_Handle *h, + int include_friend_only, const struct GNUNET_PeerIdentity *peer, - int trust_delta, - struct GNUNET_TIME_Relative timeout, GNUNET_PEERINFO_Processor callback, void *callback_cls); +/** + * Cancel an iteration over peer information. + * + * @param ic context of the iterator to cancel + */ +void +GNUNET_PEERINFO_iterate_cancel (struct GNUNET_PEERINFO_IteratorContext *ic); + + /** * Handle for notifications about changes to the set of known peers. */ @@ -108,21 +170,23 @@ struct GNUNET_PEERINFO_NotifyContext; /** * Call a method whenever our known information about peers * changes. Initially calls the given function for all known - * peers and then only signals changes. Note that it is - * possible (i.e. on disconnects) that the callback is called - * twice with the same peer information. + * peers and then only signals changes. + * + * If @a include_friend_only is set to #GNUNET_YES peerinfo will include HELLO + * messages which are intended for friend to friend mode and which do not + * have to be gossiped. Otherwise these messages are skipped. * * @param cfg configuration to use - * @param sched scheduler to use + * @param include_friend_only include HELLO messages for friends only * @param callback the method to call for each peer - * @param callback_cls closure for callback + * @param callback_cls closure for @a callback * @return NULL on error */ struct GNUNET_PEERINFO_NotifyContext * GNUNET_PEERINFO_notify (const struct GNUNET_CONFIGURATION_Handle *cfg, - struct GNUNET_SCHEDULER_Handle *sched, - GNUNET_PEERINFO_Processor callback, - void *callback_cls); + int include_friend_only, + GNUNET_PEERINFO_Processor callback, + void *callback_cls); /** @@ -141,6 +205,6 @@ GNUNET_PEERINFO_notify_cancel (struct GNUNET_PEERINFO_NotifyContext *nc); } #endif - -/* end of gnunet_peerinfo_service.h */ #endif + +/** @} */ /* end of group */