Daiki Kato / mbed-os-lychee

mbed-os for GR-LYCHEE

Dependents:   mbed-os-example-blinky-gr-lychee GR-Boads_Camera_sample GR-Boards_Audio_Recoder GR-Boads_Camera_DisplayApp ... more

features/FEATURE_LWIP/lwip-interface/lwip/doc/mdns.txt@0:f782d9c66c49, 2018-02-02 (annotated)

Committer:
dkato
Date:
Fri Feb 02 05:42:23 2018 +0000
Revision:
0:f782d9c66c49
mbed-os for GR-LYCHEE

Who changed what in which revision?

UserRevisionLine numberNew contents of line
dkato 0:f782d9c66c49 1 Multicast DNS for lwIP
dkato 0:f782d9c66c49 2
dkato 0:f782d9c66c49 3 Author: Erik Ekman
dkato 0:f782d9c66c49 4
dkato 0:f782d9c66c49 5
dkato 0:f782d9c66c49 6 Note! The MDNS responder does not have all features required by the standards.
dkato 0:f782d9c66c49 7 See notes in src/apps/mdns/mdns.c for what is left. It is however usable in normal
dkato 0:f782d9c66c49 8 cases - but watch out if many devices on the same network try to use the same
dkato 0:f782d9c66c49 9 host/service instance names.
dkato 0:f782d9c66c49 10
dkato 0:f782d9c66c49 11
dkato 0:f782d9c66c49 12 How to enable:
dkato 0:f782d9c66c49 13 ==============
dkato 0:f782d9c66c49 14
dkato 0:f782d9c66c49 15 MDNS support does not depend on DNS.
dkato 0:f782d9c66c49 16 MDNS supports using IPv4 only, v6 only, or v4+v6.
dkato 0:f782d9c66c49 17
dkato 0:f782d9c66c49 18 To enable MDNS responder, set
dkato 0:f782d9c66c49 19 LWIP_MDNS_RESPONDER = 1
dkato 0:f782d9c66c49 20 in lwipopts.h and add src/apps/mdns/mdns.c to your list of files to build.
dkato 0:f782d9c66c49 21
dkato 0:f782d9c66c49 22 The max number of services supported per netif is defined by MDNS_MAX_SERVICES,
dkato 0:f782d9c66c49 23 default is 1.
dkato 0:f782d9c66c49 24
dkato 0:f782d9c66c49 25 Increase MEMP_NUM_UDP_PCB by 1. MDNS needs one PCB.
dkato 0:f782d9c66c49 26 Increase LWIP_NUM_NETIF_CLIENT_DATA by 1 (MDNS needs one entry on netif).
dkato 0:f782d9c66c49 27
dkato 0:f782d9c66c49 28 MDNS with IPv4 requires LWIP_IGMP = 1, and preferably LWIP_AUTOIP = 1.
dkato 0:f782d9c66c49 29 MDNS with IPv6 requires LWIP_IPV6_MLD = 1, and that a link-local address is
dkato 0:f782d9c66c49 30 generated.
dkato 0:f782d9c66c49 31
dkato 0:f782d9c66c49 32 The MDNS code puts its structs on the stack where suitable to reduce dynamic
dkato 0:f782d9c66c49 33 memory allocation. It may use up to 1kB of stack.
dkato 0:f782d9c66c49 34
dkato 0:f782d9c66c49 35 MDNS needs a strncasecmp() implementation. If you have one, define
dkato 0:f782d9c66c49 36 LWIP_MDNS_STRNCASECMP to it. Otherwise the code will provide an implementation
dkato 0:f782d9c66c49 37 for you.
dkato 0:f782d9c66c49 38
dkato 0:f782d9c66c49 39
dkato 0:f782d9c66c49 40 How to use:
dkato 0:f782d9c66c49 41 ===========
dkato 0:f782d9c66c49 42
dkato 0:f782d9c66c49 43 Call mdns_resp_init() during system initialization.
dkato 0:f782d9c66c49 44 This opens UDP sockets on port 5353 for IPv4 and IPv6.
dkato 0:f782d9c66c49 45
dkato 0:f782d9c66c49 46
dkato 0:f782d9c66c49 47 To start responding on a netif, run
dkato 0:f782d9c66c49 48 mdns_resp_add_netif(struct netif *netif, char *hostname, u32_t dns_ttl)
dkato 0:f782d9c66c49 49
dkato 0:f782d9c66c49 50 The hostname will be copied. If this returns successfully, the netif will join
dkato 0:f782d9c66c49 51 the multicast groups and any MDNS/legacy DNS requests sent unicast or multicast
dkato 0:f782d9c66c49 52 to port 5353 will be handled:
dkato 0:f782d9c66c49 53 - <hostname>.local type A, AAAA or ANY returns relevant IP addresses
dkato 0:f782d9c66c49 54 - Reverse lookups (PTR in-addr.arpa, ip6.arpa) of netif addresses
dkato 0:f782d9c66c49 55 returns <hostname>.local
dkato 0:f782d9c66c49 56 Answers will use the supplied TTL (in seconds)
dkato 0:f782d9c66c49 57 MDNS allows UTF-8 names, but it is recommended to stay within ASCII,
dkato 0:f782d9c66c49 58 since the default case-insensitive comparison assumes this.
dkato 0:f782d9c66c49 59
dkato 0:f782d9c66c49 60 It is recommended to call this function after an IPv4 address has been set,
dkato 0:f782d9c66c49 61 since there is currently no check if the v4 address is valid.
dkato 0:f782d9c66c49 62
dkato 0:f782d9c66c49 63 Call mdns_resp_netif_settings_changed() every time the IP address
dkato 0:f782d9c66c49 64 on the netif has changed.
dkato 0:f782d9c66c49 65
dkato 0:f782d9c66c49 66 To stop responding on a netif, run
dkato 0:f782d9c66c49 67 mdns_resp_remove_netif(struct netif *netif)
dkato 0:f782d9c66c49 68
dkato 0:f782d9c66c49 69
dkato 0:f782d9c66c49 70 Adding services:
dkato 0:f782d9c66c49 71 ================
dkato 0:f782d9c66c49 72
dkato 0:f782d9c66c49 73 The netif first needs to be registered. Then run
dkato 0:f782d9c66c49 74 mdns_resp_add_service(struct netif *netif, char *name, char *service,
dkato 0:f782d9c66c49 75 u16_t proto, u16_t port, u32_t dns_ttl,
dkato 0:f782d9c66c49 76 service_get_txt_fn_t txt_fn, void *txt_userdata);
dkato 0:f782d9c66c49 77
dkato 0:f782d9c66c49 78 The name and service pointers will be copied. Name refers to the name of the
dkato 0:f782d9c66c49 79 service instance, and service is the type of service, like _http
dkato 0:f782d9c66c49 80 proto can be DNSSD_PROTO_UDP or DNSSD_PROTO_TCP which represent _udp and _tcp.
dkato 0:f782d9c66c49 81 If this call returns successfully, the following queries will be answered:
dkato 0:f782d9c66c49 82 - _services._dns-sd._udp.local type PTR returns <service>.<proto>.local
dkato 0:f782d9c66c49 83 - <service>.<proto>.local type PTR returns <name>.<service>.<proto>.local
dkato 0:f782d9c66c49 84 - <name>.<service>.<proto>.local type SRV returns hostname and port of service
dkato 0:f782d9c66c49 85 - <name>.<service>.<proto>.local type TXT builds text strings by calling txt_fn
dkato 0:f782d9c66c49 86 with the supplied userdata. The callback adds strings to the reply by calling
dkato 0:f782d9c66c49 87 mdns_resp_add_service_txtitem(struct mdns_service *service, char *txt,
dkato 0:f782d9c66c49 88 int txt_len). Example callback method:
dkato 0:f782d9c66c49 89
dkato 0:f782d9c66c49 90 static void srv_txt(struct mdns_service *service, void *txt_userdata)
dkato 0:f782d9c66c49 91 {
dkato 0:f782d9c66c49 92 res = mdns_resp_add_service_txtitem(service, "path=/", 6);
dkato 0:f782d9c66c49 93 LWIP_ERROR("mdns add service txt failed\n", (res == ERR_OK), return);
dkato 0:f782d9c66c49 94 }
dkato 0:f782d9c66c49 95
dkato 0:f782d9c66c49 96 Since a hostname struct is used for TXT storage each single item can be max
dkato 0:f782d9c66c49 97 63 bytes long, and the total max length (including length bytes for each
dkato 0:f782d9c66c49 98 item) is 255 bytes.
dkato 0:f782d9c66c49 99
dkato 0:f782d9c66c49 100 If your device runs a webserver on port 80, an example call might be:
dkato 0:f782d9c66c49 101
dkato 0:f782d9c66c49 102 mdns_resp_add_service(netif, "myweb", "_http"
dkato 0:f782d9c66c49 103 DNSSD_PROTO_TCP, 80, 3600, srv_txt, NULL);
dkato 0:f782d9c66c49 104
dkato 0:f782d9c66c49 105 which will publish myweb._http._tcp.local for any hosts looking for web servers,
dkato 0:f782d9c66c49 106 and point them to <hostname>.local:80
dkato 0:f782d9c66c49 107
dkato 0:f782d9c66c49 108 Relevant information will be sent as additional records to reduce number of
dkato 0:f782d9c66c49 109 requests required from a client.
dkato 0:f782d9c66c49 110
dkato 0:f782d9c66c49 111 Removing services is currently not supported. Services are removed when the
dkato 0:f782d9c66c49 112 netif is removed.
dkato 0:f782d9c66c49 113