DNS Service Discovery

DNS Service Discovery. More...

Macros
#define	DNS_SD_INSTANCE_MIN_SIZE   1
#define	DNS_SD_INSTANCE_MAX_SIZE   63
#define	DNS_SD_SERVICE_MIN_SIZE   2
#define	DNS_SD_SERVICE_MAX_SIZE   16
#define	DNS_SD_SERVICE_PREFIX   '_'
#define	DNS_SD_PROTO_SIZE   4
#define	DNS_SD_DOMAIN_MIN_SIZE   2
#define	DNS_SD_DOMAIN_MAX_SIZE   63
#define	DNS_SD_REGISTER_SERVICE(id, instance, service, proto, domain, text, port)
	Register a service for DNS Service Discovery. More...
#define	DNS_SD_REGISTER_TCP_SERVICE(id, instance, service, domain, text, port)
	Register a TCP service for DNS Service Discovery. More...
#define	DNS_SD_REGISTER_UDP_SERVICE(id, instance, service, domain, text, port)
	Register a UDP service for DNS Service Discovery. More...
#define	DNS_SD_EMPTY_TXT   dns_sd_empty_txt

Functions
static size_t	dns_sd_txt_size (const struct dns_sd_rec *rec)
	Obtain the size of DNS-SD TXT data. More...

Detailed Description

DNS Service Discovery.

This API enables services to be advertised via DNS. To advvertise 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 <include/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 <include/net/dns_sd.h>

ICANN Rules for TLD naming

DNS_SD_EMPTY_TXT

#define DNS_SD_EMPTY_TXT   dns_sd_empty_txt

#include <include/net/dns_sd.h>

Empty DNS-SD TXT specifier

DNS_SD_INSTANCE_MAX_SIZE

#define DNS_SD_INSTANCE_MAX_SIZE   63

#include <include/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 <include/net/dns_sd.h>

RFC 1034 Section 3.1

DNS_SD_PROTO_SIZE

#define DNS_SD_PROTO_SIZE   4

#include <include/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 <include/net/dns_sd.h>

Value:

        static const STRUCT_SECTION_ITERABLE(dns_sd_rec, id) = {      \
                instance,                                             \
                service,                                              \
                proto,                                                \
                domain,                                               \
                (const char *)text,                                   \
                sizeof(text) - 1,                                     \
                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 <include/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 <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 <include/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 <net/dns_sd.h>
#include <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 <include/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 <include/net/dns_sd.h>

RFC 6763 Section 7.2 - inclusive of underscore

DNS_SD_SERVICE_PREFIX

#define DNS_SD_SERVICE_PREFIX   '_'

#include <include/net/dns_sd.h>

RFC 6763 Section 4.1.2

Function Documentation

dns_sd_txt_size()

static size_t dns_sd_txt_size ( const struct dns_sd_rec *  rec )

inlinestatic

#include <include/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