mDNS 服务
概述
mDNS 是一种组播 UDP 服务,用来提供本地网络服务和主机发现。
绝大多数的操作系统默认都会安装 mDNS 服务,或者提供单独的安装包。Mac OS
默认会安装名为 Bonjour
的服务(该服务基于 mDNS),此外 Apple 还发布了适用于 Windows 系统的安装程序,可以在 官方支持 找到。在 Linux
上,mDNS 服务由 avahi 提供,通常也会被默认安装。
mDNS 属性
hostname
:设备会去响应的主机名,如果没有设置,会根据设备的网络接口名定义hostname
。例如,my-esp32
会被解析为my-esp32.local
。
default_instance
:默认实例名(即易记的设备名),例如Jhon's ESP32 Thing
。如果没有设置,将会使用hostname
。
以下为 STA 接口启动 mDNS 服务并设置 hostname
和 default_instance
的示例方法:
void start_mdns_service()
{
// 初始化 mDNS 服务
esp_err_t err = mdns_init();
if (err) {
printf("MDNS Init failed: %d\n", err);
return;
}
// 设置 hostname
mdns_hostname_set("my-esp32");
// 设置默认实例
mdns_instance_name_set("Jhon's ESP32 Thing");
}
mDNS 服务
mDNS 可以广播设备能够提供的网络服务的相关信息,每个服务会由以下属性构成。
instance_name
:实例名(即易记的服务名),例如Jhon's ESP32 Web Server
。如果没有定义,会使用default_instance
。
service_type
:(必需)服务类型,以下划线为前缀,这里 列出了常见的类型。
proto
:(必需)服务运行所依赖的协议,以下划线为前缀,例如_tcp
或者_udp
。
port
:(必需)服务运行所用的端口号。
txt
:形如{var, val}
的字符串数组,用于定义服务的属性。
添加一些服务和不同属性的示例方法:
void add_mdns_services()
{
// 添加服务
mdns_service_add(NULL, "_http", "_tcp", 80, NULL, 0);
mdns_service_add(NULL, "_arduino", "_tcp", 3232, NULL, 0);
mdns_service_add(NULL, "_myservice", "_udp", 1234, NULL, 0);
// 注意:必须先添加服务,然后才能设置其属性
// web 服务器使用自定义的实例名
mdns_service_instance_name_set("_http", "_tcp", "Jhon's ESP32 Web Server");
mdns_txt_item_t serviceTxtData[3] = {
{"board","esp32"},
{"u","user"},
{"p","password"}
};
// 设置服务的文本数据(会释放并替换当前数据)
mdns_service_txt_set("_http", "_tcp", serviceTxtData, 3);
// 修改服务端口号
mdns_service_port_set("_myservice", "_udp", 4321);
}
mDNS 查询
mDNS 提供查询服务和解析主机 IP/IPv6 地址的方法。
服务查询的结果会作为 mdns_result_t
类型对象的链表返回。
解析主机 IP 地址的示例方法:
void resolve_mdns_host(const char * host_name)
{
printf("Query A: %s.local", host_name);
struct ip4_addr addr;
addr.addr = 0;
esp_err_t err = mdns_query_a(host_name, 2000, &addr);
if(err){
if(err == ESP_ERR_NOT_FOUND){
printf("Host was not found!");
return;
}
printf("Query Failed");
return;
}
printf(IPSTR, IP2STR(&addr));
}
解析本地服务的示例方法:
static const char * if_str[] = {"STA", "AP", "ETH", "MAX"};
static const char * ip_protocol_str[] = {"V4", "V6", "MAX"};
void mdns_print_results(mdns_result_t * results){
mdns_result_t * r = results;
mdns_ip_addr_t * a = NULL;
int i = 1, t;
while(r){
printf("%d: Interface: %s, Type: %s\n", i++, if_str[r->tcpip_if], ip_protocol_str[r->ip_protocol]);
if(r->instance_name){
printf(" PTR : %s\n", r->instance_name);
}
if(r->hostname){
printf(" SRV : %s.local:%u\n", r->hostname, r->port);
}
if(r->txt_count){
printf(" TXT : [%u] ", r->txt_count);
for(t=0; t<r->txt_count; t++){
printf("%s=%s; ", r->txt[t].key, r->txt[t].value);
}
printf("\n");
}
a = r->addr;
while(a){
if(a->addr.type == IPADDR_TYPE_V6){
printf(" AAAA: " IPV6STR "\n", IPV62STR(a->addr.u_addr.ip6));
} else {
printf(" A : " IPSTR "\n", IP2STR(&(a->addr.u_addr.ip4)));
}
a = a->next;
}
r = r->next;
}
}
void find_mdns_service(const char * service_name, const char * proto)
{
ESP_LOGI(TAG, "Query PTR: %s.%s.local", service_name, proto);
mdns_result_t * results = NULL;
esp_err_t err = mdns_query_ptr(service_name, proto, 3000, 20, &results);
if(err){
ESP_LOGE(TAG, "Query Failed");
return;
}
if(!results){
ESP_LOGW(TAG, "No results found!");
return;
}
mdns_print_results(results);
mdns_query_results_free(results);
}
使用上述方法的示例:
void my_app_some_method(){
// 搜索 esp32-mdns.local
resolve_mdns_host("esp32-mdns");
// 搜索 HTTP 服务器
find_mdns_service("_http", "_tcp");
// 或者搜索文件服务器
find_mdns_service("_smb", "_tcp"); // Windows 系统的共享服务
find_mdns_service("_afpovertcp", "_tcp"); // Apple AFP 文件共享服务
find_mdns_service("_nfs", "_tcp"); // NFS 服务器
find_mdns_service("_ftp", "_tcp"); // FTP 服务器
// 或者网络打印机
find_mdns_service("_printer", "_tcp");
find_mdns_service("_ipp", "_tcp");
}
应用示例
API 参考
Header File
Functions
-
esp_err_t mdns_init(void)
Initialize mDNS on given interface.
- 返回
ESP_OK on success
ESP_ERR_INVALID_STATE when failed to register event handler
ESP_ERR_NO_MEM on memory error
ESP_FAIL when failed to start mdns task
-
void mdns_free(void)
Stop and free mDNS server.
-
esp_err_t mdns_hostname_set(const char *hostname)
Set the hostname for mDNS server required if you want to advertise services.
- 参数
hostname – Hostname to set
- 返回
ESP_OK success
ESP_ERR_INVALID_ARG Parameter error
ESP_ERR_NO_MEM memory error
-
esp_err_t mdns_hostname_get(char *hostname)
Get the hostname for mDNS server.
- 参数
hostname – pointer to the hostname, it should be allocated and hold at least MDNS_NAME_BUF_LEN chars
- 返回
ESP_OK success
ESP_ERR_INVALID_ARG Parameter error
ESP_ERR_INVALID_STATE when mdns is not initialized
-
esp_err_t mdns_delegate_hostname_add(const char *hostname, const mdns_ip_addr_t *address_list)
Adds a hostname and address to be delegated A/AAAA queries will be replied for the hostname and services can be added to this host.
- 参数
hostname – Hostname to add
address_list – The IP address list of the host
- 返回
ESP_OK success
ESP_ERR_INVALID_STATE mDNS is not running
ESP_ERR_INVALID_ARG Parameter error
ESP_ERR_NO_MEM memory error
-
esp_err_t mdns_delegate_hostname_set_address(const char *hostname, const mdns_ip_addr_t *address_list)
Set the address to a delegated hostname.
- 参数
hostname – Hostname to set
address_list – The IP address list of the host
- 返回
ESP_OK success
ESP_ERR_INVALID_STATE mDNS is not running
ESP_ERR_INVALID_ARG Parameter error
ESP_ERR_NO_MEM memory error
-
esp_err_t mdns_delegate_hostname_remove(const char *hostname)
Remove a delegated hostname All the services added to this host will also be removed.
- 参数
hostname – Hostname to remove
- 返回
ESP_OK success
ESP_ERR_INVALID_STATE mDNS is not running
ESP_ERR_INVALID_ARG Parameter error
ESP_ERR_NO_MEM memory error
-
bool mdns_hostname_exists(const char *hostname)
Query whether a hostname has been added.
- 参数
hostname – Hostname to query
- 返回
true The hostname has been added.
false The hostname has not been added.
-
esp_err_t mdns_instance_name_set(const char *instance_name)
Set the default instance name for mDNS server.
- 参数
instance_name – Instance name to set
- 返回
ESP_OK success
ESP_ERR_INVALID_ARG Parameter error
ESP_ERR_NO_MEM memory error
-
esp_err_t mdns_service_add(const char *instance_name, const char *service_type, const char *proto, uint16_t port, mdns_txt_item_t txt[], size_t num_items)
Add service to mDNS server.
备注
The value length of txt items will be automatically decided by strlen
- 参数
instance_name – instance name to set. If NULL, global instance name or hostname will be used. Note that MDNS_MULTIPLE_INSTANCE config option needs to be enabled for adding multiple instances with the same instance type.
service_type – service type (_http, _ftp, etc)
proto – service protocol (_tcp, _udp)
port – service port
txt – string array of TXT data (eg. {{“var”,”val”},{“other”,”2”}})
num_items – number of items in TXT data
- 返回
ESP_OK success
ESP_ERR_INVALID_ARG Parameter error
ESP_ERR_NO_MEM memory error
ESP_FAIL failed to add service
-
esp_err_t mdns_service_add_for_host(const char *instance_name, const char *service_type, const char *proto, const char *hostname, uint16_t port, mdns_txt_item_t txt[], size_t num_items)
Add service to mDNS server with a delegated hostname.
备注
The value length of txt items will be automatically decided by strlen
- 参数
instance_name – instance name to set. If NULL, global instance name or hostname will be used Note that MDNS_MULTIPLE_INSTANCE config option needs to be enabled for adding multiple instances with the same instance type.
service_type – service type (_http, _ftp, etc)
proto – service protocol (_tcp, _udp)
hostname – service hostname. If NULL, local hostname will be used.
port – service port
txt – string array of TXT data (eg. {{“var”,”val”},{“other”,”2”}})
num_items – number of items in TXT data
- 返回
ESP_OK success
ESP_ERR_INVALID_ARG Parameter error
ESP_ERR_NO_MEM memory error
ESP_FAIL failed to add service
-
bool mdns_service_exists(const char *service_type, const char *proto, const char *hostname)
Check whether a service has been added.
- 参数
service_type – service type (_http, _ftp, etc)
proto – service protocol (_tcp, _udp)
hostname – service hostname. If NULL, checks for the local hostname.
- 返回
true Correspondding service has been added.
false Service not found.
-
bool mdns_service_exists_with_instance(const char *instance, const char *service_type, const char *proto, const char *hostname)
Check whether a service has been added.
- 参数
instance – instance name
service_type – service type (_http, _ftp, etc)
proto – service protocol (_tcp, _udp)
hostname – service hostname. If NULL, checks for the local hostname.
- 返回
true Correspondding service has been added.
false Service not found.
-
esp_err_t mdns_service_remove(const char *service_type, const char *proto)
Remove service from mDNS server.
- 参数
service_type – service type (_http, _ftp, etc)
proto – service protocol (_tcp, _udp)
- 返回
ESP_OK success
ESP_ERR_INVALID_ARG Parameter error
ESP_ERR_NOT_FOUND Service not found
ESP_ERR_NO_MEM memory error
-
esp_err_t mdns_service_remove_for_host(const char *instance, const char *service_type, const char *proto, const char *hostname)
Remove service from mDNS server with hostname.
- 参数
instance – instance name
service_type – service type (_http, _ftp, etc)
proto – service protocol (_tcp, _udp)
hostname – service hostname. If NULL, local hostname will be used.
- 返回
ESP_OK success
ESP_ERR_INVALID_ARG Parameter error
ESP_ERR_NOT_FOUND Service not found
ESP_ERR_NO_MEM memory error
-
esp_err_t mdns_service_instance_name_set(const char *service_type, const char *proto, const char *instance_name)
Set instance name for service.
- 参数
service_type – service type (_http, _ftp, etc)
proto – service protocol (_tcp, _udp)
instance_name – instance name to set
- 返回
ESP_OK success
ESP_ERR_INVALID_ARG Parameter error
ESP_ERR_NOT_FOUND Service not found
ESP_ERR_NO_MEM memory error
-
esp_err_t mdns_service_instance_name_set_for_host(const char *instance_old, const char *service_type, const char *proto, const char *hostname, const char *instance_name)
Set instance name for service with hostname.
- 参数
instance_old – original instance name
service_type – service type (_http, _ftp, etc)
proto – service protocol (_tcp, _udp)
hostname – service hostname. If NULL, local hostname will be used.
instance_name – instance name to set
- 返回
ESP_OK success
ESP_ERR_INVALID_ARG Parameter error
ESP_ERR_NOT_FOUND Service not found
ESP_ERR_NO_MEM memory error
-
esp_err_t mdns_service_port_set(const char *service_type, const char *proto, uint16_t port)
Set service port.
- 参数
service_type – service type (_http, _ftp, etc)
proto – service protocol (_tcp, _udp)
port – service port
- 返回
ESP_OK success
ESP_ERR_INVALID_ARG Parameter error
ESP_ERR_NOT_FOUND Service not found
ESP_ERR_NO_MEM memory error
-
esp_err_t mdns_service_port_set_for_host(const char *instance, const char *service_type, const char *proto, const char *hostname, uint16_t port)
Set service port with hostname.
- 参数
instance – instance name
service_type – service type (_http, _ftp, etc)
proto – service protocol (_tcp, _udp)
hostname – service hostname. If NULL, local hostname will be used.
port – service port
- 返回
ESP_OK success
ESP_ERR_INVALID_ARG Parameter error
ESP_ERR_NOT_FOUND Service not found
ESP_ERR_NO_MEM memory error
-
esp_err_t mdns_service_txt_set(const char *service_type, const char *proto, mdns_txt_item_t txt[], uint8_t num_items)
Replace all TXT items for service.
备注
The value length of txt items will be automatically decided by strlen
- 参数
service_type – service type (_http, _ftp, etc)
proto – service protocol (_tcp, _udp)
txt – array of TXT data (eg. {{“var”,”val”},{“other”,”2”}})
num_items – number of items in TXT data
- 返回
ESP_OK success
ESP_ERR_INVALID_ARG Parameter error
ESP_ERR_NOT_FOUND Service not found
ESP_ERR_NO_MEM memory error
-
esp_err_t mdns_service_txt_set_for_host(const char *instance, const char *service_type, const char *proto, const char *hostname, mdns_txt_item_t txt[], uint8_t num_items)
Replace all TXT items for service with hostname.
备注
The value length of txt items will be automatically decided by strlen
- 参数
instance – instance name
service_type – service type (_http, _ftp, etc)
proto – service protocol (_tcp, _udp)
hostname – service hostname. If NULL, local hostname will be used.
txt – array of TXT data (eg. {{“var”,”val”},{“other”,”2”}})
num_items – number of items in TXT data
- 返回
ESP_OK success
ESP_ERR_INVALID_ARG Parameter error
ESP_ERR_NOT_FOUND Service not found
ESP_ERR_NO_MEM memory error
-
esp_err_t mdns_service_txt_item_set(const char *service_type, const char *proto, const char *key, const char *value)
Set/Add TXT item for service TXT record.
备注
The value length will be automatically decided by strlen
- 参数
service_type – service type (_http, _ftp, etc)
proto – service protocol (_tcp, _udp)
key – the key that you want to add/update
value – the new value of the key
- 返回
ESP_OK success
ESP_ERR_INVALID_ARG Parameter error
ESP_ERR_NOT_FOUND Service not found
ESP_ERR_NO_MEM memory error
-
esp_err_t mdns_service_txt_item_set_with_explicit_value_len(const char *service_type, const char *proto, const char *key, const char *value, uint8_t value_len)
Set/Add TXT item for service TXT record.
- 参数
service_type – service type (_http, _ftp, etc)
proto – service protocol (_tcp, _udp)
key – the key that you want to add/update
value – the new value of the key
value_len – the length of the value
- 返回
ESP_OK success
ESP_ERR_INVALID_ARG Parameter error
ESP_ERR_NOT_FOUND Service not found
ESP_ERR_NO_MEM memory error
-
esp_err_t mdns_service_txt_item_set_for_host(const char *instance, const char *service_type, const char *proto, const char *hostname, const char *key, const char *value)
Set/Add TXT item for service TXT record with hostname.
备注
The value length will be automatically decided by strlen
- 参数
instance – instance name
service_type – service type (_http, _ftp, etc)
proto – service protocol (_tcp, _udp)
hostname – service hostname. If NULL, local hostname will be used.
key – the key that you want to add/update
value – the new value of the key
- 返回
ESP_OK success
ESP_ERR_INVALID_ARG Parameter error
ESP_ERR_NOT_FOUND Service not found
ESP_ERR_NO_MEM memory error
-
esp_err_t mdns_service_txt_item_set_for_host_with_explicit_value_len(const char *instance, const char *service_type, const char *proto, const char *hostname, const char *key, const char *value, uint8_t value_len)
Set/Add TXT item for service TXT record with hostname and txt value length.
- 参数
instance – instance name
service_type – service type (_http, _ftp, etc)
proto – service protocol (_tcp, _udp)
hostname – service hostname. If NULL, local hostname will be used.
key – the key that you want to add/update
value – the new value of the key
value_len – the length of the value
- 返回
ESP_OK success
ESP_ERR_INVALID_ARG Parameter error
ESP_ERR_NOT_FOUND Service not found
ESP_ERR_NO_MEM memory error
-
esp_err_t mdns_service_txt_item_remove(const char *service_type, const char *proto, const char *key)
Remove TXT item for service TXT record.
- 参数
service_type – service type (_http, _ftp, etc)
proto – service protocol (_tcp, _udp)
key – the key that you want to remove
- 返回
ESP_OK success
ESP_ERR_INVALID_ARG Parameter error
ESP_ERR_NOT_FOUND Service not found
ESP_ERR_NO_MEM memory error
-
esp_err_t mdns_service_txt_item_remove_for_host(const char *instance, const char *service_type, const char *proto, const char *hostname, const char *key)
Remove TXT item for service TXT record with hostname.
- 参数
instance – instance name
service_type – service type (_http, _ftp, etc)
proto – service protocol (_tcp, _udp)
hostname – service hostname. If NULL, local hostname will be used.
key – the key that you want to remove
- 返回
ESP_OK success
ESP_ERR_INVALID_ARG Parameter error
ESP_ERR_NOT_FOUND Service not found
ESP_ERR_NO_MEM memory error
-
esp_err_t mdns_service_subtype_add_for_host(const char *instance_name, const char *service_type, const char *proto, const char *hostname, const char *subtype)
Add a subtype for service.
- 参数
instance_name – instance name. If NULL, will find the first service with the same service type and protocol.
service_type – service type (_http, _ftp, etc)
proto – service protocol (_tcp, _udp)
hostname – service hostname. If NULL, local hostname will be used.
subtype – The subtype to add.
- 返回
ESP_OK success
ESP_ERR_INVALID_ARG Parameter error
ESP_ERR_NOT_FOUND Service not found
ESP_ERR_NO_MEM memory error
-
esp_err_t mdns_service_subtype_remove_for_host(const char *instance_name, const char *service_type, const char *proto, const char *hostname, const char *subtype)
Remove a subtype for service.
- 参数
instance_name – instance name. If NULL, will find the first service with the same service type and protocol.
service_type – service type (_http, _ftp, etc)
proto – service protocol (_tcp, _udp)
hostname – service hostname. If NULL, local hostname will be used.
subtype – The subtype to remove.
- 返回
ESP_OK success
ESP_ERR_INVALID_ARG Parameter error
ESP_ERR_NOT_FOUND Service not found
-
esp_err_t mdns_service_subtype_add_multiple_items_for_host(const char *instance_name, const char *service_type, const char *proto, const char *hostname, mdns_subtype_item_t subtype[], uint8_t num_items)
Add multiple subtypes for service at once.
- 参数
instance_name – instance name. If NULL, will find the first service with the same service type and protocol.
service_type – service type (_http, _ftp, etc)
proto – service protocol (_tcp, _udp)
hostname – service hostname. If NULL, local hostname will be used.
subtype – the pointer of subtype array to add.
num_items – number of items in subtype array
- 返回
ESP_OK success
ESP_ERR_INVALID_ARG Parameter error
ESP_ERR_NOT_FOUND Service not found
ESP_ERR_NO_MEM memory error
-
esp_err_t mdns_service_subtype_update_multiple_items_for_host(const char *instance_name, const char *service_type, const char *proto, const char *hostname, mdns_subtype_item_t subtype[], uint8_t num_items)
Update subtype for service.
- 参数
instance_name – instance name. If NULL, will find the first service with the same service type and protocol.
service_type – service type (_http, _ftp, etc)
proto – service protocol (_tcp, _udp)
hostname – service hostname. If NULL, local hostname will be used.
subtype – the pointer of subtype array to add.
num_items – number of items in subtype array
- 返回
ESP_OK success
ESP_ERR_INVALID_ARG Parameter error
ESP_ERR_NOT_FOUND Service not found
ESP_ERR_NO_MEM memory error
-
esp_err_t mdns_service_remove_all(void)
Remove and free all services from mDNS server.
- 返回
ESP_OK success
ESP_ERR_INVALID_ARG Parameter error
-
esp_err_t mdns_query_async_delete(mdns_search_once_t *search)
Deletes the finished query. Call this only after the search has ended!
- 参数
search – pointer to search object
- 返回
ESP_OK success
ESP_ERR_INVALID_STATE search has not finished
ESP_ERR_INVALID_ARG pointer to search object is NULL
-
bool mdns_query_async_get_results(mdns_search_once_t *search, uint32_t timeout, mdns_result_t **results, uint8_t *num_results)
Get results from search pointer. Results available as a pointer to the output parameter. Pointer to search object has to be deleted via
mdns_query_async_delete
once the query has finished. The results although have to be freed manually.- 参数
search – pointer to search object
timeout – time in milliseconds to wait for answers
results – pointer to the results of the query
num_results – pointer to the number of the actual result items (set to NULL to ignore this return value)
- 返回
True if search has finished before or at timeout False if search timeout is over
-
mdns_search_once_t *mdns_query_async_new(const char *name, const char *service_type, const char *proto, uint16_t type, uint32_t timeout, size_t max_results, mdns_query_notify_t notifier)
Query mDNS for host or service asynchronousely. Search has to be tested for progress and deleted manually!
- 参数
name – service instance or host name (NULL for PTR queries)
service_type – service type (_http, _arduino, _ftp etc.) (NULL for host queries)
proto – service protocol (_tcp, _udp, etc.) (NULL for host queries)
type – type of query (MDNS_TYPE_*)
timeout – time in milliseconds during which mDNS query is active
max_results – maximum results to be collected
notifier – Notification function to be called when the result is ready, can be NULL
- 返回
mdns_search_once_s pointer to new search object if query initiated successfully. NULL otherwise.
-
esp_err_t mdns_query_generic(const char *name, const char *service_type, const char *proto, uint16_t type, mdns_query_transmission_type_t transmission_type, uint32_t timeout, size_t max_results, mdns_result_t **results)
Generic mDNS query All following query methods are derived from this one.
- 参数
name – service instance or host name (NULL for PTR queries)
service_type – service type (_http, _arduino, _ftp etc.) (NULL for host queries)
proto – service protocol (_tcp, _udp, etc.) (NULL for host queries)
type – type of query (MDNS_TYPE_*)
transmission_type – either Unicast query, or Multicast query
timeout – time in milliseconds to wait for answers.
max_results – maximum results to be collected
results – pointer to the results of the query results must be freed using mdns_query_results_free below
- 返回
ESP_OK success
ESP_ERR_INVALID_STATE mDNS is not running
ESP_ERR_NO_MEM memory error
ESP_ERR_INVALID_ARG timeout was not given
-
esp_err_t mdns_query(const char *name, const char *service_type, const char *proto, uint16_t type, uint32_t timeout, size_t max_results, mdns_result_t **results)
Query mDNS for host or service.
Note that querying PTR types sends Multicast query, all other types send Unicast queries
- 参数
name – service instance or host name (NULL for PTR queries)
service_type – service type (_http, _arduino, _ftp etc.) (NULL for host queries)
proto – service protocol (_tcp, _udp, etc.) (NULL for host queries)
type – type of query (MDNS_TYPE_*)
timeout – time in milliseconds to wait for answers.
max_results – maximum results to be collected
results – pointer to the results of the query results must be freed using mdns_query_results_free below
- 返回
ESP_OK success
ESP_ERR_INVALID_STATE mDNS is not running
ESP_ERR_NO_MEM memory error
ESP_ERR_INVALID_ARG timeout was not given
-
void mdns_query_results_free(mdns_result_t *results)
Free query results.
- 参数
results – linked list of results to be freed
-
esp_err_t mdns_query_ptr(const char *service_type, const char *proto, uint32_t timeout, size_t max_results, mdns_result_t **results)
Query mDNS for service.
- 参数
service_type – service type (_http, _arduino, _ftp etc.)
proto – service protocol (_tcp, _udp, etc.)
timeout – time in milliseconds to wait for answer.
max_results – maximum results to be collected
results – pointer to the results of the query
- 返回
ESP_OK success
ESP_ERR_INVALID_STATE mDNS is not running
ESP_ERR_NO_MEM memory error
ESP_ERR_INVALID_ARG parameter error
-
esp_err_t mdns_query_srv(const char *instance_name, const char *service_type, const char *proto, uint32_t timeout, mdns_result_t **result)
Query mDNS for SRV record.
- 参数
instance_name – service instance name
service_type – service type (_http, _arduino, _ftp etc.)
proto – service protocol (_tcp, _udp, etc.)
timeout – time in milliseconds to wait for answer.
result – pointer to the result of the query
- 返回
ESP_OK success
ESP_ERR_INVALID_STATE mDNS is not running
ESP_ERR_NO_MEM memory error
ESP_ERR_INVALID_ARG parameter error
-
esp_err_t mdns_query_txt(const char *instance_name, const char *service_type, const char *proto, uint32_t timeout, mdns_result_t **result)
Query mDNS for TXT record.
- 参数
instance_name – service instance name
service_type – service type (_http, _arduino, _ftp etc.)
proto – service protocol (_tcp, _udp, etc.)
timeout – time in milliseconds to wait for answer.
result – pointer to the result of the query
- 返回
ESP_OK success
ESP_ERR_INVALID_STATE mDNS is not running
ESP_ERR_NO_MEM memory error
ESP_ERR_INVALID_ARG parameter error
-
esp_err_t mdns_lookup_delegated_service(const char *instance, const char *service_type, const char *proto, size_t max_results, mdns_result_t **result)
Look up delegated services.
- 参数
instance – instance name (NULL for uncertain instance)
service_type – service type (_http, _ftp, etc)
proto – service protocol (_tcp, _udp)
max_results – maximum results to be collected
result – pointer to the result of the search
- 返回
ESP_OK success
ESP_ERR_INVALID_STATE mDNS is not running
ESP_ERR_NO_MEM memory error
ESP_ERR_INVALID_ARG parameter error
-
esp_err_t mdns_lookup_selfhosted_service(const char *instance, const char *service_type, const char *proto, size_t max_results, mdns_result_t **result)
Look up self hosted services.
- 参数
instance – instance name (NULL for uncertain instance)
service_type – service type (_http, _ftp, etc)
proto – service protocol (_tcp, _udp)
max_results – maximum results to be collected
result – pointer to the result of the search
- 返回
ESP_OK success
ESP_ERR_INVALID_STATE mDNS is not running
ESP_ERR_NO_MEM memory error
ESP_ERR_INVALID_ARG parameter error
-
esp_err_t mdns_query_a(const char *host_name, uint32_t timeout, esp_ip4_addr_t *addr)
Query mDNS for A record.
- 参数
host_name – host name to look for
timeout – time in milliseconds to wait for answer.
addr – pointer to the resulting IP4 address
- 返回
ESP_OK success
ESP_ERR_INVALID_STATE mDNS is not running
ESP_ERR_NO_MEM memory error
ESP_ERR_INVALID_ARG parameter error
-
esp_err_t mdns_register_netif(esp_netif_t *esp_netif)
Register custom esp_netif with mDNS functionality mDNS service runs by default on preconfigured interfaces (STA, AP, ETH). This API enables running the service on any customized interface, either using standard WiFi or Ethernet driver or any kind of user defined driver.
- 参数
esp_netif – Pointer to esp-netif interface
- 返回
ESP_OK success
ESP_ERR_INVALID_STATE mDNS is not running or this netif is already registered
ESP_ERR_NO_MEM not enough memory for this in interface in the netif list (see CONFIG_MDNS_MAX_INTERFACES)
-
esp_err_t mdns_unregister_netif(esp_netif_t *esp_netif)
Unregister esp-netif already registered in mDNS service.
- 参数
esp_netif – Pointer to esp-netif interface
- 返回
ESP_OK success
ESP_ERR_INVALID_STATE mDNS is not running
ESP_ERR_NOT_FOUND this esp-netif was not registered in mDNS service
-
esp_err_t mdns_netif_action(esp_netif_t *esp_netif, mdns_event_actions_t event_action)
Set esp_netif to a desired state, or perform a desired action, such as enable/disable this interface or send announcement packets to this netif.
This function is used to enable (probe, resolve conflicts and announce), announce, or disable (send bye) mDNS services on the specified network interface.
This function must be called if users registers a specific interface using mdns_register_netif() to enable mDNS services on that interface.
This function could be used in IP/connection event handlers to automatically enable/announce mDNS services when network properties change and/or disable them on disconnection.
- 参数
esp_netif – Pointer to esp-netif interface
event_action – Disable/Enable/Announce on this interface over IPv4/IPv6 protocol. Actions enumerated in mdns_event_actions_t type.
- 返回
ESP_OK success
ESP_ERR_INVALID_STATE mDNS is not running or this netif is not registered
ESP_ERR_NO_MEM memory error
-
mdns_browse_t *mdns_browse_new(const char *service, const char *proto, mdns_browse_notify_t notifier)
Browse mDNS for a service
_service._proto
.- 参数
service – Pointer to the
_service
which will be browsed.proto – Pointer to the
_proto
which will be browsed.notifier – The callback which will be called when the browsing service changed.
- 返回
mdns_browse_t pointer to new browse object if initiated successfully. NULL otherwise.
-
esp_err_t mdns_browse_delete(const char *service, const char *proto)
Stop the
_service._proto
browse.- 参数
service – Pointer to the
_service
which will be browsed.proto – Pointer to the
_proto
which will be browsed.
- 返回
ESP_OK success.
ESP_ERR_FAIL mDNS is not running or the browsing of
_service._proto
is never started.ESP_ERR_NO_MEM memory error.
Structures
-
struct mdns_txt_item_t
mDNS basic text item structure Used in mdns_service_add()
-
struct mdns_subtype_item_t
mDNS basic subtype item structure Used in mdns_service_subtype_xxx() APIs
Public Members
-
const char *subtype
subtype name
-
const char *subtype
-
struct mdns_ip_addr_s
mDNS query linked list IP item
Public Members
-
esp_ip_addr_t addr
IP address
-
struct mdns_ip_addr_s *next
next IP, or NULL for the last IP in the list
-
esp_ip_addr_t addr
-
struct mdns_result_s
mDNS query result structure
Public Members
-
struct mdns_result_s *next
next result, or NULL for the last result in the list
-
esp_netif_t *esp_netif
ptr to corresponding esp-netif
-
uint32_t ttl
time to live
-
mdns_ip_protocol_t ip_protocol
ip_protocol type of the interface (v4/v6)
-
char *instance_name
instance name
-
char *service_type
service type
-
char *proto
srevice protocol
-
char *hostname
hostname
-
uint16_t port
service port
-
mdns_txt_item_t *txt
txt record
-
uint8_t *txt_value_len
array of txt value len of each record
-
size_t txt_count
number of txt items
-
mdns_ip_addr_t *addr
linked list of IP addresses found
-
struct mdns_result_s *next
Macros
-
MDNS_TYPE_A
-
MDNS_TYPE_PTR
-
MDNS_TYPE_TXT
-
MDNS_TYPE_AAAA
-
MDNS_TYPE_SRV
-
MDNS_TYPE_OPT
-
MDNS_TYPE_NSEC
-
MDNS_TYPE_ANY
Type Definitions
-
typedef struct mdns_search_once_s mdns_search_once_t
Asynchronous query handle.
-
typedef struct mdns_browse_s mdns_browse_t
Daemon query handle.
-
typedef struct mdns_ip_addr_s mdns_ip_addr_t
mDNS query linked list IP item
-
typedef struct mdns_result_s mdns_result_t
mDNS query result structure
-
typedef void (*mdns_query_notify_t)(mdns_search_once_t *search)
-
typedef void (*mdns_browse_notify_t)(mdns_result_t *result)
Enumerations
-
enum mdns_event_actions_t
Values:
-
enumerator MDNS_EVENT_ENABLE_IP4
-
enumerator MDNS_EVENT_ENABLE_IP6
-
enumerator MDNS_EVENT_ANNOUNCE_IP4
-
enumerator MDNS_EVENT_ANNOUNCE_IP6
-
enumerator MDNS_EVENT_DISABLE_IP4
-
enumerator MDNS_EVENT_DISABLE_IP6
-
enumerator MDNS_EVENT_IP4_REVERSE_LOOKUP
-
enumerator MDNS_EVENT_IP6_REVERSE_LOOKUP
-
enumerator MDNS_EVENT_ENABLE_IP4