esp-idf/components/mdns/include/mdns.h

364 lines
12 KiB
C
Raw Normal View History

2017-01-04 11:54:07 -05:00
// Copyright 2015-2016 Espressif Systems (Shanghai) PTE LTD
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
#ifndef ESP_MDNS_H_
#define ESP_MDNS_H_
#ifdef __cplusplus
extern "C" {
#endif
#include <tcpip_adapter.h>
2017-12-07 08:21:40 -05:00
#include "esp_event.h"
2017-01-04 11:54:07 -05:00
2017-12-07 08:21:40 -05:00
#define MDNS_TYPE_A 0x0001
#define MDNS_TYPE_PTR 0x000C
#define MDNS_TYPE_TXT 0x0010
#define MDNS_TYPE_AAAA 0x001C
#define MDNS_TYPE_SRV 0x0021
#define MDNS_TYPE_OPT 0x0029
#define MDNS_TYPE_NSEC 0x002F
#define MDNS_TYPE_ANY 0x00FF
2017-01-04 11:54:07 -05:00
/**
2017-12-07 08:21:40 -05:00
* @brief mDNS enum to specify the ip_protocol type
*/
typedef enum {
MDNS_IP_PROTOCOL_V4,
MDNS_IP_PROTOCOL_V6,
MDNS_IP_PROTOCOL_MAX
} mdns_ip_protocol_t;
/**
* @brief mDNS basic text item structure
* Used in mdns_service_add()
*/
typedef struct {
const char * key; /*!< item key name */
const char * value; /*!< item value string */
2017-12-07 08:21:40 -05:00
} mdns_txt_item_t;
/**
* @brief mDNS query linked list IP item
*/
typedef struct mdns_ip_addr_s {
ip_addr_t addr; /*!< IP address */
struct mdns_ip_addr_s * next; /*!< next IP, or NULL for the last IP in the list */
} mdns_ip_addr_t;
/**
* @brief mDNS query result structure
2017-01-04 11:54:07 -05:00
*/
typedef struct mdns_result_s {
2017-12-07 08:21:40 -05:00
struct mdns_result_s * next; /*!< next result, or NULL for the last result in the list */
tcpip_adapter_if_t tcpip_if; /*!< interface on which the result came (AP/STA/ETH) */
mdns_ip_protocol_t ip_protocol; /*!< ip_protocol type of the interface (v4/v6) */
// PTR
char * instance_name; /*!< instance name */
// SRV
char * hostname; /*!< hostname */
uint16_t port; /*!< service port */
// TXT
mdns_txt_item_t * txt; /*!< txt record */
size_t txt_count; /*!< number of txt items */
// A and AAAA
mdns_ip_addr_t * addr; /*!< linked list of IP addreses found */
2017-01-04 11:54:07 -05:00
} mdns_result_t;
/**
* @brief Initialize mDNS on given interface
*
* @return
* - ESP_OK on success
* - ESP_ERR_INVALID_STATE when failed to register event handler
2017-01-04 11:54:07 -05:00
* - ESP_ERR_NO_MEM on memory error
* - ESP_FAIL when failed to start mdns task
2017-01-04 11:54:07 -05:00
*/
esp_err_t mdns_init(void);
2017-01-04 11:54:07 -05:00
/**
* @brief Stop and free mDNS server
*
*/
void mdns_free(void);
2017-01-04 11:54:07 -05:00
/**
* @brief Set the hostname for mDNS server
2017-12-07 08:21:40 -05:00
* required if you want to advertise services
2017-01-04 11:54:07 -05:00
*
* @param hostname Hostname to set
*
* @return
* - ESP_OK success
* - ESP_ERR_INVALID_ARG Parameter error
* - ESP_ERR_NO_MEM memory error
*/
2017-12-07 08:21:40 -05:00
esp_err_t mdns_hostname_set(const char * hostname);
2017-01-04 11:54:07 -05:00
/**
* @brief Set the default instance name for mDNS server
*
2017-12-07 08:21:40 -05:00
* @param instance_name Instance name to set
2017-01-04 11:54:07 -05:00
*
* @return
* - ESP_OK success
* - ESP_ERR_INVALID_ARG Parameter error
* - ESP_ERR_NO_MEM memory error
*/
2017-12-07 08:21:40 -05:00
esp_err_t mdns_instance_name_set(const char * instance_name);
2017-01-04 11:54:07 -05:00
/**
* @brief Add service to mDNS server
*
2017-12-07 08:21:40 -05:00
* @param instance_name instance name to set. If NULL,
* global instance name or hostname will be used
* @param service_type service type (_http, _ftp, etc)
* @param proto service protocol (_tcp, _udp)
* @param port service port
* @param txt string array of TXT data (eg. {{"var","val"},{"other","2"}})
* @param num_items number of items in TXT data
2017-01-04 11:54:07 -05:00
*
* @return
* - ESP_OK success
* - ESP_ERR_INVALID_ARG Parameter error
* - ESP_ERR_NO_MEM memory error
* - ESP_FAIL failed to add serivce
2017-01-04 11:54:07 -05:00
*/
2017-12-07 08:21:40 -05:00
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);
2017-01-04 11:54:07 -05:00
/**
* @brief Remove service from mDNS server
*
2017-12-07 08:21:40 -05:00
* @param service_type service type (_http, _ftp, etc)
2017-01-04 11:54:07 -05:00
* @param proto service protocol (_tcp, _udp)
*
* @return
* - ESP_OK success
* - ESP_ERR_INVALID_ARG Parameter error
* - ESP_ERR_NOT_FOUND Service not found
* - ESP_ERR_NO_MEM memory error
2017-01-04 11:54:07 -05:00
*/
2017-12-07 08:21:40 -05:00
esp_err_t mdns_service_remove(const char * service_type, const char * proto);
2017-01-04 11:54:07 -05:00
/**
* @brief Set instance name for service
*
2017-12-07 08:21:40 -05:00
* @param service_type service type (_http, _ftp, etc)
* @param proto service protocol (_tcp, _udp)
* @param instance_name instance name to set
2017-01-04 11:54:07 -05:00
*
* @return
* - ESP_OK success
* - ESP_ERR_INVALID_ARG Parameter error
* - ESP_ERR_NOT_FOUND Service not found
* - ESP_ERR_NO_MEM memory error
*/
2017-12-07 08:21:40 -05:00
esp_err_t mdns_service_instance_name_set(const char * service_type, const char * proto, const char * instance_name);
/**
* @brief Set service port
*
* @param service_type service type (_http, _ftp, etc)
* @param proto service protocol (_tcp, _udp)
* @param port service port
*
* @return
* - ESP_OK success
* - ESP_ERR_INVALID_ARG Parameter error
* - ESP_ERR_NOT_FOUND Service not found
* - ESP_ERR_NO_MEM memory error
2017-12-07 08:21:40 -05:00
*/
esp_err_t mdns_service_port_set(const char * service_type, const char * proto, uint16_t port);
2017-01-04 11:54:07 -05:00
/**
2017-12-07 08:21:40 -05:00
* @brief Replace all TXT items for service
2017-01-04 11:54:07 -05:00
*
2017-12-07 08:21:40 -05:00
* @param service_type service type (_http, _ftp, etc)
2017-01-04 11:54:07 -05:00
* @param proto service protocol (_tcp, _udp)
2017-12-07 08:21:40 -05:00
* @param txt array of TXT data (eg. {{"var","val"},{"other","2"}})
* @param num_items number of items in TXT data
2017-01-04 11:54:07 -05:00
*
* @return
* - ESP_OK success
* - ESP_ERR_INVALID_ARG Parameter error
* - ESP_ERR_NOT_FOUND Service not found
* - ESP_ERR_NO_MEM memory error
*/
2017-12-07 08:21:40 -05:00
esp_err_t mdns_service_txt_set(const char * service_type, const char * proto, mdns_txt_item_t txt[], uint8_t num_items);
2017-01-04 11:54:07 -05:00
/**
2017-12-07 08:21:40 -05:00
* @brief Set/Add TXT item for service TXT record
2017-01-04 11:54:07 -05:00
*
2017-12-07 08:21:40 -05:00
* @param service_type service type (_http, _ftp, etc)
2017-01-04 11:54:07 -05:00
* @param proto service protocol (_tcp, _udp)
2017-12-07 08:21:40 -05:00
* @param key the key that you want to add/update
* @param value the new value of the key
2017-01-04 11:54:07 -05:00
*
* @return
* - ESP_OK success
* - ESP_ERR_INVALID_ARG Parameter error
* - ESP_ERR_NOT_FOUND Service not found
2017-12-07 08:21:40 -05:00
* - ESP_ERR_NO_MEM memory error
2017-01-04 11:54:07 -05:00
*/
2017-12-07 08:21:40 -05:00
esp_err_t mdns_service_txt_item_set(const char * service_type, const char * proto, const char * key, const char * value);
2017-01-04 11:54:07 -05:00
/**
2017-12-07 08:21:40 -05:00
* @brief Remove TXT item for service TXT record
2017-01-04 11:54:07 -05:00
*
2017-12-07 08:21:40 -05:00
* @param service_type service type (_http, _ftp, etc)
* @param proto service protocol (_tcp, _udp)
* @param key the key that you want to remove
*
* @return
* - 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);
/**
* @brief Remove and free all services from mDNS server
2017-01-04 11:54:07 -05:00
*
* @return
* - ESP_OK success
* - ESP_ERR_INVALID_ARG Parameter error
*/
esp_err_t mdns_service_remove_all(void);
2017-01-04 11:54:07 -05:00
/**
* @brief Query mDNS for host or service
2017-12-07 08:21:40 -05:00
* All following query methods are derived from this one
2017-01-04 11:54:07 -05:00
*
2017-12-07 08:21:40 -05:00
* @param name service instance or host name (NULL for PTR queries)
* @param service_type service type (_http, _arduino, _ftp etc.) (NULL for host queries)
* @param proto service protocol (_tcp, _udp, etc.) (NULL for host queries)
* @param type type of query (MDNS_TYPE_*)
* @param timeout time in milliseconds to wait for answers.
* @param max_results maximum results to be collected
* @param results pointer to the results of the query
* results must be freed using mdns_query_results_free below
2017-01-04 11:54:07 -05:00
*
2017-12-07 08:21:40 -05:00
* @return
* - 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);
/**
* @brief Free query results
*
* @param results linked list of results to be freed
2017-01-04 11:54:07 -05:00
*/
2017-12-07 08:21:40 -05:00
void mdns_query_results_free(mdns_result_t * results);
2017-01-04 11:54:07 -05:00
/**
2017-12-07 08:21:40 -05:00
* @brief Query mDNS for service
2017-01-04 11:54:07 -05:00
*
2017-12-07 08:21:40 -05:00
* @param service_type service type (_http, _arduino, _ftp etc.)
* @param proto service protocol (_tcp, _udp, etc.)
* @param timeout time in milliseconds to wait for answer.
* @param max_results maximum results to be collected
* @param results pointer to the results of the query
2017-01-04 11:54:07 -05:00
*
2017-12-07 08:21:40 -05:00
* @return
* - ESP_OK success
* - ESP_ERR_INVALID_STATE mDNS is not running
* - ESP_ERR_NO_MEM memory error
* - ESP_ERR_INVALID_ARG parameter error
2017-01-04 11:54:07 -05:00
*/
2017-12-07 08:21:40 -05:00
esp_err_t mdns_query_ptr(const char * service_type, const char * proto, uint32_t timeout, size_t max_results, mdns_result_t ** results);
2017-01-04 11:54:07 -05:00
/**
2017-12-07 08:21:40 -05:00
* @brief Query mDNS for SRV record
2017-01-04 11:54:07 -05:00
*
2017-12-07 08:21:40 -05:00
* @param instance_name service instance name
* @param service_type service type (_http, _arduino, _ftp etc.)
* @param proto service protocol (_tcp, _udp, etc.)
* @param timeout time in milliseconds to wait for answer.
* @param result pointer to the result of the query
2017-01-04 11:54:07 -05:00
*
2017-12-07 08:21:40 -05:00
* @return
* - ESP_OK success
* - ESP_ERR_INVALID_STATE mDNS is not running
* - ESP_ERR_NO_MEM memory error
* - ESP_ERR_INVALID_ARG parameter error
2017-01-04 11:54:07 -05:00
*/
2017-12-07 08:21:40 -05:00
esp_err_t mdns_query_srv(const char * instance_name, const char * service_type, const char * proto, uint32_t timeout, mdns_result_t ** result);
2017-01-04 11:54:07 -05:00
/**
2017-12-07 08:21:40 -05:00
* @brief Query mDNS for TXT record
2017-01-04 11:54:07 -05:00
*
2017-12-07 08:21:40 -05:00
* @param instance_name service instance name
* @param service_type service type (_http, _arduino, _ftp etc.)
* @param proto service protocol (_tcp, _udp, etc.)
* @param timeout time in milliseconds to wait for answer.
* @param result pointer to the result of the query
2017-01-04 11:54:07 -05:00
*
2017-12-07 08:21:40 -05:00
* @return
* - ESP_OK success
* - ESP_ERR_INVALID_STATE mDNS is not running
* - ESP_ERR_NO_MEM memory error
* - ESP_ERR_INVALID_ARG parameter error
2017-01-04 11:54:07 -05:00
*/
2017-12-07 08:21:40 -05:00
esp_err_t mdns_query_txt(const char * instance_name, const char * service_type, const char * proto, uint32_t timeout, mdns_result_t ** result);
2017-01-04 11:54:07 -05:00
/**
2017-12-07 08:21:40 -05:00
* @brief Query mDNS for A record
2017-01-04 11:54:07 -05:00
*
2017-12-07 08:21:40 -05:00
* @param host_name host name to look for
* @param timeout time in milliseconds to wait for answer.
* @param addr pointer to the resulting IP4 address
2017-01-04 11:54:07 -05:00
*
* @return
* - ESP_OK success
2017-12-07 08:21:40 -05:00
* - 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, ip4_addr_t * addr);
/**
* @brief Query mDNS for A record
*
* @param host_name host name to look for
* @param timeout time in milliseconds to wait for answer. If 0, max_results needs to be defined
* @param addr pointer to the resulting IP6 address
*
* @return
* - 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_aaaa(const char * host_name, uint32_t timeout, ip6_addr_t * addr);
/**
* @brief System event handler
* This method controls the service state on all active interfaces and applications are required
* to call it from the system event handler for normal operation of mDNS service.
*
* @param ctx The system event context
* @param event The system event
2017-01-04 11:54:07 -05:00
*/
2017-12-07 08:21:40 -05:00
esp_err_t mdns_handle_system_event(void *ctx, system_event_t *event);
2017-01-04 11:54:07 -05:00
#ifdef __cplusplus
}
#endif
#endif /* ESP_MDNS_H_ */