X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=src%2Finclude%2Fgnunet_peerstore_service.h;h=261d2d34f04a9b07b713e5eb71b9fa2317a392e3;hb=ec50a665dc884f7997419d0351ae8ade9c1aeabe;hp=1fd068d270aab9fe6707fac3b0eaf3d361012f62;hpb=36367311686410711f46fa3d82484a609c888acf;p=oweals%2Fgnunet.git diff --git a/src/include/gnunet_peerstore_service.h b/src/include/gnunet_peerstore_service.h index 1fd068d27..261d2d34f 100644 --- a/src/include/gnunet_peerstore_service.h +++ b/src/include/gnunet_peerstore_service.h @@ -1,32 +1,36 @@ /* 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. - - 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. + 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 . */ /** - * @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,23 +41,223 @@ 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. */ struct GNUNET_PEERSTORE_Handle; /** - * Context for add requests + * Context for a store request */ -struct GNUNET_PEERSTORE_AddContext; +struct GNUNET_PEERSTORE_StoreContext; + +/** + * Single PEERSTORE record + */ +struct GNUNET_PEERSTORE_Record +{ + + /** + * Responsible sub system string + */ + char *sub_system; + + /** + * Peer Identity + */ + struct GNUNET_PeerIdentity peer; + + /** + * Record key string + */ + char *key; + + /** + * Record value BLOB + */ + void *value; + + /** + * Size of @e value BLOB + */ + size_t value_size; + + /** + * Expiry time of entry + */ + 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 emsg error message, NULL on success + * @param success #GNUNET_OK or #GNUNET_SYSERR + */ +typedef void +(*GNUNET_PEERSTORE_Continuation)(void *cls, + int success); + + +/** + * Function called by PEERSTORE for each matching record. + * + * @param cls closure + * @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. + * + * @return NULL on error + */ +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. + * 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, + int sync_first); + + +/** + * 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 @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, + enum GNUNET_PEERSTORE_StoreOption options, + GNUNET_PEERSTORE_Continuation cont, + void *cont_cls); + + +/** + * Cancel a store request + * + * @param sc Store request context + */ +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 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); + + +/** + * 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 */ -typedef void (*GNUNET_PEERSTORE_Continuation)(void *cls, const char *emsg); +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 */ { @@ -63,3 +267,5 @@ typedef void (*GNUNET_PEERSTORE_Continuation)(void *cls, const char *emsg); #endif #endif + +/** @} */ /* end of group */