1 /* 2 * Copyright (c) 2021, 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 defines the DNS-SD server APIs. 33 */ 34 35 #ifndef OPENTHREAD_DNSSD_SERVER_H_ 36 #define OPENTHREAD_DNSSD_SERVER_H_ 37 38 #include <stdint.h> 39 40 #include <openthread/dns.h> 41 #include <openthread/error.h> 42 #include <openthread/ip6.h> 43 44 #ifdef __cplusplus 45 extern "C" { 46 #endif 47 48 /** 49 * @addtogroup api-dnssd-server 50 * 51 * @brief 52 * This module includes APIs for DNS-SD server. 53 * 54 * @{ 55 * 56 */ 57 58 /** 59 * Is called when a DNS-SD query subscribes one of: 60 * 1. a service name. 61 * 2. a service instance name. 62 * 3. a host name. 63 * 64 * The DNS-SD query implementation is responsible for identifying what @p aFullName is. 65 * If @p aFullName is a service name or service instance name, the DNS-SD query implementation should discover 66 * corresponding service instance information and notify the DNS-SD server using 67 * `otDnssdQueryHandleDiscoveredServiceInstance`. 68 * If @p aFullName is a host name, the DNS-SD query implementation should 69 * discover the host information and notify the DNS-SD server using `otDnssdQueryHandleDiscoveredHost`. 70 * 71 * @note There can be multiple subscription to the same name. DNS-SD query implementation should record the number of 72 * active subscriptions and stop notifying when there is no active subscription for @p aFullName. 73 * 74 * @param[in] aContext A pointer to the application-specific context. 75 * @param[in] aFullName The null-terminated full service name (e.g. "_ipps._tcp.default.service.arpa."), 76 * or full service instance name (e.g. "OpenThread._ipps._tcp.default.service.arpa."), 77 * or full host name (e.g. "ot-host.default.service.arpa."). 78 * 79 * @sa otDnssdQueryHandleDiscoveredServiceInstance 80 * @sa otDnssdQueryHandleDiscoveredHost 81 * 82 */ 83 typedef void (*otDnssdQuerySubscribeCallback)(void *aContext, const char *aFullName); 84 85 /** 86 * Is called when a DNS-SD query unsubscribes one of: 87 * 1. a service name. 88 * 2. a service instance name. 89 * 3. a host name. 90 * 91 * The DNS-SD query implementation is responsible for identifying what @p aFullName is. 92 * 93 * @note There can be multiple subscription to the same name. DNS-SD query implementation should record the number of 94 * active subscriptions and stop notifying when there is no active subscription for @p aFullName. 95 * 96 * @param[in] aContext A pointer to the application-specific context. 97 * @param[in] aFullName The null-terminated full service name (e.g. "_ipps._tcp.default.service.arpa."), or 98 * full service instance name (e.g. "OpenThread._ipps._tcp.default.service.arpa."). 99 * 100 */ 101 typedef void (*otDnssdQueryUnsubscribeCallback)(void *aContext, const char *aFullName); 102 103 /** 104 * This opaque type represents a DNS-SD query. 105 * 106 */ 107 typedef void otDnssdQuery; 108 109 /** 110 * Represents information of a discovered service instance for a DNS-SD query. 111 * 112 */ 113 typedef struct otDnssdServiceInstanceInfo 114 { 115 const char *mFullName; ///< Full instance name (e.g. "OpenThread._ipps._tcp.default.service.arpa."). 116 const char *mHostName; ///< Host name (e.g. "ot-host.default.service.arpa."). 117 uint8_t mAddressNum; ///< Number of host IPv6 addresses. 118 const otIp6Address *mAddresses; ///< Host IPv6 addresses. 119 uint16_t mPort; ///< Service port. 120 uint16_t mPriority; ///< Service priority. 121 uint16_t mWeight; ///< Service weight. 122 uint16_t mTxtLength; ///< Service TXT RDATA length. 123 const uint8_t *mTxtData; ///< Service TXT RDATA. 124 uint32_t mTtl; ///< Service TTL (in seconds). 125 } otDnssdServiceInstanceInfo; 126 127 /** 128 * Represents information of a discovered host for a DNS-SD query. 129 * 130 */ 131 typedef struct otDnssdHostInfo 132 { 133 uint8_t mAddressNum; ///< Number of host IPv6 addresses. 134 const otIp6Address *mAddresses; ///< Host IPv6 addresses. 135 uint32_t mTtl; ///< Service TTL (in seconds). 136 } otDnssdHostInfo; 137 138 /** 139 * Specifies a DNS-SD query type. 140 * 141 */ 142 typedef enum 143 { 144 OT_DNSSD_QUERY_TYPE_NONE = 0, ///< Service type unspecified. 145 OT_DNSSD_QUERY_TYPE_BROWSE = 1, ///< Service type browse service. 146 OT_DNSSD_QUERY_TYPE_RESOLVE = 2, ///< Service type resolve service instance. 147 OT_DNSSD_QUERY_TYPE_RESOLVE_HOST = 3, ///< Service type resolve hostname. 148 } otDnssdQueryType; 149 150 /** 151 * Contains the counters of DNS-SD server. 152 * 153 */ 154 typedef struct otDnssdCounters 155 { 156 uint32_t mSuccessResponse; ///< The number of successful responses 157 uint32_t mServerFailureResponse; ///< The number of server failure responses 158 uint32_t mFormatErrorResponse; ///< The number of format error responses 159 uint32_t mNameErrorResponse; ///< The number of name error responses 160 uint32_t mNotImplementedResponse; ///< The number of 'not implemented' responses 161 uint32_t mOtherResponse; ///< The number of other responses 162 163 uint32_t mResolvedBySrp; ///< The number of queries completely resolved by the local SRP server 164 } otDnssdCounters; 165 166 /** 167 * Sets DNS-SD server query callbacks. 168 * 169 * The DNS-SD server calls @p aSubscribe to subscribe to a service or service instance to resolve a DNS-SD query and @p 170 * aUnsubscribe to unsubscribe when the query is resolved or timeout. 171 * 172 * @note @p aSubscribe and @p aUnsubscribe must be both set or unset. 173 * 174 * @param[in] aInstance The OpenThread instance structure. 175 * @param[in] aSubscribe A pointer to the callback function to subscribe a service or service instance. 176 * @param[in] aUnsubscribe A pointer to the callback function to unsubscribe a service or service instance. 177 * @param[in] aContext A pointer to the application-specific context. 178 * 179 */ 180 void otDnssdQuerySetCallbacks(otInstance *aInstance, 181 otDnssdQuerySubscribeCallback aSubscribe, 182 otDnssdQueryUnsubscribeCallback aUnsubscribe, 183 void *aContext); 184 185 /** 186 * Notifies a discovered service instance. 187 * 188 * The external query resolver (e.g. Discovery Proxy) should call this function to notify OpenThread core of the 189 * subscribed services or service instances. 190 * 191 * @note @p aInstanceInfo must not contain unspecified or link-local or loop-back or multicast IP addresses. 192 * 193 * @param[in] aInstance The OpenThread instance structure. 194 * @param[in] aServiceFullName The null-terminated full service name. 195 * @param[in] aInstanceInfo A pointer to the discovered service instance information. 196 * 197 */ 198 void otDnssdQueryHandleDiscoveredServiceInstance(otInstance *aInstance, 199 const char *aServiceFullName, 200 otDnssdServiceInstanceInfo *aInstanceInfo); 201 /** 202 * Notifies a discovered host. 203 * 204 * The external query resolver (e.g. Discovery Proxy) should call this function to notify OpenThread core of the 205 * subscribed hosts. 206 * 207 * @note @p aHostInfo must not contain unspecified or link-local or loop-back or multicast IP addresses. 208 * 209 * @param[in] aInstance The OpenThread instance structure. 210 * @param[in] aHostFullName The null-terminated full host name. 211 * @param[in] aHostInfo A pointer to the discovered service instance information. 212 * 213 */ 214 void otDnssdQueryHandleDiscoveredHost(otInstance *aInstance, const char *aHostFullName, otDnssdHostInfo *aHostInfo); 215 216 /** 217 * Acquires the next query in the DNS-SD server. 218 * 219 * @param[in] aInstance The OpenThread instance structure. 220 * @param[in] aQuery The query pointer. Pass NULL to get the first query. 221 * 222 * @returns A pointer to the query or NULL if no more queries. 223 * 224 */ 225 const otDnssdQuery *otDnssdGetNextQuery(otInstance *aInstance, const otDnssdQuery *aQuery); 226 227 /** 228 * Acquires the DNS-SD query type and name for a specific query. 229 * 230 * @param[in] aQuery The query pointer acquired from `otDnssdGetNextQuery`. 231 * @param[out] aNameOutput The name output buffer, which should be `OT_DNS_MAX_NAME_SIZE` bytes long. 232 * 233 * @returns The DNS-SD query type. 234 * 235 */ 236 otDnssdQueryType otDnssdGetQueryTypeAndName(const otDnssdQuery *aQuery, char (*aNameOutput)[OT_DNS_MAX_NAME_SIZE]); 237 238 /** 239 * Returns the counters of the DNS-SD server. 240 * 241 * @param[in] aInstance The OpenThread instance structure. 242 * 243 * @returns A pointer to the counters of the DNS-SD server. 244 * 245 */ 246 const otDnssdCounters *otDnssdGetCounters(otInstance *aInstance); 247 248 /** 249 * Enable or disable forwarding DNS queries to platform DNS upstream API. 250 * 251 * Available when `OPENTHREAD_CONFIG_DNS_UPSTREAM_QUERY_ENABLE` is enabled. 252 * 253 * @param[in] aInstance A pointer to an OpenThread instance. 254 * @param[in] aEnabled A boolean to enable/disable forwarding DNS queries to upstream. 255 * 256 * @sa otPlatDnsStartUpstreamQuery 257 * @sa otPlatDnsCancelUpstreamQuery 258 * @sa otPlatDnsUpstreamQueryDone 259 * 260 */ 261 void otDnssdUpstreamQuerySetEnabled(otInstance *aInstance, bool aEnabled); 262 263 /** 264 * Returns whether the DNSSD server will forward DNS queries to the platform DNS upstream API. 265 * 266 * Available when `OPENTHREAD_CONFIG_DNS_UPSTREAM_QUERY_ENABLE` is enabled. 267 * 268 * @param[in] aInstance A pointer to an OpenThread instance. 269 * @retval TRUE If the DNSSD server will forward DNS queries. 270 * @retval FALSE If the DNSSD server will not forward DNS queries. 271 * 272 * @sa otDnssdUpstreamQuerySetEnabled 273 * 274 */ 275 bool otDnssdUpstreamQueryIsEnabled(otInstance *aInstance); 276 277 /** 278 * @} 279 * 280 */ 281 282 #ifdef __cplusplus 283 } // extern "C" 284 #endif 285 286 #endif // OPENTHREAD_DNSSD_SERVER_H_ 287
