bonjour

​
Find and publish network services advertised by multicast DNS (Bonjour) with Hammerspoon.
This module will allow you to discover services advertised on your network through multicast DNS and publish services offered by your computer.
Submodules
​hs.bonjour.service​
API Overview
Functions - API calls offered directly by the extension
​machineServices​
​networkServices​
Constructors - API calls which return an object, typically one that offers API methods
​new​
Methods - API calls which can only be made on an object returned by a constructor
​findBrowsableDomains​
​findRegistrationDomains​
​findServices​
​includesPeerToPeer​
​stop​
API Documentation
Functions
​machineServices​
Signature
hs.bonjour.machineServices(target, callback) -> none
Type
Function
Description
Polls a host for the service types it is advertising via multicast DNS.
Parameters
target - a string specifying the target host to query for advertised service types
callback - a callback function which will be invoked when the service type query has completed. The callback should expect one argument which will either be an array of strings specifying the service types the target is advertising or a string specifying the error that occurred.
Returns
None
Notes
this function may not work for all clients implementing multicast DNS; it has been successfully tested with macOS and Linux targets running the Avahi Daemon service, but has generally returned an error when used with minimalist implementations found in common IOT devices and embedded electronics.
​networkServices​
Signature
hs.bonjour.networkServices(callback, [timeout]) -> none
Type
Function
Description
Returns a list of service types being advertised on your local network.
Parameters
callback - a callback function which will be invoked when the services query has completed. The callback should expect one argument: an array of strings specifying the service types discovered on the local network.
timeout - an optional number, default 5, specifying the maximum number of seconds after the most recently received service type Hammerspoon should wait trying to identify advertised service types before finishing its query and invoking the callback.
Returns
None
Notes
This function is a convienence wrapper to hs.bonjour:findServices which collects the results from multiple callbacks made to findServices and returns them all at once to the callback function provided as an argument to this function.
Constructors
​new​
Signature
hs.bonjour.new() -> browserObject
Type
Constructor
Description
Creates a new network service browser that finds published services on a network using multicast DNS.
Parameters
None
Returns
a new browserObject or nil if an error occurs
Methods
​findBrowsableDomains​
Signature
hs.bonjour:findBrowsableDomains(callback) -> browserObject
Type
Method
Description
Return a list of zero-conf and bonjour domains visibile to the users computer.
Parameters
callback - a function which will be invoked as visible domains are discovered. The function should accept the following parameters and return none:
browserObject - the userdata object for the browserObject which initiated the search
type - a string which will be 'domain' or 'error'
if type == 'domain', the remaining arguments will be:
added - a boolean value indicating whether this callback invocation represents a newly discovered or added domain (true) or that the domain has been removed from the network (false)
domain - a string specifying the name of the domain discovered or removed
moreExpected - a boolean value indicating whether or not the browser expects to discover additional domains or not.
if type == 'error', the remaining arguments will be:
errorString - a string specifying the error which has occurred
Returns
the browserObject
Notes
This method returns domains which are visible to your machine; however, your machine may or may not be able to access or publish records within the returned domains. See hs.bonjour:findRegistrationDomains​
​findRegistrationDomains​
Signature
hs.bonjour:findRegistrationDomains(callback) -> browserObject
Type
Method
Description
Return a list of zero-conf and bonjour domains this computer can register services in.
Parameters
callback - a function which will be invoked as domains are discovered. The function should accept the following parameters and return none:
browserObject - the userdata object for the browserObject which initiated the search
type - a string which will be 'domain' or 'error'
if type == 'domain', the remaining arguments will be:
added - a boolean value indicating whether this callback invocation represents a newly discovered or added domain (true) or that the domain has been removed from the network (false)
domain - a string specifying the name of the domain discovered or removed
moreExpected - a boolean value indicating whether or not the browser expects to discover additional domains or not.
if type == 'error', the remaining arguments will be:
errorString - a string specifying the error which has occurred
Returns
the browserObject
Notes
This is the preferred method for accessing domains as it guarantees that the host machine can connect to services in the returned domains. Access to domains outside this list may be more limited. See also hs.bonjour:findBrowsableDomains​
​findServices​
Signature
hs.bonjour:findServices(type, [domain], [callback]) -> browserObject
Type
Method
Description
Find advertised services of the type specified.
Parameters
type - a string specifying the type of service to discover on your network. This string should be specified in the format of '_service._protocol.' where _protocol is one of '_tcp' or '_udp'. Examples of common service types can be found in hs.bonjour.serviceTypes.
domain - an optional string specifying the domain to look for advertised services in. The domain should end with a period. If you omit this parameter, the default registration domain will be used, usually "local."
callback - a callback function which will be invoked as service advertisements meeting the specified criteria are discovered. The callback function should expect 2-5 arguments as follows:
if a service is discovered or advertising for the service is terminated, the arguments will be:
the browserObject
the string "domain"
a boolean indicating whether the service is being advertised (true) or should be removed because advertisments for the service are being terminated (false)
the serviceObject for the specific advertisement (see hs.bonjour.service)
a boolean indicating if more advertisements are expected (true) or if the macOS believes that there are no more advertisements to be discovered (false).
if an error occurs, the callback arguments will be:
the browserObject
the string "error"
a string specifying the specific error that occurred
Returns
the browserObject
Notes
macOS will indicate when it believes there are no more advertisements of the type specified by type in domain by marking the last argument to your callback function as false. This is a best guess and may not always be accurate if your network is slow or some servers on your network are particularly slow to respond.
In addition, if you leave the browser running this method, you will get future updates when services are removed because of server shutdowns or added because of new servers being booted up.
Leaving the browser running does consume some system resources though, so you will have to determine, based upon your specific requirements, if this is a concern for your specific task or not. To terminate the browser when you have rtrieved all of the infomration you reuqire, you can use the hs.bonjour:stop method.
​includesPeerToPeer​
| Signature | hs.bonjour:includesPeerToPeer([value]) -> current value | browserObject | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Get or set whether to also browse over peer-to-peer Bluetooth and Wi-Fi, if available. | | Parameters |
value - an optional boolean, default false, value specifying whether to also browse over peer-to-peer Bluetooth and Wi-Fi, if available.
| | Returns |
if value is provided, returns the browserObject; otherwise returns the current value for this property
| | Notes |
This property must be set before initiating a search to have an effect.
|
​stop​
Signature
hs.bonjour:stop() -> browserObject
Type
Method
Description
Stops a currently running search or resolution for the browser object
Parameters
None
Returns
the browserObject
Notes
This method should be invoked when you have identified the services or hosts you require to reduce the consumption of system resources.
Invoking this method on an already idle browser will do nothing