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