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