src/include/gnunet_dns_service-new.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 2, 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_dns_service-new.h
  23  * @brief API to access the DNS service.
  24  * @author Christian Grothoff
  25  */
  26 #ifndef GNUNET_DNS_SERVICE_NEW_H
  27 #define GNUNET_DNS_SERVICE_NEW_H
  28
  29 #include "gnunet_common.h"
  30 #include "gnunet_util_lib.h"
  31
  32 /**
  33  * A few common DNS types.
  34  */
  35 #define GNUNET_DNS_TYPE_A 1
  36 #define GNUNET_DNS_TYPE_NS 2
  37 #define GNUNET_DNS_TYPE_CNAME 5
  38 #define GNUNET_DNS_TYPE_SOA 6
  39 #define GNUNET_DNS_TYPE_PTR 12
  40 #define GNUNET_DNS_TYPE_MX 15
  41 #define GNUNET_DNS_TYPE_TXT 16
  42 #define GNUNET_DNS_TYPE_AAAA 28
  43 #define GNUNET_DNS_TYPE_IXFR 251
  44 #define GNUNET_DNS_TYPE_AXFR 252
  45
  46 /**
  47  * A few common DNS classes (ok, only one is common, but I list a
  48  * couple more to make it clear what we're talking about here).
  49  */
  50 #define GNUNET_DNS_CLASS_INTERNET 1
  51 #define GNUNET_DNS_CLASS_CHAOS 3
  52 #define GNUNET_DNS_CLASS_HESIOD 4
  53
  54
  55 /**
  56  * Opaque DNS handle
  57  */
  58 struct GNUNET_DNS_Handle;
  59
  60 /**
  61  * Handle to identify an individual DNS request.
  62  */
  63 struct GNUNET_DNS_RequestHandle;
  64
  65
  66 /**
  67  * Signature of a function that is called whenever the DNS service
  68  * encounters a DNS request and needs to do something with it.  The
  69  * function has then the chance to generate or modify the response by
  70  * calling one of the three "GNUNET_DNS_request_*" continuations.
  71  *
  72  * When a request is intercepted, this function is called first to
  73  * give the client a chance to do the complete address resolution;
  74  * "rdata" will be NULL for this first call for a DNS request, unless
  75  * some other client has already filled in a response.
  76  *
  77  * If multiple clients exist, all of them are called before the global
  78  * DNS.  The global DNS is only called if all of the clients'
  79  * functions call GNUNET_DNS_request_forward.  Functions that call
  80  * GNUNET_DNS_request_forward will be called again before a final
  81  * response is returned to the application.  If any of the clients'
  82  * functions call GNUNET_DNS_request_drop, the response is dropped.
  83  *
  84  * @param cls closure
  85  * @param name name of the node to which the record pertains
  86  * @param dns_type type of RR
  87  * @param dns_class class code
  88  * @param dns_ttl seconds that the RR stays valid, can be updated
  89  * @param rdata_length size of rdata, can be updated
  90  * @param rdata record data, can be updated
  91  */
  92 typedef void (*GNUNET_DNS_RequestHandler)(void *cls,
  93                                           struct GNUNET_DNS_RequestHandle *rh,
  94                                           const char *name,
  95                                           uint16_t dns_type,
  96                                           uint16_t dns_class,
  97                                           uint32_t dns_ttl,
  98                                           uint16_t rdata_length,
  99                                           const char *rdata);
 100
 101
 102 /**
 103  * If a GNUNET_DNS_RequestHandler calls this function, the request is
 104  * given to other clients or the global DNS for resolution.  Once a
 105  * global response has been obtained, the request handler is AGAIN
 106  * called to give it a chance to observe and modify the response after
 107  * the "normal" resolution.  It is not legal for the request handler
 108  * to call this function if a response is already present.
 109  *
 110  * @param rh request that should now be forwarded
 111  */
 112 void
 113 GNUNET_DNS_request_forward (struct GNUNET_DNS_RequestHandle *rh);
 114
 115
 116 /**
 117  * If a GNUNET_DNS_RequestHandler calls this function, the request is
 118  * to be dropped and no response should be generated.
 119  *
 120  * @param rh request that should now be dropped
 121  */
 122 void
 123 GNUNET_DNS_request_drop (struct GNUNET_DNS_RequestHandle *rh);
 124
 125
 126 /**
 127  * If a GNUNET_DNS_RequestHandler calls this function, the request is supposed to
 128  * be answered with the data provided to this call (with the modifications the function might have made).
 129  *
 130  * @param rh request that should now be answered
 131  * @param dns_ttl seconds that the RR stays valid, can be updated
 132  * @param rdata_length size of rdata, can be updated
 133  * @param rdata record data, can be updated
 134  */
 135 void
 136 GNUNET_DNS_request_answer (struct GNUNET_DNS_RequestHandle *rh,
 137                            uint32_t dns_ttl,
 138                            uint16_t rdata_length,
 139                            char *rdata);
 140
 141
 142 /**
 143  * Connect to the service-dns
 144  *
 145  * @param cfg configuration to use
 146  * @param rh function to call with DNS requests
 147  * @param rh_cls closure to pass to rh
 148  * @return DNS handle
 149  */
 150 struct GNUNET_DNS_Handle *
 151 GNUNET_DNS_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
 152                     GNUNET_DNS_RequestHandler rh,
 153                     void *rh_cls);
 154
 155
 156 /**
 157  * Disconnect from the DNS service.
 158  *
 159  * @param dh DNS handle
 160  */
 161 void
 162 GNUNET_DNS_disconnect (struct GNUNET_DNS_Handle *dh);
 163
 164 #endif