X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=src%2Finclude%2Fgnunet_peerinfo_service.h;h=6fc48f806b809830fc9bc7770479c382aa5af1bf;hb=200d05b44a96d6fec00e28736038c838c679f650;hp=1c34d83bb1c02f975a36e0afe9660532ff51099c;hpb=ebf8ce753640b069180eadd7abf47d9a9a371a29;p=oweals%2Fgnunet.git diff --git a/src/include/gnunet_peerinfo_service.h b/src/include/gnunet_peerinfo_service.h index 1c34d83bb..6fc48f806 100644 --- a/src/include/gnunet_peerinfo_service.h +++ b/src/include/gnunet_peerinfo_service.h @@ -1,27 +1,36 @@ /* This file is part of GNUnet - (C) 2009, 2010 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 3, 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). * @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 @@ -56,14 +65,13 @@ struct GNUNET_PEERINFO_Handle; */ 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 + * Furthermore, if #GNUNET_PEERINFO_add_peer() operations are still * pending, they will be cancelled silently on disconnect. * * @param h handle to disconnect @@ -73,19 +81,28 @@ GNUNET_PEERINFO_disconnect (struct GNUNET_PEERINFO_Handle *h); /** - * Add a host to the persistent list. This method operates in + * 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 + * 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) */ -void +struct GNUNET_MQ_Envelope * GNUNET_PEERINFO_add_peer (struct GNUNET_PEERINFO_Handle *h, - const struct GNUNET_HELLO_Message *hello); + const struct GNUNET_HELLO_Message *hello, + GNUNET_SCHEDULER_TaskCallback cont, + void *cont_cls); /** @@ -95,11 +112,13 @@ GNUNET_PEERINFO_add_peer (struct GNUNET_PEERINFO_Handle *h, * @param cls closure * @param peer id of the peer, NULL for last call * @param hello hello message for the peer (can be NULL) + * @param error message */ typedef void - (*GNUNET_PEERINFO_Processor) (void *cls, - const struct GNUNET_PeerIdentity * peer, - const struct GNUNET_HELLO_Message * hello); +(*GNUNET_PEERINFO_Processor) (void *cls, + const struct GNUNET_PeerIdentity *peer, + const struct GNUNET_HELLO_Message *hello, + const char *err_msg); /** @@ -109,29 +128,28 @@ struct GNUNET_PEERINFO_IteratorContext; /** - * Call a method for each known matching host and change its trust - * value. 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. + * 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. + * + * Instead of calling this function with `peer == NULL` it is often + * better to use #GNUNET_PEERINFO_notify(). * - * 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 timeout how long to wait until timing out * @param callback the method to call for each peer - * @param callback_cls closure for callback - * @return NULL on error (in this case, 'callback' is never called!), - * otherwise an iterator context + * @param callback_cls closure for @a callback + * @return iterator context */ struct GNUNET_PEERINFO_IteratorContext * GNUNET_PEERINFO_iterate (struct GNUNET_PEERINFO_Handle *h, - const struct GNUNET_PeerIdentity *peer, - struct GNUNET_TIME_Relative timeout, - GNUNET_PEERINFO_Processor callback, - void *callback_cls); - + int include_friend_only, + const struct GNUNET_PeerIdentity *peer, + GNUNET_PEERINFO_Processor callback, + void *callback_cls); /** @@ -143,7 +161,6 @@ void GNUNET_PEERINFO_iterate_cancel (struct GNUNET_PEERINFO_IteratorContext *ic); - /** * Handle for notifications about changes to the set of known peers. */ @@ -153,19 +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 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, - GNUNET_PEERINFO_Processor callback, - void *callback_cls); + int include_friend_only, + GNUNET_PEERINFO_Processor callback, + void *callback_cls); /** @@ -184,6 +205,6 @@ GNUNET_PEERINFO_notify_cancel (struct GNUNET_PEERINFO_NotifyContext *nc); } #endif - -/* end of gnunet_peerinfo_service.h */ #endif + +/** @} */ /* end of group */