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