1 | # bonjour
|
2 |
|
3 | A Bonjour/Zeroconf protocol implementation in pure JavaScript. Publish
|
4 | services on the local network or discover existing services using
|
5 | multicast DNS.
|
6 |
|
7 | [![Build status](https://travis-ci.org/watson/bonjour.svg?branch=master)](https://travis-ci.org/watson/bonjour)
|
8 | [![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg?style=flat)](https://github.com/feross/standard)
|
9 |
|
10 | ## Installation
|
11 |
|
12 | ```
|
13 | npm install bonjour
|
14 | ```
|
15 |
|
16 | ## Usage
|
17 |
|
18 | ```js
|
19 | var bonjour = require('bonjour')()
|
20 |
|
21 | // advertise an HTTP server on port 3000
|
22 | bonjour.publish({ name: 'My Web Server', type: 'http', port: 3000 })
|
23 |
|
24 | // browse for all http services
|
25 | bonjour.find({ type: 'http' }, function (service) {
|
26 | console.log('Found an HTTP server:', service)
|
27 | })
|
28 | ```
|
29 |
|
30 | ## API
|
31 |
|
32 | ### Initializing
|
33 |
|
34 | ```js
|
35 | var bonjour = require('bonjour')([options])
|
36 | ```
|
37 |
|
38 | The `options` are optional and will be used when initializing the
|
39 | underlying multicast-dns server. For details see [the multicast-dns
|
40 | documentation](https://github.com/mafintosh/multicast-dns#mdns--multicastdnsoptions).
|
41 |
|
42 | ### Publishing
|
43 |
|
44 | #### `var service = bonjour.publish(options)`
|
45 |
|
46 | Publishes a new service.
|
47 |
|
48 | Options are:
|
49 |
|
50 | - `name` (string)
|
51 | - `host` (string, optional) - defaults to local hostname
|
52 | - `port` (number)
|
53 | - `type` (string)
|
54 | - `subtypes` (array of strings, optional)
|
55 | - `protocol` (string, optional) - `udp` or `tcp` (default)
|
56 | - `txt` (object, optional) - a key/value object to broadcast as the TXT
|
57 | record
|
58 |
|
59 | IANA maintains a [list of official service types and port
|
60 | numbers](http://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml).
|
61 |
|
62 | #### `bonjour.unpublishAll([callback])`
|
63 |
|
64 | Unpublish all services. The optional `callback` will be called when the
|
65 | services have been unpublished.
|
66 |
|
67 | #### `bonjour.destroy()`
|
68 |
|
69 | Destroy the mdns instance. Closes the udp socket.
|
70 |
|
71 | ### Browser
|
72 |
|
73 | #### `var browser = bonjour.find(options[, onup])`
|
74 |
|
75 | Listen for services advertised on the network. An optional callback can
|
76 | be provided as the 2nd argument and will be added as an event listener
|
77 | for the `up` event.
|
78 |
|
79 | Options (all optional):
|
80 |
|
81 | - `type` (string)
|
82 | - `subtypes` (array of strings)
|
83 | - `protocol` (string) - defaults to `tcp`
|
84 | - `txt` (object) - passed into [dns-txt
|
85 | module](https://github.com/watson/dns-txt) contructor. Set to `{
|
86 | binary: true }` if you want to keep the TXT records in binary
|
87 |
|
88 | #### `var browser = bonjour.findOne(options[, callback])`
|
89 |
|
90 | Listen for and call the `callback` with the first instance of a service
|
91 | matching the `options`. If no `callback` is given, it's expected that
|
92 | you listen for the `up` event. The returned `browser` will automatically
|
93 | stop it self after the first matching service.
|
94 |
|
95 | Options are the same as given in the `browser.find` function.
|
96 |
|
97 | #### `Event: up`
|
98 |
|
99 | Emitted every time a new service is found that matches the browser.
|
100 |
|
101 | #### `Event: down`
|
102 |
|
103 | Emitted every time an existing service emmits a goodbye message.
|
104 |
|
105 | #### `browser.services`
|
106 |
|
107 | An array of services known by the browser to be online.
|
108 |
|
109 | #### `browser.start()`
|
110 |
|
111 | Start looking for matching services.
|
112 |
|
113 | #### `browser.stop()`
|
114 |
|
115 | Stop looking for matching services.
|
116 |
|
117 | #### `browser.update()`
|
118 |
|
119 | Broadcast the query again.
|
120 |
|
121 | ### Service
|
122 |
|
123 | #### `Event: up`
|
124 |
|
125 | Emitted when the service is up.
|
126 |
|
127 | #### `Event: error`
|
128 |
|
129 | Emitted if an error occurrs while publishing the service.
|
130 |
|
131 | #### `service.stop([callback])`
|
132 |
|
133 | Unpublish the service. The optional `callback` will be called when the
|
134 | service have been unpublished.
|
135 |
|
136 | #### `service.start()`
|
137 |
|
138 | Publish the service.
|
139 |
|
140 | #### `service.name`
|
141 |
|
142 | The name of the service, e.g. `Apple TV`.
|
143 |
|
144 | #### `service.type`
|
145 |
|
146 | The type of the service, e.g. `http`.
|
147 |
|
148 | #### `service.subtypes`
|
149 |
|
150 | An array of subtypes. Note that this property might be `null`.
|
151 |
|
152 | #### `service.protocol`
|
153 |
|
154 | The protocol used by the service, e.g. `tcp`.
|
155 |
|
156 | #### `service.host`
|
157 |
|
158 | The hostname or ip address where the service resides.
|
159 |
|
160 | #### `service.port`
|
161 |
|
162 | The port on which the service listens, e.g. `5000`.
|
163 |
|
164 | #### `service.fqdn`
|
165 |
|
166 | The fully qualified domain name of the service. E.g. if given the name
|
167 | `Foo Bar`, the type `http` and the protocol `tcp`, the `service.fqdn`
|
168 | property will be `Foo Bar._http._tcp.local`.
|
169 |
|
170 | #### `service.txt`
|
171 |
|
172 | The TXT record advertised by the service (a key/value object). Note that
|
173 | this property might be `null`.
|
174 |
|
175 | #### `service.published`
|
176 |
|
177 | A boolean indicating if the service is currently published.
|
178 |
|
179 | ## License
|
180 |
|
181 | MIT
|