src/include/gnunet_gns_service.h

   1 /*
   2       This file is part of GNUnet
   3       (C) 2012 Christian Grothoff (and other contributing authors)
   4
   5       GNUnet is free software; you can redistribute it and/or modify
   6       it under the terms of the GNU General Public License as published
   7       by the Free Software Foundation; either version 3, or (at your
   8       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       General Public License for more details.
  14
  15       You should have received a copy of the GNU General Public License
  16       along with GNUnet; see the file COPYING.  If not, write to the
  17       Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  18       Boston, MA 02111-1307, USA.
  19  */
  20
  21 /**
  22  * @file include/gnunet_gns_service.h
  23  * @brief API to the GNS service
  24  * @author Martin Schanzenbach
  25  */
  26 #ifndef GNUNET_GNS_SERVICE_H
  27 #define GNUNET_GNS_SERVICE_H
  28
  29 #include "gnunet_util_lib.h"
  30 #include "gnunet_dnsparser_lib.h"
  31 #include "gnunet_namestore_service.h"
  32
  33 #ifdef __cplusplus
  34 extern "C"
  35 {
  36 #if 0                           /* keep Emacsens' auto-indent happy */
  37 }
  38 #endif
  39 #endif
  40
  41
  42 /**
  43  * String we use to indicate the local master zone or a
  44  * root entry in the current zone.
  45  */
  46 #define GNUNET_GNS_MASTERZONE_STR "+"
  47
  48 /**
  49  * Connection to the GNS service.
  50  */
  51 struct GNUNET_GNS_Handle;
  52
  53 /**
  54  * Handle to control a lookup operation.
  55  */
  56 struct GNUNET_GNS_LookupRequest;
  57
  58 /**
  59  * Handle to control a shorten operation.
  60  */
  61 struct GNUNET_GNS_ShortenRequest;
  62
  63 /**
  64  * Handle to control a get authority operation
  65  */
  66 struct GNUNET_GNS_GetAuthRequest;
  67
  68 /**
  69  * Record types
  70  * Based on GNUNET_DNSPARSER_TYPEs (standard DNS)
  71  */
  72 enum GNUNET_GNS_RecordType
  73 {
  74   /* Standard DNS */
  75   /* struct in_addr */
  76   GNUNET_GNS_RECORD_A          = GNUNET_DNSPARSER_TYPE_A,
  77
  78   /* char */
  79   GNUNET_GNS_RECORD_NS         = GNUNET_DNSPARSER_TYPE_NS,
  80
  81   /* char */
  82   GNUNET_GNS_RECORD_CNAME      = GNUNET_DNSPARSER_TYPE_CNAME,
  83
  84   /* struct soa_data */
  85   GNUNET_GNS_RECORD_SOA        = GNUNET_DNSPARSER_TYPE_SOA,
  86
  87   /* struct srv_data */
  88   GNUNET_GNS_RECORD_SRV        = GNUNET_DNSPARSER_TYPE_SRV,
  89
  90   /* char */
  91   GNUNET_GNS_RECORD_PTR        = GNUNET_DNSPARSER_TYPE_PTR,
  92
  93   /* uint16_t, char */
  94   GNUNET_GNS_RECORD_MX         = GNUNET_DNSPARSER_TYPE_MX,
  95
  96   /* char */
  97   GNUNET_GNS_RECORD_TXT        = GNUNET_DNSPARSER_TYPE_TXT,
  98
  99   /* struct in6_addr */
 100   GNUNET_GNS_RECORD_AAAA       = GNUNET_DNSPARSER_TYPE_AAAA,
 101
 102   /* GNS specific */
 103   /* struct GNUNET_CRYPTO_ShortHashCode */
 104   GNUNET_GNS_RECORD_PKEY = GNUNET_NAMESTORE_TYPE_PKEY,
 105
 106   /* char */
 107   GNUNET_GNS_RECORD_PSEU = GNUNET_NAMESTORE_TYPE_PSEU,
 108   GNUNET_GNS_RECORD_ANY  = GNUNET_NAMESTORE_TYPE_ANY,
 109
 110   /* char */
 111   GNUNET_GNS_RECORD_LEHO = GNUNET_NAMESTORE_TYPE_LEHO,
 112
 113   /* struct vpn_data */
 114   GNUNET_GNS_RECORD_VPN  = GNUNET_NAMESTORE_TYPE_VPN,
 115
 116   /* revocation */
 117   GNUNET_GNS_RECORD_REV  = GNUNET_NAMESTORE_TYPE_REV
 118 };
 119
 120
 121 /**
 122  * Initialize the connection with the GNS service.
 123  *
 124  * @param cfg configuration to use
 125  *
 126  * @return handle to the GNS service, or NULL on error
 127  */
 128 struct GNUNET_GNS_Handle *
 129 GNUNET_GNS_connect (const struct GNUNET_CONFIGURATION_Handle *cfg);
 130
 131
 132 /**
 133  * Shutdown connection with the GNS service.
 134  *
 135  * @param handle connection to shut down
 136  */
 137 void
 138 GNUNET_GNS_disconnect (struct GNUNET_GNS_Handle *handle);
 139
 140
 141 /* *************** Standard API: lookup ******************* */
 142
 143 /**
 144  * Iterator called on obtained result for a GNS
 145  * lookup
 146  *
 147  * @param cls closure
 148  * @param rd_count number of records
 149  * @param rd the records in reply
 150  */
 151 typedef void (*GNUNET_GNS_LookupResultProcessor) (void *cls,
 152                                                   uint32_t rd_count,
 153                                                   const struct GNUNET_NAMESTORE_RecordData *rd);
 154
 155
 156
 157 /**
 158  * Perform an asynchronous lookup operation on the GNS
 159  * in the default zone.
 160  *
 161  * @param handle handle to the GNS service
 162  * @param name the name to look up
 163  * @param type the GNUNET_GNS_RecordType to look for
 164  * @param only_cached GNUNET_NO to only check locally not DHT for performance
 165  * @param shorten_key the private key of the shorten zone (can be NULL)
 166  * @param proc function to call on result
 167  * @param proc_cls closure for processor
 168  *
 169  * @return handle to the queued request
 170  */
 171 struct GNUNET_GNS_LookupRequest*
 172 GNUNET_GNS_lookup (struct GNUNET_GNS_Handle *handle,
 173                    const char * name,
 174                    enum GNUNET_GNS_RecordType type,
 175                    int only_cached,
 176                    struct GNUNET_CRYPTO_RsaPrivateKey *shorten_key,
 177                    GNUNET_GNS_LookupResultProcessor proc,
 178                    void *proc_cls);
 179
 180
 181 /**
 182  * Perform an asynchronous lookup operation on the GNS
 183  * in the zone specified by 'zone'.
 184  *
 185  * @param handle handle to the GNS service
 186  * @param name the name to look up
 187  * @param zone the zone to start the resolution in
 188  * @param type the GNUNET_GNS_RecordType to look for
 189  * @param only_cached GNUNET_YES to only check locally not DHT for performance
 190  * @param shorten_key the private key of the shorten zone (can be NULL)
 191  * @param proc function to call on result
 192  * @param proc_cls closure for processor
 193  *
 194  * @return handle to the queued request
 195  */
 196 struct GNUNET_GNS_LookupRequest*
 197 GNUNET_GNS_lookup_zone (struct GNUNET_GNS_Handle *handle,
 198                         const char * name,
 199                         struct GNUNET_CRYPTO_ShortHashCode *zone,
 200                         enum GNUNET_GNS_RecordType type,
 201                         int only_cached,
 202                         struct GNUNET_CRYPTO_RsaPrivateKey *shorten_key,
 203                         GNUNET_GNS_LookupResultProcessor proc,
 204                         void *proc_cls);
 205
 206
 207 /**
 208  * Cancel pending lookup request
 209  *
 210  * @param lr the lookup request to cancel
 211  */
 212 void
 213 GNUNET_GNS_cancel_lookup_request (struct GNUNET_GNS_LookupRequest *lr);
 214
 215 /* *************** Standard API: shorten ******************* */
 216
 217
 218 /**
 219  * Processor called on for a name shortening result
 220  * called only once
 221  *
 222  * @param cls closure
 223  * @param short_name the shortened name or NULL if no result / error
 224  */
 225 typedef void (*GNUNET_GNS_ShortenResultProcessor) (void *cls,
 226                                                    const char* short_name);
 227
 228
 229 /**
 230  * Perform a name shortening operation on the GNS.
 231  *
 232  * @param handle handle to the GNS service
 233  * @param name the name to look up
 234  * @param private_zone the public zone of the private zone
 235  * @param shorten_zone the public zone of the shorten zone
 236  * @param proc function to call on result
 237  * @param proc_cls closure for processor
 238  * @return handle to the operation
 239  */
 240 struct GNUNET_GNS_ShortenRequest*
 241 GNUNET_GNS_shorten (struct GNUNET_GNS_Handle *handle,
 242                     const char * name,
 243                     struct GNUNET_CRYPTO_ShortHashCode *private_zone,
 244                     struct GNUNET_CRYPTO_ShortHashCode *shorten_zone,
 245                     GNUNET_GNS_ShortenResultProcessor proc,
 246                     void *proc_cls);
 247
 248
 249 /**
 250  * Perform a name shortening operation on the GNS.
 251  *
 252  * @param handle handle to the GNS service
 253  * @param name the name to look up
 254  * @param private_zone the public zone of the private zone
 255  * @param shorten_zone the public zone of the shorten zone
 256  * @param zone the zone to start the resolution in
 257  * @param proc function to call on result
 258  * @param proc_cls closure for processor
 259  * @return handle to the operation
 260  */
 261 struct GNUNET_GNS_ShortenRequest*
 262 GNUNET_GNS_shorten_zone (struct GNUNET_GNS_Handle *handle,
 263                          const char * name,
 264                          struct GNUNET_CRYPTO_ShortHashCode *private_zone,
 265                          struct GNUNET_CRYPTO_ShortHashCode *shorten_zone,
 266                          struct GNUNET_CRYPTO_ShortHashCode *zone,
 267                          GNUNET_GNS_ShortenResultProcessor proc,
 268                          void *proc_cls);
 269
 270
 271 /**
 272  * Cancel pending shorten request
 273  *
 274  * @param sr the lookup request to cancel
 275  */
 276 void
 277 GNUNET_GNS_cancel_shorten_request (struct GNUNET_GNS_ShortenRequest *sr);
 278
 279
 280 /* *************** Standard API: get authority ******************* */
 281
 282
 283 /**
 284  * Processor called on for a name shortening result
 285  * called only once
 286  *
 287  * @param cls closure
 288  * @param auth_name the name of the auhtority or NULL
 289  */
 290 typedef void (*GNUNET_GNS_GetAuthResultProcessor) (void *cls,
 291                                                    const char* short_name);
 292
 293
 294 /**
 295  * Perform an authority lookup for a given name.
 296  *
 297  * @param handle handle to the GNS service
 298  * @param name the name to look up authority for
 299  * @param proc function to call on result
 300  * @param proc_cls closure for processor
 301  * @return handle to the operation
 302  */
 303 struct GNUNET_GNS_GetAuthRequest*
 304 GNUNET_GNS_get_authority (struct GNUNET_GNS_Handle *handle,
 305                           const char * name,
 306                           GNUNET_GNS_GetAuthResultProcessor proc,
 307                           void *proc_cls);
 308
 309
 310 /**
 311  * Cancel pending get auth request
 312  *
 313  * @param gar the lookup request to cancel
 314  */
 315 void
 316 GNUNET_GNS_cancel_get_auth_request (struct GNUNET_GNS_GetAuthRequest *gar);
 317
 318 #if 0                           /* keep Emacsens' auto-indent happy */
 319 {
 320 #endif
 321 #ifdef __cplusplus
 322 }
 323 #endif
 324
 325
 326 #endif
 327 /* gnunet_gns_service.h */