gnunet-android

GNUnet for Android
Log | Files | Refs | README

gnunet_dnsstub_lib.h (4318B)

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