src/include/gnunet_gns_service.h

   1 /*
   2       This file is part of GNUnet
   3       Copyright (C) 2012-2014, 2017 GNUnet e.V.
   4
   5       GNUnet is free software: you can redistribute it and/or modify it
   6       under the terms of the GNU Affero General Public License as published
   7       by the Free Software Foundation, either version 3 of the License,
   8       or (at your option) any later version.
   9
  10       GNUnet is distributed in the hope that it will be useful, but
  11       WITHOUT ANY WARRANTY; without even the implied warranty of
  12       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13       Affero General Public License for more details.
  14
  15       You should have received a copy of the GNU Affero General Public License
  16       along with this program.  If not, see <http://www.gnu.org/licenses/>.
  17  */
  18
  19 /**
  20  * @author Martin Schanzenbach
  21  *
  22  * @file
  23  * API to the GNS service
  24  *
  25  * @defgroup gns  GNS service
  26  * GNU Name System
  27  *
  28  * @see [Documentation](https://gnunet.org/gns-implementation)
  29  *
  30  * @{
  31  */
  32 #ifndef GNUNET_GNS_SERVICE_H
  33 #define GNUNET_GNS_SERVICE_H
  34
  35 #include "gnunet_util_lib.h"
  36 #include "gnunet_dnsparser_lib.h"
  37 #include "gnunet_namestore_service.h"
  38
  39 #ifdef __cplusplus
  40 extern "C"
  41 {
  42 #if 0                           /* keep Emacsens' auto-indent happy */
  43 }
  44 #endif
  45 #endif
  46
  47
  48 /**
  49  * String we use to indicate an empty label (top-level
  50  * entry in the zone).  DNS uses "@", so do we.
  51  */
  52 #define GNUNET_GNS_EMPTY_LABEL_AT "@"
  53
  54 /**
  55  * Connection to the GNS service.
  56  */
  57 struct GNUNET_GNS_Handle;
  58
  59 /**
  60  * Handle to control a lookup operation.
  61  */
  62 struct GNUNET_GNS_LookupRequest;
  63
  64 /**
  65  * Handle to control a lookup operation where the
  66  * TLD is resolved to a zone as part of the lookup operation.
  67  */
  68 struct GNUNET_GNS_LookupWithTldRequest;
  69
  70
  71 /**
  72  * Initialize the connection with the GNS service.
  73  *
  74  * @param cfg configuration to use
  75  * @return handle to the GNS service, or NULL on error
  76  */
  77 struct GNUNET_GNS_Handle *
  78 GNUNET_GNS_connect (const struct GNUNET_CONFIGURATION_Handle *cfg);
  79
  80
  81 /**
  82  * Shutdown connection with the GNS service.
  83  *
  84  * @param handle connection to shut down
  85  */
  86 void
  87 GNUNET_GNS_disconnect (struct GNUNET_GNS_Handle *handle);
  88
  89
  90 /**
  91  * Iterator called on obtained result for a GNS lookup.
  92  *
  93  * @param cls closure
  94  * @param rd_count number of records in @a rd
  95  * @param rd the records in reply
  96  */
  97 typedef void
  98 (*GNUNET_GNS_LookupResultProcessor) (void *cls,
  99                                      uint32_t rd_count,
 100                                      const struct GNUNET_GNSRECORD_Data *rd);
 101
 102
 103 /**
 104  * Options for the GNS lookup.
 105  */
 106 enum GNUNET_GNS_LocalOptions
 107 {
 108   /**
 109    * Defaults, look in cache, then in DHT.
 110    */
 111   GNUNET_GNS_LO_DEFAULT = 0,
 112
 113   /**
 114    * Never look in the DHT, keep request to local cache.
 115    */
 116   GNUNET_GNS_LO_NO_DHT = 1,
 117
 118   /**
 119    * For the rightmost label, only look in the cache (it
 120    * is our local namestore), for the others, the DHT is OK.
 121    */
 122   GNUNET_GNS_LO_LOCAL_MASTER = 2
 123
 124 };
 125
 126
 127 /**
 128  * Perform an asynchronous lookup operation on the GNS.
 129  *
 130  * @param handle handle to the GNS service
 131  * @param name the name to look up
 132  * @param zone zone to look in
 133  * @param type the GNS record type to look for
 134  * @param options local options for the lookup
 135  * @param proc function to call on result
 136  * @param proc_cls closure for @a proc
 137  * @return handle to the queued request
 138  */
 139 struct GNUNET_GNS_LookupRequest *
 140 GNUNET_GNS_lookup (struct GNUNET_GNS_Handle *handle,
 141                    const char *name,
 142                    const struct GNUNET_CRYPTO_EcdsaPublicKey *zone,
 143                    uint32_t type,
 144                    enum GNUNET_GNS_LocalOptions options,
 145                    GNUNET_GNS_LookupResultProcessor proc,
 146                    void *proc_cls);
 147
 148
 149 /**
 150  * Cancel pending lookup request
 151  *
 152  * @param lr the lookup request to cancel
 153  * @return closure from the lookup result processor
 154  */
 155 void *
 156 GNUNET_GNS_lookup_cancel (struct GNUNET_GNS_LookupRequest *lr);
 157
 158
 159 /**
 160  * Iterator called on obtained result for a GNS lookup
 161  * where "not GNS" is a valid answer.
 162  *
 163  * @param cls closure
 164  * @param gns_tld #GNUNET_YES if a GNS lookup was attempted,
 165  *                #GNUNET_NO if the TLD is not configured for GNS
 166  * @param rd_count number of records in @a rd
 167  * @param rd the records in the reply
 168  */
 169 typedef void
 170 (*GNUNET_GNS_LookupResultProcessor2) (void *cls,
 171                                       int gns_tld,
 172                                       uint32_t rd_count,
 173                                       const struct GNUNET_GNSRECORD_Data *rd);
 174
 175
 176 /**
 177  * Perform an asynchronous lookup operation on the GNS,
 178  * determining the zone using the TLD of the given name
 179  * and the current configuration to resolve TLDs to zones.
 180  *
 181  * @param handle handle to the GNS service
 182  * @param name the name to look up, including TLD
 183  * @param type the record type to look up
 184  * @param options local options for the lookup
 185  * @param proc processor to call on result
 186  * @param proc_cls closure for @a proc
 187  * @return handle to the get request
 188  */
 189 struct GNUNET_GNS_LookupWithTldRequest*
 190 GNUNET_GNS_lookup_with_tld (struct GNUNET_GNS_Handle *handle,
 191                             const char *name,
 192                             uint32_t type,
 193                             enum GNUNET_GNS_LocalOptions options,
 194                             GNUNET_GNS_LookupResultProcessor2 proc,
 195                             void *proc_cls);
 196
 197
 198 /**
 199  * Cancel pending lookup request
 200  *
 201  * @param ltr the lookup request to cancel
 202  * @return closure from the lookup result processor
 203  */
 204 void *
 205 GNUNET_GNS_lookup_with_tld_cancel (struct GNUNET_GNS_LookupWithTldRequest *ltr);
 206
 207
 208 #if 0                           /* keep Emacsens' auto-indent happy */
 209 {
 210 #endif
 211 #ifdef __cplusplus
 212 }
 213 #endif
 214
 215 #endif
 216
 217 /** @} */  /* end of group */