1 /* 2 * Copyright (c) 2024, The OpenThread Authors. 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions are met: 7 * 1. Redistributions of source code must retain the above copyright 8 * notice, this list of conditions and the following disclaimer. 9 * 2. Redistributions in binary form must reproduce the above copyright 10 * notice, this list of conditions and the following disclaimer in the 11 * documentation and/or other materials provided with the distribution. 12 * 3. Neither the name of the copyright holder nor the 13 * names of its contributors may be used to endorse or promote products 14 * derived from this software without specific prior written permission. 15 * 16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 17 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 20 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 21 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 22 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 23 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 24 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 25 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 26 * POSSIBILITY OF SUCH DAMAGE. 27 */ 28 29 /** 30 * @file 31 * @brief 32 * This file includes the platform abstraction for mDNS socket. 33 */ 34 35 #ifndef OPENTHREAD_PLATFORM_MULTICAST_DNS_SOCKET_H_ 36 #define OPENTHREAD_PLATFORM_MULTICAST_DNS_SOCKET_H_ 37 38 #include <stdint.h> 39 40 #include <openthread/instance.h> 41 #include <openthread/ip6.h> 42 #include <openthread/message.h> 43 44 #ifdef __cplusplus 45 extern "C" { 46 #endif 47 48 /** 49 * @addtogroup plat-mdns 50 * 51 * @brief 52 * This module defines platform APIs for Multicast DNS (mDNS) socket. 53 * 54 * @{ 55 */ 56 57 /** 58 * Represents a socket address info. 59 */ 60 typedef struct otPlatMdnsAddressInfo 61 { 62 otIp6Address mAddress; ///< IP address. IPv4-mapped IPv6 format should be used to represent IPv4 address. 63 uint16_t mPort; ///< Port number. 64 uint32_t mInfraIfIndex; ///< Interface index. 65 } otPlatMdnsAddressInfo; 66 67 /** 68 * Enables or disables listening for mDNS messages sent to mDNS port 5353. 69 * 70 * When listening is enabled, the platform MUST listen for multicast messages sent to UDP destination port 5353 at the 71 * mDNS link-local multicast address `224.0.0.251` and its IPv6 equivalent `ff02::fb`. 72 * 73 * The platform SHOULD also listen for any unicast messages sent to UDP destination port 5353. If this is not possible, 74 * then OpenThread mDNS module can be configured to not use any "QU" questions requesting unicast response. 75 * 76 * While enabled, all received messages MUST be reported back using `otPlatMdnsHandleReceive()` callback. 77 * 78 * @param[in] aInstance The OpernThread instance. 79 * @param[in] aEnable Indicate whether to enable or disable. 80 * @param[in] aInfraInfIndex The infrastructure network interface index. 81 * 82 * @retval OT_ERROR_NONE Successfully enabled/disabled listening for mDNS messages. 83 * @retval OT_ERROR_FAILED Failed to enable/disable listening for mDNS messages. 84 */ 85 otError otPlatMdnsSetListeningEnabled(otInstance *aInstance, bool aEnable, uint32_t aInfraIfIndex); 86 87 /** 88 * Sends an mDNS message as multicast. 89 * 90 * The platform MUST multicast the prepared mDNS message in @p aMessage as a UDP message using the mDNS well-known port 91 * number 5353 for both source and destination ports. The message MUST be sent to the mDNS link-local multicast 92 * address `224.0.0.251` and/or its IPv6 equivalent `ff02::fb`. 93 * 94 * @p aMessage contains the mDNS message starting with DNS header at offset zero. It does not include IP or UDP headers. 95 * This function passes the ownership of @p aMessage to the platform layer and platform implementation MUST free 96 * @p aMessage once sent and no longer needed. 97 * 98 * The platform MUST allow multicast loopback, i.e., the multicast message @p aMessage MUST also be received and 99 * passed back to OpenThread stack using `otPlatMdnsHandleReceive()` callback. This behavior is essential for the 100 * OpenThread mDNS stack to process and potentially respond to its own queries, while allowing other mDNS receivers 101 * to also receive the query and its response. 102 * 103 * @param[in] aInstance The OpenThread instance. 104 * @param[in] aMessage The mDNS message to multicast. Ownership is transferred to the platform layer. 105 * @param[in] aInfraIfIndex The infrastructure network interface index. 106 */ 107 void otPlatMdnsSendMulticast(otInstance *aInstance, otMessage *aMessage, uint32_t aInfraIfIndex); 108 109 /** 110 * Sends an mDNS message as unicast. 111 * 112 * The platform MUST send the prepared mDNS message in @p aMessage as a UDP message using source UDP port 5353 to 113 * the destination address and port number specified by @p aAddress. 114 * 115 * @p aMessage contains the DNS message starting with the DNS header at offset zero. It does not include IP or UDP 116 * headers. This function passes the ownership of @p aMessage to the platform layer and platform implementation 117 * MUST free @p aMessage once sent and no longer needed. 118 * 119 * The @p aAddress fields are as follows: 120 * 121 * - `mAddress` specifies the destination address. IPv4-mapped IPv6 format is used to represent an IPv4 destination. 122 * - `mPort` specifies the destination port. 123 * - `mInfraIndex` specifies the interface index. 124 * 125 * If the @aAddress matches this devices address, the platform MUST ensure to receive and pass the message back to 126 * the OpenThread stack using `otPlatMdnsHandleReceive()` for processing. 127 * 128 * @param[in] aInstance The OpenThread instance. 129 * @param[in] aMessage The mDNS message to multicast. Ownership is transferred to platform layer. 130 * @param[in] aAddress The destination address info. 131 */ 132 void otPlatMdnsSendUnicast(otInstance *aInstance, otMessage *aMessage, const otPlatMdnsAddressInfo *aAddress); 133 134 /** 135 * Callback to notify OpenThread mDNS module of a received message on UDP port 5353. 136 * 137 * @p aMessage MUST contain DNS message starting with the DNS header at offset zero. This function passes the 138 * ownership of @p aMessage from the platform layer to the OpenThread stack. The OpenThread stack will free the 139 * message once processed. 140 * 141 * The @p aAddress fields are as follows: 142 * 143 * - `mAddress` specifies the sender's address. IPv4-mapped IPv6 format is used to represent an IPv4 destination. 144 * - `mPort` specifies the sender's port. 145 * - `mInfraIndex` specifies the interface index. 146 * 147 * @param[in] aInstance The OpenThread instance. 148 * @param[in] aMessage The received mDNS message. Ownership is transferred to the OpenThread stack. 149 * @param[in] aIsUnicast Indicates whether the received message is unicast or multicast. 150 * @param[in] aAddress The sender's address info. 151 */ 152 extern void otPlatMdnsHandleReceive(otInstance *aInstance, 153 otMessage *aMessage, 154 bool aIsUnicast, 155 const otPlatMdnsAddressInfo *aAddress); 156 157 /** 158 * @} 159 */ 160 161 #ifdef __cplusplus 162 } // extern "C" 163 #endif 164 165 #endif // OPENTHREAD_PLATFORM_MULTICAST_DNS_SOCKET_H_ 166