dns.h

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