X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=src%2Finclude%2Fgnunet_peerstore_service.h;h=55f371399f2a44860ac6dd7bd4d008a2bde12f78;hb=f1e8076ed474a429aff32839ed5f8fc20371839c;hp=fcd0bb5f295604220b52a91e2001d671349186de;hpb=c057bd312c783e0a2f3783dfd888a66f490b0a30;p=oweals%2Fgnunet.git diff --git a/src/include/gnunet_peerstore_service.h b/src/include/gnunet_peerstore_service.h index fcd0bb5f2..55f371399 100644 --- a/src/include/gnunet_peerstore_service.h +++ b/src/include/gnunet_peerstore_service.h @@ -1,32 +1,38 @@ /* This file is part of GNUnet - (C) + Copyright (C) - 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_peerstore_service.h - * @brief API to the peerstore service * @author Omar Tarabai + * + * @file + * API to the peerstore service + * + * @defgroup peerstore Peer Store service + * + * @see [Documentation](https://gnunet.org/gnunets-peerstore-subsystem) + * + * @{ */ #ifndef GNUNET_PEERSTORE_SERVICE_H #define GNUNET_PEERSTORE_SERVICE_H -#include "platform.h" #include "gnunet_util_lib.h" #ifdef __cplusplus @@ -46,13 +52,13 @@ enum GNUNET_PEERSTORE_StoreOption /** * Possibly store multiple values under given key. */ - GNUNET_PEERSTORE_STOREOPTION_MULTIPLE, + GNUNET_PEERSTORE_STOREOPTION_MULTIPLE = 0, /** * Delete any previous values for the given key before * storing the given value. */ - GNUNET_PEERSTORE_STOREOPTION_REPLACE, + GNUNET_PEERSTORE_STOREOPTION_REPLACE = 1 }; @@ -80,7 +86,7 @@ struct GNUNET_PEERSTORE_Record /** * Peer Identity */ - struct GNUNET_PeerIdentity *peer; + struct GNUNET_PeerIdentity peer; /** * Record key string @@ -93,24 +99,33 @@ struct GNUNET_PEERSTORE_Record void *value; /** - * Size of 'value' BLOB + * Size of @e value BLOB */ size_t value_size; /** * Expiry time of entry */ - struct GNUNET_TIME_Absolute *expiry; + struct GNUNET_TIME_Absolute expiry; + /** + * Client from which this record originated. + * NOTE: This is internal to the service. + */ + struct GNUNET_SERVICE_Client *client; }; + /** * Continuation called with a status result. * * @param cls closure * @param success #GNUNET_OK or #GNUNET_SYSERR */ -typedef void (*GNUNET_PEERSTORE_Continuation)(void *cls, int success); +typedef void +(*GNUNET_PEERSTORE_Continuation)(void *cls, + int success); + /** * Function called by PEERSTORE for each matching record. @@ -118,11 +133,12 @@ typedef void (*GNUNET_PEERSTORE_Continuation)(void *cls, int success); * @param cls closure * @param record peerstore record information * @param emsg error message, or NULL if no errors - * @return #GNUNET_YES to continue iterating, #GNUNET_NO to stop */ -typedef int (*GNUNET_PEERSTORE_Processor) (void *cls, - struct GNUNET_PEERSTORE_Record *record, - char *emsg); +typedef void +(*GNUNET_PEERSTORE_Processor) (void *cls, + const struct GNUNET_PEERSTORE_Record *record, + const char *emsg); + /** * Connect to the PEERSTORE service. @@ -132,6 +148,7 @@ typedef int (*GNUNET_PEERSTORE_Processor) (void *cls, struct GNUNET_PEERSTORE_Handle * GNUNET_PEERSTORE_connect (const struct GNUNET_CONFIGURATION_Handle *cfg); + /** * Disconnect from the PEERSTORE service. Any pending ITERATE and WATCH requests * will be canceled. @@ -141,7 +158,9 @@ GNUNET_PEERSTORE_connect (const struct GNUNET_CONFIGURATION_Handle *cfg); * @param sync_first send any pending STORE requests before disconnecting */ void -GNUNET_PEERSTORE_disconnect (struct GNUNET_PEERSTORE_Handle *h, int sync_first); +GNUNET_PEERSTORE_disconnect (struct GNUNET_PEERSTORE_Handle *h, + int sync_first); + /** * Store a new entry in the PEERSTORE. @@ -157,7 +176,7 @@ GNUNET_PEERSTORE_disconnect (struct GNUNET_PEERSTORE_Handle *h, int sync_first); * @param expiry absolute time after which the entry is (possibly) deleted * @param options options specific to the storage operation * @param cont Continuation function after the store request is sent - * @param cont_cls Closure for 'cont' + * @param cont_cls Closure for @a cont */ struct GNUNET_PEERSTORE_StoreContext * GNUNET_PEERSTORE_store (struct GNUNET_PEERSTORE_Handle *h, @@ -171,6 +190,7 @@ GNUNET_PEERSTORE_store (struct GNUNET_PEERSTORE_Handle *h, GNUNET_PEERSTORE_Continuation cont, void *cont_cls); + /** * Cancel a store request * @@ -179,6 +199,7 @@ GNUNET_PEERSTORE_store (struct GNUNET_PEERSTORE_Handle *h, void GNUNET_PEERSTORE_store_cancel (struct GNUNET_PEERSTORE_StoreContext *sc); + /** * Iterate over records matching supplied key information * @@ -186,17 +207,17 @@ GNUNET_PEERSTORE_store_cancel (struct GNUNET_PEERSTORE_StoreContext *sc); * @param sub_system name of sub system * @param peer Peer identity (can be NULL) * @param key entry key string (can be NULL) - * @param timeout time after which the iterate request is canceled * @param callback function called with each matching record, all NULL's on end * @param callback_cls closure for @a callback */ struct GNUNET_PEERSTORE_IterateContext * GNUNET_PEERSTORE_iterate (struct GNUNET_PEERSTORE_Handle *h, - const char *sub_system, - const struct GNUNET_PeerIdentity *peer, - const char *key, - struct GNUNET_TIME_Relative timeout, - GNUNET_PEERSTORE_Processor callback, void *callback_cls); + const char *sub_system, + const struct GNUNET_PeerIdentity *peer, + const char *key, + GNUNET_PEERSTORE_Processor callback, + void *callback_cls); + /** * Cancel an iterate request @@ -207,9 +228,10 @@ GNUNET_PEERSTORE_iterate (struct GNUNET_PEERSTORE_Handle *h, void GNUNET_PEERSTORE_iterate_cancel (struct GNUNET_PEERSTORE_IterateContext *ic); + /** * Request watching a given key - * User will be notified with any new values added to key + * User will be notified with any new values added to key. * * @param h handle to the PEERSTORE service * @param sub_system name of sub system @@ -221,10 +243,12 @@ GNUNET_PEERSTORE_iterate_cancel (struct GNUNET_PEERSTORE_IterateContext *ic); */ struct GNUNET_PEERSTORE_WatchContext * GNUNET_PEERSTORE_watch (struct GNUNET_PEERSTORE_Handle *h, - const char *sub_system, - const struct GNUNET_PeerIdentity *peer, - const char *key, - GNUNET_PEERSTORE_Processor callback, void *callback_cls); + const char *sub_system, + const struct GNUNET_PeerIdentity *peer, + const char *key, + GNUNET_PEERSTORE_Processor callback, + void *callback_cls); + /** * Cancel a watch request @@ -232,7 +256,8 @@ GNUNET_PEERSTORE_watch (struct GNUNET_PEERSTORE_Handle *h, * @param wc handle to the watch request */ void -GNUNET_PEERSTORE_watch_cancel(struct GNUNET_PEERSTORE_WatchContext *wc); +GNUNET_PEERSTORE_watch_cancel (struct GNUNET_PEERSTORE_WatchContext *wc); + #if 0 /* keep Emacsens' auto-indent happy */ { @@ -242,3 +267,5 @@ GNUNET_PEERSTORE_watch_cancel(struct GNUNET_PEERSTORE_WatchContext *wc); #endif #endif + +/** @} */ /* end of group */