mirror of https://github.com/getdnsapi/getdns.git
Make just the src/getdns files part of doxygen by default.
Add documentation to cover getdns_extra.h. Re-org of functions to align better with getdns.h Also some work on the README.
This commit is contained in:
Sara Dickinson
parent
8318766593
commit
ec09d6b8a4
82
README.md
82
README.md
|
|
@ -1,17 +1,28 @@
|
|||
getdns API
|
||||
==========
|
||||
getdns
|
||||
======
|
||||
|
||||
# Overview of getdns
|
||||
|
||||
* Date: 2016-03-24
|
||||
* GitHub: <https://github.com/getdnsapi/getdns>
|
||||
|
||||
getdns is an implementation of a modern asynchronous DNS API specification
|
||||
originally edited by Paul Hoffman. It is intended to make all types of DNS
|
||||
information easily available to application developers and non-DNS experts.
|
||||
The project home page at [getdnsapi.net](https://getdnsapi.net) provides
|
||||
documentation, binary downloads and new regarding the getdns API
|
||||
documentation, binary downloads and news regarding the getdns API
|
||||
implementation. This implementation is licensed under the New BSD License
|
||||
(BSD-new).
|
||||
|
||||
This file captures the goals and direction of the project and the current state
|
||||
of the implementation.
|
||||
|
||||
If you are just getting started with the library take a look at the section
|
||||
below that describes building and handling external dependencies for the
|
||||
library. Once it is built you should take a look at src/examples to see how
|
||||
the library is used.
|
||||
|
||||
## Download
|
||||
|
||||
Download the sources from our [github repo](https://github.com/getdnsapi/getdns)
|
||||
or from [getdnsapi.net](https://getdnsapi.net) and verify the download using
|
||||
the checksums (SHA1 or MD5) or using gpg to verify the signature. Our keys are
|
||||
|
|
@ -20,18 +31,23 @@ available from the [pgp keyservers](https://keyserver.pgp.com)
|
|||
* willem@nlnetlabs.nl, key id E5F8F8212F77A498
|
||||
* gwiley@verisign.com, key id 9DC3D572A6B73532
|
||||
|
||||
We have a [users list](https://getdnsapi.net/mailman/listinfo/spec) for this implementation.
|
||||
## Mailing lists
|
||||
|
||||
We have a [getdns users list](https://getdnsapi.net/mailman/listinfo/spec) for this implementation.
|
||||
|
||||
The [getdns-api mailing list](https://getdnsapi.net/mailman/listinfo/spec)
|
||||
is a good place to engage in discussions regarding the design of the API.
|
||||
|
||||
If you are just getting started with the library take a look at the section
|
||||
below that describes building and handling external dependencies for the
|
||||
library. Once it is built you should take a look at src/examples to see how
|
||||
the library is used.
|
||||
## Motivation for providing the API
|
||||
|
||||
This file captures the goals and direction of the project and the current state
|
||||
of the implementation.
|
||||
The developers are of the opinion that DNSSEC offers a unique global
|
||||
infrastructure for establishing and enhancing cryptographic trust relations.
|
||||
With the development of this API we intend to offer application developers a
|
||||
modern and flexible way that enables end-to-end trust in the DNS architecture
|
||||
and will inspire application developers towards innovative security solutions
|
||||
in their applications.
|
||||
|
||||
## Goals
|
||||
|
||||
The goals of this implementation of the getdns API are:
|
||||
|
||||
|
|
@ -47,22 +63,20 @@ The goals of this implementation of the getdns API are:
|
|||
Non-goals (things we will not be doing at least initially) include:
|
||||
* implementation of the traditional DNS related routines (gethostbyname, etc.)
|
||||
|
||||
## Official and Additional API
|
||||
|
||||
Note that this implementation offers additional functionality to supplement that
|
||||
in the official getdns API. Some additions are convenient utility functions but other functionality
|
||||
is experimental prior to be being recommended for inclusion in the official API.
|
||||
The 'Modules' page in the doxygen documentation provides a guide to both the
|
||||
official API and the additional functionality.
|
||||
|
||||
## Language Bindings
|
||||
|
||||
In parallel, the team is actively developing bindings for various languages.
|
||||
For more information, visit the
|
||||
[wiki](https://github.com/getdnsapi/getdns/wiki/Language-Bindings).
|
||||
|
||||
Motivation for providing the API
|
||||
================================
|
||||
|
||||
The developers are of the opinion that DNSSEC offers a unique global
|
||||
infrastructure for establishing and enhancing cryptographic trust relations.
|
||||
With the development of this API we intend to offer application developers a
|
||||
modern and flexible way that enables end-to-end trust in the DNS architecture
|
||||
and will inspire application developers towards innovative security solutions
|
||||
in their applications.
|
||||
|
||||
|
||||
Releases
|
||||
========
|
||||
|
|
@ -102,6 +116,16 @@ with:
|
|||
# libtoolize -ci (use glibtoolize for OS X, libtool is installed as glibtool to avoid name conflict on OS X)
|
||||
# autoreconf -fi
|
||||
|
||||
If you want to make use of the configuration files that utilise a JSON-like format, you must do
|
||||
|
||||
# git submodule update --init
|
||||
|
||||
before building.
|
||||
|
||||
If you want to use the getdns_query command line wrapper script for testing or to enable getdns as a daemon then you must build it using
|
||||
|
||||
# make getdns_query
|
||||
|
||||
## Minimal dependencies
|
||||
|
||||
* getdns can be configured for stub resolution mode only with the `--enable-stub-only` option to configure. This removed the dependency on `libunbound`.
|
||||
|
|
@ -143,7 +167,7 @@ execute the following steps as root:
|
|||
# mkdir -p /etc/unbound
|
||||
# unbound-anchor -a /etc/unbound/getdns-root.key
|
||||
|
||||
#Unsupported Features
|
||||
# Unsupported Features
|
||||
|
||||
The following API calls are documented in getDNS but *not supported* by the implementation at this time:
|
||||
|
||||
|
|
@ -151,7 +175,7 @@ The following API calls are documented in getDNS but *not supported* by the impl
|
|||
* Detecting changes to resolv.conf and hosts
|
||||
* MDNS, NIS and NetBIOS namespaces (only DNS and LOCALFILES are supported)
|
||||
|
||||
#Known Issues
|
||||
# Known Issues
|
||||
|
||||
There are a few known issues which we have summarized below - the most recent
|
||||
and helpful list is being maintained in the git issues list in the repository.
|
||||
|
|
@ -160,7 +184,7 @@ Other known issues are being managed in the git repository issue list.
|
|||
* When doing a synchronous lookup with a context that has outstanding asynchronous lookups, the callbacks for the asynchronous lookups might get called as a side effect of the synchronous lookup.
|
||||
|
||||
|
||||
#Supported Platforms
|
||||
# Supported Platforms
|
||||
|
||||
The primary platforms targeted are Linux and FreeBSD, other platform are supported as we get time. The names listed here are intended to help ensure that we catch platform specific breakage, not to limit the work that folks are doing.
|
||||
|
||||
|
|
@ -172,17 +196,17 @@ The primary platforms targeted are Linux and FreeBSD, other platform are support
|
|||
We intend to add Android and other platforms to the releases as we have time to port it.
|
||||
|
||||
|
||||
##Platform Specific Build Reports
|
||||
## Platform Specific Build Reports
|
||||
|
||||
[](https://travis-ci.org/getdnsapi/getdns)
|
||||
|
||||
###FreeBSD
|
||||
### FreeBSD
|
||||
|
||||
If you're using [FreeBSD](https://www.freebsd.org/), you may install getdns via the [ports tree](https://www.freshports.org/dns/getdns/) by running: `cd /usr/ports/dns/getdns && make install clean`
|
||||
|
||||
If you are using FreeBSD 10 getdns can be intalled via 'pkg install getdns'.
|
||||
|
||||
###CentOS/RHEL 6.5
|
||||
### CentOS/RHEL 6.5
|
||||
|
||||
We rely on the most excellent package manager fpm to build the linux packages which
|
||||
means that the packaging platform requires ruby 2.1.0. There are other ways to
|
||||
|
|
@ -200,7 +224,7 @@ build the packages, this is simplythe one we chose to use.
|
|||
# . /usr/local/rvm/config/alias
|
||||
# fpm -x "*.la" -a native -s dir -t rpm -n getdns -v 0.2.0rc1 -d "unbound" -d "libevent" -d "libidn" --prefix /usr --vendor "Verisign Inc., NLnet Labs" --license "BSD New" --url "https://getdnsapi.net" --description "Modern asynchronous API to the DNS" .
|
||||
|
||||
###OSX
|
||||
### OSX
|
||||
|
||||
# sw_vers
|
||||
ProductName: Mac OS X
|
||||
|
|
@ -277,7 +301,6 @@ To configure:
|
|||
./getdns_query.exe -s gmadkat.com A -l L @185.49.141.37 +return_call_reporting (TLS without authentication)
|
||||
./getdns_query.exe -s www.huque.com A +dnssec_return_status +return_call_reporting (DNSSEC)
|
||||
|
||||
|
||||
Contributors
|
||||
============
|
||||
* Theogene Bucuti
|
||||
|
|
@ -313,6 +336,7 @@ Contributors
|
|||
* Glen Wiley, Verisign, Inc.
|
||||
* Paul Wouters
|
||||
|
||||
|
||||
Acknowledgements
|
||||
================
|
||||
The development team explicitly acknowledges Paul Hoffman for his initiative and efforts to develop a consensus based DNS API. We would like to thank the participants of the [mailing list](https://getdnsapi.net/mailman/listinfo/spec) for their contributions.
|
||||
|
|
|
|||
|
|
@ -50,7 +50,7 @@ DOXYFILE_ENCODING = UTF-8
|
|||
# identify the project. Note that if you do not use Doxywizard you need
|
||||
# to put quotes around the project name if it contains spaces.
|
||||
|
||||
PROJECT_NAME = "getdns API"
|
||||
PROJECT_NAME = "getdns"
|
||||
|
||||
# The PROJECT_NUMBER tag can be used to enter a project or revision number.
|
||||
# This could be handy for archiving the generated documentation or
|
||||
|
|
@ -62,7 +62,7 @@ PROJECT_NUMBER = @PACKAGE_VERSION@
|
|||
# for a project that appears at the top of each page and should give viewer
|
||||
# a quick idea about the purpose of the project. Keep the description short.
|
||||
|
||||
PROJECT_BRIEF = "A modern asynchronous API for fetching DNS data"
|
||||
PROJECT_BRIEF = "An implementation of the getdns API - a modern asynchronous API for fetching DNS data"
|
||||
|
||||
# With the PROJECT_LOGO tag one can specify an logo or icon that is
|
||||
# included in the documentation. The maximum height of the logo should not
|
||||
|
|
@ -692,12 +692,15 @@ WARN_LOGFILE =
|
|||
# directories like "/usr/src/myproject". Separate the files or directories
|
||||
# with spaces.
|
||||
|
||||
INPUT = @srcdir@ \
|
||||
getdns/ \
|
||||
@srcdir@/getdns/ \
|
||||
@srcdir@/example/ \
|
||||
@srcdir@/test/ \
|
||||
INPUT = @srcdir@/getdns/ \
|
||||
getdns/getdns.h \
|
||||
getdns/getdns_extra.h \
|
||||
@srcdir@/../README.md
|
||||
# @srcdir@/../spec/example/ \
|
||||
# getdns/ \
|
||||
# @srcdir@ \
|
||||
# @srcdir@/test/ \
|
||||
|
||||
|
||||
# This tag can be used to specify the character encoding of the source files
|
||||
# that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is
|
||||
|
|
@ -820,7 +823,7 @@ FILTER_SOURCE_PATTERNS =
|
|||
# This can be useful if you have a project on for instance GitHub and want reuse
|
||||
# the introduction page also for the doxygen output.
|
||||
|
||||
USE_MDFILE_AS_MAINPAGE = ../README.md
|
||||
USE_MDFILE_AS_MAINPAGE = @srcdir@/../README.md
|
||||
|
||||
#---------------------------------------------------------------------------
|
||||
# configuration options related to source browsing
|
||||
|
|
|
|||
|
|
@ -665,7 +665,7 @@ getdns_return_t
|
|||
getdns_general(getdns_context *context,
|
||||
const char *name, uint16_t request_type, getdns_dict *extensions,
|
||||
void *userarg, getdns_transaction_t * transaction_id,
|
||||
getdns_callback_t callback)
|
||||
getdns_callback_t callbackfn)
|
||||
{
|
||||
getdns_return_t r;
|
||||
getdns_network_req *netreq = NULL;
|
||||
|
|
@ -673,7 +673,7 @@ getdns_general(getdns_context *context,
|
|||
if (!context) return GETDNS_RETURN_INVALID_PARAMETER;
|
||||
r = _getdns_general_loop(context, context->extension,
|
||||
name, request_type, extensions,
|
||||
userarg, &netreq, callback, NULL);
|
||||
userarg, &netreq, callbackfn, NULL);
|
||||
if (netreq && transaction_id)
|
||||
*transaction_id = netreq->owner->trans_id;
|
||||
return r;
|
||||
|
|
@ -686,12 +686,12 @@ getdns_general(getdns_context *context,
|
|||
getdns_return_t
|
||||
getdns_address(getdns_context *context,
|
||||
const char *name, getdns_dict *extensions, void *userarg,
|
||||
getdns_transaction_t *transaction_id, getdns_callback_t callback)
|
||||
getdns_transaction_t *transaction_id, getdns_callback_t callbackfn)
|
||||
{
|
||||
if (!context) return GETDNS_RETURN_INVALID_PARAMETER;
|
||||
return _getdns_address_loop(context, context->extension,
|
||||
name, extensions, userarg,
|
||||
transaction_id, callback);
|
||||
transaction_id, callbackfn);
|
||||
} /* getdns_address */
|
||||
|
||||
/*
|
||||
|
|
@ -701,11 +701,11 @@ getdns_address(getdns_context *context,
|
|||
getdns_return_t
|
||||
getdns_hostname(getdns_context *context,
|
||||
getdns_dict *address, getdns_dict *extensions, void *userarg,
|
||||
getdns_transaction_t *transaction_id, getdns_callback_t callback)
|
||||
getdns_transaction_t *transaction_id, getdns_callback_t callbackfn)
|
||||
{
|
||||
if (!context) return GETDNS_RETURN_INVALID_PARAMETER;
|
||||
return _getdns_hostname_loop(context, context->extension,
|
||||
address, extensions, userarg, transaction_id, callback);
|
||||
address, extensions, userarg, transaction_id, callbackfn);
|
||||
} /* getdns_hostname */
|
||||
|
||||
/*
|
||||
|
|
@ -715,11 +715,11 @@ getdns_hostname(getdns_context *context,
|
|||
getdns_return_t
|
||||
getdns_service(getdns_context *context,
|
||||
const char *name, getdns_dict *extensions, void *userarg,
|
||||
getdns_transaction_t *transaction_id, getdns_callback_t callback)
|
||||
getdns_transaction_t *transaction_id, getdns_callback_t callbackfn)
|
||||
{
|
||||
if (!context) return GETDNS_RETURN_INVALID_PARAMETER;
|
||||
return _getdns_service_loop(context, context->extension,
|
||||
name, extensions, userarg, transaction_id, callback);
|
||||
name, extensions, userarg, transaction_id, callbackfn);
|
||||
} /* getdns_service */
|
||||
|
||||
/* getdns_general.c */
|
||||
|
|
|
|||
|
|
@ -47,8 +47,17 @@ extern "C" {
|
|||
|
||||
#define GETDNS_COMPILATION_COMMENT "@GETDNS_COMPILATION_COMMENT@"
|
||||
|
||||
/** \defgroup getdnsAPI Official getdns API
|
||||
* @{
|
||||
*/
|
||||
|
||||
|
||||
/** \defgroup valuesandtexts Values and texts
|
||||
* @{
|
||||
*/
|
||||
|
||||
/**
|
||||
* \defgroup returntypes Return values
|
||||
* \defgroup returntypestext Return values and texts
|
||||
* @{
|
||||
*/
|
||||
typedef enum getdns_return_t {
|
||||
|
|
@ -68,13 +77,8 @@ typedef enum getdns_return_t {
|
|||
GETDNS_RETURN_INVALID_PARAMETER = 311,
|
||||
GETDNS_RETURN_NOT_IMPLEMENTED = 312
|
||||
} getdns_return_t;
|
||||
/** @}
|
||||
*/
|
||||
|
||||
/**
|
||||
* \defgroup returntypestext Return values texts
|
||||
* @{
|
||||
*/
|
||||
|
||||
#define GETDNS_RETURN_GOOD_TEXT "Good"
|
||||
#define GETDNS_RETURN_GENERIC_ERROR_TEXT "Generic error"
|
||||
#define GETDNS_RETURN_BAD_DOMAIN_NAME_TEXT "Badly-formed domain name in first argument"
|
||||
|
|
@ -113,7 +117,7 @@ typedef enum getdns_return_t {
|
|||
|
||||
|
||||
/**
|
||||
* \defgroup namespacetypes Namespace types
|
||||
* \defgroup namespacetypestext Namespace types and texts
|
||||
* @{
|
||||
*/
|
||||
typedef enum getdns_namespace_t {
|
||||
|
|
@ -123,13 +127,8 @@ typedef enum getdns_namespace_t {
|
|||
GETDNS_NAMESPACE_MDNS = 503,
|
||||
GETDNS_NAMESPACE_NIS = 504
|
||||
} getdns_namespace_t;
|
||||
/** @}
|
||||
*/
|
||||
|
||||
/**
|
||||
* \defgroup namespacetypestext Namespace types texts
|
||||
* @{
|
||||
*/
|
||||
|
||||
#define GETDNS_NAMESPACE_DNS_TEXT "See getdns_context_set_namespaces()"
|
||||
#define GETDNS_NAMESPACE_LOCALNAMES_TEXT "See getdns_context_set_namespaces()"
|
||||
#define GETDNS_NAMESPACE_NETBIOS_TEXT "See getdns_context_set_namespaces()"
|
||||
|
|
@ -140,20 +139,15 @@ typedef enum getdns_namespace_t {
|
|||
|
||||
|
||||
/**
|
||||
* \defgroup resolutiontypes Resolution types
|
||||
* \defgroup resolutiontypestext Resolution types and texts
|
||||
* @{
|
||||
*/
|
||||
typedef enum getdns_resolution_t {
|
||||
GETDNS_RESOLUTION_STUB = 520,
|
||||
GETDNS_RESOLUTION_RECURSING = 521
|
||||
} getdns_resolution_t;
|
||||
/** @}
|
||||
*/
|
||||
|
||||
/**
|
||||
* \defgroup resolutiontypestext Resolution types texts
|
||||
* @{
|
||||
*/
|
||||
|
||||
#define GETDNS_RESOLUTION_STUB_TEXT "See getdns_context_set_resolution_type()"
|
||||
#define GETDNS_RESOLUTION_RECURSING_TEXT "See getdns_context_set_resolution_type()"
|
||||
/** @}
|
||||
|
|
@ -161,20 +155,15 @@ typedef enum getdns_resolution_t {
|
|||
|
||||
|
||||
/**
|
||||
* \defgroup redirectpolicytype Redirect policies
|
||||
* \defgroup redirectpoliciestext Redirect policies and texts
|
||||
* @{
|
||||
*/
|
||||
typedef enum getdns_redirects_t {
|
||||
GETDNS_REDIRECTS_FOLLOW = 530,
|
||||
GETDNS_REDIRECTS_DO_NOT_FOLLOW = 531
|
||||
} getdns_redirects_t;
|
||||
/** @}
|
||||
*/
|
||||
|
||||
/**
|
||||
* \defgroup redirectpoliciestext Redirect policies texts
|
||||
* @{
|
||||
*/
|
||||
|
||||
#define GETDNS_REDIRECTS_FOLLOW_TEXT "See getdns_context_set_follow_redirects()"
|
||||
#define GETDNS_REDIRECTS_DO_NOT_FOLLOW_TEXT "See getdns_context_set_follow_redirects()"
|
||||
/** @}
|
||||
|
|
@ -182,7 +171,7 @@ typedef enum getdns_redirects_t {
|
|||
|
||||
|
||||
/**
|
||||
* \defgroup transporttypes Transport arrangements
|
||||
* \defgroup transporttypestext Transport arrangements and texts
|
||||
* @{
|
||||
*/
|
||||
typedef enum getdns_transport_t {
|
||||
|
|
@ -191,13 +180,7 @@ typedef enum getdns_transport_t {
|
|||
GETDNS_TRANSPORT_TCP_ONLY = 542,
|
||||
GETDNS_TRANSPORT_TCP_ONLY_KEEP_CONNECTIONS_OPEN = 543
|
||||
} getdns_transport_t;
|
||||
/** @}
|
||||
*/
|
||||
|
||||
/**
|
||||
* \defgroup transporttypestext Transport arrangements texts
|
||||
* @{
|
||||
*/
|
||||
#define GETDNS_TRANSPORT_UDP_FIRST_AND_FALL_BACK_TO_TCP_TEXT "See getdns_context_set_dns_transport()"
|
||||
#define GETDNS_TRANSPORT_UDP_ONLY_TEXT "See getdns_context_set_dns_transport()"
|
||||
#define GETDNS_TRANSPORT_TCP_ONLY_TEXT "See getdns_context_set_dns_transport()"
|
||||
|
|
@ -207,7 +190,7 @@ typedef enum getdns_transport_t {
|
|||
|
||||
|
||||
/**
|
||||
* \defgroup transportlisttypes Transport list values
|
||||
* \defgroup transportlisttypestext Transport list values and tests
|
||||
* @{
|
||||
*/
|
||||
/* Base transports for use in transport list */
|
||||
|
|
@ -216,13 +199,8 @@ typedef enum getdns_transport_list_t {
|
|||
GETDNS_TRANSPORT_TCP = 1201,
|
||||
GETDNS_TRANSPORT_TLS = 1202,
|
||||
} getdns_transport_list_t;
|
||||
/** @}
|
||||
*/
|
||||
|
||||
/**
|
||||
* \defgroup transportlisttypestext Transport list values texts
|
||||
* @{
|
||||
*/
|
||||
|
||||
#define GETDNS_TRANSPORT_UDP_TEXT "See getdns_context_set_dns_transport_list()"
|
||||
#define GETDNS_TRANSPORT_TCP_TEXT "See getdns_context_set_dns_transport_list()"
|
||||
#define GETDNS_TRANSPORT_TLS_TEXT "See getdns_context_set_dns_transport_list()"
|
||||
|
|
@ -231,7 +209,7 @@ typedef enum getdns_transport_list_t {
|
|||
|
||||
|
||||
/**
|
||||
* \defgroup suffixappendtypes Suffix appending values
|
||||
* \defgroup suffixappendtypestext Suffix appending values and texts
|
||||
* @{
|
||||
*/
|
||||
typedef enum getdns_append_name_t {
|
||||
|
|
@ -240,13 +218,8 @@ typedef enum getdns_append_name_t {
|
|||
GETDNS_APPEND_NAME_ONLY_TO_MULTIPLE_LABEL_NAME_AFTER_FAILURE = 552,
|
||||
GETDNS_APPEND_NAME_NEVER = 553
|
||||
} getdns_append_name_t;
|
||||
/** @}
|
||||
*/
|
||||
|
||||
/**
|
||||
* \defgroup suffixappendtypestext Suffix appending values texts
|
||||
* @{
|
||||
*/
|
||||
|
||||
#define GETDNS_APPEND_NAME_ALWAYS_TEXT "See getdns_context_set_append_name()"
|
||||
#define GETDNS_APPEND_NAME_ONLY_TO_SINGLE_LABEL_AFTER_FAILURE_TEXT "See getdns_context_set_append_name()"
|
||||
#define GETDNS_APPEND_NAME_ONLY_TO_MULTIPLE_LABEL_NAME_AFTER_FAILURE_TEXT "See getdns_context_set_append_name()"
|
||||
|
|
@ -256,7 +229,7 @@ typedef enum getdns_append_name_t {
|
|||
|
||||
|
||||
/**
|
||||
* \defgroup contextcodetypes Context code values
|
||||
* \defgroup contextcodetypestext Context code values and texts
|
||||
* @{
|
||||
*/
|
||||
/* Context codes */
|
||||
|
|
@ -280,13 +253,8 @@ typedef enum getdns_context_code_t {
|
|||
GETDNS_CONTEXT_CODE_TIMEOUT = 616,
|
||||
GETDNS_CONTEXT_CODE_IDLE_TIMEOUT = 617
|
||||
} getdns_context_code_t;
|
||||
/** @}
|
||||
*/
|
||||
|
||||
/**
|
||||
* \defgroup contextcodetypestext Context code values texts
|
||||
* @{
|
||||
*/
|
||||
|
||||
#define GETDNS_CONTEXT_CODE_NAMESPACES_TEXT "Change related to getdns_context_set_namespaces"
|
||||
#define GETDNS_CONTEXT_CODE_RESOLUTION_TYPE_TEXT "Change related to getdns_context_set_resolution_type"
|
||||
#define GETDNS_CONTEXT_CODE_FOLLOW_REDIRECTS_TEXT "Change related to getdns_context_set_follow_redirects"
|
||||
|
|
@ -310,7 +278,7 @@ typedef enum getdns_context_code_t {
|
|||
|
||||
|
||||
/**
|
||||
* \defgroup callbacktype Callback types
|
||||
* \defgroup callbacktype Callback types and texts
|
||||
* @{
|
||||
*/
|
||||
typedef enum getdns_callback_type_t {
|
||||
|
|
@ -319,13 +287,7 @@ typedef enum getdns_callback_type_t {
|
|||
GETDNS_CALLBACK_TIMEOUT = 702,
|
||||
GETDNS_CALLBACK_ERROR = 703
|
||||
} getdns_callback_type_t;
|
||||
/** @}
|
||||
*/
|
||||
|
||||
/**
|
||||
* \defgroup callbacktypetext Callback types texts
|
||||
* @{
|
||||
*/
|
||||
#define GETDNS_CALLBACK_COMPLETE_TEXT "The response has the requested data in it"
|
||||
#define GETDNS_CALLBACK_CANCEL_TEXT "The calling program cancelled the callback; response is NULL"
|
||||
#define GETDNS_CALLBACK_TIMEOUT_TEXT "The requested action timed out; response is filled in with empty structures"
|
||||
|
|
@ -347,7 +309,7 @@ typedef enum getdns_callback_type_t {
|
|||
|
||||
|
||||
/**
|
||||
* \defgroup respstatus Status Codes for responses and text
|
||||
* \defgroup respstatus Status Codes for responses and texts
|
||||
* @{
|
||||
*/
|
||||
#define GETDNS_RESPSTATUS_GOOD 900
|
||||
|
|
@ -364,7 +326,7 @@ typedef enum getdns_callback_type_t {
|
|||
*/
|
||||
|
||||
/**
|
||||
* \defgroup extvals Values associated with extensions
|
||||
* \defgroup extvals Values associated with extensions and texts
|
||||
* @{
|
||||
*/
|
||||
#define GETDNS_EXTENSION_TRUE 1000
|
||||
|
|
@ -375,7 +337,7 @@ typedef enum getdns_callback_type_t {
|
|||
*/
|
||||
|
||||
/**
|
||||
* \defgroup dnserrors Values associated with DNS errors found by the API and text
|
||||
* \defgroup dnserrors Values associated with DNS errors found by the API and texts
|
||||
* @{
|
||||
*/
|
||||
#define GETDNS_BAD_DNS_CNAME_IN_TARGET 1100
|
||||
|
|
@ -556,7 +518,13 @@ typedef struct getdns_dict getdns_dict;
|
|||
* Indexes are 0 based.
|
||||
*/
|
||||
typedef struct getdns_list getdns_list;
|
||||
/** @}
|
||||
*/
|
||||
|
||||
|
||||
/** \defgroup functions Functions
|
||||
* @{
|
||||
*/
|
||||
/* Specify the order of the following groups manually here so they appear in
|
||||
a better order in doxygen */
|
||||
|
||||
|
|
@ -569,15 +537,16 @@ typedef struct getdns_list getdns_list;
|
|||
* \defgroup getdns_dict_get_functions getdns_dict_get functions
|
||||
* \defgroup context_create getdns_context creation/destruction functions
|
||||
* \defgroup context_set getdns_context_set functions
|
||||
* \defgroup callbacks getdns_callback functions
|
||||
* \defgroup callbackfns getdns_callback functions
|
||||
* \defgroup eventloops getdns event loop extension functions
|
||||
* \defgroup funcs Asynchronous API functions
|
||||
* \defgroup syncfuns Synchronous API functions that do not use callbacks
|
||||
* \defgroup syncfuncs Synchronous API functions that do not use callbacks
|
||||
* \defgroup utils Utility functions
|
||||
*/
|
||||
|
||||
|
||||
/**
|
||||
* \ingroup getdns_list_get_functions getdns_list_get functions
|
||||
* \addtogroup getdns_list_get_functions getdns_list_get functions
|
||||
* @{
|
||||
*/
|
||||
|
||||
|
|
@ -656,7 +625,7 @@ getdns_return_t getdns_list_get_int(const getdns_list *list, size_t index,
|
|||
|
||||
|
||||
/**
|
||||
* \ingroup getdns_dict_get_functions getdns_dict_get functions
|
||||
* \addtogroup getdns_dict_get_functions getdns_dict_get functions
|
||||
* @{
|
||||
*/
|
||||
|
||||
|
|
@ -730,7 +699,7 @@ getdns_return_t getdns_dict_get_int(const getdns_dict *dict,
|
|||
|
||||
|
||||
/**
|
||||
* \ingroup list_create getdns_list creation/destruction functions
|
||||
* \addtogroup list_create getdns_list creation/destruction functions
|
||||
* @{
|
||||
*/
|
||||
|
||||
|
|
@ -766,7 +735,7 @@ void getdns_list_destroy(getdns_list *list);
|
|||
|
||||
|
||||
/**
|
||||
* \ingroup getdns_list_set getdns_list_set functions
|
||||
* \addtogroup getdns_list_set getdns_list_set functions
|
||||
* @{
|
||||
*/
|
||||
|
||||
|
|
@ -816,7 +785,7 @@ getdns_return_t getdns_list_set_int(getdns_list *list, size_t index,
|
|||
|
||||
|
||||
/**
|
||||
* \ingroup dict_create getdns_dict creation/destruction functions
|
||||
* \addtogroup dict_create getdns_dict creation/destruction functions
|
||||
* @{
|
||||
*/
|
||||
|
||||
|
|
@ -849,7 +818,7 @@ void getdns_dict_destroy(getdns_dict *dict);
|
|||
|
||||
|
||||
/**
|
||||
* \ingroup getdns_dict_set getdns_dict_set functions
|
||||
* \addtogroup getdns_dict_set getdns_dict_set functions
|
||||
* @{
|
||||
*/
|
||||
|
||||
|
|
@ -889,6 +858,7 @@ getdns_return_t getdns_dict_set_int(getdns_dict *dict, const char *name,
|
|||
|
||||
|
||||
/**
|
||||
* \addtogroup utils
|
||||
* remove the value associated with the specified name
|
||||
* @param dict dictionary from which to fetch the integer
|
||||
* @param name a name/key value to look up in the dictionary
|
||||
|
|
@ -899,21 +869,16 @@ getdns_return_t getdns_dict_remove_name(getdns_dict *dict, const char *name);
|
|||
|
||||
|
||||
/**
|
||||
* \ingroup callbacks getdns_callback functions
|
||||
* @{
|
||||
* \addtogroup callbackfns getdns_callback functions
|
||||
*/
|
||||
|
||||
/* Callback arguments */
|
||||
typedef void (*getdns_callback_t) (getdns_context *context,
|
||||
getdns_callback_type_t callback_type,
|
||||
getdns_dict * response,
|
||||
void *userarg, getdns_transaction_t transaction_id);
|
||||
/** @}
|
||||
*/
|
||||
|
||||
|
||||
/**
|
||||
* \ingroup funcs Asynchronous API functions
|
||||
* \addtogroup funcs Asynchronous API functions
|
||||
* @{
|
||||
*/
|
||||
|
||||
|
|
@ -940,7 +905,6 @@ getdns_general(getdns_context *context,
|
|||
* retrieve address assigned to a DNS name
|
||||
* @param context pointer to a previously created context to be used for this call
|
||||
* @param name the ASCII based domain name to lookup
|
||||
* @param request_type RR type for the query, e.g. GETDNS_RR_TYPE_NS
|
||||
* @param extensions dict data structures, NULL to use no extensions
|
||||
* @param userarg void* returned to the callback untouched
|
||||
* @param[out] transaction_id id used to identify the callback, NULL is ignored
|
||||
|
|
@ -958,7 +922,6 @@ getdns_address(getdns_context *context,
|
|||
* retrieve hostname assigned to an IP address
|
||||
* @param context pointer to a previously created context to be used for this call
|
||||
* @param address the address to look up
|
||||
* @param request_type RR type for the query, e.g. GETDNS_RR_TYPE_NS
|
||||
* @param extensions dict data structures, NULL to use no extensions
|
||||
* @param userarg void* returned to the callback untouched
|
||||
* @param[out] transaction_id id used to identify the callback, NULL is ignored
|
||||
|
|
@ -976,7 +939,6 @@ getdns_hostname(getdns_context *context,
|
|||
* retrieve a service assigned to a DNS name
|
||||
* @param context pointer to a previously created context to be used for this call
|
||||
* @param name the ASCII based domain name to lookup
|
||||
* @param request_type RR type for the query, e.g. GETDNS_RR_TYPE_NS
|
||||
* @param extensions dict data structures, NULL to use no extensions
|
||||
* @param userarg void* returned to the callback untouched
|
||||
* @param[out] transaction_id id used to identify the callback, NULL is ignored
|
||||
|
|
@ -994,7 +956,7 @@ getdns_service(getdns_context *context,
|
|||
|
||||
|
||||
/**
|
||||
* \ingroup context_create getdns_context creation/destruction functions
|
||||
* \addtogroup context_create getdns_context creation/destruction functions
|
||||
* @{
|
||||
*/
|
||||
|
||||
|
|
@ -1058,9 +1020,9 @@ void getdns_context_destroy(getdns_context *context);
|
|||
|
||||
|
||||
/**
|
||||
* \ingroup callbacks getdns_callback functions
|
||||
* @{
|
||||
*/
|
||||
* \addtogroup callbackfns getdns_callback functions
|
||||
* @{
|
||||
*/
|
||||
getdns_return_t
|
||||
getdns_cancel_callback(getdns_context *context,
|
||||
getdns_transaction_t transaction_id);
|
||||
|
|
@ -1069,12 +1031,13 @@ getdns_cancel_callback(getdns_context *context,
|
|||
|
||||
|
||||
/**
|
||||
* \ingroup syncfuns Synchronous API functions that do not use callbacks
|
||||
* These functions do not use callbacks, when the application calls one of these
|
||||
* \addtogroup syncfuncs Synchronous API functions that do not use callbacks
|
||||
* @{
|
||||
*/
|
||||
/** These functions do not use callbacks, when the application calls one of these
|
||||
* functions the library retrieves all of the data before returning. Return
|
||||
* values are exactly the same as if you had used a callback with the
|
||||
* asynchronous functions.
|
||||
* @{
|
||||
*/
|
||||
|
||||
/**
|
||||
|
|
@ -1139,7 +1102,7 @@ getdns_service_sync(getdns_context *context,
|
|||
*/
|
||||
|
||||
/**
|
||||
* \ingroup utils Utility functions
|
||||
* \addtogroup utils Utility functions
|
||||
* @{
|
||||
*/
|
||||
|
||||
|
|
@ -1181,7 +1144,7 @@ char *getdns_display_ip_address(const getdns_bindata
|
|||
|
||||
|
||||
/**
|
||||
* \ingroup context_set getdns_context_set functions
|
||||
* \addtogroup context_set getdns_context_set functions
|
||||
* @{
|
||||
*/
|
||||
getdns_return_t
|
||||
|
|
@ -1279,6 +1242,12 @@ getdns_context_set_extended_memory_functions(getdns_context *context,
|
|||
getdns_dict*
|
||||
getdns_context_get_api_information(getdns_context* context);
|
||||
|
||||
/** @}
|
||||
*/
|
||||
|
||||
/** @}
|
||||
*/
|
||||
|
||||
#ifdef __cplusplus
|
||||
}
|
||||
#endif
|
||||
|
|
|
|||
|
|
@ -44,6 +44,10 @@ extern "C" {
|
|||
#include <getdns/getdns_extra.h>
|
||||
struct ev_loop;
|
||||
|
||||
|
||||
/**
|
||||
* \ingroup eventloops
|
||||
*/
|
||||
/* For libevent, which we are using for these examples */
|
||||
getdns_return_t
|
||||
getdns_extension_set_libev_loop(struct getdns_context *context,
|
||||
|
|
|
|||
|
|
@ -44,6 +44,9 @@ extern "C" {
|
|||
#include <getdns/getdns_extra.h>
|
||||
struct event_base;
|
||||
|
||||
/**
|
||||
* \ingroup eventloops
|
||||
*/
|
||||
/* For libevent, which we are using for these examples */
|
||||
getdns_return_t
|
||||
getdns_extension_set_libevent_base(struct getdns_context *context,
|
||||
|
|
|
|||
|
|
@ -44,6 +44,9 @@ extern "C" {
|
|||
#include <getdns/getdns_extra.h>
|
||||
struct uv_loop_s;
|
||||
|
||||
/**
|
||||
* \ingroup eventloops
|
||||
*/
|
||||
/* For libevent, which we are using for these examples */
|
||||
getdns_return_t
|
||||
getdns_extension_set_libuv_loop(struct getdns_context *context,
|
||||
|
|
|
|||
|
|
@ -1,3 +1,10 @@
|
|||
/**
|
||||
* \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.
|
||||
|
|
@ -37,34 +44,111 @@
|
|||
extern "C" {
|
||||
#endif
|
||||
|
||||
/* Enable the return_dnssec_status extension on every request.
|
||||
value is either GETDNS_EXTENSION_TRUE or GETDNS_EXTENSION_FALSE
|
||||
returns GETDNS_RETURN_GOOD on success or GETDNS_RETURN_INVALID_PARAMETER
|
||||
if context or value is invalid */
|
||||
getdns_return_t getdns_context_set_return_dnssec_status(
|
||||
getdns_context *context, int enabled);
|
||||
/** \defgroup UnofficialgetdnsAPI Additional API for getdns implementation
|
||||
* @{
|
||||
*/
|
||||
|
||||
/* dict util */
|
||||
/* set a string as bindata */
|
||||
getdns_return_t getdns_dict_util_set_string(struct getdns_dict * dict,
|
||||
char *name, const char *value);
|
||||
/** \defgroup Uvaluesandtexts Additional values and texts
|
||||
* @{
|
||||
*/
|
||||
|
||||
/* get a string from a dict. the result must be freed if valid */
|
||||
getdns_return_t getdns_dict_util_get_string(struct getdns_dict * dict,
|
||||
char *name, char **result);
|
||||
/**
|
||||
* \defgroup Ureturnvaluesandtext Additional return values and texts
|
||||
* @{
|
||||
*/
|
||||
#define GETDNS_RETURN_NEED_MORE_SPACE ((getdns_return_t) 399 )
|
||||
#define GETDNS_RETURN_NEED_MORE_SPACE_TEXT "The buffer was too small"
|
||||
/** @}
|
||||
*/
|
||||
|
||||
/* tells underlying unbound to use background threads or fork */
|
||||
getdns_return_t getdns_context_set_use_threads(getdns_context* context,
|
||||
int use_threads);
|
||||
|
||||
/* Async support */
|
||||
uint32_t getdns_context_get_num_pending_requests(getdns_context* context,
|
||||
struct timeval* next_timeout);
|
||||
/**
|
||||
* \defgroup Ucontextcodes Additional context codes 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"
|
||||
/** @}
|
||||
*/
|
||||
|
||||
/* process async reqs */
|
||||
getdns_return_t getdns_context_process_async(getdns_context* context);
|
||||
|
||||
/***************** functions for eventloop extensions ******************/
|
||||
/**
|
||||
* \defgroup versions Additional version values
|
||||
* @{
|
||||
*/
|
||||
#define GETDNS_VERSION "@GETDNS_VERSION@"
|
||||
#define GETDNS_NUMERIC_VERSION @GETDNS_NUMERIC_VERSION@
|
||||
#define GETDNS_API_VERSION "@API_VERSION@"
|
||||
#define GETDNS_API_NUMERIC_VERSION @API_NUMERIC_VERSION@
|
||||
/** @}
|
||||
*/
|
||||
|
||||
|
||||
/* an alias for REQUIRED */
|
||||
#define GETDNS_AUTHENTICATION_HOSTNAME GETDNS_AUTHENTICATION_REQUIRED
|
||||
|
||||
/**
|
||||
* \defgroup authvaulesandtext Additional 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()"
|
||||
/** @}
|
||||
*/
|
||||
|
||||
|
||||
/**
|
||||
* \defgroup appendname Additional append name 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()"
|
||||
/** @}
|
||||
*/
|
||||
|
||||
|
||||
/**
|
||||
* \defgroup Uvaluesandtextsdepricated Additional transport values and texts (will be deprecated)
|
||||
* @{
|
||||
*/
|
||||
|
||||
/** 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()"
|
||||
|
||||
/** @}
|
||||
*/
|
||||
/** @}
|
||||
*/
|
||||
|
||||
|
||||
/**
|
||||
* \defgroup Ufunctions Additional functions
|
||||
* @{
|
||||
*/
|
||||
|
||||
/**
|
||||
* \defgroup Ueventloops Additional event loop extension functions
|
||||
* @{
|
||||
*/
|
||||
|
||||
typedef void (*getdns_eventloop_callback)(void *userarg);
|
||||
|
||||
|
|
@ -131,7 +215,66 @@ getdns_context_detach_eventloop(getdns_context *context);
|
|||
/* Run the context's event loop until nothing more to do */
|
||||
void
|
||||
getdns_context_run(getdns_context *context);
|
||||
/** @}
|
||||
*/
|
||||
|
||||
|
||||
/**
|
||||
* \defgroup contextfunction Additional getdns_context async functions
|
||||
* @{
|
||||
*/
|
||||
/* process async reqs */
|
||||
getdns_return_t getdns_context_process_async(getdns_context* context);
|
||||
/** @}
|
||||
*/
|
||||
|
||||
/**
|
||||
* \defgroup Ucontextset Additional getdns_context_set functions
|
||||
* @{
|
||||
*/
|
||||
/**
|
||||
* Register a callback function for context changes.
|
||||
* @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.
|
||||
value is either GETDNS_EXTENSION_TRUE or GETDNS_EXTENSION_FALSE
|
||||
returns GETDNS_RETURN_GOOD on success or GETDNS_RETURN_INVALID_PARAMETER
|
||||
if context or value is invalid */
|
||||
getdns_return_t getdns_context_set_return_dnssec_status(
|
||||
getdns_context *context, int enabled);
|
||||
|
||||
/* tells underlying unbound to use background threads or fork */
|
||||
getdns_return_t getdns_context_set_use_threads(getdns_context* context,
|
||||
int use_threads);
|
||||
|
||||
getdns_return_t
|
||||
getdns_context_set_tls_authentication(
|
||||
getdns_context *context, getdns_tls_authentication_t value);
|
||||
|
||||
getdns_return_t
|
||||
getdns_context_set_edns_client_subnet_private(getdns_context *context, uint8_t value);
|
||||
|
||||
getdns_return_t
|
||||
getdns_context_set_tls_query_padding_blocksize(getdns_context *context, uint16_t value);
|
||||
/** @}
|
||||
*/
|
||||
|
||||
/**
|
||||
* \defgroup Ucontextget Additional getdns_context_get functions
|
||||
* @{
|
||||
*/
|
||||
/** begin getters **/
|
||||
getdns_return_t
|
||||
getdns_context_get_resolution_type(getdns_context *context,
|
||||
|
|
@ -201,16 +344,154 @@ getdns_context_get_edns_version(getdns_context *context, uint8_t* value);
|
|||
getdns_return_t
|
||||
getdns_context_get_edns_do_bit(getdns_context *context, uint8_t* value);
|
||||
|
||||
getdns_return_t
|
||||
getdns_context_set_edns_client_subnet_private(getdns_context *context, uint8_t value);
|
||||
getdns_return_t
|
||||
getdns_context_get_edns_client_subnet_private(getdns_context *context, uint8_t* value);
|
||||
|
||||
getdns_return_t
|
||||
getdns_context_set_tls_query_padding_blocksize(getdns_context *context, uint16_t value);
|
||||
getdns_return_t
|
||||
getdns_context_get_tls_query_padding_blocksize(getdns_context *context, uint16_t* value);
|
||||
|
||||
getdns_return_t
|
||||
getdns_context_get_tls_authentication(getdns_context *context,
|
||||
getdns_tls_authentication_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.
|
||||
* @param context The context to monitor for changes
|
||||
* @return userarg A user defined argument to be passed to the callback
|
||||
* function.
|
||||
* @return 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 *));
|
||||
|
||||
/* Async support */
|
||||
uint32_t getdns_context_get_num_pending_requests(getdns_context* context,
|
||||
struct timeval* next_timeout);
|
||||
/** @}
|
||||
*/
|
||||
|
||||
|
||||
/**
|
||||
* \defgroup Uutilityfunctions Additional utility functions
|
||||
* @{
|
||||
*/
|
||||
|
||||
const char *getdns_get_version(void);
|
||||
uint32_t getdns_get_version_number(void);
|
||||
const char *getdns_get_api_version(void);
|
||||
uint32_t getdns_get_api_version_number(void);
|
||||
|
||||
/**
|
||||
* 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);
|
||||
|
||||
/* dict util */
|
||||
/* set a string as bindata */
|
||||
getdns_return_t getdns_dict_util_set_string(struct getdns_dict * dict,
|
||||
char *name, const char *value);
|
||||
|
||||
/* get a string from a dict. the result must be freed if valid */
|
||||
getdns_return_t getdns_dict_util_get_string(struct getdns_dict * dict,
|
||||
char *name, char **result);
|
||||
|
||||
/**
|
||||
* Validate replies or resource records.
|
||||
*
|
||||
* @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);
|
||||
|
||||
/**
|
||||
* 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.
|
||||
* @return 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);
|
||||
|
||||
|
||||
/**
|
||||
* Pretty print the getdns_dict in a given buffer snprintf style.
|
||||
|
|
@ -306,169 +587,6 @@ int
|
|||
getdns_snprint_json_list(
|
||||
char *str, size_t size, const getdns_list *list, int pretty);
|
||||
|
||||
/**
|
||||
* Register a callback function for context changes.
|
||||
* @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 *));
|
||||
|
||||
/**
|
||||
* 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.
|
||||
* @param context The context to monitor for changes
|
||||
* @return userarg A user defined argument to be passed to the callback
|
||||
* function.
|
||||
* @return 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 *));
|
||||
|
||||
/**
|
||||
* 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);
|
||||
|
||||
|
||||
|
||||
/**
|
||||
* 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.
|
||||
* @return 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);
|
||||
|
||||
|
||||
|
||||
/* 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);
|
||||
|
||||
#define GETDNS_VERSION "@GETDNS_VERSION@"
|
||||
#define GETDNS_NUMERIC_VERSION @GETDNS_NUMERIC_VERSION@
|
||||
#define GETDNS_API_VERSION "@API_VERSION@"
|
||||
#define GETDNS_API_NUMERIC_VERSION @API_NUMERIC_VERSION@
|
||||
|
||||
const char *getdns_get_version(void);
|
||||
uint32_t getdns_get_version_number(void);
|
||||
const char *getdns_get_api_version(void);
|
||||
uint32_t getdns_get_api_version_number(void);
|
||||
|
||||
/* Authentication options used when doing TLS */
|
||||
typedef enum getdns_tls_authentication_t {
|
||||
GETDNS_AUTHENTICATION_NONE = 1300,
|
||||
GETDNS_AUTHENTICATION_REQUIRED = 1301
|
||||
} getdns_tls_authentication_t;
|
||||
|
||||
/* an alias for REQUIRED */
|
||||
#define GETDNS_AUTHENTICATION_HOSTNAME GETDNS_AUTHENTICATION_REQUIRED
|
||||
|
||||
/**
|
||||
* \defgroup authtext Authentication texts
|
||||
* @{
|
||||
*/
|
||||
#define GETDNS_AUTHENTICATION_NONE_TEXT "See getdns_context_set_tls_authentication()"
|
||||
#define GETDNS_AUTHENTICATION_REQUIRED_TEXT "See getdns_context_set_tls_authentication()"
|
||||
/** @}
|
||||
*/
|
||||
|
||||
#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"
|
||||
|
||||
getdns_return_t
|
||||
getdns_context_set_tls_authentication(
|
||||
getdns_context *context, getdns_tls_authentication_t value);
|
||||
|
||||
getdns_return_t
|
||||
getdns_context_get_tls_authentication(getdns_context *context,
|
||||
getdns_tls_authentication_t* value);
|
||||
|
||||
|
||||
/* 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()"
|
||||
|
||||
#define GETDNS_RETURN_NEED_MORE_SPACE ((getdns_return_t) 399 )
|
||||
#define GETDNS_RETURN_NEED_MORE_SPACE_TEXT "The buffer was too small"
|
||||
|
||||
/**
|
||||
* Convert rr_dict to wireformat representation of the resource record.
|
||||
|
|
@ -630,7 +748,7 @@ getdns_str2rr_dict(
|
|||
/**
|
||||
* Read the zonefile and convert to a list of rr_dict's.
|
||||
*
|
||||
* @param fp An opened FILE pointer on the zone file.
|
||||
* @param FILE An opened FILE pointer on the zone file.
|
||||
* @return 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
|
||||
|
|
@ -782,46 +900,27 @@ getdns_msg_dict2str_buf(
|
|||
getdns_return_t
|
||||
getdns_msg_dict2str_scan(
|
||||
const getdns_dict *msg_dict, char **str, int *str_len);
|
||||
/** @}
|
||||
*/
|
||||
|
||||
|
||||
/**
|
||||
* Validate replies or resource records.
|
||||
*
|
||||
* @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.
|
||||
* \defgroup Uutilityfunctionsdeprecated Additional utility functions (will be deprecated)
|
||||
* @{
|
||||
*/
|
||||
/* 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);
|
||||
/** @}
|
||||
*/
|
||||
/** @}
|
||||
*/
|
||||
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);
|
||||
|
||||
|
||||
#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()"
|
||||
|
||||
/** @}
|
||||
*/
|
||||
|
||||
#ifdef __cplusplus
|
||||
}
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
/**
|
||||
* \file
|
||||
* \brief Public interfaces to getdns, include in your application to use getdns API.
|
||||
* \brief Testing interfaces to getdns
|
||||
*
|
||||
* This source was taken from the original pseudo-implementation by
|
||||
* Paul Hoffman.
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
/**
|
||||
* \file
|
||||
* \brief Public interfaces to getdns, include in your application to use getdns API.
|
||||
* \brief Testing interfaces to getdns
|
||||
*
|
||||
* This source was taken from the original pseudo-implementation by
|
||||
* Paul Hoffman.
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
/**
|
||||
* \file
|
||||
* \brief Public interfaces to getdns, include in your application to use getdns API.
|
||||
* \brief Testing interfaces to getdns
|
||||
*
|
||||
* This source was taken from the original pseudo-implementation by
|
||||
* Paul Hoffman.
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
/**
|
||||
* \file
|
||||
* \brief Public interfaces to getdns, include in your application to use getdns API.
|
||||
* \brief Testing interfaces to getdns
|
||||
*
|
||||
* This source was taken from the original pseudo-implementation by
|
||||
* Paul Hoffman.
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
/**
|
||||
* \file
|
||||
* \brief Public interfaces to getdns, include in your application to use getdns API.
|
||||
* \brief Testing interfaces to getdns
|
||||
*
|
||||
* This source was taken from the original pseudo-implementation by
|
||||
* Paul Hoffman.
|
||||
|
|
|
|||
|
|
@ -1381,6 +1381,14 @@ error:
|
|||
getdns_dict_destroy(response);
|
||||
}
|
||||
|
||||
/**
|
||||
* \brief A wrapper script for command line testing of getdns
|
||||
* getdns_query -h provides details of the available options (the syntax is
|
||||
* similar to that of drill)
|
||||
* Note that for getdns the -z options enables getdns as a daemon which
|
||||
* allows getdns to be used as the local stub (or recursive) resolver
|
||||
*/
|
||||
|
||||
int
|
||||
main(int argc, char **argv)
|
||||
{
|
||||
|
|
|
|||
|
|
@ -68,7 +68,7 @@ getdns_return_t getdns_apply_network_result(getdns_network_req* netreq,
|
|||
* description but the list_set functions seem to be designed to modify an existing
|
||||
* item in the list. The newly added item has no data type.
|
||||
* @param list list containing the item to which child_list is to be added
|
||||
* @param *index assigned to the index of the newly added item on success
|
||||
* @param *child_dict dict to append to the list
|
||||
* @return GETDNS_RETURN_GOOD on success
|
||||
* @return GETDNS_RETURN_GENERAL_ERROR if out of memory
|
||||
*/
|
||||
|
|
|
|||
Loading…
Reference in New Issue