src/inet/DNSResolver.h

   1 /*
   2  *
   3  *    Copyright (c) 2020 Project CHIP Authors
   4  *    Copyright (c) 2013-2017 Nest Labs, Inc.
   5  *
   6  *    Licensed under the Apache License, Version 2.0 (the "License");
   7  *    you may not use this file except in compliance with the License.
   8  *    You may obtain a copy of the License at
   9  *
  10  *        http://www.apache.org/licenses/LICENSE-2.0
  11  *
  12  *    Unless required by applicable law or agreed to in writing, software
  13  *    distributed under the License is distributed on an "AS IS" BASIS,
  14  *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15  *    See the License for the specific language governing permissions and
  16  *    limitations under the License.
  17  */
  18
  19 /**
  20  *    @file
  21  *      This file defines DNSResolver, the object that abstracts
  22  *      Domain Name System (DNS) resolution in InetLayer.
  23  *
  24  */
  25
  26 #pragma once
  27
  28 #include <inet/IPAddress.h>
  29 #include <inet/InetError.h>
  30 #include <inet/InetLayerBasis.h>
  31
  32 #define NL_DNS_HOSTNAME_MAX_LEN (253)
  33
  34 struct addrinfo;
  35
  36 namespace chip {
  37 namespace Inet {
  38
  39 class InetLayer;
  40
  41 /**
  42  * Options controlling how IP address resolution is performed.
  43  */
  44 enum DNSOptions
  45 {
  46     kDNSOption_AddrFamily_Mask = 0x07, ///< Bits within a DNSOptions integer value representing the desired address family.
  47     kDNSOption_Flags_Mask      = 0xF8, ///< Bits within a DNSOptions integer value reserved for flags.
  48
  49     // Address Family Choices
  50     kDNSOption_AddrFamily_Any = 0x00, ///< Return IPv4 and/or IPv6 addresses in the order returned by the nameserver.
  51 #if INET_CONFIG_ENABLE_IPV4
  52     kDNSOption_AddrFamily_IPv4Only      = 0x01, ///< Return only IPv4 addresses.
  53     kDNSOption_AddrFamily_IPv4Preferred = 0x02, ///< Return IPv4 and/or IPv6 addresses, with IPv4 addresses listed first.
  54 #endif
  55     kDNSOption_AddrFamily_IPv6Only      = 0x03, ///< Return only IPv6 addresses.
  56     kDNSOption_AddrFamily_IPv6Preferred = 0x04, ///< Return IPv4 and/or IPv6 addresses, with IPv6 addresses listed first.
  57
  58     // NOTE: At present there are no DNSOption flags define.
  59     kDNSOption_ValidFlags = 0, ///< Set of all valid DNSOption flags.
  60
  61     kDNSOption_Default = kDNSOption_AddrFamily_Any
  62 };
  63
  64 /**
  65  *  @class DNSResolver
  66  *
  67  *  @brief
  68  *    This is an internal class to InetLayer that provides the abstraction of
  69  *    Domain Name System (DNS) resolution in InetLayer. There is no public
  70  *    interface available for the application layer.
  71  *
  72  */
  73 class DNSResolver : public InetLayerBasis
  74 {
  75 private:
  76     friend class InetLayer;
  77
  78 #if CHIP_SYSTEM_CONFIG_USE_SOCKETS
  79 #if INET_CONFIG_ENABLE_ASYNC_DNS_SOCKETS
  80     friend class AsyncDNSResolverSockets;
  81
  82     /// States of the DNSResolver object with respect to hostname resolution.
  83     typedef enum DNSResolverState{
  84         kState_Unused   = 0, ///< Used to indicate that the DNSResolver object is not used.
  85         kState_Active   = 2, ///< Used to indicate that a DNS resolution is being performed on the DNSResolver object.
  86         kState_Complete = 3, ///< Used to indicate that the DNS resolution on the DNSResolver object is complete.
  87         kState_Canceled = 4, ///< Used to indicate that the DNS resolution on the DNSResolver has been canceled.
  88     } DNSResolverState;
  89 #endif // CHIP_SYSTEM_CONFIG_USE_SOCKETS
  90 #endif // INET_CONFIG_ENABLE_ASYNC_DNS_SOCKETS
  91
  92     /**
  93      * @brief   Type of event handling function called when a DNS request completes.
  94      *
  95      * @param[in]   appState    Application state pointer.
  96      * @param[in]   err         Error code.
  97      * @param[in]   addrCount   Number of IP addresses in the \c addrArray list.
  98      * @param[in]   addrArray   List of addresses in the answer.
  99      *
 100      * @details
 101      *  Provide a function of this type to the \c Resolve method to process
 102      *  completion events.
 103      */
 104     typedef void (*OnResolveCompleteFunct)(void * appState, INET_ERROR err, uint8_t addrCount, IPAddress * addrArray);
 105
 106     static chip::System::ObjectPool<DNSResolver, INET_CONFIG_NUM_DNS_RESOLVERS> sPool;
 107
 108     /**
 109      *  A pointer to the callback function when a DNS request is complete.
 110      */
 111     OnResolveCompleteFunct OnComplete;
 112
 113     /**
 114      *  A pointer to the DNS table that stores a list of resolved addresses.
 115      */
 116     IPAddress * AddrArray;
 117
 118     /**
 119      *  The maximum number of addresses that could be stored in the DNS table.
 120      */
 121     uint8_t MaxAddrs;
 122
 123     /**
 124      *  The actual number of addresses that are stored in the DNS table.
 125      */
 126     uint8_t NumAddrs;
 127
 128     /**
 129      * DNS options for the current request.
 130      */
 131     uint8_t DNSOptions;
 132
 133 #if CHIP_SYSTEM_CONFIG_USE_SOCKETS
 134
 135     void InitAddrInfoHints(struct addrinfo & hints);
 136     INET_ERROR ProcessGetAddrInfoResult(int returnCode, struct addrinfo * results);
 137     void CopyAddresses(int family, uint8_t maxAddrs, const struct addrinfo * addrs);
 138     uint8_t CountAddresses(int family, const struct addrinfo * addrs);
 139
 140 #if INET_CONFIG_ENABLE_ASYNC_DNS_SOCKETS
 141
 142     /* Hostname that requires resolution */
 143     char asyncHostNameBuf[NL_DNS_HOSTNAME_MAX_LEN + 1]; // DNS limits hostnames to 253 max characters.
 144
 145     INET_ERROR asyncDNSResolveResult;
 146     /* The next DNSResolver object in the asynchronous DNS resolution queue. */
 147     DNSResolver * pNextAsyncDNSResolver;
 148
 149     DNSResolverState mState;
 150
 151     void HandleAsyncResolveComplete();
 152
 153 #endif // INET_CONFIG_ENABLE_ASYNC_DNS_SOCKETS
 154
 155 #endif // CHIP_SYSTEM_CONFIG_USE_SOCKETS
 156
 157     INET_ERROR Resolve(const char * hostName, uint16_t hostNameLen, uint8_t options, uint8_t maxAddrs, IPAddress * addrArray,
 158                        OnResolveCompleteFunct onComplete, void * appState);
 159     INET_ERROR Cancel();
 160
 161 #if CHIP_SYSTEM_CONFIG_USE_LWIP
 162     void HandleResolveComplete(void);
 163 #if LWIP_VERSION_MAJOR > 1
 164     static void LwIPHandleResolveComplete(const char * name, const ip_addr_t * ipaddr, void * callback_arg);
 165 #else  // LWIP_VERSION_MAJOR <= 1
 166     static void LwIPHandleResolveComplete(const char * name, ip_addr_t * ipaddr, void * callback_arg);
 167 #endif // LWIP_VERSION_MAJOR <= 1
 168 #endif // CHIP_SYSTEM_CONFIG_USE_LWIP
 169 };
 170
 171 } // namespace Inet
 172 } // namespace chip