X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=src%2Finclude%2Fgnunet_gns_service.h;h=8a1099444075b367477cd605605a0361eaa19136;hb=17047b7bcbe3f1756028058a9887416c6afab5d8;hp=780ddbcca80a31ee28f29c85974ebea40503ab6b;hpb=18805673bf25fb6924280a54754e240a1402f46f;p=oweals%2Fgnunet.git diff --git a/src/include/gnunet_gns_service.h b/src/include/gnunet_gns_service.h index 780ddbcca..8a1099444 100644 --- a/src/include/gnunet_gns_service.h +++ b/src/include/gnunet_gns_service.h @@ -1,6 +1,6 @@ /* This file is part of GNUnet - (C) 2012 Christian Grothoff (and other contributing authors) + Copyright (C) 2012-2014 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 @@ -14,26 +14,29 @@ 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. + Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, + Boston, MA 02110-1301, USA. */ /** - * @file include/gnunet_gns_service.h - * @brief API to the GNS service * @author Martin Schanzenbach * - * TODO: - * - decide what goes into storage API and what into GNS-service API - * - decide where to pass/expose/check keys / signatures - * - are GNS private keys per peer or per user? + * @file + * API to the GNS service + * + * @defgroup gns GNS service + * GNU Name System + * + * @see [Documentation](https://gnunet.org/gns-implementation) + * + * @{ */ - - #ifndef GNUNET_GNS_SERVICE_H #define GNUNET_GNS_SERVICE_H #include "gnunet_util_lib.h" +#include "gnunet_dnsparser_lib.h" +#include "gnunet_namestore_service.h" #ifdef __cplusplus extern "C" @@ -45,43 +48,30 @@ extern "C" /** - * Connection to the GNS service. + * String we use to indicate the local master zone or a + * root entry in the current zone. */ -struct GNUNET_GNS_Handle; +#define GNUNET_GNS_MASTERZONE_STR "+" /** - * Handle to control a get operation. + * Connection to the GNS service. */ -struct GNUNET_GNS_LookupHandle; +struct GNUNET_GNS_Handle; /** - * A single GNS record. + * Handle to control a lookup operation. */ -struct GNUNET_GNS_Record; +struct GNUNET_GNS_LookupRequest; -/** - * Records types - */ -enum GNUNET_GNS_RecordType -{ - // FIXME: should be based on GNUNET_DNSPARSER_TYPE's (standard DNS), - // and then maybe our extensions in the area > 255? - GNUNET_GNS_RECORD_A, - GNUNET_GNS_RECORD_AAAA, - GNUNET_GNS_RECORD_MX, - GNUNET_GNS_RECORD_PKEY -}; /** * Initialize the connection with the GNS service. * * @param cfg configuration to use - * @param ht_len size of the internal hash table to use for parallel lookups - * @return NULL on error + * @return handle to the GNS service, or NULL on error */ struct GNUNET_GNS_Handle * -GNUNET_GNS_connect (const struct GNUNET_CONFIGURATION_Handle *cfg - unsigned int ht_len); +GNUNET_GNS_connect (const struct GNUNET_CONFIGURATION_Handle *cfg); /** @@ -93,105 +83,104 @@ void GNUNET_GNS_disconnect (struct GNUNET_GNS_Handle *handle); -/* *************** Standard API: add and lookup ******************* */ - /** - * Perform an add operation storing records in the GNS. + * Iterator called on obtained result for a GNS lookup. * - * FIXME: Yes, we need this kind of API, but should it not be with the - * NameDataStore, rather than the GNS-service? - * - * @param handle handle to GNS service - * @param name the key to store under - * // FIXME: need to be precise here what 'name' is. Does it - // include '.gnunet'? What happens if we specify 'a.b.c.gnunet' - // but 'b.c.gnunet' has been delegated? (error?) - * @param desired_replication_level estimate of how many - * nearest peers this request should reach - * @param options routing options for this message - // FIXME: which are? where is the arg? - // FIXME: we should probably distinguish between 'private' and 'public' - // records; - * @param type type of the value - * @param size number of bytes in data; must be less than 64k - * @param data the data to store - // FIXME: what is the exact format of data? - * @param exp desired expiration time for the value - * @param timeout how long to wait for transmission of this request - * @param cont continuation to call when done (transmitting request to service) - * @param cont_cls closure for cont - * // FIXME: where are the continuations? + * @param cls closure + * @param rd_count number of records in @a rd + * @param rd the records in reply */ -void -GNUNET_GNS_add_record (struct GNUNET_GNS_Handle *handle, - const char* name, - enum GNUNET_GNS_RecordType type, - size_t size, const char *data, - struct GNUNET_TIME_Absolute exp, - struct GNUNET_TIME_Relative timeout); - +typedef void (*GNUNET_GNS_LookupResultProcessor) (void *cls, + uint32_t rd_count, + const struct GNUNET_GNSRECORD_Data *rd); /** - * Iterator called on each result obtained for a GNS - * operation that expects a reply TODO: eh? - * + * Iterator called on obtained result for a GNS lookup. * * @param cls closure - * @param exp when will this value expire - * @param key key of the result - * // how does the key relate to the name exactly? Why not give the name? - * @param record the records in reply - * // FIXME: shouldn't this then be an array of pointers? - * @param num_records the number of records in reply - * @param type type of the result - * // FIXME: not in signature + * @param rd_count number of records in @a rd + * @param rd the records in reply + */ +typedef void (*GNUNET_GNS_ReverseLookupResultProcessor) (void *cls, + const char* name); + + +/** + * Options for the GNS lookup. */ -typedef void (*GNUNET_GNS_LookupIterator) (void *cls, - const GNUNET_HashCode * key, - const struct GNUNET_GNS_Record *record, - unsigned int num_records); +enum GNUNET_GNS_LocalOptions +{ + /** + * Defaults, look in cache, then in DHT. + */ + GNUNET_GNS_LO_DEFAULT = 0, + + /** + * Never look in the DHT, keep request to local cache. + */ + GNUNET_GNS_LO_NO_DHT = 1, + + /** + * For the rightmost label, only look in the cache (it + * is our master zone), for the others, the DHT is OK. + */ + GNUNET_GNS_LO_LOCAL_MASTER = 2 +}; /** * Perform an asynchronous lookup operation on the GNS. * * @param handle handle to the GNS service - * @param timeout how long to wait for transmission of this request to the service - * // FIXME: what happens afterwards? - * @param type expected type of the response object - * @param key the key to look up - * // FIXME: key, name, what format? - * @param desired_replication_level estimate of how many - nearest peers this request should reach - * @param options routing options for this message - * //FIXME: missmatch between documented and actual options... - * @param xquery extended query data (can be NULL, depending on type) - * @param xquery_size number of bytes in xquery - * @param iter function to call on each result - * @param iter_cls closure for iter + * @param name the name to look up + * @param zone zone to look in + * @param type the GNS record type to look for + * @param options local options for the lookup + * @param shorten_zone_key the private key of the shorten zone (can be NULL); + * specify to enable automatic shortening (given a PSEU + * record, if a given pseudonym is not yet used in the + * shorten zone, we automatically add the respective zone + * under that name) + * @param proc function to call on result + * @param proc_cls closure for processor + * @return handle to the queued request + */ +struct GNUNET_GNS_LookupRequest * +GNUNET_GNS_lookup (struct GNUNET_GNS_Handle *handle, + const char *name, + const struct GNUNET_CRYPTO_EcdsaPublicKey *zone, + uint32_t type, + enum GNUNET_GNS_LocalOptions options, + const struct GNUNET_CRYPTO_EcdsaPrivateKey *shorten_zone_key, + GNUNET_GNS_LookupResultProcessor proc, + void *proc_cls); + +/** + * Perform an asynchronous reverse lookup operation on the GNS. * - * @return handle to stop the async get + * @param handle handle to the GNS service + * @param zone_key zone to find a name for + * @param root_key our zone + * @param proc processor to call on result + * @param proc_cls closure for @a proc + * @return handle to the request */ -struct GNUNET_GNS_LookupHandle * -GNUNET_GNS_lookup_start (struct GNUNET_GNS_Handle *handle, - struct GNUNET_TIME_Relative timeout, - const char * name, - enum GNUNET_GNS_RecordType type, - GNUNET_GNS_LookupIterator iter, - void *iter_cls); +struct GNUNET_GNS_ReverseLookupRequest* +GNUNET_GNS_reverse_lookup (struct GNUNET_GNS_Handle *handle, + const struct GNUNET_CRYPTO_EcdsaPublicKey *zone_key, + const struct GNUNET_CRYPTO_EcdsaPublicKey *root_key, + GNUNET_GNS_ReverseLookupResultProcessor proc, + void *proc_cls); /** - * Stop async GNS lookup. Frees associated resources. - * - * @param lookup_handle lookup operation to stop. + * Cancel pending lookup request * - * On return lookup_handle will no longer be valid, caller - * must not use again!!! + * @param lr the lookup request to cancel */ void -GNUNET_GNS_lookup_stop (struct GNUNET_GNS_LookupHandle *lookup_handle); +GNUNET_GNS_lookup_cancel (struct GNUNET_GNS_LookupRequest *lr); #if 0 /* keep Emacsens' auto-indent happy */ @@ -201,6 +190,6 @@ GNUNET_GNS_lookup_stop (struct GNUNET_GNS_LookupHandle *lookup_handle); } #endif - #endif -/* gnunet_gns_service.h */ + +/** @} */ /* end of group */