Browse files

[doc] tweaked documentation on network interfaces

  • Loading branch information...
1 parent e9fb6cf commit 8a3ac950f4955ba3837b8b37c9af9b37161d7f8e @agnat committed Dec 28, 2012
Showing with 12 additions and 3 deletions.
  1. +12 −3 doc/pages/user_guide.ejs
@@ -19,6 +19,7 @@ h1. mdns User Guide
** "TXT Records":#txt_records
** "The Resolver Sequence":#resolver_sequence
** "Network Interfaces":#network_interfaces
+** "Error Handling":#error_handling
* "Reference":#reference
** "mdns.Advertisement()":#advertisement
** "mdns.Browser()":#browser
@@ -43,7 +44,7 @@ h2(#tutorial). Tutorial
Before we begin go to the internet and get you a _bonjour browser_ so that you can _ALL_ the service discovery.
-Multicast DNS service discovery provides a way to announce and discover services on the local network. Here is how to announce a HTTP server running on port 4321:
+Multicast DNS service discovery is a solution to announce and discover services on the local network. Here is how to announce a HTTP server running on port 4321:
bc. var mdns = require('mdns')
, ad = mdns.createAdvertisement(mdns.tcp('http'), 4321)
@@ -107,6 +108,10 @@ In fact all of these are legal constructor arguments for @ServiceType@. JSON (de
Note: mdns liberally makes up service types for testing purposes and it is probably OK if you do the same for your media art project or something. But if you ship a product you should register your service type with the "IANA":
+h4(#subtypes). Subtypes
h3(#txt_records). TXT Records
Each service has an associated DNS TXT record. The application can use it to publish a small amount of metadata. The record contains key-value pairs. The keys must be all printable ascii characters excluding '='. The value may contain any data.
@@ -183,10 +188,14 @@ These are the same names as returned by @os.networkInterfaces()@. They are persi
When browsing the @service@ object passed to the event listeners has a @networkInterface@ property. It contains the human readable name of the network interface the service was discovered on. See the "service object example":#service_object_example above.
+On windows interface names are only available on vista and better.
h4. IP Addresses
IP addresses are portable across platforms. In an environment that uses dynamic addresses (DHCP, mdns, zeroconf or MS autoconf) they are not necessarily persistent across reboots or disconnects. Also, note that currently simple string comparison is used to find the address in the result returned by @os.networkInterfaces()@. This works great for IPv4 addresses. However, IPv6 addresses have multiple equivalent string representations. That means at present you have to use the exact same string as found in the result of @os.networkInterfaces()@. Otherwise mdns will fail to find the corresponding interface. This makes IPv6 addresses less portable than IPv4 ones.
+On windows IP addresses are only available on vista and better.
h4. Interface Indices
The underlying library dns_sd uses interface indices to identify network interfaces. It is a one-based index into the list of interfaces as returned by @ifconfig@ or @ipconfig@. It is not a valid index into the list returned by @os.networkInterfaces()@ because node intentionally skips interfaces that have no address assigned or are down. Passing zero as @networkInterface@ means "do the right thing". Refer to the dns_sd API documentation under "Further Reading":#further_reading for details. This is the default behavior.
@@ -200,9 +209,9 @@ bc. var browser = mdns.createBrowser( mdns.tcp('http')
On current versions of Mac OS X a @Browser@ listening on the loopback interface will still discover _all_ services running on the local host. To discover only services that are announced on the loopback interface you'll have to do some filtering in your @serviceUp@ and @serviceDown@ listeners. Just ignore any event where @service.interfaceIndex@ does not equal @mdns.loopbackInterface()@. This approach is portable across platforms.
-h4. Compatibility
+h3(#error_handling). Error Handling
-On windows interface names and IP addresses are only available on vista and better. Also note that historic versions of node did not have @os.networkInterfaces()@. On these versions using an IP address will not work.
h2(#reference). Reference

0 comments on commit 8a3ac95

Please sign in to comment.