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
53typedef 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 */
98extern dns_handle_t dns_open(const char *name);
99
100/*
101 * Close a client and free its resources.
102 */
103extern void dns_free(dns_handle_t dns);
104
105/*
106 * Enable / Disable debug logging.
107 */
108extern void dns_set_debug(dns_handle_t dns, uint32_t flag);
109
110/*
111 * Returns the number of names in the search list.
112 */
113extern 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 */
121extern 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 */
128extern 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 */
134extern 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__ */
139