File espos_mdns.h¶

File List > espos_net > include > espos_mdns.h
/*
 * SPDX-FileCopyrightText: 2026 Dirk Wahrheit
 * SPDX-License-Identifier: Apache-2.0
 *
 * espos_mdns — the device's mDNS responder, and the one place a component or
 * an application registers a service it wants found on the LAN.
 *
 * espOS names the device <net.hostname>.local and advertises
 *
 *   _http._tcp   on httpd.port   TXT path=/
 *   _espos._tcp  on httpd.port   TXT v=<app version> app=<app name>
 *                                    espos=<espOS version> target=<chip>
 *                                    id=<espos_net_short_id()> api=/api/v1 auth=0
 *
 * so a browser finds every espOS device with one query and knows what it is
 * talking to before it fetches anything. Anything else — a SignalK player, a
 * candump server — is added with espos_mdns_add_service(); that call may be
 * made at any time, before the network or the responder exists, and the entry
 * is kept and registered when they do.
 *
 * Lives in espos_net: the responder follows whatever interface carries the
 * default route (docs/net.md), so it is the same API on a WiFi, Ethernet or
 * Thread build. It moved here from espos_wifi unchanged; espos_wifi still
 * REQUIRES espos_net, so a consumer that found it through espos_wifi's
 * include path still does.
 *
 * Threading: espos_mdns_start(), espos_mdns_add_service() and
 * espos_mdns_remove_service() run on the caller's task and MAY BLOCK for a
 * few milliseconds on the responder's own task or lock — call them from an
 * application task or from app_main(), never from an ESPOS_EVENT handler or a
 * URI handler. espos_mdns_is_ready() only takes the table mutex.
 *
 * Readiness is also published as ESPOS_EVENT_MDNS_READY (espos_event.h):
 * posted on every ESPOS_EVENT_NETWORK_UP once the responder runs, and once
 * from espos_mdns_start() when the link is already up. Subscribe to that, or
 * poll espos_mdns_is_ready(); both mean "a query or an announcement can reach
 * the network now".
 */
#pragma once

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include "esp_err.h"

#ifdef __cplusplus
extern "C" {
#endif

/* Limits of one registered service; a request beyond them is refused, never
 * truncated. Values are part of the ABI. */
#define ESPOS_MDNS_TYPE_MAX      32   /* service type incl. NUL: "_signalk-player" */
#define ESPOS_MDNS_PROTO_MAX     8    /* "_tcp" | "_udp" */
#define ESPOS_MDNS_TXT_MAX_ITEMS 8    /* "k=v" items per service */
#define ESPOS_MDNS_TXT_MAX_BYTES 256  /* all keys + values of one service, NULs included */

esp_err_t espos_mdns_start(void);

esp_err_t espos_mdns_add_service(const char *type, const char *proto, uint16_t port, const char *const *txt_kv, size_t n_txt);

esp_err_t espos_mdns_remove_service(const char *type, const char *proto);

bool espos_mdns_is_ready(void);

#ifdef __cplusplus
}
#endif