From 88671dbbba21591d3fd5e1405dd14066a63a9372 Mon Sep 17 00:00:00 2001 From: Jukka Rissanen Date: Mon, 16 Jun 2025 18:16:03 +0300 Subject: [PATCH] net: doc: Add information of DNS service discovery Add documentation how to do DNS service discovery queries. Signed-off-by: Jukka Rissanen --- .../networking/api/dns_resolve.rst | 107 ++++++++++++++++++ 1 file changed, 107 insertions(+) diff --git a/doc/connectivity/networking/api/dns_resolve.rst b/doc/connectivity/networking/api/dns_resolve.rst index d119fc74190..605a26a1f4f 100644 --- a/doc/connectivity/networking/api/dns_resolve.rst +++ b/doc/connectivity/networking/api/dns_resolve.rst @@ -32,6 +32,113 @@ For more information about DNS configuration variables, see: :zephyr_file:`subsys/net/lib/dns/Kconfig`. The DNS resolver API can be found at :zephyr_file:`include/zephyr/net/dns_resolve.h`. +DNS-based service discovery queries described in +`IETF RFC6763 `_ +can be done by :c:func:`dns_resolve_service` API. +The returned service descriptions are passed to user supplied callback +and the API sets the address family to :c:macro:`AF_LOCAL` to indicate that +the value is not an IPv4 or IPv6 address but a service description. + +Example: + +.. code-block:: c + + #include + + #define MAX_STR_LEN CONFIG_DNS_RESOLVER_MAX_NAME_LEN + + static void dns_result_cb(enum dns_resolve_status status, + struct dns_addrinfo *info, + void *user_data) + { + if (status == DNS_EAI_CANCELED) { + /* dns: Timeout while resolving name */ + return; + } + + if (status == DNS_EAI_INPROGRESS && info) { + char str[MAX_STR_LEN + 1]; + + if (info->ai_family == AF_INET) { + net_addr_ntop(AF_INET, + &net_sin(&info->ai_addr)->sin_addr, + str, NET_IPV4_ADDR_LEN); + } else if (info->ai_family == AF_INET6) { + net_addr_ntop(AF_INET6, + &net_sin6(&info->ai_addr)->sin6_addr, + str, NET_IPV6_ADDR_LEN); + } else if (info->ai_family == AF_LOCAL) { + /* service discovery */ + memset(str, 0, MAX_STR_LEN); + memcpy(str, info->ai_canonname, + MIN(info->ai_addrlen, MAX_STR_LEN)); + } else { + strncpy(str, "Invalid proto family", MAX_STR_LEN + 1); + } + + str[MAX_STR_LEN] = '\0'; + + printk("dns: %s\n", str); + return; + } + + if (status == DNS_EAI_ALLDONE) { + printk("dns: All results received\n"); + return; + } + + if (status == DNS_EAI_FAIL) { + printk("dns: No such name found.\n"); + return; + } + + printk("dns: Unhandled status %d received (errno %d)\n", status, errno); + } + + #define DNS_TIMEOUT (MSEC_PER_SEC * 5) /* in ms */ + + static void discover_service(void) + { + int ret = dns_resolve_service(dns_resolve_get_default(), + "_http._tcp.dns-sd.org", + NULL, dns_result_cb, + NULL, DNS_TIMEOUT); + ... + } + +The above query would return output like this: + +.. code-block: console + + Query for '_http._tcp.dns-sd.org' sent. + dns: . * cnn, world news._http._tcp.dns-sd.org + dns: .source de télévision, département de langues._http._tcp.dns-sd.org + dns: . * multicast dns._http._tcp.dns-sd.org + dns: . * amazon.com, on-line shopping._http._tcp.dns-sd.org + dns: . * google, searching the web._http._tcp.dns-sd.org + dns: . * ebay, online auctions._http._tcp.dns-sd.org + dns: . * apple, makers of the ipod._http._tcp.dns-sd.org + dns: . * yahoo, maps, weather, and stock quotes._http._tcp.dns-sd.org + dns: .about bonjour in web browsers._http._tcp.dns-sd.org + dns: .π._http._tcp.•bullets•.dns-sd.org + dns: . * dns service discovery._http._tcp.dns-sd.org + dns: . * wired, technology, culture, business, politics._http._tcp.dns-sd.org + dns: . * slashdot, news for nerds, stuff that matters._http._tcp.dns-sd.org + dns: . * bbc, world news._http._tcp.dns-sd.org + dns: .stuart’s printer._http._tcp.dns-sd.org + dns: . * zeroconf._http._tcp.dns-sd.org + dns: All results received + +As the service discovery query could return long strings and the packet size could +be large, you might need to adjust following Kconfig options: + +- :kconfig:option:`CONFIG_DNS_RESOLVER_MAX_ANSWER_SIZE`. This tells the maximum size of the + answer, typical value for this option could be 1024. The default size for this option is + 512 bytes. + +- :kconfig:option:`CONFIG_DNS_RESOLVER_MAX_NAME_LEN`. This tells the maximum length of the + returned name. The value depends on your expected data size, typical value might be 128 bytes. + Sample usage ************