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