X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=src%2Finclude%2Fgnunet_peerinfo_service.h;h=6fc48f806b809830fc9bc7770479c382aa5af1bf;hb=200d05b44a96d6fec00e28736038c838c679f650;hp=49ba916001ab76c3bfecec34c6120f70a5bb3a1d;hpb=31fa7ff21510bad20198b2e6d2b93d62d7624394;p=oweals%2Fgnunet.git diff --git a/src/include/gnunet_peerinfo_service.h b/src/include/gnunet_peerinfo_service.h index 49ba91600..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 @@ -62,7 +71,7 @@ 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 @@ -71,26 +80,10 @@ void GNUNET_PEERINFO_disconnect (struct GNUNET_PEERINFO_Handle *h); -/** - * Continuation called with a status result. - * - * @param cls closure - * @param emsg error message, NULL on success - */ -typedef void (*GNUNET_PEERINFO_Continuation)(void *cls, - const char *emsg); - - -/** - * Opaque handle to cancel 'add' operation. - */ -struct GNUNET_PEERINFO_AddContext; - - /** * 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. @@ -98,30 +91,20 @@ struct GNUNET_PEERINFO_AddContext; * @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 'cont' + * @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 'cont' is NULL and at some point - * calling 'cont' must be prevented) + * handle (unless @a cont is non-NULL and at some point + * calling @a cont must be prevented) */ -struct GNUNET_PEERINFO_AddContext * +struct GNUNET_MQ_Envelope * GNUNET_PEERINFO_add_peer (struct GNUNET_PEERINFO_Handle *h, const struct GNUNET_HELLO_Message *hello, - GNUNET_PEERINFO_Continuation cont, + GNUNET_SCHEDULER_TaskCallback cont, void *cont_cls); -/** - * Cancel pending 'add' operation. Must only be called before - * either 'cont' or 'GNUNET_PEERINFO_disconnect' are invoked. - * - * @param ac handle for the add operation to cancel - */ -void -GNUNET_PEERINFO_add_peer_cancel (struct GNUNET_PEERINFO_AddContext *ac); - - /** * Type of an iterator over the hosts. Note that each * host will be called with each available protocol. @@ -131,11 +114,11 @@ GNUNET_PEERINFO_add_peer_cancel (struct GNUNET_PEERINFO_AddContext *ac); * @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, const char *err_msg); +typedef void +(*GNUNET_PEERINFO_Processor) (void *cls, + const struct GNUNET_PeerIdentity *peer, + const struct GNUNET_HELLO_Message *hello, + const char *err_msg); /** @@ -145,31 +128,30 @@ struct GNUNET_PEERINFO_IteratorContext; /** - * Call a method for each known matching host to get its HELLO. - * 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, + int include_friend_only, const struct GNUNET_PeerIdentity *peer, - struct GNUNET_TIME_Relative timeout, GNUNET_PEERINFO_Processor callback, void *callback_cls); - /** * Cancel an iteration over peer information. * @@ -179,7 +161,6 @@ void GNUNET_PEERINFO_iterate_cancel (struct GNUNET_PEERINFO_IteratorContext *ic); - /** * Handle for notifications about changes to the set of known peers. */ @@ -189,18 +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); /** @@ -219,6 +205,6 @@ GNUNET_PEERINFO_notify_cancel (struct GNUNET_PEERINFO_NotifyContext *nc); } #endif - -/* end of gnunet_peerinfo_service.h */ #endif + +/** @} */ /* end of group */