src/include/gnunet_dns_service.h

   1 /*
   2       This file is part of GNUnet
   3       Copyright (C) 2012 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 Christian Grothoff
  21  *
  22  * @file
  23  * API to access the DNS service.
  24  *
  25  * @defgroup dns  DNS service
  26  *
  27  * @see [Documentation](https://gnunet.org/gnunet-service-dns)
  28  *
  29  * @{
  30  */
  31 #ifndef GNUNET_DNS_SERVICE_H
  32 #define GNUNET_DNS_SERVICE_H
  33
  34 #include "gnunet_util_lib.h"
  35
  36
  37 /**
  38  * Opaque DNS handle
  39  */
  40 struct GNUNET_DNS_Handle;
  41
  42 /**
  43  * Handle to identify an individual DNS request.
  44  */
  45 struct GNUNET_DNS_RequestHandle;
  46
  47 /**
  48  * Flags that specify when to call the client's handler.
  49  */
  50 enum GNUNET_DNS_Flags
  51 {
  52
  53   /**
  54    * Useless option: never call the client.
  55    */
  56   GNUNET_DNS_FLAG_NEVER = 0,
  57
  58   /**
  59    * Set this flag to see all requests first prior to resolution
  60    * (for monitoring).  Clients that set this flag must then
  61    * call "GNUNET_DNS_request_forward" when they process a request
  62    * for the first time.  Caling "GNUNET_DNS_request_answer" is
  63    * not allowed for MONITOR peers.
  64    */
  65   GNUNET_DNS_FLAG_REQUEST_MONITOR = 1,
  66
  67   /**
  68    * This client should be called on requests that have not
  69    * yet been resolved as this client provides a resolution
  70    * service.  Note that this does not guarantee that the
  71    * client will see all requests as another client might be
  72    * called first and that client might have already done the
  73    * resolution, in which case other pre-resolution clients
  74    * won't see the request anymore.
  75    */
  76   GNUNET_DNS_FLAG_PRE_RESOLUTION = 2,
  77
  78   /**
  79    * This client wants to be called on the results of a DNS resolution
  80    * (either resolved by PRE-RESOLUTION clients or the global DNS).
  81    * The client then has a chance to modify the answer (or cause it to
  82    * be dropped).  There is no guarantee that other POST-RESOLUTION
  83    * client's won't modify (or drop) the answer afterwards.
  84    */
  85   GNUNET_DNS_FLAG_POST_RESOLUTION = 4,
  86
  87   /**
  88    * Set this flag to see all requests just before they are
  89    * returned to the network.  Clients that set this flag must then
  90    * call "GNUNET_DNS_request_forward" when they process a request
  91    * for the last time.  Caling "GNUNET_DNS_request_answer" is
  92    * not allowed for MONITOR peers.
  93    */
  94   GNUNET_DNS_FLAG_RESPONSE_MONITOR = 8
  95
  96 };
  97
  98
  99
 100 /**
 101  * Signature of a function that is called whenever the DNS service
 102  * encounters a DNS request and needs to do something with it.  The
 103  * function has then the chance to generate or modify the response by
 104  * calling one of the three "GNUNET_DNS_request_*" continuations.
 105  *
 106  * When a request is intercepted, this function is called first to
 107  * give the client a chance to do the complete address resolution;
 108  * "rdata" will be NULL for this first call for a DNS request, unless
 109  * some other client has already filled in a response.
 110  *
 111  * If multiple clients exist, all of them are called before the global
 112  * DNS.  The global DNS is only called if all of the clients'
 113  * functions call GNUNET_DNS_request_forward.  Functions that call
 114  * GNUNET_DNS_request_forward will be called again before a final
 115  * response is returned to the application.  If any of the clients'
 116  * functions call GNUNET_DNS_request_drop, the response is dropped.
 117  *
 118  * @param cls closure
 119  * @param rh request handle to user for reply
 120  * @param request_length number of bytes in request
 121  * @param request udp payload of the DNS request
 122  */
 123 typedef void
 124 (*GNUNET_DNS_RequestHandler)(void *cls,
 125                              struct GNUNET_DNS_RequestHandle *rh,
 126                              size_t request_length,
 127                              const char *request);
 128
 129
 130 /**
 131  * If a GNUNET_DNS_RequestHandler calls this function, the client
 132  * has no desire to interfer with the request and it should
 133  * continue to be processed normally.
 134  *
 135  * @param rh request that should now be forwarded
 136  */
 137 void
 138 GNUNET_DNS_request_forward (struct GNUNET_DNS_RequestHandle *rh);
 139
 140
 141 /**
 142  * If a GNUNET_DNS_RequestHandler calls this function, the request is
 143  * to be dropped and no response should be generated.
 144  *
 145  * @param rh request that should now be dropped
 146  */
 147 void
 148 GNUNET_DNS_request_drop (struct GNUNET_DNS_RequestHandle *rh);
 149
 150
 151 /**
 152  * If a GNUNET_DNS_RequestHandler calls this function, the request is
 153  * supposed to be answered with the data provided to this call (with
 154  * the modifications the function might have made).  The reply given
 155  * must always be a valid DNS reply and not a mutated DNS request.
 156  *
 157  * @param rh request that should now be answered
 158  * @param reply_length size of @a reply (uint16_t to force sane size)
 159  * @param reply reply data
 160  */
 161 void
 162 GNUNET_DNS_request_answer (struct GNUNET_DNS_RequestHandle *rh,
 163                            uint16_t reply_length,
 164                            const char *reply);
 165
 166
 167 /**
 168  * Connect to the service-dns
 169  *
 170  * @param cfg configuration to use
 171  * @param flags when to call @a rh
 172  * @param rh function to call with DNS requests
 173  * @param rh_cls closure to pass to @a rh
 174  * @return DNS handle
 175  */
 176 struct GNUNET_DNS_Handle *
 177 GNUNET_DNS_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
 178                     enum GNUNET_DNS_Flags flags,
 179                     GNUNET_DNS_RequestHandler rh,
 180                     void *rh_cls);
 181
 182
 183 /**
 184  * Disconnect from the DNS service.
 185  *
 186  * @param dh DNS handle
 187  */
 188 void
 189 GNUNET_DNS_disconnect (struct GNUNET_DNS_Handle *dh);
 190
 191
 192 #endif
 193
 194 /** @} */  /* end of group */