DNS Service Discovery

DNS Service Discovery. More...

Data Structures
struct	dns_sd_rec
	DNS Service Discovery record. More...

Macros
#define	DNS_SD_INSTANCE_MIN_SIZE   1
	RFC 1034 Section 3.1.
#define	DNS_SD_INSTANCE_MAX_SIZE   63
	RFC 1034 Section 3.1, RFC 6763 Section 7.2.
#define	DNS_SD_SERVICE_MIN_SIZE   2
	RFC 6763 Section 7.2 - inclusive of underscore.
#define	DNS_SD_SERVICE_MAX_SIZE   16
	RFC 6763 Section 7.2 - inclusive of underscore.
#define	DNS_SD_SERVICE_PREFIX   '_'
	RFC 6763 Section 4.1.2.
#define	DNS_SD_PROTO_SIZE   4
	RFC 6763 Section 4.1.2 - either _tcp or _udp (case insensitive)
#define	DNS_SD_DOMAIN_MIN_SIZE   2
	ICANN Rules for TLD naming.
#define	DNS_SD_DOMAIN_MAX_SIZE   63
	RFC 1034 Section 3.1, RFC 6763 Section 7.2.
#define	DNS_SD_MIN_LABELS   3
	Minimum number of segments in a fully-qualified name.
#define	DNS_SD_MAX_LABELS   4
	Maximum number of segments in a fully-qualified name.
#define	DNS_SD_REGISTER_SERVICE(_id, _instance, _service, _proto, _domain, _text, _port)
	Register a service for DNS Service Discovery.
#define	DNS_SD_REGISTER_TCP_SERVICE(id, instance, service, domain, text, port)
	Register a TCP service for DNS Service Discovery.
#define	DNS_SD_REGISTER_UDP_SERVICE(id, instance, service, domain, text, port)
	Register a UDP service for DNS Service Discovery.
#define	DNS_SD_EMPTY_TXT   dns_sd_empty_txt
	Empty DNS-SD TXT specifier.

Functions
static size_t	dns_sd_txt_size (const struct dns_sd_rec *rec)
	Obtain the size of DNS-SD TXT data.
bool	dns_sd_is_service_type_enumeration (const struct dns_sd_rec *rec)
	Check if rec is a DNS-SD Service Type Enumeration.
void	dns_sd_create_wildcard_filter (struct dns_sd_rec *filter)
	Create a wildcard filter for DNS-SD records.

Detailed Description

DNS Service Discovery.

This API enables services to be advertised via DNS. To advertise a service, system or application code should use DNS_SD_REGISTER_TCP_SERVICE or DNS_SD_REGISTER_UDP_SERVICE.

See also

RFC 6763

Macro Definition Documentation

DNS_SD_DOMAIN_MAX_SIZE

#define DNS_SD_DOMAIN_MAX_SIZE   63

#include <zephyr/net/dns_sd.h>

RFC 1034 Section 3.1, RFC 6763 Section 7.2.

DNS_SD_DOMAIN_MIN_SIZE

#define DNS_SD_DOMAIN_MIN_SIZE   2

#include <zephyr/net/dns_sd.h>

ICANN Rules for TLD naming.

DNS_SD_EMPTY_TXT

#define DNS_SD_EMPTY_TXT   dns_sd_empty_txt

#include <zephyr/net/dns_sd.h>

Empty DNS-SD TXT specifier.

DNS_SD_INSTANCE_MAX_SIZE

#define DNS_SD_INSTANCE_MAX_SIZE   63

#include <zephyr/net/dns_sd.h>

RFC 1034 Section 3.1, RFC 6763 Section 7.2.

DNS_SD_INSTANCE_MIN_SIZE

#define DNS_SD_INSTANCE_MIN_SIZE   1

#include <zephyr/net/dns_sd.h>

RFC 1034 Section 3.1.

DNS_SD_MAX_LABELS

#define DNS_SD_MAX_LABELS   4

#include <zephyr/net/dns_sd.h>

Maximum number of segments in a fully-qualified name.

This represents FQN's of the form below

<instance>.<sn>._tcp.<domain>.

Currently sub-types and service domains are unsupported and only the "local" domain is supported. Specifically, that excludes the following:

<sub>._sub.<sn>._tcp.<servicedomain>.<parentdomain>.

See also

RFC 6763, Section 7.2.

DNS_SD_MIN_LABELS

#define DNS_SD_MIN_LABELS   3

#include <zephyr/net/dns_sd.h>

Minimum number of segments in a fully-qualified name.

This represents FQN's of the form below

<sn>._tcp.<domain>.

Currently sub-types and service domains are unsupported and only the "local" domain is supported. Specifically, that excludes the following:

<sub>._sub.<sn>._tcp.<servicedomain>.<parentdomain>.

See also

RFC 6763, Section 7.2.

DNS_SD_PROTO_SIZE

#define DNS_SD_PROTO_SIZE   4

#include <zephyr/net/dns_sd.h>

RFC 6763 Section 4.1.2 - either _tcp or _udp (case insensitive)

DNS_SD_REGISTER_SERVICE

#define DNS_SD_REGISTER_SERVICE	(		_id,
			_instance,
			_service,
			_proto,
			_domain,
			_text,
			_port
	)

#include <zephyr/net/dns_sd.h>

Value:

        static const STRUCT_SECTION_ITERABLE(dns_sd_rec, _id) = {       \
                .instance = _instance,                                  \
                .service = _service,                                    \
                .proto = _proto,                                        \
                .domain = _domain,                                      \
                .text = (const char *)_text,                            \
                .text_size = sizeof(_text) - 1,                         \
                .port = _port,                                          \
        }

Register a service for DNS Service Discovery.

This macro should be used for advanced use cases. Two simple use cases are when a custom _domain or a custom (non-standard) _proto is required.

Another use case is when the port number is not preassigned. That could be for a number of reasons, but the most common use case would be for ephemeral port usage - i.e. when the service is bound using port number 0. In that case, Zephyr (like other OS's) will simply choose an unused port. When using ephemeral ports, it can be helpful to assign _port to the sockaddr_in::sin_port field of an IPv4 sockaddr_in, or to the sockaddr_in6::sin6_port field of an IPv6 sockaddr_in6.

The service can be referenced using the _id variable.

Parameters

_id	variable name for the DNS-SD service record
_instance	name of the service instance such as "My HTTP Server"
_service	name of the service, such as "_http"
_proto	protocol used by the service - either "_tcp" or "_udp"
_domain	the domain of the service, such as "local"
_text	information for the DNS TXT record
_port	a pointer to the port number that this service will use

DNS_SD_REGISTER_TCP_SERVICE

#define DNS_SD_REGISTER_TCP_SERVICE	(		id,
			instance,
			service,
			domain,
			text,
			port
	)

#include <zephyr/net/dns_sd.h>

Value:

        static const uint16_t id ## _port = sys_cpu_to_be16(port); \
        DNS_SD_REGISTER_SERVICE(id, instance, service, "_tcp", domain,   \
                                text, &id ## _port)

Register a TCP service for DNS Service Discovery.

This macro can be used for service advertisement using DNS-SD.

The service can be referenced using the id variable.

Example (with TXT):

#include <zephyr/net/dns_sd.h>
static const bar_txt[] = {
  "\x06" "path=/"
  "\x0f" "this=is the way"
  "\x0e" "foo or=foo not"
  "\x17" "this=has\0embedded\0nulls"
  "\x04" "true"
};
// Possibly use an ephemeral port
// Possibly only assign bar_port when the service is running
static uint16_t bar_port;
DNS_SD_REGISTER_TCP_SERVICE(bar, CONFIG_NET_HOSTNAME,
  "_bar", "local", bar_txt, &bar_port);

{c}

TXT records begin with a single length byte (hex-encoded) and contain key=value pairs. Thus, the length of the key-value pair must not exceed 255 bytes. Care must be taken to ensure that the encoded length value is correct.

For additional rules on TXT encoding, see RFC 6763, Section 6.

Parameters

id	variable name for the DNS-SD service record
instance	name of the service instance such as "My HTTP Server"
service	name of the service, such as "_http"
domain	the domain of the service, such as "local"
text	information for the DNS TXT record
port	the port number that this service will use

See also

RFC 6763

DNS_SD_REGISTER_UDP_SERVICE

#define DNS_SD_REGISTER_UDP_SERVICE	(		id,
			instance,
			service,
			domain,
			text,
			port
	)

#include <zephyr/net/dns_sd.h>

Value:

        static const uint16_t id ## _port = sys_cpu_to_be16(port); \
        DNS_SD_REGISTER_SERVICE(id, instance, service, "_udp", domain,   \
                                text, &id ## _port)

Register a UDP service for DNS Service Discovery.

This macro can be used for service advertisement using DNS-SD.

The service can be referenced using the id variable.

Example (no TXT):

#include <zephyr/net/dns_sd.h>
#include <zephyr/sys/byteorder.h>
static const foo_port = sys_cpu_to_be16(4242);
DNS_SD_REGISTER_UDP_SERVICE(foo, CONFIG_NET_HOSTNAME,
  "_foo", DNS_SD_EMPTY_TXT, &foo_port);

{c}

Parameters

id	variable name for the DNS-SD service record
instance	name of the service instance such as "My TFTP Server"
service	name of the service, such as "_tftp"
domain	the domain of the service, such as "local" or "zephyrproject.org"
text	information for the DNS TXT record
port	a pointer to the port number that this service will use

See also

RFC 6763

DNS_SD_SERVICE_MAX_SIZE

#define DNS_SD_SERVICE_MAX_SIZE   16

#include <zephyr/net/dns_sd.h>

RFC 6763 Section 7.2 - inclusive of underscore.

DNS_SD_SERVICE_MIN_SIZE

#define DNS_SD_SERVICE_MIN_SIZE   2

#include <zephyr/net/dns_sd.h>

RFC 6763 Section 7.2 - inclusive of underscore.

DNS_SD_SERVICE_PREFIX

#define DNS_SD_SERVICE_PREFIX   '_'

#include <zephyr/net/dns_sd.h>

RFC 6763 Section 4.1.2.

Function Documentation

dns_sd_create_wildcard_filter()

void dns_sd_create_wildcard_filter

(

struct dns_sd_rec *

filter

)

#include <zephyr/net/dns_sd.h>

Create a wildcard filter for DNS-SD records.

Parameters

filter

a pointer to the filter to use

dns_sd_is_service_type_enumeration()

bool dns_sd_is_service_type_enumeration

(

const struct dns_sd_rec *

rec

)

#include <zephyr/net/dns_sd.h>

Check if rec is a DNS-SD Service Type Enumeration.

DNS-SD Service Type Enumeration is used by network tooling to acquire a list of all mDNS-advertised services belonging to a particular host on a particular domain.

For example, for the domain '.local', the equivalent query would be '_services._dns-sd._udp.local'.

Currently, only the '.local' domain is supported.

See also

Service Type Enumeration, RFC 6763.

Parameters

rec	the record to in question

Returns

true if rec is a DNS-SD Service Type Enumeration

dns_sd_txt_size()

static size_t dns_sd_txt_size ( const struct dns_sd_rec *  rec )

inlinestatic

#include <zephyr/net/dns_sd.h>

Obtain the size of DNS-SD TXT data.

Parameters

rec	the record to in question

Returns

the size of the text field