| 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 | [](https://travis-ci.org/watson/bonjour)
|
|---|
| 8 | [](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
|
|---|
