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 * Represents the count of queries, responses, failures handled by upstream DNS server. 152 * 153 * Requires `OPENTHREAD_CONFIG_DNS_UPSTREAM_QUERY_ENABLE`. 154 */ 155 typedef struct otUpstreamDnsCounters 156 { 157 uint32_t mQueries; ///< The number of queries forwarded. 158 uint32_t mResponses; ///< The number of responses forwarded. 159 uint32_t mFailures; ///< The number of upstream DNS failures. 160 } otUpstreamDnsCounters; 161 162 /** 163 * Contains the counters of DNS-SD server. 164 * 165 */ 166 typedef struct otDnssdCounters 167 { 168 uint32_t mSuccessResponse; ///< The number of successful responses. 169 uint32_t mServerFailureResponse; ///< The number of server failure responses. 170 uint32_t mFormatErrorResponse; ///< The number of format error responses. 171 uint32_t mNameErrorResponse; ///< The number of name error responses. 172 uint32_t mNotImplementedResponse; ///< The number of 'not implemented' responses. 173 uint32_t mOtherResponse; ///< The number of other responses. 174 uint32_t mResolvedBySrp; ///< The number of queries resolved by the local SRP server. 175 otUpstreamDnsCounters mUpstreamDnsCounters; ///< The number of queries, responses, 176 ///< failures handled by upstream DNS server. 177 } otDnssdCounters; 178 179 /** 180 * Sets DNS-SD server query callbacks. 181 * 182 * The DNS-SD server calls @p aSubscribe to subscribe to a service or service instance to resolve a DNS-SD query and @p 183 * aUnsubscribe to unsubscribe when the query is resolved or timeout. 184 * 185 * @note @p aSubscribe and @p aUnsubscribe must be both set or unset. 186 * 187 * @param[in] aInstance The OpenThread instance structure. 188 * @param[in] aSubscribe A pointer to the callback function to subscribe a service or service instance. 189 * @param[in] aUnsubscribe A pointer to the callback function to unsubscribe a service or service instance. 190 * @param[in] aContext A pointer to the application-specific context. 191 * 192 */ 193 void otDnssdQuerySetCallbacks(otInstance *aInstance, 194 otDnssdQuerySubscribeCallback aSubscribe, 195 otDnssdQueryUnsubscribeCallback aUnsubscribe, 196 void *aContext); 197 198 /** 199 * Notifies a discovered service instance. 200 * 201 * The external query resolver (e.g. Discovery Proxy) should call this function to notify OpenThread core of the 202 * subscribed services or service instances. 203 * 204 * @note @p aInstanceInfo must not contain unspecified or link-local or loop-back or multicast IP addresses. 205 * 206 * @param[in] aInstance The OpenThread instance structure. 207 * @param[in] aServiceFullName The null-terminated full service name. 208 * @param[in] aInstanceInfo A pointer to the discovered service instance information. 209 * 210 */ 211 void otDnssdQueryHandleDiscoveredServiceInstance(otInstance *aInstance, 212 const char *aServiceFullName, 213 otDnssdServiceInstanceInfo *aInstanceInfo); 214 /** 215 * Notifies a discovered host. 216 * 217 * The external query resolver (e.g. Discovery Proxy) should call this function to notify OpenThread core of the 218 * subscribed hosts. 219 * 220 * @note @p aHostInfo must not contain unspecified or link-local or loop-back or multicast IP addresses. 221 * 222 * @param[in] aInstance The OpenThread instance structure. 223 * @param[in] aHostFullName The null-terminated full host name. 224 * @param[in] aHostInfo A pointer to the discovered service instance information. 225 * 226 */ 227 void otDnssdQueryHandleDiscoveredHost(otInstance *aInstance, const char *aHostFullName, otDnssdHostInfo *aHostInfo); 228 229 /** 230 * Acquires the next query in the DNS-SD server. 231 * 232 * @param[in] aInstance The OpenThread instance structure. 233 * @param[in] aQuery The query pointer. Pass NULL to get the first query. 234 * 235 * @returns A pointer to the query or NULL if no more queries. 236 * 237 */ 238 const otDnssdQuery *otDnssdGetNextQuery(otInstance *aInstance, const otDnssdQuery *aQuery); 239 240 /** 241 * Acquires the DNS-SD query type and name for a specific query. 242 * 243 * @param[in] aQuery The query pointer acquired from `otDnssdGetNextQuery`. 244 * @param[out] aNameOutput The name output buffer, which should be `OT_DNS_MAX_NAME_SIZE` bytes long. 245 * 246 * @returns The DNS-SD query type. 247 * 248 */ 249 otDnssdQueryType otDnssdGetQueryTypeAndName(const otDnssdQuery *aQuery, char (*aNameOutput)[OT_DNS_MAX_NAME_SIZE]); 250 251 /** 252 * Returns the counters of the DNS-SD server. 253 * 254 * @param[in] aInstance The OpenThread instance structure. 255 * 256 * @returns A pointer to the counters of the DNS-SD server. 257 * 258 */ 259 const otDnssdCounters *otDnssdGetCounters(otInstance *aInstance); 260 261 /** 262 * Enable or disable forwarding DNS queries to 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 * @param[in] aEnabled A boolean to enable/disable forwarding DNS queries to upstream. 268 * 269 * @sa otPlatDnsStartUpstreamQuery 270 * @sa otPlatDnsCancelUpstreamQuery 271 * @sa otPlatDnsUpstreamQueryDone 272 * 273 */ 274 void otDnssdUpstreamQuerySetEnabled(otInstance *aInstance, bool aEnabled); 275 276 /** 277 * Returns whether the DNSSD server will forward DNS queries to the platform DNS upstream API. 278 * 279 * Available when `OPENTHREAD_CONFIG_DNS_UPSTREAM_QUERY_ENABLE` is enabled. 280 * 281 * @param[in] aInstance A pointer to an OpenThread instance. 282 * @retval TRUE If the DNSSD server will forward DNS queries. 283 * @retval FALSE If the DNSSD server will not forward DNS queries. 284 * 285 * @sa otDnssdUpstreamQuerySetEnabled 286 * 287 */ 288 bool otDnssdUpstreamQueryIsEnabled(otInstance *aInstance); 289 290 /** 291 * @} 292 * 293 */ 294 295 #ifdef __cplusplus 296 } // extern "C" 297 #endif 298 299 #endif // OPENTHREAD_DNSSD_SERVER_H_ 300
