include/openthread/dnssd_server.h - third_party/openthread - Git at Google

 /*
  *  Copyright (c) 2021, The OpenThread Authors.
  *  All rights reserved.
  *
  *  Redistribution and use in source and binary forms, with or without
  *  modification, are permitted provided that the following conditions are met:
  *  1. Redistributions of source code must retain the above copyright
  *     notice, this list of conditions and the following disclaimer.
  *  2. Redistributions in binary form must reproduce the above copyright
  *     notice, this list of conditions and the following disclaimer in the
  *     documentation and/or other materials provided with the distribution.
  *  3. Neither the name of the copyright holder nor the
  *     names of its contributors may be used to endorse or promote products
  *     derived from this software without specific prior written permission.
  *
  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  *  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  *  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  *  ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
  *  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  *  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  *  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  *  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  *  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  *  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  *  POSSIBILITY OF SUCH DAMAGE.
  */

 /**
  * @file
  * @brief
  *  This file defines the DNS-SD server APIs.
  */

 #ifndef OPENTHREAD_DNSSD_SERVER_H_
 #define OPENTHREAD_DNSSD_SERVER_H_

 #include <stdint.h>

 #include <openthread/dns.h>
 #include <openthread/error.h>
 #include <openthread/ip6.h>

 #ifdef __cplusplus
 extern "C" {
 #endif

 /**
  * @addtogroup api-dnssd-server
  *
  * @brief
  *   This module includes APIs for DNS-SD server.
  *
  * @{
  *
  */

 /**
  * This function is called when a DNS-SD query subscribes one of:
  *      1. a service name.
  *      2. a service instance name.
  *      3. a host name.
  *
  * The DNS-SD query implementation is responsible for identifying what @p aFullName is.
  * If @p aFullName is a service name or service instance name, the DNS-SD query implementation should discover
  * corresponding service instance information and notify the DNS-SD server using
  * `otDnssdQueryHandleDiscoveredServiceInstance`.
  * If @p aFullName is a host name, the DNS-SD query implementation should
  * discover the host information and notify the DNS-SD server using `otDnssdQueryHandleDiscoveredHost`.
  *
  * @note There can be multiple subscription to the same name. DNS-SD query implementation should record the number of
  * active subscriptions and stop notifying when there is no active subscription for @p aFullName.
  *
  * @param[in] aContext      A pointer to the application-specific context.
  * @param[in] aFullName     The null-terminated full service name (e.g. "_ipps._tcp.default.service.arpa."),
  *                          or full service instance name (e.g. "OpenThread._ipps._tcp.default.service.arpa."),
  *                          or full host name (e.g. "ot-host.default.service.arpa.").
  *
  * @sa otDnssdQueryHandleDiscoveredServiceInstance
  * @sa otDnssdQueryHandleDiscoveredHost
  *
  */
 typedef void (*otDnssdQuerySubscribeCallback)(void *aContext, const char *aFullName);

 /**
  * This function is called when a DNS-SD query unsubscribes one of:
  *      1. a service name.
  *      2. a service instance name.
  *      3. a host name.
  *
  * The DNS-SD query implementation is responsible for identifying what @p aFullName is.
  *
  * @note There can be multiple subscription to the same name. DNS-SD query implementation should record the number of
  * active subscriptions and stop notifying when there is no active subscription for @p aFullName.
  *
  * @param[in] aContext      A pointer to the application-specific context.
  * @param[in] aFullName     The null-terminated full service name (e.g. "_ipps._tcp.default.service.arpa."), or
  *                          full service instance name (e.g. "OpenThread._ipps._tcp.default.service.arpa.").
  *
  */
 typedef void (*otDnssdQueryUnsubscribeCallback)(void *aContext, const char *aFullName);

 /**
  * This opaque type represents a DNS-SD query.
  *
  */
 typedef void otDnssdQuery;

 /**
  * This structure represents information of a discovered service instance for a DNS-SD query.
  *
  */
 typedef struct otDnssdServiceInstanceInfo
 {
     const char *        mFullName;   ///< Full instance name (e.g. "OpenThread._ipps._tcp.default.service.arpa.").
     const char *        mHostName;   ///< Host name (e.g. "ot-host.default.service.arpa.").
     uint8_t             mAddressNum; ///< Number of host IPv6 addresses.
     const otIp6Address *mAddresses;  ///< Host IPv6 addresses.
     uint16_t            mPort;       ///< Service port.
     uint16_t            mPriority;   ///< Service priority.
     uint16_t            mWeight;     ///< Service weight.
     uint16_t            mTxtLength;  ///< Service TXT RDATA length.
     const uint8_t *     mTxtData;    ///< Service TXT RDATA.
     uint32_t            mTtl;        ///< Service TTL (in seconds).
 } otDnssdServiceInstanceInfo;

 /**
  * This structure represents information of a discovered host for a DNS-SD query.
  *
  */
 typedef struct otDnssdHostInfo
 {
     uint8_t             mAddressNum; ///< Number of host IPv6 addresses.
     const otIp6Address *mAddresses;  ///< Host IPv6 addresses.
     uint32_t            mTtl;        ///< Service TTL (in seconds).
 } otDnssdHostInfo;

 /**
  * This enumeration specifies a DNS-SD query type.
  *
  */
 typedef enum
 {
     OT_DNSSD_QUERY_TYPE_NONE         = 0, ///< Service type unspecified.
     OT_DNSSD_QUERY_TYPE_BROWSE       = 1, ///< Service type browse service.
     OT_DNSSD_QUERY_TYPE_RESOLVE      = 2, ///< Service type resolve service instance.
     OT_DNSSD_QUERY_TYPE_RESOLVE_HOST = 3, ///< Service type resolve hostname.
 } otDnssdQueryType;

 /**
  * This function sets DNS-SD server query callbacks.
  *
  * The DNS-SD server calls @p aSubscribe to subscribe to a service or service instance to resolve a DNS-SD query and @p
  * aUnsubscribe to unsubscribe when the query is resolved or timeout.
  *
  * @note @p aSubscribe and @p aUnsubscribe must be both set or unset.
  *
  * @param[in] aInstance     The OpenThread instance structure.
  * @param[in] aSubscribe    A pointer to the callback function to subscribe a service or service instance.
  * @param[in] aUnsubscribe  A pointer to the callback function to unsubscribe a service or service instance.
  * @param[in] aContext      A pointer to the application-specific context.
  *
  */
 void otDnssdQuerySetCallbacks(otInstance *                    aInstance,
                               otDnssdQuerySubscribeCallback   aSubscribe,
                               otDnssdQueryUnsubscribeCallback aUnsubscribe,
                               void *                          aContext);

 /**
  * This function notifies a discovered service instance.
  *
  * The external query resolver (e.g. Discovery Proxy) should call this function to notify OpenThread core of the
  * subscribed services or service instances.
  *
  * @note @p aInstanceInfo must not contain unspecified or link-local or loop-back or multicast IP addresses.
  *
  * @param[in] aInstance         The OpenThread instance structure.
  * @param[in] aServiceFullName  The null-terminated full service name.
  * @param[in] aInstanceInfo     A pointer to the discovered service instance information.
  *
  */
 void otDnssdQueryHandleDiscoveredServiceInstance(otInstance *                aInstance,
                                                  const char *                aServiceFullName,
                                                  otDnssdServiceInstanceInfo *aInstanceInfo);
 /**
  * This function notifies a discovered host.
  *
  * The external query resolver (e.g. Discovery Proxy) should call this function to notify OpenThread core of the
  * subscribed hosts.
  *
  * @note @p aHostInfo must not contain unspecified or link-local or loop-back or multicast IP addresses.
  *
  * @param[in] aInstance         The OpenThread instance structure.
  * @param[in] aHostFullName     The null-terminated full host name.
  * @param[in] aHostInfo         A pointer to the discovered service instance information.
  *
  */
 void otDnssdQueryHandleDiscoveredHost(otInstance *aInstance, const char *aHostFullName, otDnssdHostInfo *aHostInfo);

 /**
  * This function acquires the next query in the DNS-SD server.
  *
  * @param[in] aInstance         The OpenThread instance structure.
  * @param[in] aQuery            The query pointer. Pass NULL to get the first query.
  *
  * @returns  A pointer to the query or NULL if no more queries.
  *
  */
 const otDnssdQuery *otDnssdGetNextQuery(otInstance *aInstance, const otDnssdQuery *aQuery);

 /**
  * This function acquires the DNS-SD query type and name for a specific query.
  *
  * @param[in]   aQuery            The query pointer acquired from `otDnssdGetNextQuery`.
  * @param[out]  aNameOutput       The name output buffer, which should be `OT_DNS_MAX_NAME_SIZE` bytes long.
  *
  * @returns The DNS-SD query type.
  *
  */
 otDnssdQueryType otDnssdGetQueryTypeAndName(const otDnssdQuery *aQuery, char (*aNameOutput)[OT_DNS_MAX_NAME_SIZE]);

 /**
  * @}
  *
  */

 #ifdef __cplusplus
 } // extern "C"
 #endif

 #endif // OPENTHREAD_DNSSD_SERVER_H_
	/*
	* Copyright (c) 2021, The OpenThread Authors.
	* All rights reserved.
	*
	* Redistribution and use in source and binary forms, with or without
	* modification, are permitted provided that the following conditions are met:
	* 1. Redistributions of source code must retain the above copyright
	* notice, this list of conditions and the following disclaimer.
	* 2. Redistributions in binary form must reproduce the above copyright
	* notice, this list of conditions and the following disclaimer in the
	* documentation and/or other materials provided with the distribution.
	* 3. Neither the name of the copyright holder nor the
	* names of its contributors may be used to endorse or promote products
	* derived from this software without specific prior written permission.
	*
	* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
	* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	* ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
	* LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
	* CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
	* SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
	* INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
	* CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
	* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
	* POSSIBILITY OF SUCH DAMAGE.
	*/

	/**
	* @file
	* @brief
	* This file defines the DNS-SD server APIs.
	*/

	#ifndef OPENTHREAD_DNSSD_SERVER_H_
	#define OPENTHREAD_DNSSD_SERVER_H_

	#include <stdint.h>

	#include <openthread/dns.h>
	#include <openthread/error.h>
	#include <openthread/ip6.h>

	#ifdef __cplusplus
	extern "C" {
	#endif

	/**
	* @addtogroup api-dnssd-server
	*
	* @brief
	* This module includes APIs for DNS-SD server.
	*
	* @{
	*
	*/

	/**
	* This function is called when a DNS-SD query subscribes one of:
	* 1. a service name.
	* 2. a service instance name.
	* 3. a host name.
	*
	* The DNS-SD query implementation is responsible for identifying what @p aFullName is.
	* If @p aFullName is a service name or service instance name, the DNS-SD query implementation should discover
	* corresponding service instance information and notify the DNS-SD server using
	* `otDnssdQueryHandleDiscoveredServiceInstance`.
	* If @p aFullName is a host name, the DNS-SD query implementation should
	* discover the host information and notify the DNS-SD server using `otDnssdQueryHandleDiscoveredHost`.
	*
	* @note There can be multiple subscription to the same name. DNS-SD query implementation should record the number of
	* active subscriptions and stop notifying when there is no active subscription for @p aFullName.
	*
	* @param[in] aContext A pointer to the application-specific context.
	* @param[in] aFullName The null-terminated full service name (e.g. "_ipps._tcp.default.service.arpa."),
	* or full service instance name (e.g. "OpenThread._ipps._tcp.default.service.arpa."),
	* or full host name (e.g. "ot-host.default.service.arpa.").
	*
	* @sa otDnssdQueryHandleDiscoveredServiceInstance
	* @sa otDnssdQueryHandleDiscoveredHost
	*
	*/
	typedef void (otDnssdQuerySubscribeCallback)(void aContext, const char *aFullName);

	/**
	* This function is called when a DNS-SD query unsubscribes one of:
	* 1. a service name.
	* 2. a service instance name.
	* 3. a host name.
	*
	* The DNS-SD query implementation is responsible for identifying what @p aFullName is.
	*
	* @note There can be multiple subscription to the same name. DNS-SD query implementation should record the number of
	* active subscriptions and stop notifying when there is no active subscription for @p aFullName.
	*
	* @param[in] aContext A pointer to the application-specific context.
	* @param[in] aFullName The null-terminated full service name (e.g. "_ipps._tcp.default.service.arpa."), or
	* full service instance name (e.g. "OpenThread._ipps._tcp.default.service.arpa.").
	*
	*/
	typedef void (otDnssdQueryUnsubscribeCallback)(void aContext, const char *aFullName);

	/**
	* This opaque type represents a DNS-SD query.
	*
	*/
	typedef void otDnssdQuery;

	/**
	* This structure represents information of a discovered service instance for a DNS-SD query.
	*
	*/
	typedef struct otDnssdServiceInstanceInfo
	{
	const char * mFullName; ///< Full instance name (e.g. "OpenThread._ipps._tcp.default.service.arpa.").
	const char * mHostName; ///< Host name (e.g. "ot-host.default.service.arpa.").
	uint8_t mAddressNum; ///< Number of host IPv6 addresses.
	const otIp6Address *mAddresses; ///< Host IPv6 addresses.
	uint16_t mPort; ///< Service port.
	uint16_t mPriority; ///< Service priority.
	uint16_t mWeight; ///< Service weight.
	uint16_t mTxtLength; ///< Service TXT RDATA length.
	const uint8_t * mTxtData; ///< Service TXT RDATA.
	uint32_t mTtl; ///< Service TTL (in seconds).
	} otDnssdServiceInstanceInfo;

	/**
	* This structure represents information of a discovered host for a DNS-SD query.
	*
	*/
	typedef struct otDnssdHostInfo
	{
	uint8_t mAddressNum; ///< Number of host IPv6 addresses.
	const otIp6Address *mAddresses; ///< Host IPv6 addresses.
	uint32_t mTtl; ///< Service TTL (in seconds).
	} otDnssdHostInfo;

	/**
	* This enumeration specifies a DNS-SD query type.
	*
	*/
	typedef enum
	{
	OT_DNSSD_QUERY_TYPE_NONE = 0, ///< Service type unspecified.
	OT_DNSSD_QUERY_TYPE_BROWSE = 1, ///< Service type browse service.
	OT_DNSSD_QUERY_TYPE_RESOLVE = 2, ///< Service type resolve service instance.
	OT_DNSSD_QUERY_TYPE_RESOLVE_HOST = 3, ///< Service type resolve hostname.
	} otDnssdQueryType;

	/**
	* This function sets DNS-SD server query callbacks.
	*
	* The DNS-SD server calls @p aSubscribe to subscribe to a service or service instance to resolve a DNS-SD query and @p
	* aUnsubscribe to unsubscribe when the query is resolved or timeout.
	*
	* @note @p aSubscribe and @p aUnsubscribe must be both set or unset.
	*
	* @param[in] aInstance The OpenThread instance structure.
	* @param[in] aSubscribe A pointer to the callback function to subscribe a service or service instance.
	* @param[in] aUnsubscribe A pointer to the callback function to unsubscribe a service or service instance.
	* @param[in] aContext A pointer to the application-specific context.
	*
	*/
	void otDnssdQuerySetCallbacks(otInstance * aInstance,
	otDnssdQuerySubscribeCallback aSubscribe,
	otDnssdQueryUnsubscribeCallback aUnsubscribe,
	void * aContext);

	/**
	* This function notifies a discovered service instance.
	*
	* The external query resolver (e.g. Discovery Proxy) should call this function to notify OpenThread core of the
	* subscribed services or service instances.
	*
	* @note @p aInstanceInfo must not contain unspecified or link-local or loop-back or multicast IP addresses.
	*
	* @param[in] aInstance The OpenThread instance structure.
	* @param[in] aServiceFullName The null-terminated full service name.
	* @param[in] aInstanceInfo A pointer to the discovered service instance information.
	*
	*/
	void otDnssdQueryHandleDiscoveredServiceInstance(otInstance * aInstance,
	const char * aServiceFullName,
	otDnssdServiceInstanceInfo *aInstanceInfo);
	/**
	* This function notifies a discovered host.
	*
	* The external query resolver (e.g. Discovery Proxy) should call this function to notify OpenThread core of the
	* subscribed hosts.
	*
	* @note @p aHostInfo must not contain unspecified or link-local or loop-back or multicast IP addresses.
	*
	* @param[in] aInstance The OpenThread instance structure.
	* @param[in] aHostFullName The null-terminated full host name.
	* @param[in] aHostInfo A pointer to the discovered service instance information.
	*
	*/
	void otDnssdQueryHandleDiscoveredHost(otInstance aInstance, const char aHostFullName, otDnssdHostInfo *aHostInfo);

	/**
	* This function acquires the next query in the DNS-SD server.
	*
	* @param[in] aInstance The OpenThread instance structure.
	* @param[in] aQuery The query pointer. Pass NULL to get the first query.
	*
	* @returns A pointer to the query or NULL if no more queries.
	*
	*/
	const otDnssdQuery otDnssdGetNextQuery(otInstance aInstance, const otDnssdQuery *aQuery);

	/**
	* This function acquires the DNS-SD query type and name for a specific query.
	*
	* @param[in] aQuery The query pointer acquired from `otDnssdGetNextQuery`.
	* @param[out] aNameOutput The name output buffer, which should be `OT_DNS_MAX_NAME_SIZE` bytes long.
	*
	* @returns The DNS-SD query type.
	*
	*/
	otDnssdQueryType otDnssdGetQueryTypeAndName(const otDnssdQuery aQuery, char (aNameOutput)[OT_DNS_MAX_NAME_SIZE]);

	/**
	* @}
	*
	*/

	#ifdef __cplusplus
	} // extern "C"
	#endif

	#endif // OPENTHREAD_DNSSD_SERVER_H_