1238106Sdes/* 2238106Sdes * unbound.h - unbound validating resolver public API 3238106Sdes * 4238106Sdes * Copyright (c) 2007, NLnet Labs. All rights reserved. 5238106Sdes * 6238106Sdes * This software is open source. 7238106Sdes * 8238106Sdes * Redistribution and use in source and binary forms, with or without 9238106Sdes * modification, are permitted provided that the following conditions 10238106Sdes * are met: 11238106Sdes * 12238106Sdes * Redistributions of source code must retain the above copyright notice, 13238106Sdes * this list of conditions and the following disclaimer. 14238106Sdes * 15238106Sdes * Redistributions in binary form must reproduce the above copyright notice, 16238106Sdes * this list of conditions and the following disclaimer in the documentation 17238106Sdes * and/or other materials provided with the distribution. 18238106Sdes * 19238106Sdes * Neither the name of the NLNET LABS nor the names of its contributors may 20238106Sdes * be used to endorse or promote products derived from this software without 21238106Sdes * specific prior written permission. 22238106Sdes * 23238106Sdes * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 24269257Sdes * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 25269257Sdes * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 26269257Sdes * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 27269257Sdes * HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 28269257Sdes * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED 29269257Sdes * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 30269257Sdes * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 31269257Sdes * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 32269257Sdes * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 33269257Sdes * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 34238106Sdes */ 35238106Sdes 36238106Sdes/** 37238106Sdes * \file 38238106Sdes * 39238106Sdes * This file contains functions to resolve DNS queries and 40238106Sdes * validate the answers. Synchonously and asynchronously. 41238106Sdes * 42238106Sdes * Several ways to use this interface from an application wishing 43238106Sdes * to perform (validated) DNS lookups. 44238106Sdes * 45238106Sdes * All start with 46238106Sdes * ctx = ub_ctx_create(); 47238106Sdes * err = ub_ctx_add_ta(ctx, "..."); 48238106Sdes * err = ub_ctx_add_ta(ctx, "..."); 49238106Sdes * ... some lookups 50238106Sdes * ... call ub_ctx_delete(ctx); when you want to stop. 51238106Sdes * 52238106Sdes * Application not threaded. Blocking. 53238106Sdes * int err = ub_resolve(ctx, "www.example.com", ... 54238106Sdes * if(err) fprintf(stderr, "lookup error: %s\n", ub_strerror(err)); 55238106Sdes * ... use the answer 56238106Sdes * 57238106Sdes * Application not threaded. Non-blocking ('asynchronous'). 58238106Sdes * err = ub_resolve_async(ctx, "www.example.com", ... my_callback); 59238106Sdes * ... application resumes processing ... 60238106Sdes * ... and when either ub_poll(ctx) is true 61238106Sdes * ... or when the file descriptor ub_fd(ctx) is readable, 62238106Sdes * ... or whenever, the app calls ... 63238106Sdes * ub_process(ctx); 64238106Sdes * ... if no result is ready, the app resumes processing above, 65238106Sdes * ... or process() calls my_callback() with results. 66238106Sdes * 67238106Sdes * ... if the application has nothing more to do, wait for answer 68238106Sdes * ub_wait(ctx); 69238106Sdes * 70238106Sdes * Application threaded. Blocking. 71238106Sdes * Blocking, same as above. The current thread does the work. 72238106Sdes * Multiple threads can use the *same context*, each does work and uses 73238106Sdes * shared cache data from the context. 74238106Sdes * 75238106Sdes * Application threaded. Non-blocking ('asynchronous'). 76238106Sdes * ... setup threaded-asynchronous config option 77238106Sdes * err = ub_ctx_async(ctx, 1); 78238106Sdes * ... same as async for non-threaded 79238106Sdes * ... the callbacks are called in the thread that calls process(ctx) 80238106Sdes * 81269257Sdes * Openssl needs to have locking in place, and the application must set 82269257Sdes * it up, because a mere library cannot do this, use the calls 83269257Sdes * CRYPTO_set_id_callback and CRYPTO_set_locking_callback. 84269257Sdes * 85238106Sdes * If no threading is compiled in, the above async example uses fork(2) to 86238106Sdes * create a process to perform the work. The forked process exits when the 87238106Sdes * calling process exits, or ctx_delete() is called. 88238106Sdes * Otherwise, for asynchronous with threading, a worker thread is created. 89238106Sdes * 90238106Sdes * The blocking calls use shared ctx-cache when threaded. Thus 91238106Sdes * ub_resolve() and ub_resolve_async() && ub_wait() are 92238106Sdes * not the same. The first makes the current thread do the work, setting 93238106Sdes * up buffers, etc, to perform the work (but using shared cache data). 94238106Sdes * The second calls another worker thread (or process) to perform the work. 95238106Sdes * And no buffers need to be set up, but a context-switch happens. 96238106Sdes */ 97238106Sdes#ifndef _UB_UNBOUND_H 98238106Sdes#define _UB_UNBOUND_H 99238106Sdes 100238106Sdes#ifdef __cplusplus 101238106Sdesextern "C" { 102238106Sdes#endif 103238106Sdes 104269257Sdes/** the version of this header file */ 105269257Sdes#define UNBOUND_VERSION_MAJOR @UNBOUND_VERSION_MAJOR@ 106269257Sdes#define UNBOUND_VERSION_MINOR @UNBOUND_VERSION_MINOR@ 107269257Sdes#define UNBOUND_VERSION_MICRO @UNBOUND_VERSION_MICRO@ 108269257Sdes 109238106Sdes/** 110238106Sdes * The validation context is created to hold the resolver status, 111238106Sdes * validation keys and a small cache (containing messages, rrsets, 112238106Sdes * roundtrip times, trusted keys, lameness information). 113238106Sdes * 114238106Sdes * Its contents are internally defined. 115238106Sdes */ 116238106Sdesstruct ub_ctx; 117238106Sdes 118238106Sdes/** 119238106Sdes * The validation and resolution results. 120238106Sdes * Allocated by the resolver, and need to be freed by the application 121238106Sdes * with ub_resolve_free(). 122238106Sdes */ 123238106Sdesstruct ub_result { 124238106Sdes /** The original question, name text string. */ 125238106Sdes char* qname; 126238106Sdes /** the type asked for */ 127238106Sdes int qtype; 128238106Sdes /** the class asked for */ 129238106Sdes int qclass; 130238106Sdes 131238106Sdes /** 132238106Sdes * a list of network order DNS rdata items, terminated with a 133238106Sdes * NULL pointer, so that data[0] is the first result entry, 134238106Sdes * data[1] the second, and the last entry is NULL. 135238106Sdes * If there was no data, data[0] is NULL. 136238106Sdes */ 137238106Sdes char** data; 138238106Sdes 139238106Sdes /** the length in bytes of the data items, len[i] for data[i] */ 140238106Sdes int* len; 141238106Sdes 142238106Sdes /** 143238106Sdes * canonical name for the result (the final cname). 144238106Sdes * zero terminated string. 145238106Sdes * May be NULL if no canonical name exists. 146238106Sdes */ 147238106Sdes char* canonname; 148238106Sdes 149238106Sdes /** 150238106Sdes * DNS RCODE for the result. May contain additional error code if 151238106Sdes * there was no data due to an error. 0 (NOERROR) if okay. 152238106Sdes */ 153238106Sdes int rcode; 154238106Sdes 155238106Sdes /** 156238106Sdes * The DNS answer packet. Network formatted. Can contain DNSSEC types. 157238106Sdes */ 158238106Sdes void* answer_packet; 159238106Sdes /** length of the answer packet in octets. */ 160238106Sdes int answer_len; 161238106Sdes 162238106Sdes /** 163238106Sdes * If there is any data, this is true. 164238106Sdes * If false, there was no data (nxdomain may be true, rcode can be set). 165238106Sdes */ 166238106Sdes int havedata; 167238106Sdes 168238106Sdes /** 169238106Sdes * If there was no data, and the domain did not exist, this is true. 170238106Sdes * If it is false, and there was no data, then the domain name 171238106Sdes * is purported to exist, but the requested data type is not available. 172238106Sdes */ 173238106Sdes int nxdomain; 174238106Sdes 175238106Sdes /** 176238106Sdes * True, if the result is validated securely. 177238106Sdes * False, if validation failed or domain queried has no security info. 178238106Sdes * 179238106Sdes * It is possible to get a result with no data (havedata is false), 180238106Sdes * and secure is true. This means that the non-existance of the data 181238106Sdes * was cryptographically proven (with signatures). 182238106Sdes */ 183238106Sdes int secure; 184238106Sdes 185238106Sdes /** 186238106Sdes * If the result was not secure (secure==0), and this result is due 187238106Sdes * to a security failure, bogus is true. 188238106Sdes * This means the data has been actively tampered with, signatures 189238106Sdes * failed, expected signatures were not present, timestamps on 190238106Sdes * signatures were out of date and so on. 191238106Sdes * 192238106Sdes * If !secure and !bogus, this can happen if the data is not secure 193238106Sdes * because security is disabled for that domain name. 194238106Sdes * This means the data is from a domain where data is not signed. 195238106Sdes */ 196238106Sdes int bogus; 197238106Sdes 198238106Sdes /** 199238106Sdes * If the result is bogus this contains a string (zero terminated) 200238106Sdes * that describes the failure. There may be other errors as well 201238106Sdes * as the one described, the description may not be perfectly accurate. 202238106Sdes * Is NULL if the result is not bogus. 203238106Sdes */ 204238106Sdes char* why_bogus; 205249141Sdes 206249141Sdes /** 207249141Sdes * TTL for the result, in seconds. If the security is bogus, then 208249141Sdes * you also cannot trust this value. 209249141Sdes */ 210249141Sdes int ttl; 211238106Sdes}; 212238106Sdes 213238106Sdes/** 214238106Sdes * Callback for results of async queries. 215238106Sdes * The readable function definition looks like: 216238106Sdes * void my_callback(void* my_arg, int err, struct ub_result* result); 217238106Sdes * It is called with 218238106Sdes * void* my_arg: your pointer to a (struct of) data of your choice, 219238106Sdes * or NULL. 220238106Sdes * int err: if 0 all is OK, otherwise an error occured and no results 221238106Sdes * are forthcoming. 222238106Sdes * struct result: pointer to more detailed result structure. 223238106Sdes * This structure is allocated on the heap and needs to be 224238106Sdes * freed with ub_resolve_free(result); 225238106Sdes */ 226238106Sdestypedef void (*ub_callback_t)(void*, int, struct ub_result*); 227238106Sdes 228238106Sdes/** 229238106Sdes * Create a resolving and validation context. 230238106Sdes * The information from /etc/resolv.conf and /etc/hosts is not utilised by 231238106Sdes * default. Use ub_ctx_resolvconf and ub_ctx_hosts to read them. 232238106Sdes * @return a new context. default initialisation. 233238106Sdes * returns NULL on error. 234238106Sdes */ 235238106Sdesstruct ub_ctx* ub_ctx_create(void); 236238106Sdes 237238106Sdes/** 238238106Sdes * Destroy a validation context and free all its resources. 239238106Sdes * Outstanding async queries are killed and callbacks are not called for them. 240238106Sdes * @param ctx: context to delete. 241238106Sdes */ 242238106Sdesvoid ub_ctx_delete(struct ub_ctx* ctx); 243238106Sdes 244238106Sdes/** 245238106Sdes * Set an option for the context. 246238106Sdes * @param ctx: context. 247238106Sdes * @param opt: option name from the unbound.conf config file format. 248238106Sdes * (not all settings applicable). The name includes the trailing ':' 249238106Sdes * for example ub_ctx_set_option(ctx, "logfile:", "mylog.txt"); 250238106Sdes * This is a power-users interface that lets you specify all sorts 251238106Sdes * of options. 252238106Sdes * For some specific options, such as adding trust anchors, special 253238106Sdes * routines exist. 254238106Sdes * @param val: value of the option. 255238106Sdes * @return: 0 if OK, else error. 256238106Sdes */ 257255584Sdesint ub_ctx_set_option(struct ub_ctx* ctx, const char* opt, const char* val); 258238106Sdes 259238106Sdes/** 260238106Sdes * Get an option from the context. 261238106Sdes * @param ctx: context. 262238106Sdes * @param opt: option name from the unbound.conf config file format. 263238106Sdes * (not all settings applicable). The name excludes the trailing ':' 264238106Sdes * for example ub_ctx_get_option(ctx, "logfile", &result); 265238106Sdes * This is a power-users interface that lets you specify all sorts 266238106Sdes * of options. 267238106Sdes * @param str: the string is malloced and returned here. NULL on error. 268238106Sdes * The caller must free() the string. In cases with multiple 269238106Sdes * entries (auto-trust-anchor-file), a newline delimited list is 270238106Sdes * returned in the string. 271238106Sdes * @return 0 if OK else an error code (malloc failure, syntax error). 272238106Sdes */ 273255584Sdesint ub_ctx_get_option(struct ub_ctx* ctx, const char* opt, char** str); 274238106Sdes 275238106Sdes/** 276238106Sdes * setup configuration for the given context. 277238106Sdes * @param ctx: context. 278238106Sdes * @param fname: unbound config file (not all settings applicable). 279238106Sdes * This is a power-users interface that lets you specify all sorts 280238106Sdes * of options. 281238106Sdes * For some specific options, such as adding trust anchors, special 282238106Sdes * routines exist. 283238106Sdes * @return: 0 if OK, else error. 284238106Sdes */ 285255584Sdesint ub_ctx_config(struct ub_ctx* ctx, const char* fname); 286238106Sdes 287238106Sdes/** 288238106Sdes * Set machine to forward DNS queries to, the caching resolver to use. 289238106Sdes * IP4 or IP6 address. Forwards all DNS requests to that machine, which 290238106Sdes * is expected to run a recursive resolver. If the proxy is not 291238106Sdes * DNSSEC-capable, validation may fail. Can be called several times, in 292238106Sdes * that case the addresses are used as backup servers. 293238106Sdes * 294238106Sdes * To read the list of nameservers from /etc/resolv.conf (from DHCP or so), 295238106Sdes * use the call ub_ctx_resolvconf. 296238106Sdes * 297238106Sdes * @param ctx: context. 298238106Sdes * At this time it is only possible to set configuration before the 299238106Sdes * first resolve is done. 300238106Sdes * @param addr: address, IP4 or IP6 in string format. 301238106Sdes * If the addr is NULL, forwarding is disabled. 302238106Sdes * @return 0 if OK, else error. 303238106Sdes */ 304255584Sdesint ub_ctx_set_fwd(struct ub_ctx* ctx, const char* addr); 305238106Sdes 306238106Sdes/** 307238106Sdes * Read list of nameservers to use from the filename given. 308238106Sdes * Usually "/etc/resolv.conf". Uses those nameservers as caching proxies. 309238106Sdes * If they do not support DNSSEC, validation may fail. 310238106Sdes * 311238106Sdes * Only nameservers are picked up, the searchdomain, ndots and other 312238106Sdes * settings from resolv.conf(5) are ignored. 313238106Sdes * 314238106Sdes * @param ctx: context. 315238106Sdes * At this time it is only possible to set configuration before the 316238106Sdes * first resolve is done. 317238106Sdes * @param fname: file name string. If NULL "/etc/resolv.conf" is used. 318238106Sdes * @return 0 if OK, else error. 319238106Sdes */ 320255584Sdesint ub_ctx_resolvconf(struct ub_ctx* ctx, const char* fname); 321238106Sdes 322238106Sdes/** 323238106Sdes * Read list of hosts from the filename given. 324238106Sdes * Usually "/etc/hosts". 325238106Sdes * These addresses are not flagged as DNSSEC secure when queried for. 326238106Sdes * 327238106Sdes * @param ctx: context. 328238106Sdes * At this time it is only possible to set configuration before the 329238106Sdes * first resolve is done. 330238106Sdes * @param fname: file name string. If NULL "/etc/hosts" is used. 331238106Sdes * @return 0 if OK, else error. 332238106Sdes */ 333255584Sdesint ub_ctx_hosts(struct ub_ctx* ctx, const char* fname); 334238106Sdes 335238106Sdes/** 336238106Sdes * Add a trust anchor to the given context. 337238106Sdes * The trust anchor is a string, on one line, that holds a valid DNSKEY or 338238106Sdes * DS RR. 339238106Sdes * @param ctx: context. 340238106Sdes * At this time it is only possible to add trusted keys before the 341238106Sdes * first resolve is done. 342238106Sdes * @param ta: string, with zone-format RR on one line. 343238106Sdes * [domainname] [TTL optional] [type] [class optional] [rdata contents] 344238106Sdes * @return 0 if OK, else error. 345238106Sdes */ 346255584Sdesint ub_ctx_add_ta(struct ub_ctx* ctx, const char* ta); 347238106Sdes 348238106Sdes/** 349238106Sdes * Add trust anchors to the given context. 350238106Sdes * Pass name of a file with DS and DNSKEY records (like from dig or drill). 351238106Sdes * @param ctx: context. 352238106Sdes * At this time it is only possible to add trusted keys before the 353238106Sdes * first resolve is done. 354238106Sdes * @param fname: filename of file with keyfile with trust anchors. 355238106Sdes * @return 0 if OK, else error. 356238106Sdes */ 357255584Sdesint ub_ctx_add_ta_file(struct ub_ctx* ctx, const char* fname); 358238106Sdes 359238106Sdes/** 360285206Sdes * Add trust anchor to the given context that is tracked with RFC5011 361285206Sdes * automated trust anchor maintenance. The file is written to when the 362285206Sdes * trust anchor is changed. 363285206Sdes * Pass the name of a file that was output from eg. unbound-anchor, 364285206Sdes * or you can start it by providing a trusted DNSKEY or DS record on one 365285206Sdes * line in the file. 366285206Sdes * @param ctx: context. 367285206Sdes * At this time it is only possible to add trusted keys before the 368285206Sdes * first resolve is done. 369285206Sdes * @param fname: filename of file with trust anchor. 370285206Sdes * @return 0 if OK, else error. 371285206Sdes */ 372285206Sdesint ub_ctx_add_ta_autr(struct ub_ctx* ctx, const char* fname); 373285206Sdes 374285206Sdes/** 375238106Sdes * Add trust anchors to the given context. 376238106Sdes * Pass the name of a bind-style config file with trusted-keys{}. 377238106Sdes * @param ctx: context. 378238106Sdes * At this time it is only possible to add trusted keys before the 379238106Sdes * first resolve is done. 380238106Sdes * @param fname: filename of file with bind-style config entries with trust 381238106Sdes * anchors. 382238106Sdes * @return 0 if OK, else error. 383238106Sdes */ 384255584Sdesint ub_ctx_trustedkeys(struct ub_ctx* ctx, const char* fname); 385238106Sdes 386238106Sdes/** 387238106Sdes * Set debug output (and error output) to the specified stream. 388238106Sdes * Pass NULL to disable. Default is stderr. 389238106Sdes * @param ctx: context. 390238106Sdes * @param out: FILE* out file stream to log to. 391238106Sdes * Type void* to avoid stdio dependency of this header file. 392238106Sdes * @return 0 if OK, else error. 393238106Sdes */ 394238106Sdesint ub_ctx_debugout(struct ub_ctx* ctx, void* out); 395238106Sdes 396238106Sdes/** 397238106Sdes * Set debug verbosity for the context 398238106Sdes * Output is directed to stderr. 399238106Sdes * @param ctx: context. 400238106Sdes * @param d: debug level, 0 is off, 1 is very minimal, 2 is detailed, 401238106Sdes * and 3 is lots. 402238106Sdes * @return 0 if OK, else error. 403238106Sdes */ 404238106Sdesint ub_ctx_debuglevel(struct ub_ctx* ctx, int d); 405238106Sdes 406238106Sdes/** 407238106Sdes * Set a context behaviour for asynchronous action. 408238106Sdes * @param ctx: context. 409238106Sdes * @param dothread: if true, enables threading and a call to resolve_async() 410238106Sdes * creates a thread to handle work in the background. 411238106Sdes * If false, a process is forked to handle work in the background. 412238106Sdes * Changes to this setting after async() calls have been made have 413238106Sdes * no effect (delete and re-create the context to change). 414238106Sdes * @return 0 if OK, else error. 415238106Sdes */ 416238106Sdesint ub_ctx_async(struct ub_ctx* ctx, int dothread); 417238106Sdes 418238106Sdes/** 419238106Sdes * Poll a context to see if it has any new results 420238106Sdes * Do not poll in a loop, instead extract the fd below to poll for readiness, 421238106Sdes * and then check, or wait using the wait routine. 422238106Sdes * @param ctx: context. 423238106Sdes * @return: 0 if nothing to read, or nonzero if a result is available. 424238106Sdes * If nonzero, call ctx_process() to do callbacks. 425238106Sdes */ 426238106Sdesint ub_poll(struct ub_ctx* ctx); 427238106Sdes 428238106Sdes/** 429238106Sdes * Wait for a context to finish with results. Calls ub_process() after 430238106Sdes * the wait for you. After the wait, there are no more outstanding 431238106Sdes * asynchronous queries. 432238106Sdes * @param ctx: context. 433238106Sdes * @return: 0 if OK, else error. 434238106Sdes */ 435238106Sdesint ub_wait(struct ub_ctx* ctx); 436238106Sdes 437238106Sdes/** 438238106Sdes * Get file descriptor. Wait for it to become readable, at this point 439238106Sdes * answers are returned from the asynchronous validating resolver. 440238106Sdes * Then call the ub_process to continue processing. 441238106Sdes * This routine works immediately after context creation, the fd 442238106Sdes * does not change. 443238106Sdes * @param ctx: context. 444238106Sdes * @return: -1 on error, or file descriptor to use select(2) with. 445238106Sdes */ 446238106Sdesint ub_fd(struct ub_ctx* ctx); 447238106Sdes 448238106Sdes/** 449238106Sdes * Call this routine to continue processing results from the validating 450238106Sdes * resolver (when the fd becomes readable). 451238106Sdes * Will perform necessary callbacks. 452238106Sdes * @param ctx: context 453238106Sdes * @return: 0 if OK, else error. 454238106Sdes */ 455238106Sdesint ub_process(struct ub_ctx* ctx); 456238106Sdes 457238106Sdes/** 458238106Sdes * Perform resolution and validation of the target name. 459238106Sdes * @param ctx: context. 460238106Sdes * The context is finalized, and can no longer accept config changes. 461238106Sdes * @param name: domain name in text format (a zero terminated text string). 462238106Sdes * @param rrtype: type of RR in host order, 1 is A (address). 463238106Sdes * @param rrclass: class of RR in host order, 1 is IN (for internet). 464238106Sdes * @param result: the result data is returned in a newly allocated result 465238106Sdes * structure. May be NULL on return, return value is set to an error 466238106Sdes * in that case (out of memory). 467238106Sdes * @return 0 if OK, else error. 468238106Sdes */ 469255584Sdesint ub_resolve(struct ub_ctx* ctx, const char* name, int rrtype, 470238106Sdes int rrclass, struct ub_result** result); 471238106Sdes 472238106Sdes/** 473238106Sdes * Perform resolution and validation of the target name. 474238106Sdes * Asynchronous, after a while, the callback will be called with your 475238106Sdes * data and the result. 476238106Sdes * @param ctx: context. 477238106Sdes * If no thread or process has been created yet to perform the 478238106Sdes * work in the background, it is created now. 479238106Sdes * The context is finalized, and can no longer accept config changes. 480238106Sdes * @param name: domain name in text format (a string). 481238106Sdes * @param rrtype: type of RR in host order, 1 is A. 482238106Sdes * @param rrclass: class of RR in host order, 1 is IN (for internet). 483238106Sdes * @param mydata: this data is your own data (you can pass NULL), 484238106Sdes * and is passed on to the callback function. 485238106Sdes * @param callback: this is called on completion of the resolution. 486238106Sdes * It is called as: 487238106Sdes * void callback(void* mydata, int err, struct ub_result* result) 488238106Sdes * with mydata: the same as passed here, you may pass NULL, 489238106Sdes * with err: is 0 when a result has been found. 490238106Sdes * with result: a newly allocated result structure. 491238106Sdes * The result may be NULL, in that case err is set. 492238106Sdes * 493238106Sdes * If an error happens during processing, your callback will be called 494238106Sdes * with error set to a nonzero value (and result==NULL). 495238106Sdes * @param async_id: if you pass a non-NULL value, an identifier number is 496238106Sdes * returned for the query as it is in progress. It can be used to 497238106Sdes * cancel the query. 498238106Sdes * @return 0 if OK, else error. 499238106Sdes */ 500255584Sdesint ub_resolve_async(struct ub_ctx* ctx, const char* name, int rrtype, 501238106Sdes int rrclass, void* mydata, ub_callback_t callback, int* async_id); 502238106Sdes 503238106Sdes/** 504238106Sdes * Cancel an async query in progress. 505238106Sdes * Its callback will not be called. 506238106Sdes * 507238106Sdes * @param ctx: context. 508238106Sdes * @param async_id: which query to cancel. 509238106Sdes * @return 0 if OK, else error. 510238106Sdes * This routine can return an error if the async_id passed does not exist 511238106Sdes * or has already been delivered. If another thread is processing results 512238106Sdes * at the same time, the result may be delivered at the same time and the 513238106Sdes * cancel fails with an error. Also the cancel can fail due to a system 514238106Sdes * error, no memory or socket failures. 515238106Sdes */ 516238106Sdesint ub_cancel(struct ub_ctx* ctx, int async_id); 517238106Sdes 518238106Sdes/** 519238106Sdes * Free storage associated with a result structure. 520238106Sdes * @param result: to free 521238106Sdes */ 522238106Sdesvoid ub_resolve_free(struct ub_result* result); 523238106Sdes 524238106Sdes/** 525238106Sdes * Convert error value to a human readable string. 526285206Sdes * @param err: error code from one of the libunbound functions. 527238106Sdes * @return pointer to constant text string, zero terminated. 528238106Sdes */ 529238106Sdesconst char* ub_strerror(int err); 530238106Sdes 531238106Sdes/** 532238106Sdes * Debug routine. Print the local zone information to debug output. 533238106Sdes * @param ctx: context. Is finalized by the routine. 534238106Sdes * @return 0 if OK, else error. 535238106Sdes */ 536238106Sdesint ub_ctx_print_local_zones(struct ub_ctx* ctx); 537238106Sdes 538238106Sdes/** 539238106Sdes * Add a new zone with the zonetype to the local authority info of the 540238106Sdes * library. 541238106Sdes * @param ctx: context. Is finalized by the routine. 542238106Sdes * @param zone_name: name of the zone in text, "example.com" 543238106Sdes * If it already exists, the type is updated. 544238106Sdes * @param zone_type: type of the zone (like for unbound.conf) in text. 545238106Sdes * @return 0 if OK, else error. 546238106Sdes */ 547269257Sdesint ub_ctx_zone_add(struct ub_ctx* ctx, const char *zone_name, 548269257Sdes const char *zone_type); 549238106Sdes 550238106Sdes/** 551238106Sdes * Remove zone from local authority info of the library. 552238106Sdes * @param ctx: context. Is finalized by the routine. 553238106Sdes * @param zone_name: name of the zone in text, "example.com" 554238106Sdes * If it does not exist, nothing happens. 555238106Sdes * @return 0 if OK, else error. 556238106Sdes */ 557269257Sdesint ub_ctx_zone_remove(struct ub_ctx* ctx, const char *zone_name); 558238106Sdes 559238106Sdes/** 560238106Sdes * Add localdata to the library local authority info. 561238106Sdes * Similar to local-data config statement. 562238106Sdes * @param ctx: context. Is finalized by the routine. 563238106Sdes * @param data: the resource record in text format, for example 564238106Sdes * "www.example.com IN A 127.0.0.1" 565238106Sdes * @return 0 if OK, else error. 566238106Sdes */ 567269257Sdesint ub_ctx_data_add(struct ub_ctx* ctx, const char *data); 568238106Sdes 569238106Sdes/** 570238106Sdes * Remove localdata from the library local authority info. 571238106Sdes * @param ctx: context. Is finalized by the routine. 572238106Sdes * @param data: the name to delete all data from, like "www.example.com". 573238106Sdes * @return 0 if OK, else error. 574238106Sdes */ 575269257Sdesint ub_ctx_data_remove(struct ub_ctx* ctx, const char *data); 576238106Sdes 577238106Sdes/** 578238106Sdes * Get a version string from the libunbound implementation. 579238106Sdes * @return a static constant string with the version number. 580238106Sdes */ 581238106Sdesconst char* ub_version(void); 582238106Sdes 583238106Sdes#ifdef __cplusplus 584238106Sdes} 585238106Sdes#endif 586238106Sdes 587238106Sdes#endif /* _UB_UNBOUND_H */ 588