docs » hs.bonjour

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.

Because this function collects the results of multiple callbacks before invoking its own callback, the timeout value specified indicates the maximum number of seconds to wait after the latest value received by findServices unless the macOS specifies that it believes there are no more service types to identify.

• This is a best guess made by the macOS which may not always be accurate if your local network is particularly slow or if there are machines on your network which are slow to respond.
• See hs.bonjour:findServices for more details if you need to create your own query which can persist for longer periods of time or require termination logic that ignores the macOS's best guess.

• 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

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

For most non-coporate network users, it is likely that the callback will only be invoked once for the local domain. This is normal. Corporate networks or networks including Linux machines using additional domains defined with Avahi may see additional domains as well, though most Avahi installations now use only 'local' by default unless specifically configured to do otherwise.

When moreExpected becomes false, it is the macOS's best guess as to whether additional records are available.

• Generally macOS is fairly accurate in this regard concerning domain searchs, so to reduce the impact on system resources, it is recommended that you use hs.bonjour:stop when this parameter is false

• 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

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

For most non-coporate network users, it is likely that the callback will only be invoked once for the local domain. This is normal. Corporate networks or networks including Linux machines using additional domains defined with Avahi may see additional domains as well, though most Avahi installations now use only 'local' by default unless specifically configured to do otherwise.

When moreExpected becomes false, it is the macOS's best guess as to whether additional records are available.

• Generally macOS is fairly accurate in this regard concerning domain searchs, so to reduce the impact on system resources, it is recommended that you use hs.bonjour:stop when this parameter is false

• 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

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.

The special type "_services._dns-sd._udp." can be used to discover the types of services being advertised on your network. The hs.bonjour.service objects returned to the callback function cannot actually be resolved, but you can use the hs.bonjour.service:name method to create a list of services that are currently present and being advertised.

• this special type is used by the shortcut function hs.bonjour.networkServices for this specific purpose.

The special domain "dns-sd.org." can be specified to find services advertised through Wide-Area Service Discovery as described at http://www.dns-sd.org. This can be used to discover a limited number of globally available sites on the internet, especially with a service type of _http._tcp..

• In theory, with additional software, you may be able to publish services on your machine for Wide-Area Service discovery using this domain with hs.bonjour.service.new but the local dns server requirements and security implications of doing so are beyond the scope of this documentation. You should refer to http://www.dns-sd.org and your local DNS Server administrator or provider for more details.

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

In general, when your callback function for hs.bonjour:findBrowsableDomains, hs.bonjour:findRegistrationDomains, or hs.bonjour:findServices receives false for the moreExpected paramter, you should invoke this method on the browserObject unless there are specific reasons not to. Possible reasons you might want to extend the life of the browserObject are documented within each method.