/usr/include/getdns/getdns_extra.h is in libgetdns-dev 1.4.0-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441 1442 1443 1444 1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457 1458 1459 1460 1461 1462 1463 1464 1465 1466 1467 1468 1469 1470 1471 1472 1473 1474 1475 1476 1477 1478 1479 1480 1481 1482 1483 1484 1485 1486 1487 1488 1489 1490 1491 1492 1493 1494 1495 1496 1497 1498 1499 1500 1501 1502 1503 1504 1505 1506 1507 1508 1509 1510 1511 1512 1513 1514 1515 1516 1517 1518 1519 1520 1521 1522 1523 1524 1525 1526 1527 1528 1529 1530 1531 1532 1533 1534 1535 1536 1537 1538 1539 1540 1541 1542 1543 1544 1545 1546 1547 1548 1549 1550 1551 1552 1553 1554 1555 1556 1557 1558 1559 1560 1561 1562 1563 1564 1565 1566 1567 1568 1569 1570 1571 1572 1573 1574 1575 1576 1577 1578 1579 1580 1581 1582 1583 1584 1585 1586 1587 1588 1589 1590 1591 1592 1593 1594 1595 1596 1597 1598 1599 1600 1601 1602 1603 1604 1605 1606 1607 1608 1609 1610 1611 1612 1613 1614 1615 1616 1617 1618 1619 1620 1621 1622 1623 1624 1625 1626 1627 1628 1629 1630 1631 1632 1633 1634 1635 1636 1637 1638 1639 1640 1641 1642 1643 1644 1645 1646 1647 1648 1649 1650 1651 1652 1653 1654 1655 1656 1657 1658 1659 1660 1661 1662 1663 1664 1665 1666 1667 1668 1669 1670 1671 1672 1673 1674 1675 1676 1677 1678 1679 1680 1681 1682 1683 1684 1685 1686 1687 1688 1689 1690 1691 1692 1693 1694 1695 1696 1697 1698 1699 1700 1701 1702 1703 1704 1705 1706 1707 1708 1709 1710 1711 1712 1713 1714 1715 1716 1717 1718 1719 1720 1721 1722 1723 1724 1725 1726 1727 1728 1729 1730 1731 1732 1733 1734 1735 1736 1737 1738 1739 1740 1741 1742 1743 1744 1745 1746 1747 1748 1749 1750 1751 1752 1753 1754 1755 1756 1757 1758 1759 1760 1761 1762 1763 1764 1765 1766 1767 1768 1769 1770 1771 1772 1773 1774 1775 1776 1777 1778 1779 1780 1781 1782 1783 1784 1785 1786 1787 1788 1789 1790 1791 1792 1793 1794 1795 1796 1797 1798 1799 1800 1801 1802 1803 1804 1805 1806 1807 1808 1809 1810 1811 1812 1813 1814 1815 1816 1817 1818 1819 1820 1821 1822 1823 1824 1825 1826 1827 1828 1829 1830 1831 1832 1833 1834 1835 1836 1837 1838 1839 1840 1841 1842 1843 1844 1845 1846 1847 1848 1849 1850 1851 1852 1853 1854 1855 1856 1857 1858 1859 1860 1861 1862 1863 1864 1865 1866 1867 1868 1869 1870 1871 1872 1873 1874 1875 1876 1877 1878 1879 1880 1881 1882 1883 1884 1885 1886 1887 1888 1889 1890 1891 1892 1893 1894 1895 1896 1897 1898 1899 1900 1901 1902 1903 1904 1905 1906 1907 1908 1909 1910 1911 1912 1913 1914 1915 1916 1917 1918 1919 1920 1921 1922 1923 1924 1925 1926 1927 1928 1929 1930 1931 1932 1933 1934 1935 1936 1937 1938 1939 1940 1941 1942 1943 1944 1945 1946 1947 1948 1949 1950 1951 1952 1953 1954 1955 1956 1957 1958 1959 1960 1961 1962 1963 1964 1965 1966 1967 1968 1969 1970 1971 1972 1973 1974 1975 1976 1977 1978 1979 1980 1981 1982 1983 1984 1985 1986 1987 1988 1989 1990 1991 1992 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009 2010 2011 2012 2013 2014 2015 2016 2017 2018 2019 2020 2021 2022 2023 2024 2025 2026 2027 2028 2029 2030 2031 2032 2033 2034 2035 2036 2037 2038 2039 2040 2041 2042 2043 2044 2045 2046 2047 2048 2049 2050 2051 2052 2053 2054 2055 2056 2057 2058 2059 2060 2061 2062 2063 2064 2065 2066 2067 2068 2069 2070 2071 2072 2073 2074 2075 2076 2077 2078 2079 2080 2081 2082 2083 2084 2085 2086 2087 2088 2089 2090 2091 2092 2093 2094 2095 2096 2097 2098 2099 2100 2101 2102 2103 2104 2105 2106 2107 2108 2109 2110 2111 2112 2113 2114 2115 2116 2117 2118 2119 2120 2121 2122 2123 2124 2125 2126 2127 2128 2129 2130 2131 2132 2133 2134 2135 2136 2137 2138 2139 2140 2141 2142 2143 2144 2145 2146 2147 2148 2149 2150 2151 2152 2153 2154 2155 2156 2157 2158 2159 2160 2161 2162 2163 2164 2165 2166 2167 2168 2169 2170 2171 2172 2173 2174 2175 2176 2177 2178 2179 2180 2181 2182 2183 2184 2185 2186 2187 2188 2189 2190 2191 2192 2193 2194 2195 2196 2197 2198 2199 2200 2201 2202 2203 2204 2205 2206 2207 2208 2209 2210 2211 2212 2213 2214 2215 2216 2217 2218 2219 2220 2221 2222 2223 2224 2225 2226 2227 2228 2229 | /**
* \file
* \brief Public interface to getdns that is ADDITIONAL to the official getdns API, include
* in your application to use additional functionality offered by
* this implementation.
*/
/*
* Copyright (c) 2013, NLNet Labs, Verisign, Inc.
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions are met:
* * Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
* * Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
* * Neither the names of the copyright holders nor the
* names of its contributors may be used to endorse or promote products
* derived from this software without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
* ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
* WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL Verisign, Inc. BE LIABLE FOR ANY
* DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
* (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
* LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
* SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
#ifndef _GETDNS_EXTRA_H_
#define _GETDNS_EXTRA_H_
#include <getdns/getdns.h>
#include <sys/time.h>
#include <stdio.h>
#include <time.h>
#include <stdarg.h>
#ifdef __cplusplus
extern "C" {
#endif
/** \addtogroup valuesandtexts Values and texts
* @{
*/
/**
* \addtogroup returntypestext Return values and texts
* @{
*/
#define GETDNS_RETURN_IO_ERROR ((getdns_return_t) 397 )
#define GETDNS_RETURN_IO_ERROR_TEXT "An input/output error occurred. Inspect errno for details."
#define GETDNS_RETURN_NO_UPSTREAM_AVAILABLE ((getdns_return_t) 398 )
#define GETDNS_RETURN_NO_UPSTREAM_AVAILABLE_TEXT "None of the configured upstreams could be used to send queries on the specified transports"
#define GETDNS_RETURN_NEED_MORE_SPACE ((getdns_return_t) 399 )
#define GETDNS_RETURN_NEED_MORE_SPACE_TEXT "The buffer was too small"
/** @}
*/
/**
* \addtogroup contextcodetypestext Context code values and texts
* @{
*/
#define GETDNS_CONTEXT_CODE_TLS_AUTHENTICATION 618
#define GETDNS_CONTEXT_CODE_TLS_AUTHENTICATION_TEXT "Change related to getdns_context_set_tls_authentication"
#define GETDNS_CONTEXT_CODE_EDNS_CLIENT_SUBNET_PRIVATE 619
#define GETDNS_CONTEXT_CODE_EDNS_CLIENT_SUBNET_PRIVATE_TEXT "Change related to getdns_context_set_edns_client_subnet_private"
#define GETDNS_CONTEXT_CODE_TLS_QUERY_PADDING_BLOCKSIZE 620
#define GETDNS_CONTEXT_CODE_TLS_QUERY_PADDING_BLOCKSIZE_TEXT "Change related to getdns_context_set_tls_query_padding_blocksize"
#define GETDNS_CONTEXT_CODE_PUBKEY_PINSET 621
#define GETDNS_CONTEXT_CODE_PUBKEY_PINSET_TEXT "Change related to getdns_context_set_pubkey_pinset"
#define GETDNS_CONTEXT_CODE_ROUND_ROBIN_UPSTREAMS 622
#define GETDNS_CONTEXT_CODE_ROUND_ROBIN_UPSTREAMS_TEXT "Change related to getdns_context_set_round_robin_upstreams"
#define GETDNS_CONTEXT_CODE_TLS_BACKOFF_TIME 623
#define GETDNS_CONTEXT_CODE_TLS_BACKOFF_TIME_TEXT "Change related to getdns_context_set_tls_backoff_time"
#define GETDNS_CONTEXT_CODE_TLS_CONNECTION_RETRIES 624
#define GETDNS_CONTEXT_CODE_TLS_CONNECTION_RETRIES_TEXT "Change related to getdns_context_set_tls_connection_retries"
#define GETDNS_CONTEXT_CODE_TRUST_ANCHORS_URL 625
#define GETDNS_CONTEXT_CODE_TRUST_ANCHORS_URL_TEXT "Change related to getdns_context_set_trust_anchors_url"
#define GETDNS_CONTEXT_CODE_TRUST_ANCHORS_VERIFY_CA 626
#define GETDNS_CONTEXT_CODE_TRUST_ANCHORS_VERIFY_CA_TEXT "Change related to getdns_context_set_trust_anchors_verify_ca"
#define GETDNS_CONTEXT_CODE_TRUST_ANCHORS_VERIFY_EMAIL 627
#define GETDNS_CONTEXT_CODE_TRUST_ANCHORS_VERIFY_EMAIL_TEXT "Change related to getdns_context_set_trust_anchors_verify_email"
#define GETDNS_CONTEXT_CODE_APPDATA_DIR 628
#define GETDNS_CONTEXT_CODE_APPDATA_DIR_TEXT "Change related to getdns_context_set_appdata_dir"
#define GETDNS_CONTEXT_CODE_RESOLVCONF 629
#define GETDNS_CONTEXT_CODE_RESOLVCONF_TEXT "Change related to getdns_context_set_resolvconf"
#define GETDNS_CONTEXT_CODE_HOSTS 630
#define GETDNS_CONTEXT_CODE_HOSTS_TEXT "Change related to getdns_context_set_hosts"
#define GETDNS_CONTEXT_CODE_TLS_CA_PATH 631
#define GETDNS_CONTEXT_CODE_TLS_CA_PATH_TEXT "Change related to getdns_context_set_tls_ca_path"
#define GETDNS_CONTEXT_CODE_TLS_CA_FILE 632
#define GETDNS_CONTEXT_CODE_TLS_CA_FILE_TEXT "Change related to getdns_context_set_tls_ca_file"
#define GETDNS_CONTEXT_CODE_TLS_CIPHER_LIST 633
#define GETDNS_CONTEXT_CODE_TLS_CIPHER_LIST_TEXT "Change related to getdns_context_set_tls_cipher_list"
#define GETDNS_CONTEXT_CODE_TLS_CURVES_LIST 634
#define GETDNS_CONTEXT_CODE_TLS_CURVES_LIST_TEXT "Change related to getdns_context_set_tls_curves_list"
/** @}
*/
/**
* \defgroup versions Version values
* @{
*/
#define GETDNS_VERSION "1.4.0"
#define GETDNS_NUMERIC_VERSION 0x01040000
#define GETDNS_API_VERSION "December 2015"
#define GETDNS_API_NUMERIC_VERSION 0x07df0c00
/** @}
*/
/* an alias for REQUIRED */
#define GETDNS_AUTHENTICATION_HOSTNAME GETDNS_AUTHENTICATION_REQUIRED
/**
* \defgroup authvaulesandtext Authentication values and texts
* @{
*/
/* Authentication options used when doing TLS */
typedef enum getdns_tls_authentication_t {
GETDNS_AUTHENTICATION_NONE = 1300,
GETDNS_AUTHENTICATION_REQUIRED = 1301
} getdns_tls_authentication_t;
#define GETDNS_AUTHENTICATION_NONE_TEXT "See getdns_context_set_tls_authentication()"
#define GETDNS_AUTHENTICATION_REQUIRED_TEXT "See getdns_context_set_tls_authentication()"
/** @}
*/
/**
* \addtogroup suffixappendtypestext Suffix appending values and texts
* @{
*/
#define GETDNS_APPEND_NAME_TO_SINGLE_LABEL_FIRST ((getdns_append_name_t) 554 )
#define GETDNS_APPEND_NAME_TO_SINGLE_LABEL_FIRST_TEXT "See getdns_context_set_append_name()"
/** @}
*/
/**
* \addtogroup transporttypestext Transport arrangements and texts
* @{
*/
/**
* WARNING! Do not use the constants below. They will be removed from future
* releases. Please use the getdns_context_set_dns_transport_list with the
* GETDNS_TRANSPORT_UDP, GETDNS_TRANSPORT_TCP and GETDNS_TRANSPORT_TLS
* constants instead.
*/
#define GETDNS_TRANSPORT_TLS_ONLY_KEEP_CONNECTIONS_OPEN 544
#define GETDNS_TRANSPORT_TLS_ONLY_KEEP_CONNECTIONS_OPEN_TEXT "See getdns_context_set_dns_transport()"
#define GETDNS_TRANSPORT_TLS_FIRST_AND_FALL_BACK_TO_TCP_KEEP_CONNECTIONS_OPEN 545
#define GETDNS_TRANSPORT_TLS_FIRST_AND_FALL_BACK_TO_TCP_KEEP_CONNECTIONS_OPEN_TEXT "See getdns_context_set_dns_transport()"
/** @}
*/
/** @}
*/
/**
* \addtogroup functions Functions
* @{
*/
/**
* \addtogroup eventloops Event loop extension functions
* @{
*/
/**
* The type of callback function that is used by the callbacks in an
* getdns_eventloop_event.
* @param userarg This will have the value of the userarg attribute of the
* getdns_eventloop_event struct in which this callback was
* present.
*/
typedef void (*getdns_eventloop_callback)(void *userarg);
typedef struct getdns_eventloop_event getdns_eventloop_event;
/**
* getdns uses an event loop abstraction layer to interface with event loop
* extensions. The extension accepts registration of getdns_eventloop_events
* and translates them to the underlying event loop API for which it is an
* extension. Also applications using getdns can use the abstraction layer
* themselves and in doing so inherit the flexibility being immediately
* compatible with all the event loop systems for which there is an extension
* already (i.e. libevent, libev and libuv).
*/
struct getdns_eventloop_event {
/**
* The userarg argument that will be passed to the
* getdns_eventloop_callbacks when they are fired.
*/
void *userarg;
/**
* When not NULL, it will be fired when the associated file descriptor
* is readable.
*/
getdns_eventloop_callback read_cb;
/**
* When not NULL, it will be fired when the associated file descriptor
* is writable.
*/
getdns_eventloop_callback write_cb;
/**
* When not NULL, it will be fired when the during scheduling specified
* timeout time has passed.
*/
getdns_eventloop_callback timeout_cb;
/**
* Pointer to the underlying event
* that an eventloop extension must manage (i.e. create and free.)
*/
void *ev;
};
typedef struct getdns_eventloop_vmt getdns_eventloop_vmt;
/**
* The manifestation of the event loop abstraction layer. Event loop
* extension implementers should extend this with attributed needed for the
* underlying event loop.
* The current event loop extension can be obtained with the
* getdns_context_get_eventloop() function.
*/
typedef struct getdns_eventloop {
/**
* The Virtual Method Table providing the interface for this specific
* event loop extension.
*/
getdns_eventloop_vmt *vmt;
} getdns_eventloop;
/**
* The function prototype for the `cleanup` and `run` functions in an getdns
* event loop's Virtual Method Table. These methods have no (extra) arguments
* and return nothing.
* @param loop The event loop to `run` or `cleanup`
*/
typedef void (*getdns_eventloop_noargs)(getdns_eventloop *loop);
/**
* The function prototype for the `schedule` function in an event loop
* Virtual Method Table.
* The getdns_eventloop_event must be provided by the caller with the callbacks
* and userarg therein already supplied (by the caller). This function will set
* the ev pointer (in the getdns_eventloop_event) to refer to the underlying
* (extension) event.
* @param loop The event loop for which to register the event.
* @param fd The file descriptor for which to schedule the read_cb and/or
* write_cb callbacks.
* @param timeout The number of milliseconds that must pass without read
* and/or write event after which the timeout_cb callback is fired.
* @param ev The event with all attributes provisioned, except for the ev->ev
* attribute, which will be provisioned by the implementation of
* the schedule method.
* @return GETDNS_RETURN_GOOD when successful and an error code otherwise.
*/
typedef getdns_return_t (*getdns_eventloop_schedule)(getdns_eventloop *loop,
int fd, uint64_t timeout, getdns_eventloop_event *ev);
/**
* The function prototype for the `clean` function in an event loop
* Virtual Method Table.
* The implementation must clear the event (which is referred to with
* ev->ev) in the underlying event loop and make ev->ev NULL when done.
* getdns will test for this value to determine if events are scheduled or not.
* @param loop The event loop for which to event needs to be cleared.
* @param[in,out] ev The event with the ev->ev attribute referring to the
* underlying event. ev->ev must be set to NULL after the event
* was cleared.
* @return GETDNS_RETURN_GOOD when successful and an error code otherwise.
*/
typedef getdns_return_t (*getdns_eventloop_clear)
(getdns_eventloop *loop, getdns_eventloop_event *ev);
/**
* The function prototype for the `run_once` function in an event loop
* Virtual Method Table. The implementation must do a single round of
* firing callbacks, either blocking or not.
* @param loop The event loop to run
* @param blocking When 0, only callbacks for file descriptors that are
* immediately readable or writable or timeouts that have
* passed will be fired. When 1, the eventloop will wait
* until the first callback can be fired, either because a
* associated file descriptor has become readable or writeable,
* or because a timeout time passed.
*/
typedef void (*getdns_eventloop_run_once)(getdns_eventloop *loop,int blocking);
/**
* The Virtual Method Table providing the interface for this specific
* event loop extension.
*/
struct getdns_eventloop_vmt {
/**
* Destroy the getdns_eventloop and the associated underlying event
* loop for which it is an extension.
*/
getdns_eventloop_noargs cleanup;
/**
* Schedule a getdns_eventloop_event with a getdns_eventloop.
*/
getdns_eventloop_schedule schedule;
/**
* Clear a getdns_eventloop_event
*/
getdns_eventloop_clear clear;
/**
* Run the getdns_eventloop until it has no getdns_eventloop_events
* scheduled.
*/
getdns_eventloop_noargs run;
/**
* Do a single iteration of firing callbacks for scheduled events
* and then return.
*/
getdns_eventloop_run_once run_once;
};
/**
* Configure a context to use the specified event loop abstraction extension.
* This function must be called with an provisioned eventloop by the
* event loop extension registration functions.
* @see getdns_context_get_eventloop
* @param context The context to configure
* @param eventloop The event loop abstraction extension with a completely
* provisioned Virtual Method Table and other associated
* data which is opaque to the user.
* @return GETDNS_RETURN_GOOD when successful
* @return GETDNS_RETURN_INVALID_PARAMETER when context or eventloop were NULL.
*/
getdns_return_t
getdns_context_set_eventloop(getdns_context* context,
getdns_eventloop *eventloop);
/**
* Get the current event loop abstraction extension from the context
* Applications using getdns can use the event loop abstraction extension
* themselves directly to inherit the flexibility being immediately
* compatible with all the event loop systems for which there is an extension
* (i.e. libevent, libev and libuv).
* @see getdns_context_set_eventloop
* @param[in] context The context to get the eventloop from
* @param[out] eventloop The currently active event loop abstraction extension
* @return GETDNS_RETURN_GOOD when successful
* @return GETDNS_RETURN_INVALID_PARAMETER when context or evenloop were NULL
*/
getdns_return_t
getdns_context_get_eventloop(getdns_context* context,
getdns_eventloop **eventloop);
/**
* Run the context's event loop until nothing more to do.
* This is equivalend to:
* ```c
* if (getdns_context_get_eventloop(context, &loop) == GETDNS_RETURN_GOOD)
* loop->vmt->run(loop);
* ```
* @param context The context which event loop to run.
*/
void
getdns_context_run(getdns_context *context);
/** @}
*/
/**
* \addtogroup getdns_context
* @{
*/
/**
* Register a callback function for context changes.
* @see getdns_context_set_context_update_callback
* @see contextcodetypestext
* @param context The context to monitor for changes
* @param userarg A user defined argument that will be passed to the callback
* function.
* @param value The callback function that will be called when a context
* value is changed. The arguments to the callback function
* are the context for which the value changes, a code
* referencing the changed value and the userarg parameter
* supplied during callback registration.
* @return GETDNS_RETURN_GOOD on success or an error code on failure.
*/
getdns_return_t
getdns_context_set_update_callback(getdns_context *context, void *userarg,
void (*value) (getdns_context *, getdns_context_code_t, void *));
/**
* Enable the return_dnssec_status extension on every request.
* @param context The context to configure
* @param enabled is either GETDNS_EXTENSION_TRUE or GETDNS_EXTENSION_FALSE
* @return GETDNS_RETURN_GOOD on success
* @return GETDNS_RETURN_INVALID_PARAMETER if context or value is invalid
*/
getdns_return_t getdns_context_set_return_dnssec_status(
getdns_context *context, int enabled);
/**
* Configure context for oppertunistic or scrict usage profile with DNS
* over TLS.
* @see getdns_context_get_tls_authentication
* @see authvaulesandtext
* @param context The context to configure
* @param value is either GETDNS_AUTHENTICATION_REQUIRED for the strict
* usage profile or GETDNS_AUTHENTICATION_NONE for opportunistic
* profile.
* See #getdns_context_set_upstream_recursive_servers
* for details on how to configure credentials per upstream.
* @return GETDNS_RETURN_GOOD on success
* @return GETDNS_RETURN_INVALID_PARAMETER if context is null or value has an
* invalid value.
*/
getdns_return_t
getdns_context_set_tls_authentication(
getdns_context *context, getdns_tls_authentication_t value);
/**
* Configure context to round robin queries over the available upstreams
* when resolving with the stub resolution type.
* @see getdns_context_get_round_robin_upstreams
* @param context The context to configure
* @param value is either 1 to enable and 0 to disable round robin.
* @return GETDNS_RETURN_GOOD on success
* @return GETDNS_RETURN_INVALID_PARAMETER if context is null or value has an
* invalid value.
*/
getdns_return_t
getdns_context_set_round_robin_upstreams(getdns_context *context, uint8_t value);
/**
* Configure the amount of seconds a TLS connection should not be tried with
* an upstream when it has never been tried before. Default is 3600 which is
* one hour.
* @see getdns_context_get_tls_backoff_time
* @param context The context to configure
* @param value Number of seconds before an attempt to setup DNS over TLS,
* with an upstream for which setting up an TLS connection has
* never been successful before, will be retried.
* @return GETDNS_RETURN_GOOD on success
* @return GETDNS_RETURN_INVALID_PARAMETER if context is null.
*/
getdns_return_t
getdns_context_set_tls_backoff_time(getdns_context *context, uint16_t value);
/**
* Configure the number of times getdns retries to setup DNS over TLS with a
* specific upstream, before it decides to give up for tls_backoff_time
* seconds. The default is 2.
* @see getdns_context_get_tls_connection_retries
* @param context The context to configure
* @param value Number of attempts to retry setting up a DNS over TLS
* connection before giving up.
* @return GETDNS_RETURN_GOOD on success
* @return GETDNS_RETURN_INVALID_PARAMETER if context is null.
*/
getdns_return_t
getdns_context_set_tls_connection_retries(getdns_context *context, uint16_t value);
/**
* Configure context to sent queries with the EDNS Client Subnet option set
* to hide the originating network when resolving in stub resolution.
* The default is 0 (disabled).
* @see getdns_context_get_edns_client_subnet_private
* @param context The context to configure
* @param value is either 1 to enable and 0 to disable.
* @return GETDNS_RETURN_GOOD on success
* @return GETDNS_RETURN_INVALID_PARAMETER if context is null or value has an
* invalid value.
*/
getdns_return_t
getdns_context_set_edns_client_subnet_private(getdns_context *context, uint8_t value);
/**
* Configure context to pad each outgoing query over TLS to a multiple of the
* requested blocksizes. A value of 0 means disable, and a value of 1 means
* to "pad using a sensible policy". The default is 1 (pad using sensible policy).
* @see getdns_context_get_tls_query_padding_blocksize
* @param context The context to configure
* @param value The requested block size to pad to, or 0 to disable, or 1 to
* indicate that the library should use a sinsible policy.
* Currently that just means to pad to a multiple of 128 octets for
* outgoing queries, but this might change in the future.
* @return GETDNS_RETURN_GOOD on success
* @return GETDNS_RETURN_INVALID_PARAMETER if context is null or value has an
* invalid value.
*/
getdns_return_t
getdns_context_set_tls_query_padding_blocksize(getdns_context *context, uint16_t value);
/**
* Configure context to advertise maximum UDP payload size values, that
* adhere to the suggestions in RFC 6891 and may follow a scheme that uses
* multiple values to maximize receptivity. In practice with our implementation
* this means 1432 for IPv4 upstreams and 1232 for IPv6 upstreams.
* The default is to have the edns maximum UDP payload size to be unset and
* thus use the adaptive scheme.
* @see getdns_context_set_edns_maximum_udp_payload_size
* @see getdns_context_get_edns_maximum_udp_payload_size
* @param context The context to configure
* @return GETDNS_RETURN_GOOD on success
* @return GETDNS_RETURN_INVALID_PARAMETER if context is null.
*/
getdns_return_t
getdns_context_unset_edns_maximum_udp_payload_size(getdns_context *context);
typedef enum getdns_loglevel_type {
GETDNS_LOG_EMERG = 0,
GETDNS_LOG_ALERT = 1,
GETDNS_LOG_CRIT = 2,
GETDNS_LOG_ERR = 3,
GETDNS_LOG_WARNING = 4,
GETDNS_LOG_NOTICE = 5,
GETDNS_LOG_INFO = 6,
GETDNS_LOG_DEBUG = 7
} getdns_loglevel_type;
#define GETDNS_LOG_EMERG_TEXT "System is unusable"
#define GETDNS_LOG_ALERT_TEXT "Action must be taken immediately"
#define GETDNS_LOG_CRIT_TEXT "Critical conditions"
#define GETDNS_LOG_ERR_TEXT "Error conditions"
#define GETDNS_LOG_WARNING_TEXT "Warning conditions"
#define GETDNS_LOG_NOTICE_TEXT "Normal, but significant, condition"
#define GETDNS_LOG_INFO_TEXT "Informational message"
#define GETDNS_LOG_DEBUG_TEXT "Debug-level message"
#define GETDNS_LOG_UPSTREAM_STATS 4096
#define GETDNS_LOG_UPSTREAM_STATS_TEXT "Log messages about upstream statistics"
typedef void (*getdns_logfunc_type) (void *userarg, uint64_t log_systems,
getdns_loglevel_type, const char *, va_list ap);
/**
* Register a function that will be called when there is something to log
* equally or more severe than the given level for the given system.
* @param[in] context The context from which to get the setting
* @param[in] userarg A user defined argument to be passed to the
* log function.
* @param[in] system A bitwise ORed collection of systems for which the log
* function should be called. Currently only logging
* information about upstream statistics is available;
* i.e.: GETDNS_LOG_UPSTREAM_STATS
* @param[in] level A severity level. The log function will be called
* only for messages with an equal or more severe level.
* More severe has a lower value.
* @param[in] func The log function to call with the user argument,
* the system for which the log message, the severity
* level, a printf style format string and the arguments
* for the format string, as parameter.
* @see getdns_loglevel_type
* @see getdns_logfunc_type
* @return GETDNS_RETURN_GOOD when successful
* @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL.
*/
getdns_return_t
getdns_context_set_logfunc(getdns_context *context, void *userarg,
uint64_t system, getdns_loglevel_type level, getdns_logfunc_type func);
/**
* Define the location for storing library specific data. The location should
* be writable for the current user using the application with which the
* library is linked. Currently this is only used for storing data concerning
* zero configuration dnssec.
* @param[in] context The context from which to get the setting
* @param[in] appdata_dir A user writable location in which the library can
* store data. The last element of the path is tried
* to be created if it does not exist. When NULL is
* given, the default location is used which is
* ${HOME}/.getdns/ on Unix line systems (Linux, BSD's,
* MacOS), and %AppData%\getnds\ on Windows.
* @return GETDNS_RETURN_GOOD when successful
* @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL.
*/
getdns_return_t
getdns_context_set_appdata_dir(
getdns_context *context, const char *appdata_dir);
/**
* Sets the url for the location of the XML file from which to fetch the
* trust anchors with Zero configuration DNSSEC. The url should be for
* http, and the file should have the .xml extension.
*
* Alongside the XML file, also the S/MIME signature that will be used to
* validate the XML file, will be fetched from the url with the .xml extension
* replaced by .p7s.
*
* When successfully validated with the verify Certificate Authority and the
* verify email address, the context will be equipped with the DNSSEC trust
* anchors defined within the XML file as described in RFC7958.
* The XML file will also be stored together with the .p7s file in the
* appdata directory with the names "root-anchors.xml" and "root-anchors.p7s"
* respectively.
*
* When the trust-anchors from the XML file are used, the root DNSKEY is
* tracked and stored in the appdata directory too as "root.key"
*
* Trust anchors from the XML file will be tried when:
* - There were no other trust anchors provided, either by the default
* trust anchor file "/usr/share/dns/root.key", or set with the
* getdns_context_set_dnssec_trust_anchors() function.
* - or the available trust anchors (from the default location or set by
* the application) caused the root DNSKEY rrset to be BOGUS.
*
* Trust anchors from the XML file will be read from the root-anchors.xml
* file in appdata directory and will only be used when validation with the
* S/MIME signatures in root-anchors.p7s succeeds with the verification
* Certificate Authority and the verification email address.
*
* A (new) version of "root-anchors.xml" and "root-anchors.p7s" will be
* fetched when:
* - The appdata directory is writeable by the current used, but the
* "root-anchors.xml" or "root-anchors.p7s" files were not available.
* - or there is a new root DNSKEY RRset (or signature) and it contains
* key_ids which were not in "root-anchors.xml."
*
* @see getdns_context_get_trust_anchors_url
* @see getdns_context_set_trust_anchors_verify_CA
* @see getdns_context_set_trust_anchors_verify_email
* @param[in] context The context to configure
* @param[in] url The url including the XML file from which the
* trust anchors (and the S/MIME signature) will be
* fetched. Default is:
* http://data.iana.org/root-anchors/root-anchors.xml
* When NULL is given, the default will be used.
* @return GETDNS_RETURN_GOOD when successful
* @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL.
*/
getdns_return_t
getdns_context_set_trust_anchors_url(getdns_context *context, const char *url);
/**
* Sets the public certificate for the Certificate Authority with which to
* validate the XML file with the S/MIME signatures fetch from the url
* given with the getdns_context_set_trust_anchors_url() function.
* @see getdns_context_get_trust_anchors_verify_CA
* @see getdns_context_set_trust_anchors_url
* @see getdns_context_set_trust_anchors_verify_email
* @param[in] context The context to configure
* @param[in] verify_CA The certificate of the Certificate Authority with
* which to validate the XML trust anchors.
* The default is the ICANN Root CA, which is valid
* till Dec 18 2029.
* When NULL is given, the default will be used.
* When an empty string is given, Zero configuration
* DNSSEC will be disabled.
* @return GETDNS_RETURN_GOOD when successful
* @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL.
*/
getdns_return_t
getdns_context_set_trust_anchors_verify_CA(
getdns_context *context, const char *verify_CA);
/**
* Sets the email address for the Subject of the signer's certificate from the
* p7s signature file with which to validate the XML file fetched from the url
* given with the getdns_context_set_trust_anchors_url() function.
* @see getdns_context_get_trust_anchors_verify_email
* @see getdns_context_set_trust_anchors_url
* @see getdns_context_set_trust_anchors_verify_CA
* @param[in] context The context to configure
* @param[in] verify_email Only signatures from this name are allowed.
* The default dnssec@iana.org.
* When NULL is given, the default will be used.
* When an empty string is given, Zero configuration
* DNSSEC will be disabled.
* @return GETDNS_RETURN_GOOD when successful
* @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL.
*/
getdns_return_t
getdns_context_set_trust_anchors_verify_email(
getdns_context *context, const char *verify_email);
/**
* Initialized the context's upstream recursive servers and suffixes
* with the values from the given resolv.conf file.
* @see getdns_context_get_resolvconf
* @see getdns_context_set_hosts
* @param[in] context The context to configure
* @param[in] resolvonf Defaults to /etc/resolv.conf
* @return GETDNS_RETURN_GOOD when successful and error code otherwise.
*/
getdns_return_t
getdns_context_set_resolvconf(getdns_context *context, const char *resolvconf);
/**
* Initialized the context's GETDNS_NAMESPACE_LOCALNAMES namespace with
* values from the given hosts file.
* @see getdns_context_get_hosts
* @see getdns_context_set_resolvconf
* @param[in] context The context to configure
* @param[in] hosts Defaults to /etc/hosts
* @return GETDNS_RETURN_GOOD when successful and error code otherwise.
*/
getdns_return_t
getdns_context_set_hosts(getdns_context *context, const char *hosts);
/**
* Specify where the location for CA certificates for verification purposes
* are located.
* @see getdns_context_get_tls_ca_path
* @see getdns_context_set_tls_ca_file
* @param[in] context The context to configure
* @param[in] tls_ca_path Directory with Certificate Authority certificates.
* @return GETDNS_RETURN_GOOD when successful
* @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL.
*/
getdns_return_t
getdns_context_set_tls_ca_path(getdns_context *context, const char *tls_ca_path);
/**
* Specify the file with CA certificates for verification purposes.
* @see getdns_context_get_tls_ca_file
* @see getdns_context_set_tls_ca_path
* @param[in] context The context to configure
* @param[in] tls_ca_file The file with Certificate Authority certificates.
* @return GETDNS_RETURN_GOOD when successful
* @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL.
*/
getdns_return_t
getdns_context_set_tls_ca_file(getdns_context *context, const char *tls_ca_file);
/**
* Sets the list of available ciphers for authenticated TLS upstreams.
* @see getdns_context_get_tls_cipher_list
* @param[in] context The context to configure
* @param[in] cipher_list The cipher list
* @return GETDNS_RETURN_GOOD when successful
* @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL.
*/
getdns_return_t
getdns_context_set_tls_cipher_list(
getdns_context *context, const char *cipher_list);
/**
* Sets the supported curves TLS upstreams.
* @see getdns_context_get_tls_curves_list
* @param[in] context The context to configure
* @param[in] curves_list The string is a colon separated list of curve
* NIDs or names, for example "P-521:P-384:P-256".
* @return GETDNS_RETURN_GOOD when successful
* @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL.
*/
getdns_return_t
getdns_context_set_tls_curves_list(
getdns_context *context, const char *curves_list);
/**
* Get the current resolution type setting from this context.
* @see getdns_context_set_resolution_type
* @see resolutiontypestext
* @param[in] context The context from which to get the setting
* @param[out] value The resolution type, either GETDNS_RESOLUTION_RECURSING
* or GETDNS_RESOLUTION_STUB.
* @return GETDNS_RETURN_GOOD when successful
* @return GETDNS_RETURN_INVALID_PARAMETER when context or value was NULL.
*/
getdns_return_t
getdns_context_get_resolution_type(getdns_context *context,
getdns_resolution_t* value);
/**
* Get a copy of the namespaces list setting from this context.
* Users must call free on the resulting namespaces if not NULL
* @see getdns_context_set_namespaces
* @see namespacetypestext
* @param[in] context The context from which to get the setting
* @param[out] namespace_count The length of the list.
* @param[out] namespaces The returned namespaces list.
* @return GETDNS_RETURN_GOOD when successful
* @return GETDNS_RETURN_INVALID_PARAMETER when any of the arguments was NULL.
*/
getdns_return_t
getdns_context_get_namespaces(getdns_context *context,
size_t* namespace_count, getdns_namespace_t **namespaces);
/**
* Get what transports are used for DNS lookups.
* @see getdns_context_set_dns_transport
* @see transporttypestext
* @see getdns_context_get_dns_transport_list
* @param[in] context The context from which to get the setting
* @param[out] value The transport to use for DNS lookups.
* @return GETDNS_RETURN_GOOD when successful
* @return GETDNS_RETURN_INVALID_PARAMETER when any of the arguments was NULL.
*/
getdns_return_t
getdns_context_get_dns_transport(getdns_context *context,
getdns_transport_t* value);
/**
* Get a copy of the transports list setting from this context.
* Users must call free on the resulting transports if not NULL
* @see getdns_context_set_dns_transport_list
* @see transportlisttypestext
* @see getdns_context_get_dns_transport
* @param[in] context The context from which to get the setting
* @param[out] transport_count The length of the list.
* @param[out] transports The returned transports list.
* @return GETDNS_RETURN_GOOD when successful
* @return GETDNS_RETURN_INVALID_PARAMETER when any of the arguments was NULL.
*/
getdns_return_t
getdns_context_get_dns_transport_list(getdns_context *context,
size_t* transport_count, getdns_transport_list_t **transports);
/**
* Get the current limit for oustanding queries setting from this context.
* @see getdns_context_set_limit_outstanding_queries
* @param[in] context The context from which to get the setting
* @param[out] limit The current limit for oustanding queries
* @return GETDNS_RETURN_GOOD when successful
* @return GETDNS_RETURN_INVALID_PARAMETER when context or limit was NULL.
*/
getdns_return_t
getdns_context_get_limit_outstanding_queries(getdns_context *context,
uint16_t* limit);
/**
* Get the current number of milliseconds the API will wait for request
* to return setting from this context.
* @see getdns_context_set_timeout
* @param[in] context The context from which to get the setting
* @param[out] timeout The number of milliseconds the API will wait for a
* response.
* @return GETDNS_RETURN_GOOD when successful
* @return GETDNS_RETURN_INVALID_PARAMETER when context or limit was NULL.
*/
getdns_return_t
getdns_context_get_timeout(getdns_context *context, uint64_t* timeout);
/**
* Get the current number of milliseconds the API will leave an idle TCP or TLS
* connection open for (idle means no outstanding responses and no pending
* queries).
* @see getdns_context_set_idle_timeout
* @param[in] context The context from which to get the setting
* @param[out] timeout The number of milliseconds the API will leave an idle TCP
* or TLS connection open for
* @return GETDNS_RETURN_GOOD when successful
* @return GETDNS_RETURN_INVALID_PARAMETER when context or timeout was NULL.
*/
getdns_return_t
getdns_context_get_idle_timeout(getdns_context *context, uint64_t* timeout);
/**
* Get the setting that says whether or not DNS queries follow redirects.
* @see getdns_context_set_follow_redirects
* @see redirectpoliciestext
* @param[in] context The context from which to get the setting
* @param[out] value Either GETDNS_REDIRECTS_FOLLOW or GETDNS_REDIRECTS_DO_NOT_FOLLOW
* @return GETDNS_RETURN_GOOD when successful
* @return GETDNS_RETURN_INVALID_PARAMETER when context or value was NULL.
*/
getdns_return_t
getdns_context_get_follow_redirects(getdns_context *context,
getdns_redirects_t* value);
/**
* Get a copy of the list of addresses in use for looking up top-level domains
* in use by the context.
* Callers are responsible for deallocating the returned list with
* #getdns_list_destroy()
* @see getdns_context_set_dns_root_servers
* @param[in] context The context from which to get the setting
* @param[out] addresses A copy of the list of dns root servers in use for
* looking up top level domains. The caller must
* destroy this list.
* @return GETDNS_RETURN_GOOD when successful
* @return GETDNS_RETURN_INVALID_PARAMETER when context or adresses was NULL.
* @return GETDNS_RETURN_MEMORY_ERROR when the copy could not be allocated
*/
getdns_return_t
getdns_context_get_dns_root_servers(getdns_context *context,
getdns_list **addresses);
/**
* Get whether, how and when a suffix is appended to a query string with
* the context.
* @see getdns_context_set_append_name
* @see suffixappendtypestext
* @param[in] context The context from which to get the setting
* @param[out] value GETDNS_APPEND_NAME_TO_SINGLE_LABEL_FIRST,
* GETDNS_APPEND_NAME_ALWAYS,
* GETDNS_APPEND_NAME_ONLY_TO_SINGLE_LABEL_AFTER_FAILURE,
* GETDNS_APPEND_NAME_ONLY_TO_MULTIPLE_LABEL_NAME_AFTER_FAILURE,
* or GETDNS_APPEND_NAME_NEVER
* @return GETDNS_RETURN_GOOD when successful
* @return GETDNS_RETURN_INVALID_PARAMETER when context or value was NULL.
*/
getdns_return_t
getdns_context_get_append_name(getdns_context *context,
getdns_append_name_t* value);
/**
* Get a copy of the list of suffixes to be appended based on the value off the
* append_name setting in use by context
* Callers are responsible for deallocating the returned list with
* #getdns_list_destroy()
* @see getdns_context_set_suffix
* @param[in] context The context from which to get the setting
* @param[out] value A copy of the list of suffixes. The caller must destroy
* this list.
* @return GETDNS_RETURN_GOOD when successful
* @return GETDNS_RETURN_INVALID_PARAMETER when context or value was NULL.
* @return GETDNS_RETURN_MEMORY_ERROR when the copy could not be allocated
*/
getdns_return_t
getdns_context_get_suffix(getdns_context *context, getdns_list **value);
/**
* Get a copy of the list of DNSSEC trust anchors in use by context.
* Callers are responsible for deallocating the returned list with
* #getdns_list_destroy()
* @see getdns_context_set_dnssec_trust_anchors
* @param[in] context The context from which to get the setting
* @param[out] value A copy of the list of DNSSEC trust anchors.
* The caller must destroy this list.
* @return GETDNS_RETURN_GOOD when successful
* @return GETDNS_RETURN_INVALID_PARAMETER when context or value was NULL.
* @return GETDNS_RETURN_MEMORY_ERROR when the copy could not be allocated
*/
getdns_return_t
getdns_context_get_dnssec_trust_anchors(getdns_context *context,
getdns_list **value);
/**
* Get the allowed DNSSEC skew setting from context
* @see getdns_context_set_dnssec_allowed_skew
* @param[in] context The context from which to get the setting
* @param[out] value The number of seconds of skew that is allowed in either
* direction when checking an RRSIG's Expiration and Inception
* fields.
* @return GETDNS_RETURN_GOOD when successful
* @return GETDNS_RETURN_INVALID_PARAMETER when context or value was NULL.
*/
getdns_return_t
getdns_context_get_dnssec_allowed_skew(getdns_context *context,
uint32_t* value);
/**
* Get a copy of the list of upstream that will be targeted in stub resolution
* mode.
* Callers are responsible for deallocating the returned list with
* #getdns_list_destroy()
* @see getdns_context_set_upstream_recursive_servers
* @param[in] context The context from which to get the setting
* @param[out] upstream_list A copy of the list of upstreams.
* The caller must destroy this list.
* @return GETDNS_RETURN_GOOD when successful
* @return GETDNS_RETURN_INVALID_PARAMETER when context or value was NULL.
* @return GETDNS_RETURN_MEMORY_ERROR when the copy could not be allocated
*/
getdns_return_t
getdns_context_get_upstream_recursive_servers(getdns_context *context,
getdns_list **upstream_list);
/**
* Get the maximum UDP payload size advertised in an EDNS0 OPT record
* setting from context
* @see getdns_context_set_edns_maximum_udp_payload_size
* @see getdns_context_unset_edns_maximum_udp_payload_size
* @param[in] context The context from which to get the setting
* @param[out] value the maximum UDP payload size advertised in an EDNS0
* OPT record. When the value is unset, 0 is returned.
* @return GETDNS_RETURN_GOOD when successful
* @return GETDNS_RETURN_INVALID_PARAMETER when context or value was NULL.
*/
getdns_return_t
getdns_context_get_edns_maximum_udp_payload_size(getdns_context *context,
uint16_t* value);
/**
* Get the rcode advertised in an EDNS0 OPT record setting from context
* @see getdns_context_set_edns_extended_rcode
* @param[in] context The context from which to get the setting
* @param[out] value The rcode advertised in an EDNS0 OPT record
* @return GETDNS_RETURN_GOOD when successful
* @return GETDNS_RETURN_INVALID_PARAMETER when context or value was NULL.
*/
getdns_return_t
getdns_context_get_edns_extended_rcode(getdns_context *context,
uint8_t* value);
/**
* Get the version advertised in an EDNS0 OPT record setting from context
* @see getdns_context_set_edns_version
* @param[in] context The context from which to get the setting
* @param[out] value The version advertised in an EDNS0 OPT record
* @return GETDNS_RETURN_GOOD when successful
* @return GETDNS_RETURN_INVALID_PARAMETER when context or value was NULL.
*/
getdns_return_t
getdns_context_get_edns_version(getdns_context *context, uint8_t* value);
/**
* Get the DO bit advertised in an EDNS0 OPT record setting from context
* @see getdns_context_set_edns_do_bit
* @param[in] context The context from which to get the setting
* @param[out] value 1 if the DO bit is advertised in EDNS0 OPT records,
* 0 otherwise.
* @return GETDNS_RETURN_GOOD when successful
* @return GETDNS_RETURN_INVALID_PARAMETER when context or value was NULL.
*/
getdns_return_t
getdns_context_get_edns_do_bit(getdns_context *context, uint8_t* value);
/**
* Get whether queries with this context will have the EDNS Client Subnet
* option set to hide the originating network when resolving in stub
* resolution.
* @see getdns_context_set_edns_do_bit
* @param[in] context The context from which to get the setting
* @param[out] value 1 if the setting is on, 0 otherwise
* @return GETDNS_RETURN_GOOD when successful
* @return GETDNS_RETURN_INVALID_PARAMETER when context or value was NULL.
*/
getdns_return_t
getdns_context_get_edns_client_subnet_private(getdns_context *context, uint8_t* value);
/**
* Get the blocksize that will be used to pad outgoing queries over TLS.
* @see getdns_context_set_tls_query_padding_blocksize
* @param[in] context The context from which to get the setting
* @param[out] value The padding blocksize, or 0 if padding is disabled,
* or 1 if the setting is to pad using a sensible policy.
* @return GETDNS_RETURN_GOOD when successful
* @return GETDNS_RETURN_INVALID_PARAMETER when context or value was NULL.
*/
getdns_return_t
getdns_context_get_tls_query_padding_blocksize(getdns_context *context, uint16_t* value);
/**
* Get whether the upstream needs to be authenticated whith DNS over TLS.
* @see getdns_context_set_tls_authentication
* @see authvaulesandtext
* @param[in] context The context from which to get the setting
* @param[out] value is either GETDNS_AUTHENTICATION_REQUIRED if
* authentication is required, or GETDNS_AUTHENTICATION_NONE
* if authentication is optional. When credentials are
* available, the API will still try to authenticate the
* upstream.
* See #getdns_context_set_upstream_recursive_servers
* for details on how to configure credentials per upstream.
* @return GETDNS_RETURN_GOOD when successful
* @return GETDNS_RETURN_INVALID_PARAMETER when context or value was NULL.
*/
getdns_return_t
getdns_context_get_tls_authentication(getdns_context *context,
getdns_tls_authentication_t* value);
/**
* Get whether the context is configured to round robin queries over the available
* upstreams.
* @see getdns_context_get_round_robin_upstreams
* @param[in] context The context from which to get the setting
* @param[out] value 1 if the setting is on, 0 otherwise
* @return GETDNS_RETURN_GOOD when successful
* @return GETDNS_RETURN_INVALID_PARAMETER when context or value was NULL.
*/
getdns_return_t
getdns_context_get_round_robin_upstreams(getdns_context *context,
uint8_t* value);
/**
* Get the amount of seconds a TLS connection should not be tried with
* an upstream when it has never been tried before.
* @see getdns_context_set_tls_backoff_time
* @param[in] context The context from which to get the setting
* @param[out] value Number of seconds before an attempt to setup DNS over TLS,
* with an upstream for which setting up an TLS connection has
* never been successful before, will be retried.
* @return GETDNS_RETURN_GOOD when successful
* @return GETDNS_RETURN_INVALID_PARAMETER when context or value was NULL.
*/
getdns_return_t
getdns_context_get_tls_backoff_time(getdns_context *context,
uint16_t* value);
/**
* Get the number of times getdns retries to setup DNS over TLS with a
* specific upstream, before it decides to give up for tls_backoff_time
* seconds.
* @see getdns_context_set_tls_connection_retries
* @param[in] context The context from which to get the setting
* @param[out] value Number of attempts to retry setting up a DNS over TLS
* connection before giving up.
* @return GETDNS_RETURN_GOOD when successful
* @return GETDNS_RETURN_INVALID_PARAMETER when context or value was NULL.
*/
getdns_return_t
getdns_context_get_tls_connection_retries(getdns_context *context,
uint16_t* value);
/**
* Get the currently registered callback function and user defined argument
* for context changes.
* Combined with #getdns_context_set_update_callback this can be used to
* "chain" context update callbacks and in this way create a subscription
* service catering multiple interested parties.
* @see contextcodetypestext
* @param context The context to monitor for changes
* @param userarg A user defined argument to be passed to the callback
* function.
* @param value The callback function to be called on context value
* changes.
* @return GETDNS_RETURN_GOOD on success or an error code on failure.
*/
getdns_return_t
getdns_context_get_update_callback(getdns_context *context, void **userarg,
void (**value) (getdns_context *, getdns_context_code_t, void *));
/**
* Gets the url for the location of the XML file from which to fetch the
* trust anchors with Zero configuration DNSSEC.
*
* Alongside the XML file, also the S/MIME signature that will be used to
* validate the XML file, will be fetched from the url with the .xml extension
* replaced by .p7s.
*
* When successfully validated with the verify Certificate Authority and the
* verify email address, the context will be equipped with the DNSSEC trust
* anchors defined within the XML file as described in RFC7958.
* The XML file will also be stored together with the .p7s file in the
* appdata directory with the names "root-anchors.xml" and "root-anchors.p7s"
* respectively.
*
* When the trust-anchors from the XML file are used, the root DNSKEY is
* tracked and stored in the appdata directory too as "root.key"
*
* Trust anchors from the XML file will be tried when:
* - There were no other trust anchors provided, either by the default
* trust anchor file "/usr/share/dns/root.key", or set with the
* getdns_context_set_dnssec_trust_anchors() function.
* - or the available trust anchors (from the default location or set by
* the application) caused the root DNSKEY rrset to be BOGUS.
*
* Trust anchors from the XML file will be read from the root-anchors.xml
* file in appdata directory and will only be used when validation with the
* S/MIME signatures in root-anchors.p7s succeeds with the verification
* Certificate Authority and the verification email address.
*
* A (new) version of "root-anchors.xml" and "root-anchors.p7s" will be
* fetched when:
* - The appdata directory is writeable by the current used, but the
* "root-anchors.xml" or "root-anchors.p7s" files were not available.
* - or there is a new root DNSKEY RRset (or signature) and it contains
* key_ids which were not in "root-anchors.xml."
*
* @see getdns_context_set_trust_anchors_url
* @see getdns_context_get_trust_anchors_verify_CA
* @see getdns_context_get_trust_anchors_verify_email
* @param[in] context The context to configure
* @param[out] url The url including the XML file, from which the
* trust anchors (and the S/MIME signature) will be
* fetched. Default is:
* http://data.iana.org/root-anchors/root-anchors.xml
* @return GETDNS_RETURN_GOOD when successful
* @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL.
*/
getdns_return_t
getdns_context_get_trust_anchors_url(
getdns_context *context, const char **url);
/**
* Gets the public certificate for the Certificate Authority with which to
* validate the XML file with the S/MIME signatures fetch from the url
* given with the getdns_context_set_trust_anchors_url() function.
* @see getdns_context_set_trust_anchors_verify_CA
* @see getdns_context_get_trust_anchors_url
* @see getdns_context_get_trust_anchors_verify_email
* @param[in] context The context to configure
* @param[out] verify_CA The certificate of the Certificate Authority with
* which to validate the XML trust anchors.
* The default is the ICANN Root CA, which is valid
* till Dec 18 2029.
* @return GETDNS_RETURN_GOOD when successful
* @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL.
*/
getdns_return_t
getdns_context_get_trust_anchors_verify_CA(
getdns_context *context, const char **verify_CA);
/**
* Gets the email address for the Subject of the signer's certificate from the
* p7s signature file with which to validate the XML file fetched from the url
* given with the getdns_context_set_trust_anchors_url() function.
* @see getdns_context_set_trust_anchors_verify_email
* @see getdns_context_get_trust_anchors_url
* @see getdns_context_get_trust_anchors_verify_CA
* @param[in] context The context to configure
* @param[out] verify_email Only signatures from this name are allowed.
* The default dnssec@iana.org.
* @return GETDNS_RETURN_GOOD when successful
* @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL.
*/
getdns_return_t
getdns_context_get_trust_anchors_verify_email(
getdns_context *context, const char **verify_email);
/**
* Get the value with which the context's upstream recursive servers
* and suffixes were initialized.
* @see getdns_context_set_resolvconf
* @see getdns_context_get_hosts
* @param[in] context The context to configure
* @param[out] resolvonf NULL if the context was not initialized with a
* resolv.conf file.
* @return GETDNS_RETURN_GOOD when successful and error code otherwise.
*/
getdns_return_t
getdns_context_get_resolvconf(getdns_context *context, const char **resolvconf);
/**
* Get the value with which the context's GETDNS_NAMESPACE_LOCALNAMES namespace
* was initialized.
* @see getdns_context_set_hosts
* @see getdns_context_get_resolvconf
* @param[in] context The context to configure
* @param[out] hosts NULL when GETDNS_NAMESPACE_LOCALNAMES namespace
* was not initialized.
* @return GETDNS_RETURN_GOOD when successful and error code otherwise.
*/
getdns_return_t
getdns_context_get_hosts(getdns_context *context, const char **hosts);
/**
* Get the location of the directory for CA certificates for verification
* purposes.
* @see getdns_context_set_tls_ca_path
* @see getdns_context_get_tls_ca_file
* @param[in] context The context to configure
* @param[out] tls_ca_path Directory with Certificate Authority certificates
* or NULL when one was not configured.
* @return GETDNS_RETURN_GOOD when successful
* @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL.
*/
getdns_return_t
getdns_context_get_tls_ca_path(getdns_context *context, const char **tls_ca_path);
/**
* Get the file location with CA certificates for verification purposes.
* @see getdns_context_set_tls_ca_file
* @see getdns_context_get_tls_ca_path
* @param[in] context The context to configure
* @param[out] tls_ca_file The file with Certificate Authority certificates
* or NULL when one was not configured.
* @return GETDNS_RETURN_GOOD when successful
* @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL.
*/
getdns_return_t
getdns_context_get_tls_ca_file(getdns_context *context, const char **tls_ca_file);
/**
* Get the list of available ciphers for authenticated TLS upstreams.
* @see getdns_context_set_tls_cipher_list
* @param[in] context The context configure
* @param[out] cipher_list The cipher list
* @return GETDNS_RETURN_GOOD when successful
* @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL.
*/
getdns_return_t
getdns_context_get_tls_cipher_list(
getdns_context *context, const char **cipher_list);
/**
* Get the supported curves list if one has been set earlier.
* @see getdns_context_set_tls_curves_list
* @param[in] context The configured context
* @param[out] curves_list The string is a colon separated list of curve
* NIDs or names, for example "P-521:P-384:P-256",
* when one has been configured on the context,
* or NULL when none has been set before.
* @return GETDNS_RETURN_GOOD when successful
* @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL.
*/
getdns_return_t
getdns_context_get_tls_curves_list(
getdns_context *context, const char **curves_list);
/** @}
*/
/**
* \addtogroup versionfuncs Version functions
* @{
*/
/**
* Get the version number of this implementation.
* @see versions
* @return The version number as string. For example "1.4.0".
*/
const char *getdns_get_version(void);
/**
* Get the version number of this implementation as number.
* @see versions
* @return The version number as number. For example 0x01040000.
* - The most significant byte of this uint32_t is the Major version.
* - The second most significant byte is the Minor version.
* - The third most significant byte the Patch version.
*/
uint32_t getdns_get_version_number(void);
/**
* Get the version of the getdns API specification this library implements
* as a string.
* @see versions
* @return The API specification version as string. For example "December 2015"
*/
const char *getdns_get_api_version(void);
/**
* Get the version of the getdns API specification this library implements
* as a number.
* @see versions
* @return The API specification version as number. For example "0x07df0c00"
* - The most significant 16 bits represent the year.
* - The third most significant byte the day.
*/
uint32_t getdns_get_api_version_number(void);
/** @}
*/
/**
* \addtogroup utils Utility functions
* @{
*/
/**
* Returns a text describing the getdns error code, or NULL when the error
* code is unkown.
* @param err The error code for which to return the describing text
* @return The describing text for the error code. The string is in library
* space and the caller must *not* free this.
*/
const char *getdns_get_errorstr_by_id(uint16_t err);
/** @}
*/
/**
* \addtogroup getdns_dict
* @{
*/
/**
* Create a new entry in the dictionary, or replace the value of an existing
* entry, with a getdns_bindata representing a string. The string will be
* copied. The size of the bindata will be strlen(value), though there will
* be a '\0' byte directly after the size'd position even, though the size
* argument suggests that this would not be part of the bindata's date space.
* @see getdns_dict_set_bindata
* @param dict dictionary in which to add or change the value
* @param name key that identifies which item in the dictionary to add/change
* @param value string to be copied and stored in the bindata at key
* @return GETDNS_RETURN_GOOD on success
* @return GETDNS_RETURN_INVALID_PARAMETER when one of the arguments was NULL
* @return GETDNS_RETURN_MEMORY_ERROR when the copy could not be allocated
*/
getdns_return_t
getdns_dict_util_set_string(getdns_dict *dict, char *name, const char *value);
/**
* Get the string associated with the speicifed name. The string should not
* be free()'d by the caller.
* @see getdns_dict_get_bindata
* @param dict dictionary from which to fetch the bindata
* @param name a name/key value to look up in the dictionary
* @param result The bindata's data value
* @return GETDNS_RETURN_GOOD on success
* @return GETDNS_RETURN_NO_SUCH_DICT_NAME if dict is invalid or name does not exist
*/
getdns_return_t
getdns_dict_util_get_string(getdns_dict * dict, char *name, char **result);
/** @}
*/
/**
* \addtogroup dnssecfuncs
* @{
*/
/**
* Validate replies or resource records.
*
* @see dnssecvalues
* @param to_validate A list of RR-dicts with companion RRSIG-RR-dicts
* which will be validated. Or a list of reply-dicts
* that will be validated. The "replies_tree" list
* of a response dict can be used directly here.
* @param support_records A list of DS's RR-dicts and DNSKEY RR-dicts with
* companion RRSIG-RR-dicts that lead up from one of
* the trust_anchors to the RR-dicts or replies to
* validate. The "validation_chain" list of a response
* dict (with the dnssec_return_validation_chain
* extension) can be used directly here.
* @param trust_anchors The list of trusted DNSKEYs or DS'es RR-dicts.
* The result of the getdns_root_trust_anchor() or the
* getdns_context_get_dnssec_trust_anchors() function
* can be used directly here.
* @param validation_time The point in time in seconds since 1 January 1970
* 00:00:00 UTC, ignoring leap seconds, wrapping using
* "Serial number arithmetic", as defined in RFC1982.
* @param skew The numer of seconds of skew that is allowed in
* either direction when checking an RRSIG's
* Expiration and Inception fields
* @return The dnssec status of validated records or replies,
* GETDNS_DNSSEC_SECURE, GETDNS_DNSSEC_INSECURE,
* GETDNS_DNSSEC_INDETERMINATE or GETDNS_DNSSEC_BOGUS, or an error
* return code.
*/
getdns_return_t
getdns_validate_dnssec2(getdns_list *to_validate,
getdns_list *support_records,
getdns_list *trust_anchors,
time_t validation_time, uint32_t skew);
/** @}
*/
/**
* \addtogroup utils
* @{
*/
/**
* Public Key Pinning functionality:
*
* a public key pinset is a list of dicts. each dict should have a
* "digest" and a "value".
*
* "digest": a string indicating the type of digest. at the moment, we
* only support a "digest" of "sha256".
*
* "value": a binary representation of the digest provided.
*
* given a such a pinset, we should be able to validate a chain
* properly according to section 2.6 of RFC 7469.
*/
/**
* convert an HPKP-style pin description to an appropriate getdns data
* structure. An example string is: (with the quotes, without any
* leading or trailing whitespace):
*
* pin-sha256="E9CZ9INDbd+2eRQozYqqbQ2yXLVKB9+xcprMF+44U1g="
*
* It is the caller's responsibility to call getdns_dict_destroy() on
* the dict returned when it is no longer needed.
*
* @param context a context to use to create the dict, or NULL to create
* it generically
* @param str the pinning string to parse
* @return a dict created from ctx, or NULL if the string did not match.
*/
getdns_dict* getdns_pubkey_pin_create_from_string(
getdns_context* context,
const char* str);
/**
* Test whether a given pinset is reasonable, including:
*
* is it well-formed?
* are there at least two pins?
* are the digests used sane?
*
* @param pinset the set of public key pins to check for sanity. This
* should be a list of dicts.
* @param errorlist if not NULL, a list of human-readable strings is
* appended to errorlist.
* @return GETDNS_RETURN_GOOD if the pinset passes the sanity check.
*/
getdns_return_t getdns_pubkey_pinset_sanity_check(
const getdns_list* pinset,
getdns_list* errorlist);
/** @}
*/
/**
* \addtogroup getdns_context
* @{
*/
/**
* Configure a context with settings given in a getdns_dict.
*
* @param context The context to be configured.
* @param config_dict The getdns_dict containing the settings.
* The settings have the same name as returned by the
* getdns_context_get_api_information() function, or as
* used in the names of the getdns_context_get_*() and
* getdns_context_set_*() functions.
* - The dict returned by
* getdns_context_get_api_information() can be used
* as the config_dict directly, but context settings
* do *not* have to be below a `"all_context"` key.
* - It is possible to set default values for extensions
* that could otherwise only be given on a per query
* basis. For example:
* `{ dnssec_return_status: GETDNS_EXTENSION_TRUE }` is
* equivalent to using the
* getdns_context_set_return_dnssec_status() function
* with that value, but default values for the other
* extensions can be set by this method now too.
* For example
* `{ return_call_reporting: GETDNS_EXTENSION_TRUE}`
* - Trust anchor files and root hints content can also be
* given by file, for example:
*
* { dns_root_servers : "named.root"
* , dnssec_trust_anchors: "/etc/unbound/getdns-root.key"
* }
* @return GETDNS_RETURN_GOOD on success or an error code on failure.
* **Beware** that context might be partially configured on error. For retry
* strategies it is advised to recreate a new config.
*/
getdns_return_t
getdns_context_config(getdns_context *context, const getdns_dict *config_dict);
/** @}
*/
/**
* \addtogroup getdns_dict
* @{
*/
/**
* Pretty print the getdns_dict in a given buffer snprintf style.
* @param str pointer to the buffer to print to
* @param size size of the given buffer. No more than size bytes (including
* the terminating null byte) will be written to str.
* @param dict getdns_dict to print
* @return The number of characters written excluding the terminating null byte
* or the number of characters which would have been written if enough space
* had been available.
*/
int
getdns_pretty_snprint_dict(char *str, size_t size, const getdns_dict *dict);
/**
* creates a string containing a json representation of some_dict.
* bindatas are converted to strings when possible, including bindatas for
* addresses, dnames and other printable data. All other bindatas are
* converted to lists of byte values.
* @param some_dict dict to represent as json data
* @param pretty when non-zero returns formatted json
* @return character array (caller must free this) containing pretty string
*/
char *
getdns_print_json_dict(const getdns_dict *some_dict, int pretty);
/**
* Prints a json representation of dict in a given buffer snprintf style.
* bindatas are converted to strings when possible, including bindatas for
* addresses, dnames and other printable data. All other bindatas are
* converted to lists of byte values.
* @param str pointer to the buffer to print to
* @param size size of the given buffer. No more than size bytes (including
* the terminating null byte) will be written to str.
* @param dict dict to represent as json data
* @param pretty when non-zero returns formatted json
* @return The number of characters written excluding the terminating null byte
* or the number of characters which would have been written if enough space
* had been available.
*/
int
getdns_snprint_json_dict(
char *str, size_t size, const getdns_dict *dict, int pretty);
/** @}
*/
/**
* \addtogroup getdns_list
* @{
*/
/**
* creates a string that describes the list in a human readable form.
* @param some_list list to pretty print
* @return character array (caller must free this) containing pretty string
*/
char *
getdns_pretty_print_list(const getdns_list *some_list);
/**
* Pretty print the getdns_list in a given buffer snprintf style.
* @param str pointer to the buffer to print to
* @param size size of the given buffer. No more than size bytes (including
* the terminating null byte) will be written to str.
* @param list getdns_list to print
* @return The number of characters written excluding the terminating null byte
* or the number of characters which would have been written if enough space
* had been available.
*/
int
getdns_pretty_snprint_list(char *str, size_t size, const getdns_list *list);
/**
* creates a string containing a json representation of some_list.
* bindatas are converted to strings when possible, including bindatas for
* addresses, dnames and other printable data. All other bindatas are
* converted to lists of byte values.
* @param some_list list to represent as json data
* @param pretty when non-zero returns formatted json
* @return character array (caller must free this) containing pretty string
*/
char *
getdns_print_json_list(const getdns_list *some_list, int pretty);
/**
* Prints a json representation of list in a given buffer snprintf style.
* bindatas are converted to strings when possible, including bindatas for
* addresses, dnames and other printable data. All other bindatas are
* converted to lists of byte values.
* @param str pointer to the buffer to print to
* @param size size of the given buffer. No more than size bytes (including
* the terminating null byte) will be written to str.
* @param list list to represent as json data
* @param pretty when non-zero returns formatted json
* @return The number of characters written excluding the terminating null byte
* or the number of characters which would have been written if enough space
* had been available.
*/
int
getdns_snprint_json_list(
char *str, size_t size, const getdns_list *list, int pretty);
/** @}
*/
/**
* \defgroup UDNSDataConversionFunctions Converting between getdns DNS dicts, DNS wire format and DNS presentation format
* @{
*/
/**
* Convert rr_dict to wireformat representation of the resource record.
*
* @param rr_dict The getdns dict representation of the resource record
* @param wire A newly allocated buffer which will contain the wireformat.
* @param wire_sz The size of the allocated buffer and the wireformat.
* @return GETDNS_RETURN_GOOD on success or an error code on failure.
*/
getdns_return_t
getdns_rr_dict2wire(
const getdns_dict *rr_dict, uint8_t **wire, size_t *wire_sz);
/**
* Convert rr_dict to wireformat representation of the resource record.
*
* @param rr_dict The getdns dict representation of the resource record
* @param wire The buffer in which the wireformat will be written
* @param wire_sz On input the size of the wire buffer,
* On output the amount of wireformat needed for the
* wireformat representation of the resource record;
* even if it did not fit.
* @return GETDNS_RETURN_GOOD on success or an error code on failure.
* GETDNS_RETURN_NEED_MORE_SPACE will be returned when the buffer was too
* small. wire_sz will be set to the needed buffer space then.
*/
getdns_return_t
getdns_rr_dict2wire_buf(
const getdns_dict *rr_dict, uint8_t *wire, size_t *wire_sz);
/**
* Convert rr_dict to wireformat representation of the resource record.
*
* @param rr_dict The getdns dict representation of the resource record
* @param wire A pointer to the buffer pointer in which the wireformat
* will be written.
* On output the buffer pointer will have moved along
* the buffer and point right after the just written RR.
* @param wire_sz On input the size of the wire buffer,
* On output the amount of wireformat needed for the
* wireformat will have been substracted from wire_sz.
* @return GETDNS_RETURN_GOOD on success or an error code on failure.
* GETDNS_RETURN_NEED_MORE_SPACE will be returned when the buffer was too
* small. The function will pretend that it had written beyond the end
* of the buffer, and wire will point past the buffer and wire_sz will
* contain a negative value.
*/
getdns_return_t
getdns_rr_dict2wire_scan(
const getdns_dict *rr_dict, uint8_t **wire, int *wire_sz);
/**
* Convert wireformat resource record in a getdns rr_dict representation.
*
* @param wire Buffer containing the wireformat rr
* @param wire_sz Size of the wire buffer
* @param rr_dict The returned rr_dict
* @return GETDNS_RETURN_GOOD on success or an error code on failure.
*/
getdns_return_t
getdns_wire2rr_dict(
const uint8_t *wire, size_t wire_sz, getdns_dict **rr_dict);
/**
* Convert wireformat resource record in a getdns rr_dict representation.
*
* @param wire Buffer containing the wireformat rr
* @param wire_sz On input the size of the wire buffer
* On output the length of the wireformat rr.
* @param rr_dict The returned rr_dict
* @return GETDNS_RETURN_GOOD on success or an error code on failure.
*/
getdns_return_t
getdns_wire2rr_dict_buf(
const uint8_t *wire, size_t *wire_sz, getdns_dict **rr_dict);
/**
* Convert wireformat resource record in a getdns rr_dict representation.
*
* @param wire A pointer to the pointer of the wireformat buffer.
* On return this pointer is moved to after first read
* in resource record.
* @param wire_sz On input the size of the wire buffer
* On output the size is decreased with the length
* of the wireformat resource record.
* @param rr_dict The returned rr_dict
* @return GETDNS_RETURN_GOOD on success or an error code on failure.
*/
getdns_return_t
getdns_wire2rr_dict_scan(
const uint8_t **wire, size_t *wire_sz, getdns_dict **rr_dict);
/**
* Convert rr_dict to the string representation of the resource record.
*
* @param rr_dict The getdns dict representation of the resource record
* @param str A newly allocated string representation of the rr
* @return GETDNS_RETURN_GOOD on success or an error code on failure.
*/
getdns_return_t
getdns_rr_dict2str(
const getdns_dict *rr_dict, char **str);
/**
* Convert rr_dict to the string representation of the resource record.
*
* @param rr_dict The getdns dict representation of the resource record
* @param str The buffer in which the string will be written
* @param str_len On input the size of the text buffer,
* On output the amount of characters needed to write
* the string representation of the rr. Even if it does
* not fit.
* @return GETDNS_RETURN_GOOD on success or an error code on failure.
* GETDNS_RETURN_NEED_MORE_SPACE will be returned when the buffer was too
* small. str_len will be set to the needed buffer space then.
*/
getdns_return_t
getdns_rr_dict2str_buf(
const getdns_dict *rr_dict, char *str, size_t *str_len);
/**
* Convert rr_dict to the string representation of the resource record.
*
* @param rr_dict The getdns dict representation of the resource record
* @param str A pointer to the buffer pointer in which the string
* will be written.
* On output the buffer pointer will have moved along
* the buffer and point right after the just written RR.
* @param str_len On input the size of the str buffer,
* On output the number of characters needed for the
* string will have been substracted from strlen.
* @return GETDNS_RETURN_GOOD on success or an error code on failure.
* GETDNS_RETURN_NEED_MORE_SPACE will be returned when the buffer was too
* small. The function will pretend that it had written beyond the end
* of the buffer, and str will point past the buffer and str_len will
* contain a negative value.
*/
getdns_return_t
getdns_rr_dict2str_scan(
const getdns_dict *rr_dict, char **str, int *str_len);
/**
* Convert the string representation of the resource record to rr_dict format.
*
* @param str String representation of the resource record.
* @param rr_dict The result getdns dict representation of the resource record
* @param origin Default suffix for not fully qualified domain names
* @param default_ttl Default ttl
* @return GETDNS_RETURN_GOOD on success or an error code on failure.
*/
getdns_return_t
getdns_str2rr_dict(
const char *str, getdns_dict **rr_dict,
const char *origin, uint32_t default_ttl);
/**
* Read the zonefile and convert to a list of rr_dict's.
*
* @param in An opened FILE pointer on the zone file.
* @param rr_list The result list of rr_dicts representing the zone file.
* @param origin Default suffix for not fully qualified domain names
* @param default_ttl Default ttl
* @return GETDNS_RETURN_GOOD on success or an error code on failure.
*/
getdns_return_t
getdns_fp2rr_list(
FILE *in, getdns_list **rr_list,
const char *origin, uint32_t default_ttl);
/**
* Convert DNS message dict to wireformat representation.
*
* @param msg_dict The getdns dict representation of a DNS message
* @param wire A newly allocated buffer which will contain the wireformat.
* @param wire_sz The size of the allocated buffer and the wireformat.
* @return GETDNS_RETURN_GOOD on success or an error code on failure.
*/
getdns_return_t
getdns_msg_dict2wire(
const getdns_dict *msg_dict, uint8_t **wire, size_t *wire_sz);
/**
* Convert DNS message dict to wireformat representation.
*
* @param msg_dict The getdns dict representation of a DNS message
* @param wire The buffer in which the wireformat will be written
* @param wire_sz On input the size of the wire buffer,
* On output the amount of wireformat needed for the
* wireformat representation of the DNS message;
* even if it did not fit.
* @return GETDNS_RETURN_GOOD on success or an error code on failure.
* GETDNS_RETURN_NEED_MORE_SPACE will be returned when the buffer was too
* small. wire_sz will be set to the needed buffer space then.
*/
getdns_return_t
getdns_msg_dict2wire_buf(
const getdns_dict *msg_dict, uint8_t *wire, size_t *wire_sz);
/**
* Convert DNS message dict to wireformat representation.
*
* @param msg_dict The getdns dict representation of the DNS message
* @param wire A pointer to the buffer pointer in which the wireformat
* will be written.
* On output the buffer pointer will have moved along
* the buffer and point right after the just written RR.
* @param wire_sz On input the size of the wire buffer,
* On output the amount of wireformat needed for the
* wireformat will have been substracted from wire_sz.
* @return GETDNS_RETURN_GOOD on success or an error code on failure.
* GETDNS_RETURN_NEED_MORE_SPACE will be returned when the buffer was too
* small. The function will pretend that it had written beyond the end
* of the buffer, and wire will point past the buffer and wire_sz will
* contain a negative value.
*/
getdns_return_t
getdns_msg_dict2wire_scan(
const getdns_dict *msg_dict, uint8_t **wire, int *wire_sz);
/**
* Convert wireformat DNS message in a getdns msg_dict representation.
*
* @param wire Buffer containing the wireformat rr
* @param wire_sz Size of the wire buffer
* @param msg_dict The returned DNS message
* @return GETDNS_RETURN_GOOD on success or an error code on failure.
*/
getdns_return_t
getdns_wire2msg_dict(
const uint8_t *wire, size_t wire_sz, getdns_dict **msg_dict);
/**
* Convert wireformat DNS message in a getdns msg_dict representation.
*
* @param wire Buffer containing the wireformat rr
* @param wire_sz On input the size of the wire buffer
* On output the length of the wireformat rr.
* @param msg_dict The returned DNS message
* @return GETDNS_RETURN_GOOD on success or an error code on failure.
*/
getdns_return_t
getdns_wire2msg_dict_buf(
const uint8_t *wire, size_t *wire_sz, getdns_dict **msg_dict);
/**
* Convert wireformat DNS message in a getdns msg_dic representation.
*
* @param wire A pointer to the pointer of the wireformat buffer.
* On return this pointer is moved to after first read
* in resource record.
* @param wire_sz On input the size of the wire buffer
* On output the size is decreased with the length
* of the wireformat DNS message.
* @param msg_dict The returned DNS message
* @return GETDNS_RETURN_GOOD on success or an error code on failure.
*/
getdns_return_t
getdns_wire2msg_dict_scan(
const uint8_t **wire, size_t *wire_sz, getdns_dict **msg_dict);
/**
* Convert msg_dict to the string representation of the DNS message.
*
* @param msg_dict The getdns dict representation of the DNS message
* @param str A newly allocated string representation of the rr
* @return GETDNS_RETURN_GOOD on success or an error code on failure.
*/
getdns_return_t
getdns_msg_dict2str(
const getdns_dict *msg_dict, char **str);
/**
* Convert msg_dict to the string representation of the DNS message.
*
* @param msg_dict The getdns dict representation of the resource record
* @param str The buffer in which the string will be written
* @param str_len On input the size of the text buffer,
* On output the amount of characters needed to write
* the string representation of the rr. Even if it does
* not fit.
* @return GETDNS_RETURN_GOOD on success or an error code on failure.
* GETDNS_RETURN_NEED_MORE_SPACE will be returned when the buffer was too
* small. str_len will be set to the needed buffer space then.
*/
getdns_return_t
getdns_msg_dict2str_buf(
const getdns_dict *msg_dict, char *str, size_t *str_len);
/**
* Convert msg_dict to the string representation of the resource record.
*
* @param msg_dict The getdns dict representation of the resource record
* @param str A pointer to the buffer pointer in which the string
* will be written.
* On output the buffer pointer will have moved along
* the buffer and point right after the just written RR.
* @param str_len On input the size of the str buffer,
* On output the number of characters needed for the
* string will have been substracted from strlen.
* @return GETDNS_RETURN_GOOD on success or an error code on failure.
* GETDNS_RETURN_NEED_MORE_SPACE will be returned when the buffer was too
* small. The function will pretend that it had written beyond the end
* of the buffer, and str will point past the buffer and str_len will
* contain a negative value.
*/
getdns_return_t
getdns_msg_dict2str_scan(
const getdns_dict *msg_dict, char **str, int *str_len);
/** @}
*/
/**
* \defgroup Ustring2getdns_data Converting strings to getdns data structures
* @{
*/
/**
* Convert string text to a getdns_dict.
*
* @param str A textual representation of a getdns_dict.
* The format is similar, but not precisely JSON.
* - dict keys may be given without quotes.
* For example: `{ timeout: 2000 }` is the same as { "timeout": 2000 }
* - When str contains an IP or IPv6 address, it is converted
* to an getdns dict representation of that address. This may contain
* a port, tls_port, tsig spec or tls authentication name in the same
* way as may be given with the `getdns_query` tool. For example:
* `185.49.140.67:80#443` will result in the following getdns_dict:
*
* { address_type: "IPv4"
* , address_data: "185.49.140.67"
* , port: 80
* , tls_port: 443
* }
*
* @param dict The returned getdns_dict.
* @return GETDNS_RETURN_GOOD on success or an error code on failure.
*/
getdns_return_t
getdns_str2dict(const char *str, getdns_dict **dict);
/**
* Convert string text to a getdns_list.
*
* @param str A textual representation of a getdns_list.
* The format is similar, but not precisely JSON.
* @param list The returned getdns_list.
* @return GETDNS_RETURN_GOOD on success or an error code on failure.
*/
getdns_return_t
getdns_str2list(const char *str, getdns_list **list);
/**
* Convert string text to a getdns_bindata.
*
* @param str A textual representation of a getdns_bindata
* The format is similar, but not precisely JSON.
* - Strings between double-quotes will be converted to bindata
* containers, but *without the trailing null byte*.
* For example: `{ suffix: [ "nlnetlabs.nl.", "nlnet.nl." ] }`
* - bindata representation of IP or IPv6 addresses may be
* given in their presentation format. For example:
* `{ dns_root_servers: [ 2001:7fd::1, 193.0.14.129 ] }`
* - Arbitrary binary data may be given with a `0x` prefix,
* or in base64 encoding.
* For example:
*
* { add_opt_parameters:
* { options: [ { option_code: 10
* , option_data: 0xA9E4EC50C03F5D65
* } ]
* }
* }
*
* - Wireformat domain name bindatas can be given with a trailing dot.
* For example:
*
* { upstream_recursive_servers:
* [ { address_data : 2a04:b900:0:100::37
* , tsig_name : hmac-md5.tsigs.getdnsapi.net.
* , tsig_algorithm: hmac-md5.sig-alg.reg.int.
* , tsig_secret : 16G69OTeXW6xSQ==
* } ]
* }
*
* @param bindata The returned getdns_bindata.
* @return GETDNS_RETURN_GOOD on success or an error code on failure.
*/
getdns_return_t
getdns_str2bindata(const char *str, getdns_bindata **bindata);
/**
* Convert string text to a getdns 32 bits unsigned integer.
*
* @param str A textual representation of the integer.
* The format is similar, but not precisely JSON.
* - integer values may be given by the constant name.
* For example: `{ resolution_type: GETDNS_RESOLUTION_STUB }`
* or `{ specify_class: GETDNS_RRCLASS_CH }`
* @param value The returned integer.
* @return GETDNS_RETURN_GOOD on success or an error code on failure.
*/
getdns_return_t
getdns_str2int(const char *str, uint32_t *value);
/** @}
*/
/**
* \defgroup UServerFunctions Creating simple DNS servers
* @{
*/
/**
* The user defined request handler that will be called on incoming requests.
*/
typedef void (*getdns_request_handler_t)(
getdns_context *context,
getdns_callback_type_t callback_type,
getdns_dict *request,
void *userarg,
getdns_transaction_t request_id
);
/**
* Create a name server by registering a list of addresses to listen on and
* a user defined function that will handle the requests.
*
* @param context The context managing the eventloop that needs to be run to
* start serving.
* @param listen_addresses A list of address dicts or bindatas that will be
* listened on for DNS requests. Both UDP and TCP
* transports will be used.
* @param userarg A user defined argument that will be passed to the handler
* untouched.
* @param handler The user defined request handler that will be called with the
* request received in reply dict format. To reply to this request
* the function has to construct a response (or modify the request)
* and call getdns_reply() with the response and the with the request
* associated request_id. The user is responsible of destroying
* both the replies and the response. **Beware** that if requests are
* not answered by the function, by not calling getdns_reply() this
* will cause a memory leak. The user most use getdns_reply()
* with NULL as the response to not answer/cancel a request.
* @return GETDNS_RETURN_GOOD on success or an error code on failure.
* On failure, the current set of listening addresses is left in place.
* Also, if there is overlap in listening_addresses between the active set
* and the newly given set, the ones in the active set will remain in their
* current condition and will not be closed and reopened, also all assoicated
* DNS transactions will remain.
*/
getdns_return_t
getdns_context_set_listen_addresses(
getdns_context *context, const getdns_list *listen_addresses,
void *userarg, getdns_request_handler_t handler);
/**
* Answer the request associated with a request_id that is received by a
* request handler
*
* @param context The context managing the eventloop that needs to be run to
* listen for and answer requests.
* @param reply The answer in getdns reply dict or response dict format.
* When NULL is given as reply, the request is not answered
* but all associated state is deleted.
* @param request_id The identifier that links this response with the
* received request.
* @return GETDNS_RETURN_GOOD on success or an error code on failure.
* On fatal failure (no retry strategy possible) the user still needs to
* cancel the request by recalling getdns_reply() but with NULL as response,
* to clean up state.
*/
getdns_return_t
getdns_reply(getdns_context *context,
getdns_dict *reply, getdns_transaction_t request_id);
/** @}
*/
/**
* \defgroup Uutilityfunctionsdeprecated Deptricated utility functions
* @{
*/
/**
* WARNING! Function getdns_strerror is not in the API specification and
* is likely to be removed from future versions of our implementation, to be
* replaced by getdns_get_errorstr_by_id or something similar.
* Please use getdns_get_errorstr_by_id instead of getdns_strerror.
*/
getdns_return_t getdns_strerror(getdns_return_t err, char *buf, size_t buflen);
/**
* Runs the event loop once non blocking.
* WARNING! Do not use this function. This function will be removed in
* future versions of getdns.
*/
getdns_return_t getdns_context_process_async(getdns_context* context);
/**
* Return the number of pending requests and the point of time of the next
* timeout.
* WARNING! Do not use this function. This function will be removed in
* future versions of getdns.
*/
uint32_t getdns_context_get_num_pending_requests(getdns_context* context,
struct timeval* next_timeout);
/**
* Detach the eventloop from the context. Resets the context with the default
* event loop based on poll(). WARNING! Do not use this function. It is For
* internal use only and may disappear in future releases.
* @param context The context to reset to default event loop usage
* @return GETDNS_RETURN_GOOD when successful
* @return GETDNS_RETURN_INVALID_PARAMETER when context is NULL
*/
getdns_return_t
getdns_context_detach_eventloop(getdns_context *context);
/**
* Tell underlying unbound context to use background threads or fork.
* This is only relevant for libunbound version before 1.5.9. After this
* version the underlying unbound will share the event loop with getdns
* eliminating the use for threads. Since the need for this function is
* doubtful and likely to disappear in the future, use is strongly
* discouraged.
* @param context The context to configure
* @param use_threads is either 1 to use threads, or 0 to use fork
* @return GETDNS_RETURN_GOOD on success
* @return GETDNS_RETURN_INVALID_PARAMETER if context is NULL
*/
getdns_return_t getdns_context_set_use_threads(getdns_context* context,
int use_threads);
/** @}
*/
/** @}
*/
#ifdef __cplusplus
}
#endif
#endif
|