Zephyr API Documentation  3.7.0-rc2
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
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, \
}
#define STRUCT_SECTION_ITERABLE(struct_type, varname)
Defines a new element for an iterable section.
Definition: iterable_sections.h:216
DNS Service Discovery record.
Definition: dns_sd.h:217

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
_idvariable name for the DNS-SD service record
_instancename of the service instance such as "My HTTP Server"
_servicename of the service, such as "_http"
_protoprotocol used by the service - either "_tcp" or "_udp"
_domainthe domain of the service, such as "local"
_textinformation for the DNS TXT record
_porta 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)
__UINT16_TYPE__ uint16_t
Definition: stdint.h:89
#define sys_cpu_to_be16(val)
Convert 16-bit integer from host endianness to big-endian.
Definition: byteorder.h:278

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):

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);
DNS Service Discovery.
#define DNS_SD_REGISTER_TCP_SERVICE(id, instance, service, domain, text, port)
Register a TCP service for DNS Service Discovery.
Definition: dns_sd.h:161

{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
idvariable name for the DNS-SD service record
instancename of the service instance such as "My HTTP Server"
servicename of the service, such as "_http"
domainthe domain of the service, such as "local"
textinformation for the DNS TXT record
portthe 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):

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);
#define DNS_SD_EMPTY_TXT
Empty DNS-SD TXT specifier.
Definition: dns_sd.h:199
#define DNS_SD_REGISTER_UDP_SERVICE(id, instance, service, domain, text, port)
Register a UDP service for DNS Service Discovery.
Definition: dns_sd.h:192
Byte order helpers.

{c}

Parameters
idvariable name for the DNS-SD service record
instancename of the service instance such as "My TFTP Server"
servicename of the service, such as "_tftp"
domainthe domain of the service, such as "local" or "zephyrproject.org"
textinformation for the DNS TXT record
porta 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
filtera 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
recthe 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
recthe record to in question
Returns
the size of the text field