src/include/gnunet_dnsstub_lib.h

   1 /*
   2       This file is part of GNUnet
   3       Copyright (C) 2012, 2018 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 for helper library to send DNS requests to DNS resolver
  24  *
  25  * @defgroup dns-stub  DNS Stub library
  26  * Helper library to send DNS requests to DNS resolver
  27  * @{
  28  */
  29 #ifndef GNUNET_DNSSTUB_LIB_H
  30 #define GNUNET_DNSSTUB_LIB_H
  31
  32 #include "gnunet_util_lib.h"
  33
  34 /**
  35  * Opaque handle to the stub resolver.
  36  */
  37 struct GNUNET_DNSSTUB_Context;
  38
  39 /**
  40  * Opaque handle to a socket doing UDP requests.
  41  */
  42 struct GNUNET_DNSSTUB_RequestSocket;
  43
  44
  45 /**
  46  * Start a DNS stub resolver.
  47  *
  48  * @param num_sockets how many sockets should we open
  49  *        in parallel for DNS queries for this stub?
  50  * @return NULL on error
  51  */
  52 struct GNUNET_DNSSTUB_Context *
  53 GNUNET_DNSSTUB_start (unsigned int num_sockets);
  54
  55
  56 /**
  57  * Add nameserver for use by the DNSSTUB.  We will use
  58  * all provided nameservers for resolution (round-robin).
  59  *
  60  * @param ctx resolver context to modify
  61  * @param dns_ip target IP address to use (as string)
  62  * @return #GNUNET_OK on success
  63  */
  64 int
  65 GNUNET_DNSSTUB_add_dns_ip (struct GNUNET_DNSSTUB_Context *ctx,
  66                            const char *dns_ip);
  67
  68
  69 /**
  70  * Add nameserver for use by the DNSSTUB.  We will use
  71  * all provided nameservers for resolution (round-robin).
  72  *
  73  * @param ctx resolver context to modify
  74  * @param sa socket address of DNS resolver to use
  75  * @return #GNUNET_OK on success
  76  */
  77 int
  78 GNUNET_DNSSTUB_add_dns_sa (struct GNUNET_DNSSTUB_Context *ctx,
  79                            const struct sockaddr *sa);
  80
  81
  82 /**
  83  * How long should we try requests before timing out?
  84  * Only effective for requests issued after this call.
  85  *
  86  * @param ctx resolver context to modify
  87  * @param retry_frequ how long to wait between retries
  88  */
  89 void
  90 GNUNET_DNSSTUB_set_retry (struct GNUNET_DNSSTUB_Context *ctx,
  91                           struct GNUNET_TIME_Relative retry_freq);
  92
  93 /**
  94  * Cleanup DNSSTUB resolver.
  95  *
  96  * @param ctx stub resolver to clean up
  97  */
  98 void
  99 GNUNET_DNSSTUB_stop (struct GNUNET_DNSSTUB_Context *ctx);
 100
 101
 102 /**
 103  * Function called with the result of a DNS resolution.
 104  * Once this function is called, the resolution request
 105  * is automatically cancelled / cleaned up.  In particular,
 106  * the function will only be called once.
 107  *
 108  * @param cls closure
 109  * @param dns dns response, NULL on hard error (i.e. timeout)
 110  * @param dns_len number of bytes in @a dns
 111  */
 112 typedef void
 113 (*GNUNET_DNSSTUB_ResultCallback)(void *cls,
 114                                  const struct GNUNET_TUN_DnsHeader *dns,
 115                                  size_t dns_len);
 116
 117
 118 /**
 119  * Perform DNS resolution using our default IP from init.
 120  *
 121  * @param ctx stub resolver to use
 122  * @param request DNS request to transmit
 123  * @param request_len number of bytes in msg
 124  * @param rc function to call with result (once)
 125  * @param rc_cls closure for @a rc
 126  * @return socket used for the request, NULL on error
 127  */
 128 struct GNUNET_DNSSTUB_RequestSocket *
 129 GNUNET_DNSSTUB_resolve (struct GNUNET_DNSSTUB_Context *ctx,
 130                         const void *request,
 131                         size_t request_len,
 132                         GNUNET_DNSSTUB_ResultCallback rc,
 133                         void *rc_cls);
 134
 135
 136 /**
 137  * Cancel DNS resolution.
 138  *
 139  * @param rs resolution to cancel
 140  */
 141 void
 142 GNUNET_DNSSTUB_resolve_cancel (struct GNUNET_DNSSTUB_RequestSocket *rs);
 143
 144
 145 #endif
 146
 147 /** @} */  /* end of group */