X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=src%2Finclude%2Fgnunet_peerstore_service.h;h=55f371399f2a44860ac6dd7bd4d008a2bde12f78;hb=f1e8076ed474a429aff32839ed5f8fc20371839c;hp=b802fb3900e35aeb553adaae25c91ecc2cf7b579;hpb=3c9e8b1b0f7f83f27fefb02bd67b481c67cad0c8;p=oweals%2Fgnunet.git diff --git a/src/include/gnunet_peerstore_service.h b/src/include/gnunet_peerstore_service.h index b802fb390..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 @@ -37,6 +43,25 @@ extern "C" #endif #endif +/** + * Options for storing values in PEERSTORE + */ +enum GNUNET_PEERSTORE_StoreOption +{ + + /** + * Possibly store multiple values under given key. + */ + GNUNET_PEERSTORE_STOREOPTION_MULTIPLE = 0, + + /** + * Delete any previous values for the given key before + * storing the given value. + */ + GNUNET_PEERSTORE_STOREOPTION_REPLACE = 1 + +}; + /** * Handle to the peerstore service. */ @@ -61,7 +86,7 @@ struct GNUNET_PEERSTORE_Record /** * Peer Identity */ - struct GNUNET_PeerIdentity *peer; + struct GNUNET_PeerIdentity peer; /** * Record key string @@ -74,42 +99,46 @@ 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 for each matching record. + * Function called by PEERSTORE for each matching record. * * @param cls closure - * @param peer peer identity - * @param sub_system name of the GNUnet sub system responsible - * @param value stored value - * @param size size of stored value - * @return #GNUNET_YES to continue iterating, #GNUNET_NO to stop - */ -typedef int (*GNUNET_PEERSTORE_Processor) (void *cls, - const char *sub_system, - const struct GNUNET_PeerIdentity *peer, - const char *key, - const void *value, - size_t size, - struct GNUNET_TIME_Absolute expiry); + * @param record peerstore record information + * @param emsg error message, or NULL if no errors + */ +typedef void +(*GNUNET_PEERSTORE_Processor) (void *cls, + const struct GNUNET_PEERSTORE_Record *record, + const char *emsg); + /** * Connect to the PEERSTORE service. @@ -119,37 +148,48 @@ 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 + * Disconnect from the PEERSTORE service. Any pending ITERATE and WATCH requests + * will be canceled. + * Any pending STORE requests will depend on @e snyc_first flag. * * @param h handle to disconnect + * @param sync_first send any pending STORE requests before disconnecting */ void -GNUNET_PEERSTORE_disconnect(struct GNUNET_PEERSTORE_Handle *h); +GNUNET_PEERSTORE_disconnect (struct GNUNET_PEERSTORE_Handle *h, + int sync_first); + /** - * Store a new entry in the PEERSTORE + * Store a new entry in the PEERSTORE. + * Note that stored entries can be lost in some cases + * such as power failure. * * @param h Handle to the PEERSTORE service * @param sub_system name of the sub system * @param peer Peer Identity * @param key entry key * @param value entry value BLOB - * @param size size of 'value' - * @param lifetime relative time after which the entry is (possibly) deleted - * @param cont Continuation function after the store request is processed - * @param cont_cls Closure for 'cont' + * @param size size of @e value + * @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 @a cont */ struct GNUNET_PEERSTORE_StoreContext * GNUNET_PEERSTORE_store (struct GNUNET_PEERSTORE_Handle *h, - const char *sub_system, - const struct GNUNET_PeerIdentity *peer, - const char *key, - const void *value, - size_t size, - struct GNUNET_TIME_Absolute expiry, - GNUNET_PEERSTORE_Continuation cont, - void *cont_cls); + const char *sub_system, + const struct GNUNET_PeerIdentity *peer, + const char *key, + const void *value, + size_t size, + struct GNUNET_TIME_Absolute expiry, + enum GNUNET_PEERSTORE_StoreOption options, + GNUNET_PEERSTORE_Continuation cont, + void *cont_cls); + /** * Cancel a store request @@ -159,6 +199,66 @@ 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 + * + * @param h handle to the PEERSTORE service + * @param sub_system name of sub system + * @param peer Peer identity (can be NULL) + * @param key entry key string (can be NULL) + * @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, + GNUNET_PEERSTORE_Processor callback, + void *callback_cls); + + +/** + * Cancel an iterate request + * Please do not call after the iterate request is done + * + * @param ic Iterate request context as returned by GNUNET_PEERSTORE_iterate() + */ +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. + * + * @param h handle to the PEERSTORE service + * @param sub_system name of sub system + * @param peer Peer identity + * @param key entry key string + * @param callback function called with each new value + * @param callback_cls closure for @a callback + * @return Handle to watch request + */ +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); + + +/** + * Cancel a watch request + * + * @param wc handle to the watch request + */ +void +GNUNET_PEERSTORE_watch_cancel (struct GNUNET_PEERSTORE_WatchContext *wc); + + #if 0 /* keep Emacsens' auto-indent happy */ { #endif @@ -167,3 +267,5 @@ GNUNET_PEERSTORE_store_cancel (struct GNUNET_PEERSTORE_StoreContext *sc); #endif #endif + +/** @} */ /* end of group */