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