Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 195 lines (148 sloc) 7.567 kb
81017d5 andrewtj initial commit
andrewtj authored
1 #dnssd_erlang
2
27dab9e andrewtj Format to 80 columns where appropriate.
andrewtj authored
3 dnssd_erlang is an interface to Apple's Bonjour DNS Service Discovery
4 implementation. Bonjour allows applications to browse, resolve and register
5 network services via link-local multicast DNS on the local network and via
6 unicast DNS over the internet. In the later case if the service is running
7 behind a NAT gateway Bonjour will only advertise it if a port forward can be
8 negotiated via NAT-PMP or uPNP (which is attempted automatically).
81017d5 andrewtj initial commit
andrewtj authored
9
dcbf45e andrewtj Integrated building of Windows DLL with rebar
andrewtj authored
10 ### Development Status
959bd83 andrewtj Update readme
andrewtj authored
11
27dab9e andrewtj Format to 80 columns where appropriate.
andrewtj authored
12 The API and functionality provided aren't yet set in stone but will be locked
13 down before release 1.0.
81017d5 andrewtj initial commit
andrewtj authored
14
dcbf45e andrewtj Integrated building of Windows DLL with rebar
andrewtj authored
15 ### Prerequisites
81017d5 andrewtj initial commit
andrewtj authored
16
27dab9e andrewtj Format to 80 columns where appropriate.
andrewtj authored
17 Apple Bonjour or a compatible API such as [Avahi](http://avahi.org/) with it's
18 compatibility layer along with the appropriate development files:
6a6169c andrewtj Add pointers to compatible software in readme
andrewtj authored
19
20 * OS X - bundled
21 * Windows - [Bonjour SDK](http://developer.apple.com/opensource/)
22 * BSD/Linux - search for Avahi in your operating systems software manager
47fea47 andrewtj Add some examples
andrewtj authored
23
dcbf45e andrewtj Integrated building of Windows DLL with rebar
andrewtj authored
24 ### Build Process
25
95ab64d andrewtj Remove bundled rebar and Makefile
andrewtj authored
26 Build with [rebar](https://github.com/basho/rebar):
27
28 * compile: `rebar compile`
29 * test: `rebar eunit`
30 * edoc: `rebar doc`
dcbf45e andrewtj Integrated building of Windows DLL with rebar
andrewtj authored
31
27dab9e andrewtj Format to 80 columns where appropriate.
andrewtj authored
32 If you are running Linux with Avahi you will need Avahi's Bonjour compatibility
94fa69b andrewtj Add note about running avahi-daemon to readme
andrewtj authored
33 layer installed. If `{error,-65537}` is returned when starting an operation
34 it may be that avahi-daemon is not running.
dcbf45e andrewtj Integrated building of Windows DLL with rebar
andrewtj authored
35
27dab9e andrewtj Format to 80 columns where appropriate.
andrewtj authored
36 If you are running Windows you will need Visual Studio and the Bonjour SDK
37 installed. The project can then be built from a Visual Studio command prompt.
dcbf45e andrewtj Integrated building of Windows DLL with rebar
andrewtj authored
38
39 ### Feedback
40
41 Please direct your [feedback here](http://andrew.tj.id.au/email).
42
43 ### Example use
47fea47 andrewtj Add some examples
andrewtj authored
44
32f9030 andrewtj Try again at plain markdown...
andrewtj authored
45 Eshell V5.8.2 (abort with ^G)
46 1> dnssd:start().
47 ok
47fea47 andrewtj Add some examples
andrewtj authored
48
682155d andrewtj More minor readme tweaks
andrewtj authored
49 First start the application via `dnssd:start/1` or `application:start(dnssd)`.
47fea47 andrewtj Add some examples
andrewtj authored
50
51 ### Browsing for Services
52
32f9030 andrewtj Try again at plain markdown...
andrewtj authored
53 2> dnssd:browse("_http._tcp").
54 {ok,#Ref<0.0.0.197>}
47fea47 andrewtj Add some examples
andrewtj authored
55
27dab9e andrewtj Format to 80 columns where appropriate.
andrewtj authored
56 In the success case, all functions return a tuple of the form `{ok, Reference}`.
682155d andrewtj More minor readme tweaks
andrewtj authored
57 Reference should be retained to pass to `dnssd:stop/1` when no further results
58 are required.
47fea47 andrewtj Add some examples
andrewtj authored
59
32f9030 andrewtj Try again at plain markdown...
andrewtj authored
60 3> flush().
61 Shell got {dnssd,#Ref<0.0.0.197>,
62 {browse,add,
63 {<<"dnsndnsweb">>,<<"_http._tcp.">>,
64 <<"bonjour.tj.id.au.">>}}}
65 Shell got {dnssd,#Ref<0.0.0.197>,
66 {browse,add,{<<"TIVO">>,<<"_http._tcp.">>,<<"local.">>}}}
67 ok
68
27dab9e andrewtj Format to 80 columns where appropriate.
andrewtj authored
69 Results will be sent in tuples of the form
70 `{dnssd, Reference, {Operation, Change, Result}}`. Reference will be the same
71 reference which was used to start the operation. Operation will be one of the
72 atoms `browse`, `resolve`, `register` or `enumerate`. Change will be the atom
73 `add` or `remove` and the result will be an operation specific term. For the
74 browse operation, it will be a tuple containing binaries of the form
75 `{ServiceName, ServiceType, Domain}`.
47fea47 andrewtj Add some examples
andrewtj authored
76
32f9030 andrewtj Try again at plain markdown...
andrewtj authored
77 4> dnssd:browse(<<"_http._tcp">>, <<"dns-sd.org">>).
78 {ok,#Ref<0.0.0.488>}
79 5> flush().
80 Shell got {dnssd,#Ref<0.0.0.488>,
81 {browse,add,
82 {<<" * Apple, makers of the iPod">>,
83 <<"_http._tcp.">>,<<"dns-sd.org.">>}}}
84 Shell got {dnssd,#Ref<0.0.0.488>,
85 {browse,add,
86 {<<" * Google, searching the Web">>,
87 <<"_http._tcp.">>,<<"dns-sd.org.">>}}}
88 %% snipped %%
89 ok
47fea47 andrewtj Add some examples
andrewtj authored
90
27dab9e andrewtj Format to 80 columns where appropriate.
andrewtj authored
91 Browsing can be limited to a specific domain by specifying the domain as
92 argument two. Both domains and service types may be specified as lists or
93 binaries.
47fea47 andrewtj Add some examples
andrewtj authored
94
95 ### Resolving a Service Instance
96
32f9030 andrewtj Try again at plain markdown...
andrewtj authored
97 6> dnssd:resolve(<<" * DNS Service Discovery">>, <<"_http._tcp.">>, <<"dns-sd.org.">>).
98 {ok,#Ref<0.0.0.20357>}
47fea47 andrewtj Add some examples
andrewtj authored
99
27dab9e andrewtj Format to 80 columns where appropriate.
andrewtj authored
100 To resolve a service, supply it's name, registration type and domain to the
101 resolve function.
47fea47 andrewtj Add some examples
andrewtj authored
102
32f9030 andrewtj Try again at plain markdown...
andrewtj authored
103 7> flush().
104 Shell got {dnssd,#Ref<0.0.0.20357>,
105 {resolve,{<<"dns-sd.org.">>,80,
106 [{<<"txtvers">>,<<"1">>},{<<"path">>,<<"/">>}]}}}
107 ok
47fea47 andrewtj Add some examples
andrewtj authored
108
27dab9e andrewtj Format to 80 columns where appropriate.
andrewtj authored
109 Unlike the other operations results won't be tagged add or remove as the
110 underlying DNSSD API does not provide this information. As resolve is generally
111 called just prior to connecting to a service this shouldn't pose a problem. The
7a915c6 andrewtj Resolve decodes key=value strings into {Key, Value} tuples
andrewtj authored
112 Result term for this operation is a tuple of the form
27dab9e andrewtj Format to 80 columns where appropriate.
andrewtj authored
113 `{Hostname, Port, TxtStrings}` where Hostname is a binary, Port is an integer
7a915c6 andrewtj Resolve decodes key=value strings into {Key, Value} tuples
andrewtj authored
114 and TxtStrings is a list containing either binaries or should a given string
115 contain an equals sign, a `{Key, Value}` tuple wherein Key is everything up to
116 the first equals sign and the remainder of the string is the value.
2787526 andrewtj Modify dnssd:resolve and add dnssd:resolve_sync
andrewtj authored
117
32f9030 andrewtj Try again at plain markdown...
andrewtj authored
118 8> dnssd:resolve_sync(<<" * DNS Service Discovery">>, <<"_http._tcp.">>, <<"dns-sd.org.">>).
119 {ok,{<<"dns-sd.org.">>,80,[<<"txtvers=1">>,<<"path=/">>]}}
2787526 andrewtj Modify dnssd:resolve and add dnssd:resolve_sync
andrewtj authored
120
27dab9e andrewtj Format to 80 columns where appropriate.
andrewtj authored
121 A synchronous wrapper to resolve is also provided. A timeout in milliseconds can
122 also be specified by adding a fourth argument. The default timeout is 5 seconds.
123 `{error, timeout}` will be returned should the operation timeout.
47fea47 andrewtj Add some examples
andrewtj authored
124
125 ### Registering Services
126
32f9030 andrewtj Try again at plain markdown...
andrewtj authored
127 9> dnssd:register("_answer._udp",42).
128 {ok,#Ref<0.0.0.10006>}
129 10> flush().
130 Shell got {dnssd,#Ref<0.0.0.10006>,
131 {register,add,
132 {<<"atj-mbp">>,<<"_answer._udp.">>,<<"local.">>}}}
133 ok
134
27dab9e andrewtj Format to 80 columns where appropriate.
andrewtj authored
135 The minimum arguments needed to register a service are the service type and
136 port. If no service name is supplied, the machines name is used (in the example
137 above, that's `<<"atj-mbp">>`). The Result term for this operation is a tuple
138 containing binaries of the form `{ServiceName, ServiceType, Domain}`.
47fea47 andrewtj Add some examples
andrewtj authored
139
140 For brevity, the alternative invocations of register are:
698b980 andrewtj Fix rendering of readme's register examples
andrewtj authored
141
32f9030 andrewtj Try again at plain markdown...
andrewtj authored
142 dnssd:register(Name, Type, Port).
143 dnssd:register(Type, Port, Txt).
144 dnssd:register(Name, Type, Port, Txt).
145 dnssd:register(Name, Type, Port, Txt, Host, Domain).
146
92d60e6 andrewtj tweak copy
andrewtj authored
147 Wherein:
d7e00b0 andrewtj fix bullets; hopefully...
andrewtj authored
148
27dab9e andrewtj Format to 80 columns where appropriate.
andrewtj authored
149 * `Txt` is a TXT record data in either binary form (a sequence of
150 `<<Size, String:Size/binary>>`), a list of atoms, strings or binaries or tuples
151 of the form {Key,Value} where Key and Value are atoms, strings or binaries.
152 * `Host` is the hostname of the machine running the service. Pass an empty
153 string or binary for the local machine.
154 * `Domain` is the domain to register the service within. Pass an empty string
155 or binary for all domains.
47fea47 andrewtj Add some examples
andrewtj authored
156
682155d andrewtj More minor readme tweaks
andrewtj authored
157 ***Note:*** A service may be renamed if it conflicts with another service. Check
27dab9e andrewtj Format to 80 columns where appropriate.
andrewtj authored
158 the Results tuple to determine what name a service has been assigned.
b031513 andrewtj Provide more detail on the messages dnssd sends
andrewtj authored
159
afee1c8 andrewtj Add support for local-only registrations
andrewtj authored
160 #### Local Registrations
161
f62e0cd andrewtj Use plain markdown
andrewtj authored
162 If `localhost` is passed as Host to `dnssd:register/6` the service will be
27dab9e andrewtj Format to 80 columns where appropriate.
andrewtj authored
163 registered only in the local domain (regardless of the Domain argument) and only
164 on the local machine.
afee1c8 andrewtj Add support for local-only registrations
andrewtj authored
165
47fea47 andrewtj Add some examples
andrewtj authored
166 ### Enumerating Domains
167
32f9030 andrewtj Try again at plain markdown...
andrewtj authored
168 11> dnssd:enumerate(browse).
169 {ok,#Ref<0.0.0.15448>}
170 12> flush().
171 Shell got {dnssd,#Ref<0.0.0.15448>,{enumerate,add,<<"local.">>}}
172 Shell got {dnssd,#Ref<0.0.0.15448>,{enumerate,add,<<"bonjour.tj.id.au.">>}}
173 ok
174 13> dnssd:enumerate(reg).
175 {ok,#Ref<0.0.0.15529>}
176 14> flush().
177 Shell got {dnssd,#Ref<0.0.0.15529>,{enumerate,add,<<"local.">>}}
178 Shell got {dnssd,#Ref<0.0.0.15529>,{enumerate,add,<<"bonjour.tj.id.au.">>}}
179 ok
47fea47 andrewtj Add some examples
andrewtj authored
180
27dab9e andrewtj Format to 80 columns where appropriate.
andrewtj authored
181 The Result term for this operation is a binary containing the browse or
182 registration domain.
b031513 andrewtj Provide more detail on the messages dnssd sends
andrewtj authored
183
47fea47 andrewtj Add some examples
andrewtj authored
184 ### Stopping Operations
185
27dab9e andrewtj Format to 80 columns where appropriate.
andrewtj authored
186 It's important to stop operations when no more results are needed to avoid
187 generating needless network traffic. To stop an operation pass the Reference
682155d andrewtj More minor readme tweaks
andrewtj authored
188 returned when you started the operation to `dnssd:stop/1`. Operations will also
189 be stopped if your process exits.
690e011 andrewtj Add dnssd:results/1
andrewtj authored
190
191 ### Retrieving Results
192
682155d andrewtj More minor readme tweaks
andrewtj authored
193 Results from a running operation can be retrieved by calling
194 `dnssd:results(Ref)`. For resolve operations this will only return the last
195 result. For all other operations it will return all current results.
Something went wrong with that request. Please try again.