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