dns.h

   1 /*
   2  * Copyright (c) 2003-2006 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. Please obtain a copy of the License at
  10  * http://www.opensource.apple.com/apsl/ and read it before using this
  11  * file.
  12  *
  13  * The Original Code and all software distributed under the License are
  14  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  15  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  16  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  17  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  18  * Please see the License for the specific language governing rights and
  19  * limitations under the License.
  20  *
  21  * @APPLE_LICENSE_HEADER_END@
  22  */
  23
  24 #ifndef __DNS_H__
  25 #define __DNS_H__
  26
  27 #include <sys/cdefs.h>
  28 #include <sys/types.h>
  29 #include <stdint.h>
  30 #include <sys/socket.h>
  31
  32 /*
  33  * The functions described in this access layer support multiple DNS
  34  * client configurations.  Each DNS client has its own set of nameserver
  35  * addresses and its own set of operational parameters.  Each client
  36  * can perform DNS queries and searches independent of other clients.
  37  * Each client has a symbolic name which is of the same format as a
  38  * domain name, e.g. "apple.com".  A special meta-client, known as the
  39  * "Super" DNS client, acts as a router for DNS queries.  The Super
  40  * client chooses among all available clients by finding a best match
  41  * between the domain name given in a query and the names of all known
  42  * clients.
  43  *
  44  * The configuration for a particular client may be read from a file
  45  * having the same format as the traditional "/etc/resolv.conf" file.
  46  * However, client configurations are not limited to being stored in
  47  * files.  The implementation of the library may also locate client
  48  * configuratins in other data sources, such as the System Configuration
  49  * Database.  Users of this API should make no assumptions about the
  50  * source of the configuration data.
  51  */
  52
  53 typedef const struct __dns_handle_private_struct *dns_handle_t;
  54
  55
  56 __BEGIN_DECLS
  57
  58 /*
  59  * Create a client handle for DNS access.
  60  *
  61  * "Super" DNS client
  62  *
  63  * dns_open(NULL) returns a "super" client that routes DNS queries
  64  * among all DNS configurations known to the system.
  65  *
  66  * Queries for qualified names are sent using a client configuration that
  67  * best matches the domain name given in the query. For example, if there
  68  * is a client named "apple.com", a search for "foo.apple.com" would use the
  69  * resolver configuration specified for that client.  The matching algorithm
  70  * chooses the client with the maximum number of matching domain components.
  71  * For example, if there are clients named "a.b.c", and "b.c", a search for
  72  * "x.a.b.c" would use the "a.b.c" resolver configuration, while a search
  73  * for "x.y.b.c" would use the "b.c" client.  If there are no matches, the
  74  * configuration settings in the default client - generally corresponding to
  75  * the /etc/resolv.conf file or to the "primary" DNS configuration on the
  76  * system are used for the query.
  77  *
  78  * The domain search list defined in the "default" client is used to search
  79  * for unqualified names, by appending each domain in the search list and
  80  * then following the logic for matching qualified names described above.
  81  *
  82  * The DNS access APIs may be used by multiple threads.  Each thread must
  83  * use a separate DNS client handle created by calling dns_open().
  84  *
  85  * A simple DNS client handle may be obtained by providing a non-NULL value
  86  * for the "name" parameter.  Simple clients correspond to a single DNS
  87  * configuration, derived from a resolv.conf format file or from some other
  88  * source of configurations known to the system.
  89  * The name parameter may be a full or relative path name (starting with '/'
  90  * or '.'), in which case the client's configuration is read from the
  91  * named file.  If the name parameter is not a file path name, the routine
  92  * will search through all known sources of DNS configuration data on the
  93  * system to locate DNS configuration data corresponding to the name supplied,
  94  * or NULL if none can be found.
  95  *
  96  * Use _PATH_RESCONF to open /etc/resolv.conf.
  97  */
  98 extern dns_handle_t dns_open(const char *name);
  99
 100 /*
 101  * Close a client and free its resources.
 102  */
 103 extern void dns_free(dns_handle_t dns);
 104
 105 /*
 106  * Enable / Disable debug logging.
 107  */
 108 extern void dns_set_debug(dns_handle_t dns, uint32_t flag);
 109
 110 /*
 111  * Returns the number of names in the search list.
 112  */
 113 extern uint32_t dns_search_list_domain_count(dns_handle_t dns);
 114
 115 /*
 116  * Returns the domain name at index i in the search list.
 117  * Returns NULL if there are no names in the search list,
 118  * or if i is out of range.
 119  * Caller must free the returned value.
 120  */
 121 extern char *dns_search_list_domain(dns_handle_t dns, uint32_t i);
 122
 123 /*
 124  * Resolve a name.
 125  * The name is considered fully-qualified (the search list is not used).
 126  * Caller must supply buffer space for the reply message and the server address.
 127  */
 128 extern int32_t dns_query(dns_handle_t dns, const char *name, uint32_t dnsclass, uint32_t dnstype, char *buf, uint32_t len, struct sockaddr *from, uint32_t *fromlen);
 129
 130 /*
 131  * Search for a name.
 132  * Caller must supply buffer space for the reply message and the server address.
 133  */
 134 extern int32_t dns_search(dns_handle_t dns, const char *name, uint32_t dnsclass, uint32_t dnstype, char *buf, uint32_t len, struct sockaddr *from, uint32_t *fromlen);
 135
 136 __END_DECLS
 137
 138 #endif /* __DNS_H__ */