1/** 2 * \file 3 * \brief Public interfaces to getdns, include in your application to use getdns API. 4 * 5 * This source was taken from the original pseudo-implementation by 6 * Paul Hoffman. 7 */ 8 9/* 10 * Copyright (c) 2013, NLNet Labs, Verisign, Inc. 11 * All rights reserved. 12 * 13 * Redistribution and use in source and binary forms, with or without 14 * modification, are permitted provided that the following conditions are met: 15 * * Redistributions of source code must retain the above copyright 16 * notice, this list of conditions and the following disclaimer. 17 * * Redistributions in binary form must reproduce the above copyright 18 * notice, this list of conditions and the following disclaimer in the 19 * documentation and/or other materials provided with the distribution. 20 * * Neither the names of the copyright holders nor the 21 * names of its contributors may be used to endorse or promote products 22 * derived from this software without specific prior written permission. 23 * 24 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND 25 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 26 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 27 * DISCLAIMED. IN NO EVENT SHALL Verisign, Inc. BE LIABLE FOR ANY 28 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 29 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 30 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND 31 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 32 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 33 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 34 */ 35 36 37#ifndef GETDNS_H 38#define GETDNS_H 39 40#include <stdint.h> 41#include <stdlib.h> 42#include <time.h> 43 44#ifdef __cplusplus 45extern "C" { 46#endif 47 48#define GETDNS_COMPILATION_COMMENT "@GETDNS_COMPILATION_COMMENT@" 49 50/** 51 * \defgroup functions Functions 52 * \defgroup valuesandtexts Values and texts 53 */ 54 55/** \addtogroup valuesandtexts Values and texts 56 * @{ 57 */ 58 59/** 60 * \defgroup returntypestext Return values and texts 61 * @{ 62 */ 63typedef enum getdns_return_t { 64 GETDNS_RETURN_GOOD = 0, 65 GETDNS_RETURN_GENERIC_ERROR = 1, 66 GETDNS_RETURN_BAD_DOMAIN_NAME = 300, 67 GETDNS_RETURN_BAD_CONTEXT = 301, 68 GETDNS_RETURN_CONTEXT_UPDATE_FAIL = 302, 69 GETDNS_RETURN_UNKNOWN_TRANSACTION = 303, 70 GETDNS_RETURN_NO_SUCH_LIST_ITEM = 304, 71 GETDNS_RETURN_NO_SUCH_DICT_NAME = 305, 72 GETDNS_RETURN_WRONG_TYPE_REQUESTED = 306, 73 GETDNS_RETURN_NO_SUCH_EXTENSION = 307, 74 GETDNS_RETURN_EXTENSION_MISFORMAT = 308, 75 GETDNS_RETURN_DNSSEC_WITH_STUB_DISALLOWED = 309, 76 GETDNS_RETURN_MEMORY_ERROR = 310, 77 GETDNS_RETURN_INVALID_PARAMETER = 311, 78 GETDNS_RETURN_NOT_IMPLEMENTED = 312 79} getdns_return_t; 80 81 82#define GETDNS_RETURN_GOOD_TEXT "Good" 83#define GETDNS_RETURN_GENERIC_ERROR_TEXT "Generic error" 84#define GETDNS_RETURN_BAD_DOMAIN_NAME_TEXT "Badly-formed domain name in first argument" 85#define GETDNS_RETURN_BAD_CONTEXT_TEXT "The context has internal deficiencies" 86#define GETDNS_RETURN_CONTEXT_UPDATE_FAIL_TEXT "Did not update the context" 87#define GETDNS_RETURN_UNKNOWN_TRANSACTION_TEXT "An attempt was made to cancel a callback with a transaction_id that is not recognized" 88#define GETDNS_RETURN_NO_SUCH_LIST_ITEM_TEXT "A helper function for lists had an index argument that was too high." 89#define GETDNS_RETURN_NO_SUCH_DICT_NAME_TEXT "A helper function for dicts had a name argument that for a name that is not in the dict." 90#define GETDNS_RETURN_WRONG_TYPE_REQUESTED_TEXT "A helper function was supposed to return a certain type for an item, but the wrong type was given." 91#define GETDNS_RETURN_NO_SUCH_EXTENSION_TEXT "A name in the extensions dict is not a valid extension." 92#define GETDNS_RETURN_EXTENSION_MISFORMAT_TEXT "One or more of the extensions have a bad format." 93#define GETDNS_RETURN_DNSSEC_WITH_STUB_DISALLOWED_TEXT "A query was made with a context that is using stub resolution and a DNSSEC extension specified." 94#define GETDNS_RETURN_MEMORY_ERROR_TEXT "Unable to allocate the memory required." 95#define GETDNS_RETURN_INVALID_PARAMETER_TEXT "A required parameter had an invalid value." 96#define GETDNS_RETURN_NOT_IMPLEMENTED_TEXT "The library did not have the requested API feature implemented." 97/** @} 98 */ 99 100 101/** 102 * \defgroup dnssecvalues DNSSEC values and texts 103 * @{ 104 */ 105#define GETDNS_DNSSEC_SECURE 400 106#define GETDNS_DNSSEC_SECURE_TEXT "The record was determined to be secure in DNSSEC" 107#define GETDNS_DNSSEC_BOGUS 401 108#define GETDNS_DNSSEC_BOGUS_TEXT "The record was determined to be bogus in DNSSEC" 109#define GETDNS_DNSSEC_INDETERMINATE 402 110#define GETDNS_DNSSEC_INDETERMINATE_TEXT "The record was not determined to be any state in DNSSEC" 111#define GETDNS_DNSSEC_INSECURE 403 112#define GETDNS_DNSSEC_INSECURE_TEXT "The record was determined to be insecure in DNSSEC" 113#define GETDNS_DNSSEC_NOT_PERFORMED 404 114#define GETDNS_DNSSEC_NOT_PERFORMED_TEXT "DNSSEC validation was not performed (only used for debugging)" 115/** @} 116 */ 117 118 119/** 120 * \defgroup namespacetypestext Namespace types and texts 121 * @{ 122 */ 123 124typedef enum getdns_namespace_t { 125 GETDNS_NAMESPACE_DNS = 500, 126 GETDNS_NAMESPACE_LOCALNAMES = 501, 127 GETDNS_NAMESPACE_NETBIOS = 502, 128 GETDNS_NAMESPACE_MDNS = 503, 129 GETDNS_NAMESPACE_NIS = 504 130} getdns_namespace_t; 131 132 133#define GETDNS_NAMESPACE_DNS_TEXT "See getdns_context_set_namespaces()" 134#define GETDNS_NAMESPACE_LOCALNAMES_TEXT "See getdns_context_set_namespaces()" 135#define GETDNS_NAMESPACE_NETBIOS_TEXT "See getdns_context_set_namespaces()" 136#define GETDNS_NAMESPACE_MDNS_TEXT "See getdns_context_set_namespaces()" 137#define GETDNS_NAMESPACE_NIS_TEXT "See getdns_context_set_namespaces()" 138/** @} 139 */ 140 141 142/** 143 * \defgroup resolutiontypestext Resolution types and texts 144 * @{ 145 */ 146typedef enum getdns_resolution_t { 147 GETDNS_RESOLUTION_STUB = 520, 148 GETDNS_RESOLUTION_RECURSING = 521 149} getdns_resolution_t; 150 151 152#define GETDNS_RESOLUTION_STUB_TEXT "See getdns_context_set_resolution_type()" 153#define GETDNS_RESOLUTION_RECURSING_TEXT "See getdns_context_set_resolution_type()" 154/** @} 155 */ 156 157 158/** 159 * \defgroup redirectpoliciestext Redirect policies and texts 160 * @{ 161 */ 162typedef enum getdns_redirects_t { 163 GETDNS_REDIRECTS_FOLLOW = 530, 164 GETDNS_REDIRECTS_DO_NOT_FOLLOW = 531 165} getdns_redirects_t; 166 167 168#define GETDNS_REDIRECTS_FOLLOW_TEXT "See getdns_context_set_follow_redirects()" 169#define GETDNS_REDIRECTS_DO_NOT_FOLLOW_TEXT "See getdns_context_set_follow_redirects()" 170/** @} 171 */ 172 173 174/** 175 * \defgroup transporttypestext Transport arrangements and texts 176 * @{ 177 */ 178typedef enum getdns_transport_t { 179 GETDNS_TRANSPORT_UDP_FIRST_AND_FALL_BACK_TO_TCP = 540, 180 GETDNS_TRANSPORT_UDP_ONLY = 541, 181 GETDNS_TRANSPORT_TCP_ONLY = 542, 182 GETDNS_TRANSPORT_TCP_ONLY_KEEP_CONNECTIONS_OPEN = 543 183} getdns_transport_t; 184 185#define GETDNS_TRANSPORT_UDP_FIRST_AND_FALL_BACK_TO_TCP_TEXT "See getdns_context_set_dns_transport()" 186#define GETDNS_TRANSPORT_UDP_ONLY_TEXT "See getdns_context_set_dns_transport()" 187#define GETDNS_TRANSPORT_TCP_ONLY_TEXT "See getdns_context_set_dns_transport()" 188#define GETDNS_TRANSPORT_TCP_ONLY_KEEP_CONNECTIONS_OPEN_TEXT "See getdns_context_set_dns_transport()" 189/** @} 190*/ 191 192 193/** 194 * \defgroup transportlisttypestext Transport list values and tests 195 * @{ 196 */ 197/* Base transports for use in transport list */ 198typedef enum getdns_transport_list_t { 199 GETDNS_TRANSPORT_UDP = 1200, 200 GETDNS_TRANSPORT_TCP = 1201, 201 GETDNS_TRANSPORT_TLS = 1202, 202} getdns_transport_list_t; 203 204 205#define GETDNS_TRANSPORT_UDP_TEXT "See getdns_context_set_dns_transport_list()" 206#define GETDNS_TRANSPORT_TCP_TEXT "See getdns_context_set_dns_transport_list()" 207#define GETDNS_TRANSPORT_TLS_TEXT "See getdns_context_set_dns_transport_list()" 208/** @} 209 */ 210 211 212/** 213 * \defgroup suffixappendtypestext Suffix appending values and texts 214 * @{ 215 */ 216typedef enum getdns_append_name_t { 217 GETDNS_APPEND_NAME_ALWAYS = 550, 218 GETDNS_APPEND_NAME_ONLY_TO_SINGLE_LABEL_AFTER_FAILURE = 551, 219 GETDNS_APPEND_NAME_ONLY_TO_MULTIPLE_LABEL_NAME_AFTER_FAILURE = 552, 220 GETDNS_APPEND_NAME_NEVER = 553 221} getdns_append_name_t; 222 223 224#define GETDNS_APPEND_NAME_ALWAYS_TEXT "See getdns_context_set_append_name()" 225#define GETDNS_APPEND_NAME_ONLY_TO_SINGLE_LABEL_AFTER_FAILURE_TEXT "See getdns_context_set_append_name()" 226#define GETDNS_APPEND_NAME_ONLY_TO_MULTIPLE_LABEL_NAME_AFTER_FAILURE_TEXT "See getdns_context_set_append_name()" 227#define GETDNS_APPEND_NAME_NEVER_TEXT "See getdns_context_set_append_name()" 228/** @} 229 */ 230 231 232/** 233* \defgroup contextcodetypestext Context code values and texts 234* @{ 235*/ 236/* Context codes */ 237typedef enum getdns_context_code_t { 238 GETDNS_CONTEXT_CODE_NAMESPACES = 600, 239 GETDNS_CONTEXT_CODE_RESOLUTION_TYPE = 601, 240 GETDNS_CONTEXT_CODE_FOLLOW_REDIRECTS = 602, 241 GETDNS_CONTEXT_CODE_UPSTREAM_RECURSIVE_SERVERS = 603, 242 GETDNS_CONTEXT_CODE_DNS_ROOT_SERVERS = 604, 243 GETDNS_CONTEXT_CODE_DNS_TRANSPORT = 605, 244 GETDNS_CONTEXT_CODE_LIMIT_OUTSTANDING_QUERIES = 606, 245 GETDNS_CONTEXT_CODE_APPEND_NAME = 607, 246 GETDNS_CONTEXT_CODE_SUFFIX = 608, 247 GETDNS_CONTEXT_CODE_DNSSEC_TRUST_ANCHORS = 609, 248 GETDNS_CONTEXT_CODE_EDNS_MAXIMUM_UDP_PAYLOAD_SIZE = 610, 249 GETDNS_CONTEXT_CODE_EDNS_EXTENDED_RCODE = 611, 250 GETDNS_CONTEXT_CODE_EDNS_VERSION = 612, 251 GETDNS_CONTEXT_CODE_EDNS_DO_BIT = 613, 252 GETDNS_CONTEXT_CODE_DNSSEC_ALLOWED_SKEW = 614, 253 GETDNS_CONTEXT_CODE_MEMORY_FUNCTIONS = 615, 254 GETDNS_CONTEXT_CODE_TIMEOUT = 616, 255 GETDNS_CONTEXT_CODE_IDLE_TIMEOUT = 617 256} getdns_context_code_t; 257 258 259#define GETDNS_CONTEXT_CODE_NAMESPACES_TEXT "Change related to getdns_context_set_namespaces" 260#define GETDNS_CONTEXT_CODE_RESOLUTION_TYPE_TEXT "Change related to getdns_context_set_resolution_type" 261#define GETDNS_CONTEXT_CODE_FOLLOW_REDIRECTS_TEXT "Change related to getdns_context_set_follow_redirects" 262#define GETDNS_CONTEXT_CODE_UPSTREAM_RECURSIVE_SERVERS_TEXT "Change related to getdns_context_set_upstream_recursive_servers" 263#define GETDNS_CONTEXT_CODE_DNS_ROOT_SERVERS_TEXT "Change related to getdns_context_set_dns_root_servers" 264#define GETDNS_CONTEXT_CODE_DNS_TRANSPORT_TEXT "Change related to getdns_context_set_dns_transport" 265#define GETDNS_CONTEXT_CODE_LIMIT_OUTSTANDING_QUERIES_TEXT "Change related to getdns_context_set_limit_outstanding_queries" 266#define GETDNS_CONTEXT_CODE_APPEND_NAME_TEXT "Change related to getdns_context_set_append_name" 267#define GETDNS_CONTEXT_CODE_SUFFIX_TEXT "Change related to getdns_context_set_suffix" 268#define GETDNS_CONTEXT_CODE_DNSSEC_TRUST_ANCHORS_TEXT "Change related to getdns_context_set_dnssec_trust_anchors" 269#define GETDNS_CONTEXT_CODE_EDNS_MAXIMUM_UDP_PAYLOAD_SIZE_TEXT "Change related to getdns_context_set_edns_maximum_udp_payload_size" 270#define GETDNS_CONTEXT_CODE_EDNS_EXTENDED_RCODE_TEXT "Change related to getdns_context_set_edns_extended_rcode" 271#define GETDNS_CONTEXT_CODE_EDNS_VERSION_TEXT "Change related to getdns_context_set_edns_version" 272#define GETDNS_CONTEXT_CODE_EDNS_DO_BIT_TEXT "Change related to getdns_context_set_edns_do_bit" 273#define GETDNS_CONTEXT_CODE_DNSSEC_ALLOWED_SKEW_TEXT "Change related to getdns_context_set_dnssec_allowed_skew" 274#define GETDNS_CONTEXT_CODE_MEMORY_FUNCTIONS_TEXT "Change related to getdns_context_set_memory_functions" 275#define GETDNS_CONTEXT_CODE_TIMEOUT_TEXT "Change related to getdns_context_set_timeout" 276#define GETDNS_CONTEXT_CODE_IDLE_TIMEOUT_TEXT "Change related to getdns_context_set_idle_timeout" 277/** @} 278 */ 279 280 281/** 282 * \defgroup callbacktype Callback types and texts 283 * @{ 284 */ 285typedef enum getdns_callback_type_t { 286 GETDNS_CALLBACK_COMPLETE = 700, 287 GETDNS_CALLBACK_CANCEL = 701, 288 GETDNS_CALLBACK_TIMEOUT = 702, 289 GETDNS_CALLBACK_ERROR = 703 290} getdns_callback_type_t; 291 292#define GETDNS_CALLBACK_COMPLETE_TEXT "The response has the requested data in it" 293#define GETDNS_CALLBACK_CANCEL_TEXT "The calling program cancelled the callback; response is NULL" 294#define GETDNS_CALLBACK_TIMEOUT_TEXT "The requested action timed out; response is filled in with empty structures" 295#define GETDNS_CALLBACK_ERROR_TEXT "The requested action had an error; response is NULL" 296/** @} 297 */ 298 299 300/** 301 * \defgroup nametype Types of name services and texts 302 * @{ 303 */ 304#define GETDNS_NAMETYPE_DNS 800 305#define GETDNS_NAMETYPE_DNS_TEXT "Normal DNS (RFC 1035)" 306#define GETDNS_NAMETYPE_WINS 801 307#define GETDNS_NAMETYPE_WINS_TEXT "The WINS name service (some reference needed)" 308/** @} 309 */ 310 311 312/** 313 * \defgroup respstatus Status Codes for responses and texts 314 * @{ 315 */ 316#define GETDNS_RESPSTATUS_GOOD 900 317#define GETDNS_RESPSTATUS_GOOD_TEXT "At least one response was returned" 318#define GETDNS_RESPSTATUS_NO_NAME 901 319#define GETDNS_RESPSTATUS_NO_NAME_TEXT "Queries for the name yielded all negative responses" 320#define GETDNS_RESPSTATUS_ALL_TIMEOUT 902 321#define GETDNS_RESPSTATUS_ALL_TIMEOUT_TEXT "All queries for the name timed out" 322#define GETDNS_RESPSTATUS_NO_SECURE_ANSWERS 903 323#define GETDNS_RESPSTATUS_NO_SECURE_ANSWERS_TEXT "The context setting for getting only secure responses was specified, and at least one DNS response was received, but no DNS response was determined to be secure through DNSSEC." 324#define GETDNS_RESPSTATUS_ALL_BOGUS_ANSWERS 904 325#define GETDNS_RESPSTATUS_ALL_BOGUS_ANSWERS_TEXT "The context setting for getting only secure responses was specified, and at least one DNS response was received, but all received responses for the requested name were bogus." 326/** @} 327 */ 328 329/** 330 * \defgroup extvals Values associated with extensions and texts 331 * @{ 332 */ 333#define GETDNS_EXTENSION_TRUE 1000 334#define GETDNS_EXTENSION_TRUE_TEXT "Turn on the extension" 335#define GETDNS_EXTENSION_FALSE 1001 336#define GETDNS_EXTENSION_FALSE_TEXT "Do not turn on the extension" 337/** @} 338 */ 339 340/** 341 * \defgroup dnserrors Values associated with DNS errors found by the API and texts 342 * @{ 343 */ 344#define GETDNS_BAD_DNS_CNAME_IN_TARGET 1100 345#define GETDNS_BAD_DNS_CNAME_IN_TARGET_TEXT "A DNS query type that does not allow a target to be a CNAME pointed to a CNAME" 346#define GETDNS_BAD_DNS_ALL_NUMERIC_LABEL 1101 347#define GETDNS_BAD_DNS_ALL_NUMERIC_LABEL_TEXT "One or more labels in a returned domain name is all-numeric; this is not legal for a hostname" 348#define GETDNS_BAD_DNS_CNAME_RETURNED_FOR_OTHER_TYPE 1102 349#define GETDNS_BAD_DNS_CNAME_RETURNED_FOR_OTHER_TYPE_TEXT "A DNS query for a type other than CNAME returned a CNAME response" 350/** @} 351 */ 352 353 354/** 355 * \defgroup rrtypes RR Types 356 * @{ 357 */ 358#define GETDNS_RRTYPE_A 1 359#define GETDNS_RRTYPE_NS 2 360#define GETDNS_RRTYPE_MD 3 361#define GETDNS_RRTYPE_MF 4 362#define GETDNS_RRTYPE_CNAME 5 363#define GETDNS_RRTYPE_SOA 6 364#define GETDNS_RRTYPE_MB 7 365#define GETDNS_RRTYPE_MG 8 366#define GETDNS_RRTYPE_MR 9 367#define GETDNS_RRTYPE_NULL 10 368#define GETDNS_RRTYPE_WKS 11 369#define GETDNS_RRTYPE_PTR 12 370#define GETDNS_RRTYPE_HINFO 13 371#define GETDNS_RRTYPE_MINFO 14 372#define GETDNS_RRTYPE_MX 15 373#define GETDNS_RRTYPE_TXT 16 374#define GETDNS_RRTYPE_RP 17 375#define GETDNS_RRTYPE_AFSDB 18 376#define GETDNS_RRTYPE_X25 19 377#define GETDNS_RRTYPE_ISDN 20 378#define GETDNS_RRTYPE_RT 21 379#define GETDNS_RRTYPE_NSAP 22 380#define GETDNS_RRTYPE_NSAP_PTR 23 381#define GETDNS_RRTYPE_SIG 24 382#define GETDNS_RRTYPE_KEY 25 383#define GETDNS_RRTYPE_PX 26 384#define GETDNS_RRTYPE_GPOS 27 385#define GETDNS_RRTYPE_AAAA 28 386#define GETDNS_RRTYPE_LOC 29 387#define GETDNS_RRTYPE_NXT 30 388#define GETDNS_RRTYPE_EID 31 389#define GETDNS_RRTYPE_NIMLOC 32 390#define GETDNS_RRTYPE_SRV 33 391#define GETDNS_RRTYPE_ATMA 34 392#define GETDNS_RRTYPE_NAPTR 35 393#define GETDNS_RRTYPE_KX 36 394#define GETDNS_RRTYPE_CERT 37 395#define GETDNS_RRTYPE_A6 38 396#define GETDNS_RRTYPE_DNAME 39 397#define GETDNS_RRTYPE_SINK 40 398#define GETDNS_RRTYPE_OPT 41 399#define GETDNS_RRTYPE_APL 42 400#define GETDNS_RRTYPE_DS 43 401#define GETDNS_RRTYPE_SSHFP 44 402#define GETDNS_RRTYPE_IPSECKEY 45 403#define GETDNS_RRTYPE_RRSIG 46 404#define GETDNS_RRTYPE_NSEC 47 405#define GETDNS_RRTYPE_DNSKEY 48 406#define GETDNS_RRTYPE_DHCID 49 407#define GETDNS_RRTYPE_NSEC3 50 408#define GETDNS_RRTYPE_NSEC3PARAM 51 409#define GETDNS_RRTYPE_TLSA 52 410#define GETDNS_RRTYPE_SMIMEA 53 411#define GETDNS_RRTYPE_HIP 55 412#define GETDNS_RRTYPE_NINFO 56 413#define GETDNS_RRTYPE_RKEY 57 414#define GETDNS_RRTYPE_TALINK 58 415#define GETDNS_RRTYPE_CDS 59 416#define GETDNS_RRTYPE_CDNSKEY 60 417#define GETDNS_RRTYPE_OPENPGPKEY 61 418#define GETDNS_RRTYPE_CSYNC 62 419#define GETDNS_RRTYPE_ZONEMD 63 420#define GETDNS_RRTYPE_SPF 99 421#define GETDNS_RRTYPE_UINFO 100 422#define GETDNS_RRTYPE_UID 101 423#define GETDNS_RRTYPE_GID 102 424#define GETDNS_RRTYPE_UNSPEC 103 425#define GETDNS_RRTYPE_NID 104 426#define GETDNS_RRTYPE_L32 105 427#define GETDNS_RRTYPE_L64 106 428#define GETDNS_RRTYPE_LP 107 429#define GETDNS_RRTYPE_EUI48 108 430#define GETDNS_RRTYPE_EUI64 109 431#define GETDNS_RRTYPE_TKEY 249 432#define GETDNS_RRTYPE_TSIG 250 433#define GETDNS_RRTYPE_IXFR 251 434#define GETDNS_RRTYPE_AXFR 252 435#define GETDNS_RRTYPE_MAILB 253 436#define GETDNS_RRTYPE_MAILA 254 437#define GETDNS_RRTYPE_ANY 255 438#define GETDNS_RRTYPE_URI 256 439#define GETDNS_RRTYPE_CAA 257 440#define GETDNS_RRTYPE_AVC 258 441#define GETDNS_RRTYPE_DOA 259 442#define GETDNS_RRTYPE_AMTRELAY 260 443#define GETDNS_RRTYPE_TA 32768 444#define GETDNS_RRTYPE_DLV 32769 445/** @} 446 */ 447 448/** 449 * \defgroup rrclasses RR Classes 450 * @{ 451 */ 452#define GETDNS_RRCLASS_IN 1 453#define GETDNS_RRCLASS_CH 3 454#define GETDNS_RRCLASS_HS 4 455#define GETDNS_RRCLASS_NONE 254 456#define GETDNS_RRCLASS_ANY 255 457/** @} 458 */ 459 460/** 461 * \defgroup opcodes Opcodes 462 * @{ 463 */ 464#define GETDNS_OPCODE_QUERY 0 465#define GETDNS_OPCODE_IQUERY 1 466#define GETDNS_OPCODE_STATUS 2 467#define GETDNS_OPCODE_NOTIFY 4 468#define GETDNS_OPCODE_UPDATE 5 469/** @} 470 */ 471 472/** 473 * \defgroup rcodes Rcodes 474 * @{ 475 */ 476#define GETDNS_RCODE_NOERROR 0 477#define GETDNS_RCODE_FORMERR 1 478#define GETDNS_RCODE_SERVFAIL 2 479#define GETDNS_RCODE_NXDOMAIN 3 480#define GETDNS_RCODE_NOTIMP 4 481#define GETDNS_RCODE_REFUSED 5 482#define GETDNS_RCODE_YXDOMAIN 6 483#define GETDNS_RCODE_YXRRSET 7 484#define GETDNS_RCODE_NXRRSET 8 485#define GETDNS_RCODE_NOTAUTH 9 486#define GETDNS_RCODE_NOTZONE 10 487#define GETDNS_RCODE_BADVERS 16 488#define GETDNS_RCODE_BADSIG 16 489#define GETDNS_RCODE_BADKEY 17 490#define GETDNS_RCODE_BADTIME 18 491#define GETDNS_RCODE_BADMODE 19 492#define GETDNS_RCODE_BADNAME 20 493#define GETDNS_RCODE_BADALG 21 494#define GETDNS_RCODE_BADTRUNC 22 495#define GETDNS_RCODE_COOKIE 23 496/** @} 497 */ 498 499 500/** 501 * Many calls in the DNS API require a DNS context. A DNS context contains 502 * the information that the API needs in order to process DNS calls, such 503 * as the locations of upstream DNS servers, DNSSEC trust anchors, and so on. 504 * The internal structure of the DNS context is opaque, and might be different 505 * on each OS. When a context is passed to any function, it must be an 506 * allocated context; the context must not be NULL. 507 * 508 * Use getdns_context_set_* functions to configure a context. 509 */ 510typedef struct getdns_context getdns_context; 511 512/** 513 * When scheduling asynchronous requests, transaction identifiers associated 514 * with the request are returned. These identifiers are of the type: 515 * getdns_transaction_t. These identifiers can be used to associate answers 516 * with requests, and also to cancel outstanding requests. 517 */ 518typedef uint64_t getdns_transaction_t; 519 520 521/** 522 * getdns_list_get_data_type() and getdns_dict_get_data_type() return the type 523 * of data on an index in a getdns_list, or on a name in a getdns_dict. 524 */ 525typedef enum getdns_data_type 526{ 527 t_dict, t_list, t_int, t_bindata 528} getdns_data_type; 529 530 531/** 532 * A struct to hold binary data. 533 */ 534typedef struct getdns_bindata 535{ 536 size_t size; 537 uint8_t *data; 538} getdns_bindata; 539 540/** 541 * getdns dictionary data type 542 * Use helper functions getdns_dict_* to manipulate and iterate dictionaries 543 */ 544typedef struct getdns_dict getdns_dict; 545 546/** 547 * getdns list data type 548 * Use helper functions getdns_list_* to manipulate and iterate lists 549 * Indexes are 0 based. 550 */ 551typedef struct getdns_list getdns_list; 552/** @} 553 */ 554 555 556/** \addtogroup functions Functions 557 * @{ 558 */ 559/* Specify the order of the following groups manually here so they appear in 560 a better order in doxygen */ 561 562/** 563 * \defgroup getdns_context Creating, destroying, configuring and reading configuration from getdns_contexts 564 * \defgroup getdns_dict Creating, destroying, reading from and manipulating getdns_dicts 565 * \defgroup getdns_list Creating, destroying, reading from and manipulating getdns_lists 566 * \defgroup asyncfuncs Scheduling asynchronous requests 567 * \defgroup syncfuncs Performing synchronous requests 568 * \defgroup eventloops Event loop extension functions 569 * \defgroup versionfuncs Version functions 570 * \defgroup dnssecfuncs DNSSEC functions 571 * \defgroup utils Utility functions 572 */ 573 574 575/** 576 * \addtogroup getdns_list 577 * @{ 578 */ 579 580/** 581 * get the length of the specified list (returned in *answer) 582 * @param list list of any of the supported data types 583 * @param answer number of valid items in the list 584 * @return GETDNS_RETURN_GOOD on success 585 * @return GETDNS_RETURN_NO_SUCH_LIST_ITEM if list is not valid or params are NULL 586 */ 587getdns_return_t getdns_list_get_length(const getdns_list *list, 588 size_t * answer); 589/** 590 * get the enumerated data type of the indexed list item 591 * @param list the list from which to fetch the data type 592 * @param index the item in the list from which to fetch the data type 593 * @param *answer assigned the value of the data type on success 594 * @return GETDNS_RETURN_GOOD on success 595 * @return GETDNS_RETURN_NO_SUCH_LIST_ITEM if the index is out of range or the list is NULL 596 */ 597getdns_return_t getdns_list_get_data_type(const getdns_list *list, 598 size_t index, getdns_data_type * answer); 599/** 600 * retrieve the dictionary value of the specified list item, the caller must not free 601 * storage associated with the return value. When the list is destroyed this 602 * dict data is also free()'d - keep this in mind when using this function. 603 * @param list the list from which to fetch the value 604 * @param index the item in the list from which to fetch the value 605 * @param **answer assigned a pointer to the dict value of the indexed element 606 * @return GETDNS_RETURN_GOOD on success 607 * @return GETDNS_RETURN_NO_SUCH_LIST_ITEM if the index is out of range or the list is NULL 608 * @return GETDNS_RETURN_WRONG_TYPE_REQUESTED if the data type does not match the contents of the indexed item 609 */ 610getdns_return_t getdns_list_get_dict(const getdns_list *list, size_t index, 611 getdns_dict **answer); 612 613/** 614 * retrieve the list value of the specified list item, the caller must not free 615 * storage associated with the return value. When the list is destroyed any 616 * list data is also free()'d - keep this in mind when using this function. 617 * @param list the list from which to fetch the value 618 * @param index the item in the list from which to fetch the value 619 * @param **answer assigned a pointer to the list value of the indexed element 620 * @return GETDNS_RETURN_GOOD on success 621 * @return GETDNS_RETURN_NO_SUCH_LIST_ITEM if the index is out of range or the list is NULL 622 * @return GETDNS_RETURN_WRONG_TYPE_REQUESTED if the data type does not match the contents of the indexed item 623 */ 624getdns_return_t getdns_list_get_list(const getdns_list *list, size_t index, 625 getdns_list **answer); 626/** 627 * retrieve the binary data value of the specified list item, the caller must not 628 * free storage associated with the return value. When the list is destroyed any 629 * bindata data is also free()'d - keep this in mind when using this function. 630 * @param list the list from which to fetch the value 631 * @param index the item in the list from which to fetch the value 632 * @param **answer assigned a pointer to the list value of the indexed element 633 * @return GETDNS_RETURN_GOOD on success 634 * @return GETDNS_RETURN_NO_SUCH_LIST_ITEM if the index is out of range or the list is NULL 635 * @return GETDNS_RETURN_WRONG_TYPE_REQUESTED if the data type does not match the contents of the indexed item 636 */ 637getdns_return_t getdns_list_get_bindata(const getdns_list *list, size_t index, 638 getdns_bindata **answer); 639/** 640 * retrieve the integer value of the specified list item 641 * @param list the list from which to fetch the item 642 * @param index the index of the element in the list to fetch from 643 * @param *answer assigned the integer value of the indexed element 644 * @return GETDNS_RETURN_GOOD on success 645 * @return GETDNS_RETURN_NO_SUCH_LIST_ITEM if the index is out of range or the list is NULL 646 * @return GETDNS_RETURN_WRONG_TYPE_REQUESTED if the data type does not match the contents of the indexed item 647 */ 648getdns_return_t getdns_list_get_int(const getdns_list *list, size_t index, 649 uint32_t * answer); 650/** @} 651 */ 652 653 654/** 655 * \addtogroup getdns_dict 656 * @{ 657 */ 658 659/** 660 * fetch a list of names from the dictionary, this list must be freed by the caller 661 * via a call to getdns_list_destroy 662 * @param dict dictionary from which to produce the list of names 663 * @param **answer a pointer to the new list will be assigned to *answer 664 * @return GETDNS_RETURN_GOOD on success 665 * @return GETDNS_RETURN_NO_SUCH_DICT_NAME if dict is invalid or empty 666 */ 667getdns_return_t getdns_dict_get_names(const getdns_dict *dict, 668 getdns_list **answer); 669/** 670 * fetch the data type for the data associated with the specified name 671 * @param dict dictionary from which to fetch the data type 672 * @param name a name/key value to look up in the dictionary 673 * @param *answer data type will be stored at this address 674 * @return GETDNS_RETURN_GOOD on success 675 * @return GETDNS_RETURN_NO_SUCH_DICT_NAME if dict is invalid or name does not exist 676 */ 677getdns_return_t getdns_dict_get_data_type(const getdns_dict *dict, 678 const char *name, getdns_data_type * answer); 679/** 680 * fetch the dictionary associated with the specified name, the dictionary should 681 * not be free()'d by the caller, it will be freed when the parent dictionary is 682 * free()'d 683 * @param dict dictionary from which to fetch the dictionary 684 * @param name a name/key value to look up in the dictionary 685 * @param **answer a copy of the dictionary will be stored at this address 686 * @return GETDNS_RETURN_GOOD on success 687 * @return GETDNS_RETURN_NO_SUCH_DICT_NAME if dict is invalid or name does not exist 688 */ 689getdns_return_t getdns_dict_get_dict(const getdns_dict *dict, 690 const char *name, getdns_dict **answer); 691/** 692 * fetch the list associated with the specified name 693 * the list should not be free()'d by the caller, when the dictionary is destroyed 694 * the list will also be destroyed 695 * @param dict dictionary from which to fetch the list 696 * @param name a name/key value to look up in the dictionary 697 * @param **answer a copy of the list will be stored at this address 698 * @return GETDNS_RETURN_GOOD on success 699 * @return GETDNS_RETURN_NO_SUCH_DICT_NAME if dict is invalid or name does not exist 700 */ 701getdns_return_t getdns_dict_get_list(const getdns_dict *dict, 702 const char *name, getdns_list **answer); 703/** 704 * fetch the bindata associated with the specified name, the bindata should not be 705 * free()'d by the caller 706 * @param dict dictionary from which to fetch the bindata 707 * @param name a name/key value to look up in the dictionary 708 * @param **answer a copy of the bindata will be stored at this address 709 * @return GETDNS_RETURN_GOOD on success 710 * @return GETDNS_RETURN_NO_SUCH_DICT_NAME if dict is invalid or name does not exist 711 */ 712getdns_return_t getdns_dict_get_bindata(const getdns_dict *dict, 713 const char *name, getdns_bindata **answer); 714/** 715 * fetch the integer value associated with the specified name 716 * @param dict dictionary from which to fetch the integer 717 * @param name a name/key value to look up in the dictionary 718 * @param *answer the integer will be stored at this address 719 * @return GETDNS_RETURN_GOOD on success 720 * @return GETDNS_RETURN_NO_SUCH_DICT_NAME if dict is invalid or name does not exist 721 */ 722getdns_return_t getdns_dict_get_int(const getdns_dict *dict, 723 const char *name, uint32_t * answer); 724/** @} 725 */ 726 727 728/** 729 * \addtogroup getdns_list 730 * @{ 731 */ 732 733/** 734 * create a new list with no items 735 * @return pointer to an allocated list, NULL if insufficient memory 736 */ 737getdns_list *getdns_list_create(); 738 739/** 740 * create a new list with no items, creating and initializing it with the 741 * custom memory function from context. These memory functions will be used 742 * for creating, and inherited by the list members when populating the list. 743 * The custom deallocator will be used for destroying the list. 744 * @param context The context from which the custom memory functions will be 745 * used to create and initialize the list. 746 * @return pointer to an allocated list, NULL if insufficient memory 747 */ 748getdns_list *getdns_list_create_with_context(const getdns_context *context); 749 750/** 751 * create a new list with no items, creating and initializing it with the 752 * provided custom memory function. These memory functions will be used 753 * for creating, and inherited by the list members when populating the list. 754 * The custom deallocator will be used for destroying the list. 755 * @param malloc Custom allocator 756 * @param realloc Custom reallocator 757 * @param free Custom deallocator 758 * @return pointer to an allocated list, NULL if insufficient memory 759 */ 760getdns_list *getdns_list_create_with_memory_functions( 761 void *(*malloc) (size_t), 762 void *(*realloc) (void *, size_t), 763 void (*free) (void *) 764); 765 766/** 767 * create a new list with no items, creating and initializing it with the 768 * provided extended custom memory function. These memory functions will be 769 * used for creating, and inherited by the list members when populating the 770 * list. The custom deallocator will be used for destroying the list. 771 * @param userarg Will be passed as the first argument to the extended 772 * custom malloc, realloc, and free. 773 * @param malloc Custom allocator 774 * @param realloc Custom reallocator 775 * @param free Custom deallocator 776 * @return pointer to an allocated list, NULL if insufficient memory 777 */ 778getdns_list *getdns_list_create_with_extended_memory_functions( 779 void *userarg, 780 void *(*malloc) (void *userarg, size_t), 781 void *(*realloc) (void *userarg, void *, size_t), 782 void (*free) (void *userarg, void *) 783); 784 785 786/** 787 * free memory allocated to the list (also frees all children of the list) 788 * note that lists and bindata retrieved from the list via the getdns_list_get_* 789 * helper functions will be destroyed as well - if you fetched them previously 790 * you MUST copy those instances BEFORE you destroy the list else 791 * unpleasant things will happen at run-time 792 */ 793void getdns_list_destroy(getdns_list *list); 794/** @} 795*/ 796 797 798/** 799 * \addtogroup getdns_list 800 * @{ 801 */ 802 803/** 804 * assign the child_dict to an item in a parent list, the parent list copies 805 * the child dict and will free the copy when the list is destroyed 806 * @param list list containing the item to which child_list is to be assigned 807 * @param index index of the item within list to which child_list is to be assigned 808 * @param *child_dict dict to assign to the item 809 * @return GETDNS_RETURN_GOOD on success 810 * @return GETDNS_RETURN_NO_SUCH_LIST_ITEM if index is out of range, or list is NULL 811 */ 812getdns_return_t getdns_list_set_dict(getdns_list *list, size_t index, 813 const getdns_dict *child_dict); 814 815/** 816 * assign the child_list to an item in a parent list, the parent list copies 817 * the child list and will free the copy when the list is destroyed 818 * @param list list containing the item to which child_list is to be assigned 819 * @param index index of the item within list to which child_list is to be assigned 820 * @param *child_list list to assign to the item 821 * @return GETDNS_RETURN_GOOD on success 822 * @return GETDNS_RETURN_NO_SUCH_LIST_ITEM if index is out of range, or list is NULL 823 */ 824getdns_return_t getdns_list_set_list(getdns_list *list, size_t index, 825 const getdns_list *child_list); 826/** 827 * assign the child_bindata to an item in a parent list, the parent list copies 828 * the child data and will free the copy when the list is destroyed 829 * @param list list contiaining the item to which child_list is to be assigned 830 * @param index index of the item within list to which child_list is to be assigned 831 * @param *child_bindata data to assign to the item 832 * @return GETDNS_RETURN_GOOD on success 833 * @return GETDNS_RETURN_NO_SUCH_LIST_ITEM if index is out of range, or list is NULL 834 */ 835getdns_return_t getdns_list_set_bindata(getdns_list *list, size_t index, 836 const getdns_bindata *child_bindata); 837/** 838 * set the integer value of the indexed item (zero based index) 839 * @return GETDNS_RETURN_GOOD on success 840 * @return GETDNS_RETURN_NO_SUCH_LIST_ITEM if index is out of range, or list is NULL 841 */ 842getdns_return_t getdns_list_set_int(getdns_list *list, size_t index, 843 uint32_t child_uint32); 844/** @} 845 */ 846 847 848/** 849 * \addtogroup getdns_dict 850 * @{ 851 */ 852 853/** 854 * create a new dictionary with no items 855 * @return pointer to an allocated dictionary, NULL if insufficient memory 856 */ 857getdns_dict *getdns_dict_create(); 858 859/** 860 * create a new dict with no items, creating and initializing it with the 861 * custom memory function from context. These memory functions will be used 862 * for creating, and inherited by the list members when populating the dict. 863 * The custom deallocator will be used for destroying the dict. 864 * @param context The context from which the custom memory functions will be 865 * used to create and initialize the dict. 866 * @return pointer to an allocated dict, NULL if insufficient memory 867 */ 868getdns_dict *getdns_dict_create_with_context(const getdns_context *context); 869 870/** 871 * create a new dict with no items, creating and initializing it with the 872 * provided custom memory function. These memory functions will be used 873 * for creating, and inherited by the dict members when populating the dict. 874 * The custom deallocator will be used for destroying the dict. 875 * @param malloc Custom allocator 876 * @param realloc Custom reallocator 877 * @param free Custom deallocator 878 * @return pointer to an allocated dict, NULL if insufficient memory 879 */ 880getdns_dict *getdns_dict_create_with_memory_functions( 881 void *(*malloc) (size_t), 882 void *(*realloc) (void *, size_t), 883 void (*free) (void *) 884); 885 886/** 887 * create a new dict with no items, creating and initializing it with the 888 * provided extended custom memory function. These memory functions will be 889 * used for creating, and inherited by the dict members when populating the 890 * dict. The custom deallocator will be used for destroying the dict. 891 * @param userarg Will be passed as the first argument to the extended 892 * custom malloc, realloc, and free. 893 * @param malloc Custom allocator 894 * @param realloc Custom reallocator 895 * @param free Custom deallocator 896 * @return pointer to an allocated dict, NULL if insufficient memory 897 */ 898getdns_dict *getdns_dict_create_with_extended_memory_functions( 899 void *userarg, 900 void *(*malloc) (void *userarg, size_t), 901 void *(*realloc) (void *userarg, void *, size_t), 902 void (*free) (void *userarg, void *) 903); 904 905/** 906 * destroy a dictionary and all items within that dictionary 907 * be aware that if you have fetched any data from the dictionary it will 908 * no longer be available (you are likely to experience bad things if you try) 909 */ 910void getdns_dict_destroy(getdns_dict *dict); 911/** @} 912*/ 913 914 915/** 916 * \addtogroup getdns_dict 917 * @{ 918 */ 919 920/** 921 * create a new entry in the dictionary, or replace the value of an existing entry 922 * this routine makes a copy of the child_dict_ 923 * @param dict dictionary in which to add or change the value 924 * @param name key that identifies which item in the dictionary to add/change 925 * @param child_dict value to assign to the node identified by name 926 * @return GETDNS_RETURN_GOOD on success 927 */ 928getdns_return_t getdns_dict_set_dict(getdns_dict *dict, 929 const char *name, const getdns_dict *child_dict); 930 931/** 932 * create a new entry in the dictionary, or replace the value of an existing entry 933 * this routine makes a copy of the child_list 934 * @param dict dictionary in which to add or change the value 935 * @param name key that identifies which item in the dictionary to add/change 936 * @param child_list value to assign to the node identified by name 937 * @return GETDNS_RETURN_GOOD on success 938 */ 939getdns_return_t getdns_dict_set_list(getdns_dict *dict, 940 const char *name, const getdns_list *child_list); 941/** 942 * create a new entry in the dictionary, or replace the value of an existing entry 943 * this routine makes a copy of the child_bindata 944 * @param dict dictionary in which to add or change the value 945 * @param name key that identifies which item in the dictionary to add/change 946 * @param child_bindata value to assign to the node identified by name 947 * @return GETDNS_RETURN_GOOD on success 948 */ 949getdns_return_t getdns_dict_set_bindata(getdns_dict *dict, 950 const char *name, const getdns_bindata *child_bindata); 951/** 952 * create a new entry in the dictionary, or replace the value of an existing entry 953 * @param dict dictionary in which to add or change the value 954 * @param name key that identifies which item in the dictionary to add/change 955 * @param child_uint32 value to assign to the node identified by name 956 * @return GETDNS_RETURN_GOOD on success 957 */ 958getdns_return_t getdns_dict_set_int(getdns_dict *dict, const char *name, 959 uint32_t child_uint32); 960 961/** 962 * creates a string that describes the dictionary in a human readable form 963 * one line per item in the dictionary 964 * @param some_dict dictionary to pretty print 965 * @return character array (caller must free this) containing pretty string 966 */ 967char *getdns_pretty_print_dict(const getdns_dict *some_dict); 968/** @} 969 */ 970 971 972/** 973 * \addtogroup utils 974 * remove the value associated with the specified name 975 * @param dict dictionary from which to fetch the integer 976 * @param name a name/key value to look up in the dictionary 977 * @return GETDNS_RETURN_GOOD on success 978 * @return GETDNS_RETURN_NO_SUCH_DICT_NAME if dict is invalid or name does not exist 979 */ 980getdns_return_t getdns_dict_remove_name(getdns_dict *dict, const char *name); 981 982/** 983 * \addtogroup asyncfuncs 984 * @{ 985 */ 986/** 987 * The type of the callback function that must be registered when scheduling 988 * asynchronous requests. The registered function will be called from the 989 * eventloop with the following parameters. 990 * @see callbacktype 991 * @param context The DNS context that was used in the calling function 992 * @param callback_type Supplies the reason for the callback. 993 * This will be one of: 994 * - GETDNS_CALLBACK_COMPLETE The response has the 995 * requested data in it 996 * - GETDNS_CALLBACK_CANCEL The calling program cancelled 997 * the callback; response is NULL 998 * - GETDNS_CALLBACK_TIMEOUT The requested action timed 999 * out; response is filled in with empty structures or 1000 * will contain additional information about the timeout 1001 * when used in combination with the 1002 * return_call_reporting extension. 1003 * - GETDNS_CALLBACK_ERROR The requested action had an 1004 * error; response is NULL. 1005 * @param response A response object with the response data. 1006 * The application is responsible for cleaning up the response 1007 * object with getdns_dict_destroy. 1008 * @param userarg Identical to the userarg passed to the calling function. 1009 * @param transaction_id The transaction identifier that was assigned by the 1010 * calling function. 1011 */ 1012typedef void (*getdns_callback_t) (getdns_context *context, 1013 getdns_callback_type_t callback_type, 1014 getdns_dict * response, 1015 void *userarg, getdns_transaction_t transaction_id); 1016 1017 1018/** 1019 * retrieve general DNS data 1020 * @see rrtypes 1021 * @see getdns_general_sync 1022 * @param context pointer to a previously created context to be used for this call 1023 * @param name the ASCII based domain name to lookup 1024 * @param request_type RR type for the query, e.g. GETDNS_RR_TYPE_NS 1025 * @param extensions dict data structures, NULL to use no extensions 1026 * @param userarg void* returned to the callback untouched 1027 * @param[out] transaction_id id used to identify the callback, NULL is ignored 1028 * @param callbackfn callback function defined by the application 1029 * @return GETDNS_RETURN_GOOD on success 1030 */ 1031getdns_return_t 1032getdns_general(getdns_context *context, 1033 const char *name, 1034 uint16_t request_type, 1035 const getdns_dict *extensions, 1036 void *userarg, 1037 getdns_transaction_t *transaction_id, getdns_callback_t callbackfn); 1038 1039/** 1040 * retrieve address assigned to a DNS name 1041 * @see getdns_address_sync 1042 * @param context pointer to a previously created context to be used for this call 1043 * @param name the ASCII based domain name to lookup 1044 * @param extensions dict data structures, NULL to use no extensions 1045 * @param userarg void* returned to the callback untouched 1046 * @param[out] transaction_id id used to identify the callback, NULL is ignored 1047 * @param callbackfn callback function defined by the application 1048 * @return GETDNS_RETURN_GOOD on success 1049 */ 1050getdns_return_t 1051getdns_address(getdns_context *context, 1052 const char *name, 1053 const getdns_dict *extensions, 1054 void *userarg, 1055 getdns_transaction_t *transaction_id, getdns_callback_t callbackfn); 1056 1057/** 1058 * retrieve hostname assigned to an IP address 1059 * @see getdns_hostname_sync 1060 * @param context pointer to a previously created context to be used for this call 1061 * @param address the address to look up 1062 * @param extensions dict data structures, NULL to use no extensions 1063 * @param userarg void* returned to the callback untouched 1064 * @param[out] transaction_id id used to identify the callback, NULL is ignored 1065 * @param callbackfn callback function defined by the application 1066 * @return GETDNS_RETURN_GOOD on success 1067 */ 1068getdns_return_t 1069getdns_hostname(getdns_context *context, 1070 const getdns_dict *address, 1071 const getdns_dict *extensions, 1072 void *userarg, 1073 getdns_transaction_t *transaction_id, getdns_callback_t callbackfn); 1074 1075/** 1076 * retrieve a service assigned to a DNS name 1077 * @see getdns_service_sync 1078 * @param context pointer to a previously created context to be used for this call 1079 * @param name the ASCII based domain name to lookup 1080 * @param extensions dict data structures, NULL to use no extensions 1081 * @param userarg void* returned to the callback untouched 1082 * @param[out] transaction_id id used to identify the callback, NULL is ignored 1083 * @param callbackfn callback function defined by the application 1084 * @return GETDNS_RETURN_GOOD on success 1085 */ 1086getdns_return_t 1087getdns_service(getdns_context *context, 1088 const char *name, 1089 const getdns_dict *extensions, 1090 void *userarg, 1091 getdns_transaction_t *transaction_id, getdns_callback_t callbackfn); 1092/** @} 1093 */ 1094 1095 1096/** 1097 * \addtogroup getdns_context 1098 * @{ 1099 */ 1100 1101/** 1102 * creates a new getdns context with default settings. 1103 * If used multi-threaded, user must define appropriate OpenSSL callback locking functions 1104 * (e.g. CRYPTO_THREADID_set_call) depending on the library version used. 1105 * @param context context that can be used immediately with other API calls 1106 * @param set_from_os set to 1 to initialize the context with os defaults 1107 * @return GETDNS_RETURN_GOOD on success 1108*/ 1109getdns_return_t 1110getdns_context_create(getdns_context ** context, int set_from_os); 1111 1112 1113/** 1114 * creates a new getdns context with default settings using custom memory functions. 1115 * If used multi-threaded, user must define appropriate OpenSSL callback locking functions 1116 * (e.g. CRYPTO_THREADID_set_call) depending on the library version used. 1117 * @param context context that can be used immediately with other API calls 1118 * @param set_from_os set to 1 to initialize the context with os defaults 1119 * @param malloc custom malloc function 1120 * @param realloc custom realloc function 1121 * @param free custom free function 1122 * @return GETDNS_RETURN_GOOD on success 1123*/ 1124getdns_return_t 1125getdns_context_create_with_memory_functions( 1126 getdns_context ** context, 1127 int set_from_os, 1128 void *(*malloc) (size_t), 1129 void *(*realloc) (void *, size_t), 1130 void (*free) (void *) 1131); 1132 1133 1134/** 1135 * creates a new getdns context with default settings using extended custom memory functions. 1136 * If used multi-threaded, user must define appropriate OpenSSL callback locking functions 1137 * (e.g. CRYPTO_THREADID_set_call) depending on the library version used. 1138 * @param context context that can be used immediately with other API calls 1139 * @param set_from_os set to 1 to initialize the context with os defaults 1140 * @param userarg parameter passed to the custom malloc, realloc and free functions 1141 * @param malloc custom malloc function 1142 * @param realloc custom realloc function 1143 * @param free custom free function 1144 * @return GETDNS_RETURN_GOOD on success 1145*/ 1146getdns_return_t 1147getdns_context_create_with_extended_memory_functions( 1148 getdns_context **context, 1149 int set_from_os, 1150 void *userarg, 1151 void *(*malloc) (void *userarg, size_t), 1152 void *(*realloc) (void *userarg, void *, size_t), 1153 void (*free) (void *userarg, void *) 1154); 1155 1156/** 1157 * destroy the context. All outstanding requests will be cancelled with 1158 * the getdns_cancel_callback() function. 1159 */ 1160void getdns_context_destroy(getdns_context *context); 1161/** @} 1162 */ 1163 1164 1165/** 1166 * \addtogroup asyncfuncs 1167 * @{ 1168 */ 1169/** 1170 * Cancel an outstanding asynchronous request. The callback registered with 1171 * the request will be called with the getdns_callback_type_t set to 1172 * GETDNS_CALLBACK_CANCEL and the response set to NULL. 1173 */ 1174getdns_return_t 1175getdns_cancel_callback(getdns_context *context, 1176 getdns_transaction_t transaction_id); 1177/** @} 1178 */ 1179 1180 1181/** 1182 * \addtogroup syncfuncs 1183 * @{ 1184 */ 1185/** These functions do not use callbacks, when the application calls one of these 1186 * functions the library retrieves all of the data before returning. Return 1187 * values are exactly the same as if you had used a callback with the 1188 * asynchronous functions. 1189 */ 1190 1191/** 1192 * retrieve general DNS data 1193 * @see rrtypes 1194 * @see getdns_general 1195 * @param context pointer to a previously created context to be used for this call 1196 * @param name the ASCII based domain name to lookup 1197 * @param request_type RR type for the query, e.g. GETDNS_RR_TYPE_NS 1198 * @param extensions dict data structures, NULL to use no extensions 1199 * @param response response 1200 * @return GETDNS_RETURN_GOOD on success 1201 */ 1202getdns_return_t 1203getdns_general_sync(getdns_context *context, 1204 const char *name, 1205 uint16_t request_type, 1206 const getdns_dict *extensions, 1207 getdns_dict **response); 1208 1209/** 1210 * retrieve address assigned to a DNS name 1211 * @see getdns_address 1212 * @param context pointer to a previously created context to be used for this call 1213 * @param name the ASCII based domain name to lookup 1214 * @param extensions dict data structures, NULL to use no extensions 1215 * @param response response 1216 * @return GETDNS_RETURN_GOOD on success 1217 */ 1218getdns_return_t 1219getdns_address_sync(getdns_context *context, 1220 const char *name, 1221 const getdns_dict *extensions, 1222 getdns_dict **response); 1223 1224/** 1225 * retrieve hostname assigned to an IP address 1226 * @see getdns_hostname 1227 * @param context pointer to a previously created context to be used for this call 1228 * @param address the address to look up 1229 * @param extensions dict data structures, NULL to use no extensions 1230 * @param response response 1231 * @return GETDNS_RETURN_GOOD on success 1232 */ 1233getdns_return_t 1234getdns_hostname_sync(getdns_context *context, 1235 const getdns_dict *address, 1236 const getdns_dict *extensions, 1237 getdns_dict **response); 1238 1239/** 1240 * retrieve a service assigned to a DNS name 1241 * @see getdns_service 1242 * @param context pointer to a previously created context to be used for this call 1243 * @param name the ASCII based domain name to lookup 1244 * @param extensions dict data structures, NULL to use no extensions 1245 * @param response response 1246 * @return GETDNS_RETURN_GOOD on success 1247 */ 1248getdns_return_t 1249getdns_service_sync(getdns_context *context, 1250 const char *name, 1251 const getdns_dict *extensions, 1252 getdns_dict **response); 1253 1254/** @} 1255 */ 1256 1257/** 1258 * \addtogroup utils Utility functions 1259 * @{ 1260 */ 1261 1262/** 1263 * Convert a domain name in DNS wire format to presentation format. 1264 * The newly allocated string should be freed with free. 1265 * @param dns_name_wire_fmt A bindata to the DNS name in wire format 1266 * @param fqdn_as_string A reference to a pointer that will be set 1267 * to a newly allocated string containing the 1268 * presentation format of the name. The caller 1269 * is responsible for deallocate this space with free(). 1270 * @return GETDNS_RETURN_GOOD on success or GETDNS_RETURN_GENERIC_ERROR 1271 * when the wireformat name could not be parsed. 1272 */ 1273getdns_return_t 1274getdns_convert_dns_name_to_fqdn( 1275 const getdns_bindata *dns_name_wire_fmt, 1276 char **fqdn_as_string); 1277 1278/** 1279 * Convert a domain name in presentation format to DNS wire format. 1280 * @param fqdn_as_string The name to convert in presentation format. 1281 * @param dns_name_wire_fmt A reference to a pointer that will be set 1282 * to a newly allocated bindata containing the 1283 * DNS wire format of the name. The caller 1284 * is responsible for deallocate this space with free(). 1285 * @return GETDNS_RETURN_GOOD on success or GETDNS_RETURN_GENERIC_ERROR 1286 * when the presentation format name could not be parsed. 1287 */ 1288getdns_return_t 1289getdns_convert_fqdn_to_dns_name( 1290 const char *fqdn_as_string, 1291 getdns_bindata **dns_name_wire_fmt); 1292 1293/** 1294 * Convert an Unicode encoded label to ASCII encoding following the 1295 * rules for IDNA 2008 described in RFC 5890-5892. 1296 * @param ulabel The Unicode encoded label to convert. 1297 * @return The ASCII encoding label. The caller is responsible for deallocate 1298 * this space with free(). 1299 */ 1300char *getdns_convert_ulabel_to_alabel(const char *ulabel); 1301 1302/** 1303 * Convert an ASCII encoded label to Unicode encoding following the 1304 * rules for IDNA 2008 described in RFC 5890-5892. 1305 * @param alabel The ASCII encoded label to convert. 1306 * @return The Unicode encoding label. The caller is responsible for 1307 * deallocation with free(). 1308 */ 1309char *getdns_convert_alabel_to_ulabel(const char *alabel); 1310 1311/** @} 1312 */ 1313 1314/** 1315 * \addtogroup dnssecfuncs 1316 * @{ 1317 */ 1318 1319/** 1320 * Offline DNSSEC validate Resource Records with the help of support 1321 * records and a DNSSEC trust anchor. 1322 * @see dnssecvalues 1323 * @param to_validate This is a list of reply_dicts to validate (as can 1324 * be seen under "replies_tree" in a response dict), or 1325 * an RRset with signatures represented as a list of 1326 * rr_dicts. The format of rr_dict can be seen in 1327 * the sections of reply_dicts in response dicts. 1328 * It is also possible to validate the non-existance 1329 * of a query. Besides all the necessary NSEC(3)s plus 1330 * signature, the to_validate should then also contain 1331 * a question rr_dict with a qname, qclass and qtype. 1332 * @param support_records A list of all the DNSKEY, DS and NSEC(3) RRsets 1333 * (in the form of rr_dicts) that may be used to 1334 * validate the RRsets or replies in to_validate. 1335 * The value returned under "validation_chain" in a 1336 * response dict when the dnssec_return_validation_chain 1337 * extension was used, can be used directly for this. 1338 * @param trust_anchors A list of rr_dicts containing the DNSSEC trust anchors. 1339 * The return value of the getdns_root_trust_anchor() 1340 * can be used directly for this. 1341 * @return The function returns one of GETDNS_DNSSEC_SECURE, 1342 * GETDNS_DNSSEC_BOGUS, GETDNS_DNSSEC_INDETERMINATE, or GETDNS_DNSSEC_INSECURE 1343 * depending on the validation status. 1344 */ 1345getdns_return_t 1346getdns_validate_dnssec(const getdns_list *to_validate, 1347 const getdns_list *support_records, const getdns_list *trust_anchors); 1348 1349/** 1350 * Get the default list of trust anchor records that is used by the library 1351 * to validate DNSSEC. 1352 * @param utc_date_of_anchor Set to the number of seconds since epoch 1353 * the trust anchors were obtained 1354 * @return The list of DNSSEC trust anchors, or NULL on error. The caller is 1355 * responsible for deallocating the list with getdns_list_destroy(). 1356 */ 1357getdns_list *getdns_root_trust_anchor(time_t *utc_date_of_anchor); 1358 1359/** @} 1360 */ 1361 1362/** 1363 * \addtogroup utils 1364 * @{ 1365 */ 1366 1367/** 1368 * Converts a getdns_bindata representing an IPv4 or IPv6 address to a 1369 * textual representation. 1370 * @param bindata_of_ipv4_or_ipv6_address The IP address to convert. 1371 * @return character array (caller must free this) containing the textual 1372 * representation of the address. 1373 */ 1374char *getdns_display_ip_address(const getdns_bindata 1375 *bindata_of_ipv4_or_ipv6_address); 1376 1377/** @} 1378 */ 1379 1380 1381/** 1382 * \addtogroup getdns_context 1383 * @{ 1384 */ 1385 1386/** 1387 * An application can be notified when the context is changed. 1388 * Note that this implementation has an extended version of this function 1389 * in which an additional userarg parameter can be registered: 1390 * #getdns_context_set_update_callback . 1391 * @see contextcodetypestext 1392 * @param context The context for which to monitor changes 1393 * @param value The callback function that will be called when any context is 1394 * changed. A update callback function can be deregistered by 1395 * passing NULL. 1396 * @return GETDNS_RETURN_GOOD when successful. 1397 * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL. 1398 */ 1399getdns_return_t 1400getdns_context_set_context_update_callback( 1401 getdns_context *context, 1402 void (*value)(getdns_context *context, 1403 getdns_context_code_t changed_item) 1404); 1405 1406/** 1407 * Specify whether DNS queries are performed with recursive lookups or as a 1408 * stub resolver. The default value is GETDNS_RESOLUTION_RECURSING. 1409 * @see getdns_context_get_resolution_type 1410 * @see resolutiontypestext 1411 * @param context The context to configure 1412 * @param value GETDNS_RESOLUTION_RECURSING or GETDNS_RESOLUTION_STUB. 1413 * @return GETDNS_RETURN_GOOD when successful 1414 * @return GETDNS_RETURN_CONTEXT_UPDATE_FAIL with unknown resolution types 1415 * @return GETDNS_RETURN_NOT_IMPLEMENTED when getdns was compiled for stub 1416 * resolution only and recursing resolution type was requested. 1417 * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL. 1418 */ 1419getdns_return_t 1420getdns_context_set_resolution_type(getdns_context *context, 1421 getdns_resolution_t value); 1422 1423/** 1424 * Sets the ordered list of namespaces that will be queried. 1425 * This context setting is ignored for the getdns_general and 1426 * getdns_general_sync functions; it is used for the other funtions. 1427 * When a normal lookup is done, the API does the lookups in the order given 1428 * and stops when it gets the first result 1429 * @see getdns_context_get_namespaces 1430 * @see namespacetypestext 1431 * @param context The context to configure 1432 * @param namespace_count The number of values in the namespaces list. 1433 * @param namespaces An ordered list of namespaces that will be queried. 1434 * The values are: GETDNS_NAMESPACE_DNS, 1435 * GETDNS_NAMESPACE_LOCALNAMES, GETDNS_NAMESPACE_NETBIOS, 1436 * GETDNS_NAMESPACE_MDNS, and GETDNS_NAMESPACE_NIS. 1437 * @return GETDNS_RETURN_GOOD when successful 1438 * @return GETDNS_RETURN_CONTEXT_UPDATE_FAIL with unknown namespace types 1439 * @return GETDNS_RETURN_NOT_IMPLEMENTED when unsupported namespaces were 1440 * given. Currently this implementation supports only 1441 * GETDNS_NAMESPACE_DNS, GETDNS_NAMESPACE_LOCALNAMES and has an 1442 * draft implementation of GETDNS_NAMESPACE_MDNS, which has to be 1443 * enabled at configure time. 1444 * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL. 1445 */ 1446getdns_return_t 1447getdns_context_set_namespaces(getdns_context *context, 1448 size_t namespace_count, const getdns_namespace_t *namespaces); 1449 1450/** 1451 * Specifies what transport are used for DNS lookups. The default is 1452 * GETDNS_TRANSPORT_UDP_FIRST_AND_FALL_BACK_TO_TCP. Use of this function 1453 * is discouraged. Please use #getdns_context_set_dns_transport_list() 1454 * instead of this function. 1455 * @see getdns_context_get_dns_transport 1456 * @see transporttypestext 1457 * @see getdns_context_set_dns_transport_list 1458 * @param context The context to configure 1459 * @param value The transport to use for DNS lookups. 1460 * The value is GETDNS_TRANSPORT_UDP_FIRST_AND_FALL_BACK_TO_TCP, 1461 * GETDNS_TRANSPORT_UDP_ONLY, GETDNS_TRANSPORT_TCP_ONLY, 1462 * GETDNS_TRANSPORT_TCP_ONLY_KEEP_CONNECTIONS_OPEN, 1463 * GETDNS_TRANSPORT_TLS_ONLY_KEEP_CONNECTIONS_OPEN or 1464 * GETDNS_TRANSPORT_TLS_FIRST_AND_FALL_BACK_TO_TCP_KEEP_CONNECTIONS_OPEN. 1465 * @return GETDNS_RETURN_GOOD when successful 1466 * @return GETDNS_RETURN_CONTEXT_UPDATE_FAIL with unknown values 1467 * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL. 1468 */ 1469getdns_return_t 1470getdns_context_set_dns_transport(getdns_context *context, 1471 getdns_transport_t value); 1472 1473/** 1474 * Specifies what transport is used for DNS lookups. The default is a list 1475 * containing GETDNS_TRANSPORT_UDP then GETDNS_TRANSPORT_TCP. The API will 1476 * return information on the actual transport used to fulfill the request in 1477 * the response dict, when the return_call_reporting extension is used. 1478 * @see getdns_context_get_dns_transport_list 1479 * @see transportlisttypestext 1480 * @see getdns_context_set_dns_transport 1481 * @param context The context to configure 1482 * @param transport_count The number of values in the transports list. 1483 * @param transports An ordered list of transports that will be used for DNS 1484 * lookups. If only one transport value is specified it will 1485 * be the only transport used. Should it not be available 1486 * basic resolution will fail. Fallback transport options are 1487 * specified by including multiple values in the list. 1488 * The values are: GETDNS_TRANSPORT_UDP, GETDNS_TRANSPORT_TCP, 1489 * or GETDNS_TRANSPORT_TLS 1490 * @return GETDNS_RETURN_GOOD when successful 1491 * @return GETDNS_RETURN_CONTEXT_UPDATE_FAIL with unknown values 1492 * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL. 1493 */ 1494getdns_return_t 1495getdns_context_set_dns_transport_list(getdns_context *context, 1496 size_t transport_count, getdns_transport_list_t *transports); 1497 1498/** 1499 * Specify number of milliseconds the API will leave an idle TCP or TLS 1500 * connection open for (idle means no outstanding responses and no pending 1501 * queries). When set to 0, all currently open idle connections will be 1502 * closed immediately. The default is 0. 1503 * Note with synchronous queries, idle connections can not reliably be timed. 1504 * Each new synchronous request, will reset the counter no matter the time 1505 * in between requests, and thus leave the connection open always. This 1506 * setting is thus only meaningful when doing requests asynchronously. 1507 * @see getdns_context_get_idle_timeout 1508 * @param context The context to configure 1509 * @param timeout The number of milliseconds the API will leave an idle TCP 1510 * or TLS connection open for 1511 * @return GETDNS_RETURN_GOOD when successful. 1512 * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL. 1513 */ 1514getdns_return_t 1515getdns_context_set_idle_timeout(getdns_context *context, uint64_t timeout); 1516 1517/** 1518 * Limit the number of outstanding DNS queries. When more than limit requests 1519 * are scheduled, they are kept on an internal queue, to be rescheduled when 1520 * the number of outstanding queries drops below the limit again. 1521 * A value of 0 indicates that the number of outstanding DNS queries is 1522 * unlimited, however, queries will be put on the internal queue too when 1523 * system resources are exhausted (i.e. number of available sockets). 1524 * The default value is 0. 1525 * @see getdns_context_get_limit_outstanding_queries 1526 * @param context The context to configure 1527 * @param limit The maximum number of outstanding DNS queries. 1528 * @return GETDNS_RETURN_GOOD when successful. 1529 * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL. 1530 */ 1531getdns_return_t 1532getdns_context_set_limit_outstanding_queries(getdns_context *context, 1533 uint16_t limit); 1534 1535/** 1536 * Specifies number of milliseconds the API will wait for request to return. 1537 * The default is 5000 (i.e. 5 seconds). 1538 * @see getdns_context_get_timeout 1539 * @param context The context to configure 1540 * @param timeout The number of milliseconds the API will wait for request to 1541 * return. 1542 * @return GETDNS_RETURN_GOOD when successful. 1543 * @return GETDNS_RETURN_INVALID_PARAMETER for a timeout 0, 1544 * or when context was NULL 1545 */ 1546getdns_return_t 1547getdns_context_set_timeout(getdns_context *context, uint64_t timeout); 1548 1549/** 1550 * Specifies whether or not DNS queries follow redirects. 1551 * The default value is GETDNS_REDIRECTS_FOLLOW. 1552 * In this implementation, redirects are only actively followed in the recursing 1553 * resolution mode. The GETDNS_REDIRECTS_DO_NOT_FOLLOW will not prevent this, 1554 * but the response will be stripped of all resource records that could only be 1555 * found through following redirects. The setting will do this with answers 1556 * provided by an upstream in stub resolution mode too. 1557 * @see getdns_context_get_follow_redirects 1558 * @see redirectpoliciestext 1559 * @param context The context to configure 1560 * @param value GETDNS_REDIRECTS_FOLLOW for normal following of redirects 1561 * through CNAME and DNAME; or GETDNS_REDIRECTS_DO_NOT_FOLLOW to 1562 * cause any lookups that would have gone through CNAME and DNAME 1563 * to return the CNAME or DNAME, not the eventual target. 1564 * @return GETDNS_RETURN_GOOD when successful. 1565 * @return GETDNS_RETURN_INVALID_PARAMETER for an unknown value, 1566 * or when context was NULL 1567 */ 1568getdns_return_t 1569getdns_context_set_follow_redirects(getdns_context *context, 1570 getdns_redirects_t value); 1571 1572/** 1573 * Configure the list of addresses to be used for looking up top-level domains. 1574 * The default is the list of "normal" IANA root servers 1575 * @see getdns_context_get_dns_root_servers 1576 * @param context The context to configure 1577 * @param addresses The list contains dicts that are addresses to be used for 1578 * looking up top-level domains. Each dict in the list 1579 * contains at least two names: address_type (whose value is 1580 * a bindata; it is currently either "IPv4" or "IPv6") and 1581 * address_data (whose value is a bindata). 1582 * This implementation also accepts a list of addressxi 1583 * bindatas. Or a list of rr_dicts for address records (i.e. 1584 * the additional section of a NS query for ".", or a with 1585 * getdns_fp2rr_list() converted root.hints file). 1586 * @return GETDNS_RETURN_GOOD when successful. 1587 * @return GETDNS_RETURN_ CONTEXT_UPDATE_FAIL when there were problems 1588 * parsing the provided addresses list. 1589 * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL 1590 */ 1591getdns_return_t 1592getdns_context_set_dns_root_servers(getdns_context *context, 1593 getdns_list *addresses); 1594 1595/** 1596 * Specifies whether, how and when to append a suffix to the query string. 1597 * The non-standard implementation default is 1598 * GETDNS_APPEND_NAME_TO_SINGLE_LABEL_FIRST. 1599 * @see getdns_context_get_append_name 1600 * @see suffixappendtypestext 1601 * @param context The context to configure 1602 * @param value GETDNS_APPEND_NAME_TO_SINGLE_LABEL_FIRST, 1603 * GETDNS_APPEND_NAME_ALWAYS, 1604 * GETDNS_APPEND_NAME_ONLY_TO_SINGLE_LABEL_AFTER_FAILURE, 1605 * GETDNS_APPEND_NAME_ONLY_TO_MULTIPLE_LABEL_NAME_AFTER_FAILURE, 1606 * or GETDNS_APPEND_NAME_NEVER. 1607 * @return GETDNS_RETURN_GOOD when successful. 1608 * @return GETDNS_RETURN_ CONTEXT_UPDATE_FAIL with unknown values. 1609 * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL 1610 */ 1611getdns_return_t 1612getdns_context_set_append_name(getdns_context *context, 1613 getdns_append_name_t value); 1614 1615/** 1616 * Specify the list of suffixes to be appended based on the value off the 1617 * append_name setting. The default is read from OS, or an empty list when 1618 * the context is not initialized with OS defaults. 1619 * @see getdns_context_get_suffix 1620 * @param context The context to configure 1621 * @param value A list of bindatas that are strings that are to be appended 1622 * based on the value off the append_name setting. 1623 * @return GETDNS_RETURN_GOOD when successful. 1624 * @return GETDNS_RETURN_ CONTEXT_UPDATE_FAIL with unknown values. 1625 * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL 1626 */ 1627getdns_return_t 1628getdns_context_set_suffix(getdns_context *context, getdns_list *value); 1629 1630/** 1631 * Specify the DNSSEC trust anchors. The default is to read it from 1632 * @TRUST_ANCHOR_FILE@. 1633 * @see getdns_context_get_dnssec_trust_anchors 1634 * @param context The context to configure 1635 * @param value A list of rr_dicts for DS or DNSKEY that are the DNSSEC 1636 * trust anchors. 1637 * @return GETDNS_RETURN_GOOD when successful. 1638 * @return GETDNS_RETURN_ CONTEXT_UPDATE_FAIL with unknown values. 1639 * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL 1640 */ 1641getdns_return_t 1642getdns_context_set_dnssec_trust_anchors(getdns_context *context, 1643 getdns_list *value); 1644 1645/** 1646 * Specify the DNSSEC allowed skew. The default is 0. 1647 * @see getdns_context_get_dnssec_allowed_skew 1648 * @param context The context to configure 1649 * @param value The number of seconds of skew that is allowed in either 1650 * direction when checking an RRSIG's Expiration and Inception 1651 * fields. 1652 * @return GETDNS_RETURN_GOOD when successful. 1653 * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL 1654 */ 1655getdns_return_t 1656getdns_context_set_dnssec_allowed_skew(getdns_context *context, 1657 uint32_t value); 1658 1659 1660/** 1661 * Specify where a stub resolver will send queries. The default value is set 1662 * from the OS when the context is created with the set_from_os flag, or 1663 * empty otherwise. 1664 * @see getdns_context_get_upstream_recursive_servers 1665 * @param context The context to configure 1666 * @param upstream_list The upstreams are specified either by a getdns_bindata 1667 * containing a IPv4 or IPv6 address in network format 1668 * or a `getdns_dict`, containing at least a name 1669 * `address_data` whose value is the address bindata, and 1670 * optionally also: 1671 * - `scode_id` containing an getdns_bindata with the 1672 * scope ID for IPv6 link-local addresses. 1673 * - `port` an integer specifying which port to use to 1674 * contact this upstream over UDP and TCP; 1675 * the default is 53 1676 * - `tsig_algorithm` (a bindata) that is the name of the 1677 * TSIG hash algorithm 1678 * - `tsig_name` (a bindata) that is the name of the TSIG key 1679 * - `tsig_secret` (a bindata) that is the TSIG key 1680 * - `tls_port` (a integer) that is the port to use to 1681 * contact this upstream over TLS 1682 * - `tls_auth_name` (a bindata) that is the name of the 1683 * upstream (as a bindata containing a string) which 1684 * must be verified to confirm its identity. 1685 * - `tls_pubkey_pinset` (a list) containing dicts with 1686 * - `digest` which must be a bindata containing the 1687 * text sha256 1688 * - `value` A SHA256 hash of the `SubjectPublicKeyInfo` 1689 * of the upstream, which will be used to authenticate 1690 * it. 1691 * - `tls_cipher_list` (a bindata) that is the string 1692 * of available ciphers specific for this upstream. 1693 * @return GETDNS_RETURN_GOOD when successful. 1694 * @return GETDNS_RETURN_INVALID_PARAMETER when `context` or `upstream_list` was `NULL` 1695 * @return GETDNS_RETURN_CONTEXT_UPDATE_FAIL when there were problems parsing 1696 * the `upstream_list`. 1697 */ 1698getdns_return_t 1699getdns_context_set_upstream_recursive_servers(getdns_context *context, 1700 getdns_list *upstream_list); 1701 1702/** 1703 * Set the maximum UDP payload size advertised in a EDNS0 OPT record. 1704 * When not set (the default), outgoing values will adhere to the suggestions 1705 * in RFC 6891 and may follow a scheme that uses multiple values to maximize 1706 * receptivity. 1707 * @see getdns_context_get_edns_maximum_udp_payload_size 1708 * @see getdns_context_unset_edns_maximum_udp_payload_size 1709 * @param context The context to configure 1710 * @param value The maximum UDP payload size advertised in a EDNS0 OPT record. 1711 * The value must be between 512 and 65536 1712 * @return GETDNS_RETURN_GOOD when successful. 1713 * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL 1714 */ 1715getdns_return_t 1716getdns_context_set_edns_maximum_udp_payload_size(getdns_context *context, 1717 uint16_t value); 1718 1719/** 1720 * Set the rcode advertised in a EDNS0 OPT record. The default is 0. 1721 * @see getdns_context_get_edns_extended_rcode 1722 * @param context The context to configure 1723 * @param value A value between 0 and 255. 1724 * @return GETDNS_RETURN_GOOD when successful. 1725 * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL 1726 */ 1727getdns_return_t 1728getdns_context_set_edns_extended_rcode(getdns_context *context, 1729 uint8_t value); 1730 1731/** 1732 * Set the version advertised in a EDNS0 OPT record. The default is 0. 1733 * @see getdns_context_get_edns_version 1734 * @param context The context to configure 1735 * @param value A value between 0 and 255. 1736 * @return GETDNS_RETURN_GOOD when successful. 1737 * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL 1738 */ 1739getdns_return_t 1740getdns_context_set_edns_version(getdns_context *context, uint8_t value); 1741 1742/** 1743 * Set the DO ibit advertised in a EDNS0 OPT record. The default is 0. 1744 * However use of any of the dnssec_* extension will override this setting 1745 * and set the DO bit. 1746 * @see getdns_context_get_edns_do_bit 1747 * @param context The context to configure 1748 * @param value A value between 0 and 1. 1749 * @return GETDNS_RETURN_GOOD when successful. 1750 * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL 1751 */ 1752getdns_return_t 1753getdns_context_set_edns_do_bit(getdns_context *context, uint8_t value); 1754 1755/** 1756 * Specify custom memory management functions to be used with this context. 1757 * The given memory management functions will be used for creating the response 1758 * dicts. The response dicts inherit the custom memory management functions 1759 * from the context and will deallocate themselves (and their members) with the 1760 * custom deallocator. By default, the system `malloc`, `realloc`, and `free` are used. 1761 * @param context The context to configure 1762 * @param malloc A custom memory allocator. The default is `malloc`. 1763 * @param realloc A custom memory reallocator. The default is `realloc`. 1764 * @param free A custom memory deallocator. The default is `free`. 1765 * @return GETDNS_RETURN_GOOD when successful. 1766 * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL 1767 */ 1768getdns_return_t 1769getdns_context_set_memory_functions(getdns_context *context, 1770 void *(*malloc) (size_t), 1771 void *(*realloc) (void *, size_t), 1772 void (*free) (void *) 1773 ); 1774 1775/** 1776 * Specify custom extended memory management functions to be used with this 1777 * context. The value of `userarg` argument will be passed to the custom 1778 * `malloc`, `realloc`, and `free`. 1779 * The response dicts inherit the custom memory management functions 1780 * from the context and will deallocate themselves (and their members) with the 1781 * custom deallocator. By default, the system `malloc`, `realloc`, and `free` are used. 1782 * @param context The context to configure 1783 * @param userarg This value will be passed as the `userarg` argument to the 1784 * custom `malloc`, `realloc` and `free` function. 1785 * @param malloc A custom memory allocator. The default is a wrapper for `malloc`. 1786 * @param realloc A custom memory reallocator. The default is a wrapper for `realloc`. 1787 * @param free A custom memory deallocator. The default is a wrapper for `free`. 1788 * @return GETDNS_RETURN_GOOD when successful. 1789 * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL 1790 */ 1791getdns_return_t 1792getdns_context_set_extended_memory_functions(getdns_context *context, 1793 void *userarg, 1794 void *(*malloc) (void *userarg, size_t sz), 1795 void *(*realloc) (void *userarg, void *ptr, size_t sz), 1796 void (*free) (void *userarg, void *ptr) 1797 ); 1798/** @} 1799 */ 1800 1801/** 1802 * Retrieve information about the API itself and inspect the current context. 1803 * The returned dictionary can be used with getdns_context_config() directly 1804 * to configure another context with precisely these settings. 1805 * @param context The context from which to get the information 1806 * @return A getdns_dict containing the following name/value pairs: 1807 * - `version_string` (a bindata) represents the version string for this version of the DNS API. 1808 * - `implementation_string` (a bindata) is a string showing which 1809 * implementation of the getdns API this is. In our implementation 1810 * this will always be set to "https://getdnsapi.net" 1811 * - resolution_type (an int) is the type of resolver that the API is 1812 * acting as in this context: GETDNS_RESOLUTION_RECURSING or 1813 * GETDNS_RESOLUTION_STUB. 1814 * - all_context (a dict) with names for all the other settings in 1815 * context. 1816 * The application is responsible for cleaning up the returned dictionary 1817 * object with getdns_dict_destroy. 1818 */ 1819getdns_dict* 1820getdns_context_get_api_information(const getdns_context *context); 1821 1822/** @} 1823 */ 1824 1825#ifdef __cplusplus 1826} 1827#endif 1828#endif /* GETDNS_H */ 1829