X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=src%2Finclude%2Fgnunet_gns_service.h;h=b6fac6111b3a2c2dbc5f3d508f271977fc440dc1;hb=418bf5953acdba2e325528d739fb115b51b7141f;hp=3e3d140b9a9c3a0c8bcb3e79250243414483a518;hpb=e5e65405bdff8e86535676dd7b84f3db9759de42;p=oweals%2Fgnunet.git diff --git a/src/include/gnunet_gns_service.h b/src/include/gnunet_gns_service.h index 3e3d140b9..b6fac6111 100644 --- a/src/include/gnunet_gns_service.h +++ b/src/include/gnunet_gns_service.h @@ -1,31 +1,34 @@ /* This file is part of GNUnet - (C) 2012 Christian Grothoff (and other contributing authors) + Copyright (C) 2012-2014, 2017 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. - - 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_gns_service.h - * @brief API to the GNS service * @author Martin Schanzenbach * + * @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 @@ -42,6 +45,12 @@ extern "C" #endif +/** + * String we use to indicate an empty label (top-level + * entry in the zone). DNS uses "@", so do we. + */ +#define GNUNET_GNS_EMPTY_LABEL_AT "@" + /** * Connection to the GNS service. */ @@ -53,71 +62,16 @@ struct GNUNET_GNS_Handle; struct GNUNET_GNS_LookupRequest; /** - * Handle to control a shorten operation. + * Handle to control a lookup operation where the + * TLD is resolved to a zone as part of the lookup operation. */ -struct GNUNET_GNS_ShortenRequest; - -/** - * Handle to control a get authority operation - */ -struct GNUNET_GNS_GetAuthRequest; - -/** - * Record types - * Based on GNUNET_DNSPARSER_TYPEs (standard DNS) - */ -enum GNUNET_GNS_RecordType -{ - /* Standard DNS */ - /* struct in_addr */ - GNUNET_GNS_RECORD_A = GNUNET_DNSPARSER_TYPE_A, - - /* char */ - GNUNET_GNS_RECORD_NS = GNUNET_DNSPARSER_TYPE_NS, - - /* char */ - GNUNET_GNS_RECORD_CNAME = GNUNET_DNSPARSER_TYPE_CNAME, - - /* struct soa_data */ - GNUNET_GNS_RECORD_SOA = GNUNET_DNSPARSER_TYPE_SOA, - - /* struct srv_data */ - GNUNET_GNS_RECORD_SRV = GNUNET_DNSPARSER_TYPE_SRV, - - /* char */ - GNUNET_GNS_RECORD_PTR = GNUNET_DNSPARSER_TYPE_PTR, - - /* uint16_t, char */ - GNUNET_GNS_RECORD_MX = GNUNET_DNSPARSER_TYPE_MX, - - /* char */ - GNUNET_GNS_RECORD_TXT = GNUNET_DNSPARSER_TYPE_TXT, - - /* struct in6_addr */ - GNUNET_GNS_RECORD_AAAA = GNUNET_DNSPARSER_TYPE_AAAA, - - /* GNS specific */ - /* struct GNUNET_CRYPTO_ShortHashCode */ - GNUNET_GNS_RECORD_PKEY = GNUNET_NAMESTORE_TYPE_PKEY, - - /* char */ - GNUNET_GNS_RECORD_PSEU = GNUNET_NAMESTORE_TYPE_PSEU, - GNUNET_GNS_RECORD_ANY = GNUNET_NAMESTORE_TYPE_ANY, - - /* char */ - GNUNET_GNS_RECORD_LEHO = GNUNET_NAMESTORE_TYPE_LEHO, - - /* struct vpn_data */ - GNUNET_GNS_RECORD_VPN = GNUNET_NAMESTORE_TYPE_VPN, - GNUNET_GNS_RECORD_REV = GNUNET_NAMESTORE_TYPE_REV -}; +struct GNUNET_GNS_LookupWithTldRequest; /** * Initialize the connection with the GNS service. * * @param cfg configuration to use - * * @return handle to the GNS service, or NULL on error */ struct GNUNET_GNS_Handle * @@ -133,183 +87,124 @@ void GNUNET_GNS_disconnect (struct GNUNET_GNS_Handle *handle); -/* *************** Standard API: lookup ******************* */ - /** - * Iterator called on obtained result for a GNS - * lookup + * Iterator called on obtained result for a GNS lookup. * * @param cls closure - * @param rd_count number of records + * @param rd_count number of records in @a rd * @param rd the records in reply */ -typedef void (*GNUNET_GNS_LookupResultProcessor) (void *cls, - uint32_t rd_count, - const struct GNUNET_NAMESTORE_RecordData *rd); - +typedef void +(*GNUNET_GNS_LookupResultProcessor) (void *cls, + uint32_t rd_count, + const struct GNUNET_GNSRECORD_Data *rd); /** - * Perform an asynchronous lookup operation on the GNS - * in the default zone. - * - * @param handle handle to the GNS service - * @param name the name to look up - * @param type the GNUNET_GNS_RecordType to look for - * @param only_cached GNUNET_NO to only check locally not DHT for performance - * @param shorten_key the private key of the shorten zone (can be NULL) - * @param proc function to call on result - * @param proc_cls closure for processor - * - * @return handle to the queued request + * Options for the GNS lookup. */ -struct GNUNET_GNS_LookupRequest* -GNUNET_GNS_lookup (struct GNUNET_GNS_Handle *handle, - const char * name, - enum GNUNET_GNS_RecordType type, - int only_cached, - struct GNUNET_CRYPTO_RsaPrivateKey *shorten_key, - GNUNET_GNS_LookupResultProcessor proc, - void *proc_cls); +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 local namestore), for the others, the DHT is OK. + */ + GNUNET_GNS_LO_LOCAL_MASTER = 2 + +}; /** - * Perform an asynchronous lookup operation on the GNS - * in the zone specified by 'zone'. + * Perform an asynchronous lookup operation on the GNS. * * @param handle handle to the GNS service * @param name the name to look up - * @param zone the zone to start the resolution in - * @param type the GNUNET_GNS_RecordType to look for - * @param only_cached GNUNET_YES to only check locally not DHT for performance - * @param shorten_key the private key of the shorten zone (can be NULL) + * @param zone zone to look in + * @param type the GNS record type to look for + * @param options local options for the lookup * @param proc function to call on result - * @param proc_cls closure for processor - * + * @param proc_cls closure for @a proc * @return handle to the queued request */ -struct GNUNET_GNS_LookupRequest* -GNUNET_GNS_lookup_zone (struct GNUNET_GNS_Handle *handle, - const char * name, - struct GNUNET_CRYPTO_ShortHashCode *zone, - enum GNUNET_GNS_RecordType type, - int only_cached, - struct GNUNET_CRYPTO_RsaPrivateKey *shorten_key, - GNUNET_GNS_LookupResultProcessor proc, - void *proc_cls); +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, + GNUNET_GNS_LookupResultProcessor proc, + void *proc_cls); /** * Cancel pending lookup request * * @param lr the lookup request to cancel + * @return closure from the lookup result processor */ -void -GNUNET_GNS_cancel_lookup_request (struct GNUNET_GNS_LookupRequest *lr); - -/* *************** Standard API: shorten ******************* */ +void * +GNUNET_GNS_lookup_cancel (struct GNUNET_GNS_LookupRequest *lr); /** - * Processor called on for a name shortening result - * called only once + * Iterator called on obtained result for a GNS lookup + * where "not GNS" is a valid answer. * * @param cls closure - * @param short_name the shortened name or NULL if no result / error + * @param gns_tld #GNUNET_YES if a GNS lookup was attempted, + * #GNUNET_NO if the TLD is not configured for GNS + * @param rd_count number of records in @a rd + * @param rd the records in the reply */ -typedef void (*GNUNET_GNS_ShortenResultProcessor) (void *cls, - const char* short_name); +typedef void +(*GNUNET_GNS_LookupResultProcessor2) (void *cls, + int gns_tld, + uint32_t rd_count, + const struct GNUNET_GNSRECORD_Data *rd); /** - * Perform a name shortening operation on the GNS. + * Perform an asynchronous lookup operation on the GNS, + * determining the zone using the TLD of the given name + * and the current configuration to resolve TLDs to zones. * * @param handle handle to the GNS service - * @param name the name to look up - * @param private_zone the public zone of the private zone - * @param shorten_zone the public zone of the shorten zone - * @param proc function to call on result - * @param proc_cls closure for processor - * @return handle to the operation - */ -struct GNUNET_GNS_ShortenRequest* -GNUNET_GNS_shorten (struct GNUNET_GNS_Handle *handle, - const char * name, - struct GNUNET_CRYPTO_ShortHashCode *private_zone, - struct GNUNET_CRYPTO_ShortHashCode *shorten_zone, - GNUNET_GNS_ShortenResultProcessor proc, - void *proc_cls); - - -/** - * Perform a name shortening operation on the GNS. - * - * @param handle handle to the GNS service - * @param name the name to look up - * @param private_zone the public zone of the private zone - * @param shorten_zone the public zone of the shorten zone - * @param zone the zone to start the resolution in - * @param proc function to call on result - * @param proc_cls closure for processor - * @return handle to the operation - */ -struct GNUNET_GNS_ShortenRequest* -GNUNET_GNS_shorten_zone (struct GNUNET_GNS_Handle *handle, - const char * name, - struct GNUNET_CRYPTO_ShortHashCode *private_zone, - struct GNUNET_CRYPTO_ShortHashCode *shorten_zone, - struct GNUNET_CRYPTO_ShortHashCode *zone, - GNUNET_GNS_ShortenResultProcessor proc, - void *proc_cls); - - -/** - * Cancel pending shorten request - * - * @param sr the lookup request to cancel - */ -void -GNUNET_GNS_cancel_shorten_request (struct GNUNET_GNS_ShortenRequest *sr); - - -/* *************** Standard API: get authority ******************* */ - - -/** - * Processor called on for a name shortening result - * called only once - * - * @param cls closure - * @param auth_name the name of the auhtority or NULL + * @param name the name to look up, including TLD + * @param type the record type to look up + * @param options local options for the lookup + * @param proc processor to call on result + * @param proc_cls closure for @a proc + * @return handle to the get request */ -typedef void (*GNUNET_GNS_GetAuthResultProcessor) (void *cls, - const char* short_name); +struct GNUNET_GNS_LookupWithTldRequest* +GNUNET_GNS_lookup_with_tld (struct GNUNET_GNS_Handle *handle, + const char *name, + uint32_t type, + enum GNUNET_GNS_LocalOptions options, + GNUNET_GNS_LookupResultProcessor2 proc, + void *proc_cls); /** - * Perform an authority lookup for a given name. + * Cancel pending lookup request * - * @param handle handle to the GNS service - * @param name the name to look up authority for - * @param proc function to call on result - * @param proc_cls closure for processor - * @return handle to the operation + * @param ltr the lookup request to cancel + * @return closure from the lookup result processor */ -struct GNUNET_GNS_GetAuthRequest* -GNUNET_GNS_get_authority (struct GNUNET_GNS_Handle *handle, - const char * name, - GNUNET_GNS_GetAuthResultProcessor proc, - void *proc_cls); +void * +GNUNET_GNS_lookup_with_tld_cancel (struct GNUNET_GNS_LookupWithTldRequest *ltr); -/** - * Cancel pending get auth request - * - * @param gar the lookup request to cancel - */ -void -GNUNET_GNS_cancel_get_auth_request (struct GNUNET_GNS_GetAuthRequest *gar); - #if 0 /* keep Emacsens' auto-indent happy */ { #endif @@ -317,6 +212,6 @@ GNUNET_GNS_cancel_get_auth_request (struct GNUNET_GNS_GetAuthRequest *gar); } #endif - #endif -/* gnunet_gns_service.h */ + +/** @} */ /* end of group */