src/include/gnunet_resolver_service.h

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (C) 2001-2013 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 /**
  22  * @author Christian Grothoff
  23  *
  24  * @file
  25  * Functions related to doing DNS lookups
  26  *
  27  * @defgroup resolver  Resolver service
  28  * Asynchronous standard DNS lookups
  29  * @{
  30  */
  31
  32 #ifndef GNUNET_RESOLVER_SERVICE_H
  33 #define GNUNET_RESOLVER_SERVICE_H
  34
  35 #ifdef __cplusplus
  36 extern "C"
  37 {
  38 #if 0                           /* keep Emacsens' auto-indent happy */
  39 }
  40 #endif
  41 #endif
  42
  43 #include "gnunet_configuration_lib.h"
  44 #include "gnunet_scheduler_lib.h"
  45 #include "gnunet_time_lib.h"
  46
  47
  48 /**
  49  * Function called by the resolver for each address obtained from DNS.
  50  *
  51  * @param cls closure
  52  * @param addr one of the addresses of the host, NULL for the last address
  53  * @param addrlen length of @a addr
  54  */
  55 typedef void
  56 (*GNUNET_RESOLVER_AddressCallback) (void *cls,
  57                                     const struct sockaddr *addr,
  58                                     socklen_t addrlen);
  59
  60
  61 /**
  62  * Handle to a request given to the resolver.  Can be used to cancel
  63  * the request prior to the timeout or successful execution.
  64  */
  65 struct GNUNET_RESOLVER_RequestHandle;
  66
  67 /**
  68  * Create the connection to the resolver service.
  69  *
  70  * @param cfg configuration to use
  71  */
  72 void
  73 GNUNET_RESOLVER_connect(const struct GNUNET_CONFIGURATION_Handle *cfg);
  74
  75
  76 /**
  77  * Destroy the connection to the resolver service.
  78  */
  79 void
  80 GNUNET_RESOLVER_disconnect(void);
  81
  82
  83 /**
  84  * Convert a string to one or more IP addresses.
  85  *
  86  * @param hostname the hostname to resolve
  87  * @param af AF_INET or AF_INET6; use AF_UNSPEC for "any"
  88  * @param callback function to call with addresses
  89  * @param callback_cls closure for @a callback
  90  * @param timeout how long to try resolving
  91  * @return handle that can be used to cancel the request, NULL on error
  92  */
  93 struct GNUNET_RESOLVER_RequestHandle *
  94 GNUNET_RESOLVER_ip_get(const char *hostname,
  95                        int af,
  96                        struct GNUNET_TIME_Relative timeout,
  97                        GNUNET_RESOLVER_AddressCallback callback,
  98                        void *callback_cls);
  99
 100
 101 /**
 102  * Resolve our hostname to an IP address.
 103  *
 104  * @param af AF_INET or AF_INET6; use AF_UNSPEC for "any"
 105  * @param callback function to call with addresses
 106  * @param cls closure for @a callback
 107  * @param timeout how long to try resolving
 108  * @return handle that can be used to cancel the request, NULL on error
 109  */
 110 struct GNUNET_RESOLVER_RequestHandle *
 111 GNUNET_RESOLVER_hostname_resolve(int af,
 112                                  struct GNUNET_TIME_Relative timeout,
 113                                  GNUNET_RESOLVER_AddressCallback callback,
 114                                  void *cls);
 115
 116
 117 /**
 118  * Function called by the resolver for each hostname obtained from DNS.
 119  *
 120  * @param cls closure
 121  * @param hostname one of the names for the host, NULL
 122  *        on the last call to the callback
 123  */
 124 typedef void
 125 (*GNUNET_RESOLVER_HostnameCallback) (void *cls,
 126                                      const char *hostname);
 127
 128 /**
 129  * Get local fully qualified domain name
 130  *
 131  * @return local hostname, caller must free
 132  */
 133 char *
 134 GNUNET_RESOLVER_local_fqdn_get(void);
 135
 136
 137 /**
 138  * Perform a reverse DNS lookup.
 139  *
 140  * @param sa host address
 141  * @param salen length of @a sa
 142  * @param do_resolve use #GNUNET_NO to return numeric hostname
 143  * @param timeout how long to try resolving
 144  * @param callback function to call with hostnames
 145  * @param cls closure for @a callback
 146  * @return handle that can be used to cancel the request, NULL on error
 147  */
 148 struct GNUNET_RESOLVER_RequestHandle *
 149 GNUNET_RESOLVER_hostname_get(const struct sockaddr *sa,
 150                              socklen_t salen,
 151                              int do_resolve,
 152                              struct GNUNET_TIME_Relative timeout,
 153                              GNUNET_RESOLVER_HostnameCallback callback,
 154                              void *cls);
 155
 156
 157 /**
 158  * Cancel a request that is still pending with the resolver.
 159  * Note that a client MUST NOT cancel a request that has
 160  * been completed (i.e, the callback has been called to
 161  * signal timeout or the final result).
 162  *
 163  * @param rh handle of request to cancel
 164  */
 165 void
 166 GNUNET_RESOLVER_request_cancel(struct GNUNET_RESOLVER_RequestHandle *rh);
 167
 168
 169 #if 0                           /* keep Emacsens' auto-indent happy */
 170 {
 171 #endif
 172 #ifdef __cplusplus
 173 }
 174 #endif
 175
 176 /* ifndef GNUNET_RESOLVER_SERVICE_H */
 177 #endif
 178
 179 /** @} */  /* end of group resolver */
 180
 181 /* end of gnunet_resolver_service.h */