fnet_mdns.h

00001 /**************************************************************************
00002 *
00003 * Copyright (c) 2017, Arm Limited and affiliates.
00004 * Copyright 2016 by Andrey Butok. FNET Community.
00005 *
00006 ***************************************************************************
00007 *
00008 *  Licensed under the Apache License, Version 2.0 (the "License"); you may
00009 *  not use this file except in compliance with the License.
00010 *  You may obtain a copy of the License at
00011 *
00012 *  http://www.apache.org/licenses/LICENSE-2.0
00013 *
00014 *  Unless required by applicable law or agreed to in writing, software
00015 *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
00016 *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00017 *  See the License for the specific language governing permissions and
00018 *  limitations under the License.
00019 *
00020 **********************************************************************/
00021 /*!
00022 * @brief mDNS (Bonjour) Server/Responder API.
00023 *
00024 ***************************************************************************/
00025 
00026 #ifndef _FNET_MDNS_H_
00027 
00028 #define _FNET_MDNS_H_
00029 
00030 #if FNET_CFG_MDNS || defined(__DOXYGEN__)
00031 
00032 /*! @addtogroup fnet_mdns
00033 *
00034 * Multicast DNS (mDNS) is used to enable DNS-like
00035 * name resolution in scenarios in which conventional Unicast DNS name resolution is not possible.
00036 * It allows both IPv4 and IPv6 hosts to perform name resolution for hosts on the same local link.@n
00037 * The protocol specification is defined by RFC6762.@n
00038 * It is natively supported by Apple OSs, and named Bonjour.@n
00039 * @n
00040 * After the MDNS server is initialized by calling the @ref fnet_mdns_init() function,
00041 * the user application should call the main service-polling function
00042 * @ref fnet_poll_service() periodically in background. @n
00043 * @n
00044 * For the MDNS-server service example, refer to the FNET Shell demo source code.@n
00045 *
00046 * Configuration parameters:
00047 * - @ref FNET_CFG_MDNS
00048 * - @ref FNET_CFG_MDNS_MAX
00049 * - @ref FNET_CFG_MDNS_PORT
00050 * - @ref FNET_CFG_MDNS_RR_TTL
00051 * - @ref FNET_CFG_MDNS_SERVICE_MAX
00052 *
00053 */
00054 
00055 /*! @{ */
00056 
00057 /**************************************************************************/ /*!
00058  * @brief Initialization parameters for the @ref fnet_mdns_init() function.
00059  ******************************************************************************/
00060 struct fnet_mdns_params
00061 {
00062     fnet_netif_desc_t           netif_desc;     /**< @brief Network interface descriptor to be used by the MDNS server.*/
00063     fnet_address_family_t       addr_family;    /**< @brief Address family (IPv6 or IPv4 or both) the server will listen for MDNS query (it is optional).@n
00064                                                    Default value is defined by @ref AF_SUPPORTED.*/
00065     fnet_uint32_t               rr_ttl;         /**< @brief TTL value that indicates for how many seconds mDNS resource records is valid for mDNS querier, in seconds (it is optional).@n
00066                                                  * Default value is defined by @ref FNET_CFG_MDNS_RR_TTL. */
00067     fnet_uint32_t               rr_ttl_ip;      /**< @brief TTL value for IP header that is hop-count limit for the packet (it is optional).@n
00068                                                  * Default value is defined by @ref FNET_CFG_MDNS_RR_TTL_IP. */
00069     const fnet_char_t           *name;          /**< @brief Name used as a host-name and service-names, advertised by the MDNS server. */
00070 };
00071 
00072 /**************************************************************************/ /*!
00073  * @brief The mDNS Service structure defining application-specific 
00074  * service, advertised by the mDNS server.
00075  * @see fnet_mdns_service_register()
00076  ******************************************************************************/
00077 typedef struct fnet_mdns_service
00078 {
00079     const char*         service_type;               /**< @brief Service Type. Null-terminated string. Example "_http._tcp". */
00080     fnet_uint16_t       service_port;               /**< @brief Service Port number (in network byte order). */
00081     const fnet_uint8_t* (*service_get_txt)(void);   /**< @brief Call-back function, which returns a pointer to the service TXT record (null-terminated). 
00082                                                     If the service does not provide any TXT record, this parameter must be set to NULL. */
00083 } fnet_mdns_service_t;
00084 
00085 /**************************************************************************/ /*!
00086  * @brief mDNS server descriptor.
00087  * @see fnet_mdns_init(), fnet_mdns_release()
00088  ******************************************************************************/
00089 typedef void* fnet_mdns_desc_t;
00090 
00091 /**************************************************************************/ /*!
00092  * @brief  mDNS advertised-service descriptor.
00093  * @see fnet_mdns_service_register(), fnet_mdns_service_unregister()
00094  ******************************************************************************/
00095 typedef void* fnet_mdns_service_desc_t;
00096 
00097 #if defined(__cplusplus)
00098 extern "C" {
00099 #endif
00100 
00101 /***************************************************************************/ /*!
00102  *
00103  * @brief    Initializes Multicast DNS (mDNS) server/responder.
00104  *
00105  * @param params     Initialization parameters defined by @ref fnet_mdns_params.
00106  *
00107  * @return This function returns:
00108  *   - mDNS server descriptor if no error occurs.
00109  *   - @c 0 if an error occurs.
00110  *
00111  * @see fnet_mdns_release(), fnet_mdns_params
00112  *
00113  ******************************************************************************
00114  *
00115  * This function initializes the Multicast DNS (mDMS)server/responder.@n
00116  * It allocates all needed resources and registers the mDNS service in the polling list.@n
00117  * After the initialization, the user application should call the main polling
00118  * function @ref fnet_poll_service() periodically to run the mDNS service routine
00119  * in the background.
00120  *
00121  ******************************************************************************/
00122 fnet_mdns_desc_t fnet_mdns_init( struct fnet_mdns_params *params );
00123 
00124 /***************************************************************************/ /*!
00125  *
00126  * @brief    Releases the Multicast DNS (mDNS) server/responder.
00127  *
00128  * @param mdns_desc     mDNS server descriptor to be unregistered.
00129  *
00130  * @see fnet_mdns_init()
00131  *
00132  ******************************************************************************
00133  *
00134  * This function releases the mDNS Server assigned to the @c desc
00135  * descriptor.@n
00136  * It releases all occupied resources, and unregisters the mDNS service from
00137  * the polling list.
00138  *
00139  ******************************************************************************/
00140 void fnet_mdns_release(fnet_mdns_desc_t mdns_desc);
00141 
00142 /***************************************************************************/ /*!
00143  *
00144  * @brief    Registers application-specific service in the mDNS server.
00145  *
00146  * @param mdns_desc     mDNS server descriptor.
00147  *
00148  * @param service      Service parameters to be advertised by the mDNS server.
00149  *
00150  * @return This function returns:
00151  *   - service descriptor if no error occurs.
00152  *   - @c 0 if an error occurs.
00153  *
00154  * @see fnet_mdns_service_unregister(), fnet_mdns_service_t
00155  *
00156  ******************************************************************************
00157  *
00158  * This function registers an application service and starts its
00159  * advertisement by the mDNS server.
00160  *
00161  ******************************************************************************/
00162 fnet_mdns_service_desc_t fnet_mdns_service_register(fnet_mdns_desc_t mdns_desc, const fnet_mdns_service_t *service);
00163 
00164 /***************************************************************************/ /*!
00165  *
00166  * @brief    Unregisters application service from the mDNS server.
00167  *
00168  * @param service_desc     Service descriptor to be unregistered.
00169  *
00170  * @see fnet_mdns_service_register()
00171  *
00172  ******************************************************************************
00173  *
00174  * This function unregisters application service, assigned to the @c service_desc
00175  * descriptor, and stops its advertisement by the mDNS server.  
00176  *
00177  ******************************************************************************/
00178 void fnet_mdns_service_unregister(fnet_mdns_service_desc_t service_desc);
00179 
00180 /***************************************************************************/ /*!
00181  *
00182  * @brief    Sends unsolicited mDNS announcement.
00183  *
00184  * @param mdns_desc     mDNS server descriptor.
00185  *
00186  * @see fnet_mdns_init()
00187  *
00188  ******************************************************************************
00189  *
00190  * This function sends unsolicited mDNS announcement.@n
00191  * Application may call it when any advertised application-specific parameter 
00192  * has changed (e.g. network interface IP address or service TXT-record content).@n
00193  * RFC 6762: "At any time, if the rdata of any of a host's Multicast DNS records
00194  *  changes, the host MUST repeat the Announcing step to
00195  *  update neighboring caches.  For example, if any of a host's IP
00196  *  addresses change, it MUST re-announce those address records".
00197  *
00198  ******************************************************************************/
00199 void fnet_mdns_announce(fnet_mdns_desc_t mdns_desc);
00200 
00201 /***************************************************************************/ /*!
00202  *
00203  * @brief    Detects if the mDNS Server is enabled or disabled.
00204  *
00205  * @param desc     mDNS server descriptor
00206  *
00207  * @return This function returns:
00208  *          - @ref FNET_TRUE if the mDNS Server is successfully initialized.
00209  *          - @ref FNET_FALSE if the mDNS Server is not initialized or is released.
00210  *
00211  ******************************************************************************
00212  *
00213  * This function detects if the mDNS Server is initialized or is released.
00214  *
00215  ******************************************************************************/
00216 fnet_bool_t fnet_mdns_is_enabled(fnet_mdns_desc_t desc);
00217 
00218 #if defined(__cplusplus)
00219 }
00220 #endif
00221 
00222 /*! @} */
00223 
00224 #endif /* FNET_CFG_MDNS */
00225 
00226 #endif /* _FNET_MDNS_H_ */