fnet_dns.h

00001 /**************************************************************************
00002 *
00003 * Copyright 2011-2016 by Andrey Butok. FNET Community.
00004 *
00005 ***************************************************************************
00006 *
00007 *  Licensed under the Apache License, Version 2.0 (the "License"); you may
00008 *  not use this file except in compliance with the License.
00009 *  You may obtain a copy of the License at
00010 *
00011 *  http://www.apache.org/licenses/LICENSE-2.0
00012 *
00013 *  Unless required by applicable law or agreed to in writing, software
00014 *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
00015 *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00016 *  See the License for the specific language governing permissions and
00017 *  limitations under the License.
00018 *
00019 **********************************************************************/
00020 /*!
00021 * @brief DNS Resolver API.
00022 *
00023 ***************************************************************************/
00024 
00025 #ifndef _FNET_DNS_H_
00026 
00027 #define _FNET_DNS_H_
00028 
00029 #if FNET_CFG_DNS_RESOLVER || defined(__DOXYGEN__)
00030 
00031 /*! @addtogroup fnet_dns
00032 *
00033 * The DNS client/resolver service allows user application to resolve IP addresses
00034 * of internet hosts that are identified by a host name. @n
00035 * It does this by sending DNS request to a DNS Server.
00036 * The IP address of a DNS Server is specified manually or can be obtained from
00037 * the DHCP Server for the Local Area Network. @n
00038 * @n
00039 * After the DNS client is initialized by calling the @ref fnet_dns_init() function,
00040 * the user application should call the main service-polling function
00041 * @ref fnet_poll_service() periodically in background. @n
00042 * The resolved IP-address will be passed to the @ref fnet_dns_callback_resolved_t callback function,
00043 * which is set during the DNS-client service initialization.
00044 * @n
00045 * The DNS client service is released automatically as soon as the requested host name is
00046 * fully resolved or an error occurs. Your application code may still continue
00047 * to call @ref fnet_poll_service() to handle other services, but this will not have any
00048 * impact on the DNS client communication until you initialize the next IP address resolving by calling
00049 * @ref fnet_dns_init() again. @n
00050 * @n
00051 * For the DNS-client service example, refer to the FNET Shell demo source code.@n
00052 * @note
00053 * Current version of the DNS client:
00054 *  - does not cache the resolved IP addresses.
00055 *  - can process only one request at a time.
00056 *  - uses UDP protocol, without message truncation.
00057 *  - does not support DNS servers without recursion (all real-life DNS servers support it).
00058 *  - takes the first resolved IP address, even if the DNS server provides several ones.
00059 *
00060 * Configuration parameters:
00061 * - @ref FNET_CFG_DNS
00062 * - @ref FNET_CFG_DNS_RESOLVER
00063 * - @ref FNET_CFG_DNS_PORT
00064 * - @ref FNET_CFG_DNS_RETRANSMISSION_MAX
00065 * - @ref FNET_CFG_DNS_RETRANSMISSION_TIMEOUT
00066 * - @ref FNET_CFG_ND6_RDNSS
00067 * - @ref FNET_CFG_ND6_RDNSS_LIST_SIZE
00068 *
00069 */
00070 
00071 /*! @{ */
00072 
00073 /**************************************************************************/ /*!
00074  * @brief DNS-client states.@n
00075  * Used mainly for debugging purposes.
00076  ******************************************************************************/
00077 typedef enum
00078 {
00079     FNET_DNS_STATE_DISABLED = 0,    /**< @brief The DNS-client service is not
00080                                     * initialized or is released.*/
00081     FNET_DNS_STATE_TX,              /**< @brief The DNS-client service sends the
00082                                     * request to the DNS server.*/
00083     FNET_DNS_STATE_RX,             /**< @brief The DNS-client service waits a response from the DNS server.*/
00084     FNET_DNS_STATE_RELEASE          /**< @brief The DNS resolving is completed
00085                                     * or received error.*/
00086 } fnet_dns_state_t;
00087 
00088 /**************************************************************************/ /*!
00089  * @brief Initialization parameters for the @ref fnet_dns_init() function.
00090  ******************************************************************************/
00091 struct fnet_dns_resolved_addr
00092 {
00093     struct sockaddr             resolved_addr;      /**< @brief Socket address of the resolved host name.*/
00094     fnet_uint32_t               resolved_addr_ttl;  /**< @brief Specifies the time interval (in seconds) that the
00095                                                     * resolved address may be cached before it should be discarded.*/
00096 };
00097 
00098 /**************************************************************************/ /*!
00099  * @brief Prototype of the DNS-client callback function that is
00100  * called when the DNS client has completed the resolving.
00101  *
00102  * @param addr_family       IP address family.@n
00103  *                          It determines the address pointed to by @c addr.
00104  * @param addr_list         Pointer to the list of addresses or @ref FNET_NULL if the resolving was failed.
00105  * @param addr_list_size    Number of resolved addresses in addr_list.
00106  * @param cookie            User-application specific parameter. It's set during
00107  *                          the DNS-client service initialization as part of
00108  *                          @ref fnet_dns_params.
00109  *
00110  * @see fnet_dns_resolve(), fnet_dns_params
00111  ******************************************************************************/
00112 typedef void(*fnet_dns_callback_resolved_t)(const struct fnet_dns_resolved_addr *addr_list, fnet_size_t addr_list_size, fnet_uint32_t cookie);
00113 
00114 /**************************************************************************/ /*!
00115  * @brief Initialization parameters for the @ref fnet_dns_init() function.
00116  ******************************************************************************/
00117 struct fnet_dns_params
00118 {
00119     struct sockaddr                 dns_server_addr;    /**< @brief Socket address of the remote DNS server to
00120                                                         * connect to. */
00121     fnet_char_t                     *host_name;         /**< @brief Host name to resolve (null-terminated string). */
00122     fnet_address_family_t           addr_family;        /**< @brief Family of the IP Address which is queried.*/
00123     fnet_dns_callback_resolved_t    callback;            /**< @brief Pointer to the callback function defined by
00124                                                         * @ref fnet_dns_callback_resolved_t. It is called when the
00125                                                         * DNS-client resolving is finished or an error is occurred. */
00126     fnet_uint32_t                   cookie;             /**< @brief Optional application-specific parameter. @n
00127                                                         * It's passed to the @c callback
00128                                                         * function as input parameter. */
00129 };
00130 
00131 #if defined(__cplusplus)
00132 extern "C" {
00133 #endif
00134 
00135 /***************************************************************************/ /*!
00136  *
00137  * @brief    Initializes DNS client service and starts the host name resolving.
00138  *
00139  * @param params     Initialization parameters.
00140  *
00141  * @return This function returns:
00142  *   - @ref FNET_OK if no error occurs.
00143  *   - @ref FNET_ERR if an error occurs.
00144  *
00145  * @see fnet_dns_params, fnet_dns_callback_resolved_t, fnet_dns_release()
00146  *
00147  ******************************************************************************
00148  *
00149  * This function initializes the DNS client service and starts the
00150  * host name resolving. It allocates all needed
00151  * resources and registers the DNS service in the polling list.@n
00152  * After the initialization, the user application should call the main polling
00153  * function @ref fnet_poll_service() periodically to run the DNS service routine
00154  * in the background.@n
00155  * The resolved IP-address will be passed to the @ref fnet_dns_callback_resolved_t callback function,
00156  * which is set in @c params. @n
00157  * The DNS service is released automatically as soon as the
00158  * resolving is finished or an error is occurred.
00159  *
00160  ******************************************************************************/
00161 fnet_return_t fnet_dns_init( struct fnet_dns_params *params );
00162 
00163 /***************************************************************************/ /*!
00164  *
00165  * @brief    Aborts the resolving and releases the DNS-client service.
00166  *
00167  * @see fnet_dns_init()
00168  *
00169  ******************************************************************************
00170  *
00171  * This function stops the DNS-client service. It releases all resources
00172  * used by the service, and unregisters it from the polling list.@n
00173  * Use this function only in the case of the early termination of the service,
00174  * because the DNS service is released automatically as soon as the
00175  * resolving is finished.
00176  *
00177  ******************************************************************************/
00178 void fnet_dns_release(void);
00179 
00180 /***************************************************************************/ /*!
00181  *
00182  * @brief    Retrieves the current state of the DNS-client service (for debugging purposes).
00183  *
00184  * @return This function returns the current state of the DNS-client service.
00185  *   The state is defined by the @ref fnet_dns_state_t.
00186  *
00187  ******************************************************************************
00188  *
00189  * This function returns the current state of the DNS-client service.
00190  * If the state is @ref FNET_DNS_STATE_DISABLED, the DNS client is not initialized
00191  * or released.@n
00192  * It is used mainly for debugging purposes.
00193  *
00194  ******************************************************************************/
00195 fnet_dns_state_t fnet_dns_state(void);
00196 
00197 #if defined(__cplusplus)
00198 }
00199 #endif
00200 
00201 /*! @} */
00202 
00203 #endif /* FNET_CFG_DNS_RESOLVER */
00204 
00205 #endif /* _FNET_DNS_H_ */