docs » hs.bonjour.service

Represents the service records that are discovered or published by the hs.bonjour module.

This module allows you to explore the details of discovered services including ip addresses and text records, and to publish your own multicast DNS advertisements for services on your computer. This can be useful to advertise network services provided by other Hammerspoon modules or other applications on your computer which do not publish their own advertisements already.

This module will not allow you to publish proxy records for other hosts on your local network. Additional submodules which may address this limitation as well as provide additional functions available with Apple's dns-sd library are being considered but there is no estimated timeframe at present.

API Overview

Constants - Useful values which cannot be changed

serviceTypes

Constructors - API calls which return an object, typically one that offers API methods

new
remote

Methods - API calls which can only be made on an object returned by a constructor

addresses
domain
hostname
includesPeerToPeer
monitor
name
port
publish
resolve
stop
stopMonitoring
txtRecord
type

API Documentation

Constants

serviceTypes

Signature	`hs.bonjour.serviceTypes`
Type	Constant
Description	A list of common service types which can used for discovery through this module.
Notes
Source	extensions/bonjour/init.lua

Constructors

new

Signature	`hs.bonjour.service.new(name, service, port, [domain]) -> serviceObject`
Type	Constructor
Description	Returns a new serviceObject for advertising a service provided by your computer.
Parameters	`name` - The name of the service being advertised. This does not have to be the hostname of the machine. However, if you specify an empty string, the computers hostname will be used. `service` - a string specifying the service being advertised. 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`. `port` - an integer specifying the tcp or udp port the service is provided at `domain` - an optional string specifying the domain you wish to advertise this service in.
Returns	the newly created service object, or nil if there was an error
Notes	If the name specified is not unique on the network for the service type specified, then a number will be appended to the end of the name. This behavior cannot be overridden and can only be detected by checking hs.bonjour.service:name after hs.bonjour.service:publish is invoked to see if the name has been changed from what you originally assigned.
Source	extensions/bonjour/init.lua

remote

Signature	`hs.bonjour.service.remote(name, service, [domain]) -> serviceObject`
Type	Constructor
Description	Returns a new serviceObject for a remote machine (i.e. not the users computer) on your network offering the specified service.
Parameters	`name` - a string specifying the name of the advertised service on the network to locate. Often, but not always, this will be the hostname of the machine providing the desired service. `service` - a string specifying the service type. 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 the service belongs to.
Returns	the newly created service object, or nil if there was an error
Notes	In general you should not need to use this constructor, as they will be created automatically for you in the callbacks to `hs.bonjour:findServices`. This method can be used, however, when you already know that a specific service should exist on the network and you wish to resolve its current IP addresses or text records.
Source	extensions/bonjour/init.lua

Methods

addresses

Signature	`hs.bonjour.service:addresses() -> table`
Type	Method
Description	Returns a table listing the addresses for the service represented by the serviceObject
Parameters	None
Returns	an array table of strings representing the IPv4 and IPv6 address of the machine which provides the services represented by the serviceObject
Notes	for remote serviceObjects, the table will be empty if this method is invoked before hs.bonjour.service:resolve. for local (published) serviceObjects, this table will always be empty.
Source	extensions/bonjour/service.m

domain

Signature	`hs.bonjour.service:domain() -> string`
Type	Method
Description	Returns the domain the service represented by the serviceObject belongs to.
Parameters	None
Returns	a string containing the domain the service represented by the serviceObject belongs to.
Notes	for remote serviceObjects, this domain will be the domain the service was discovered in. for local (published) serviceObjects, this domain will be the domain the service is published in; if you did not specify a domain with hs.bonjour.service.new then this will be an empty string until hs.bonjour.service:publish is invoked.
Source	extensions/bonjour/service.m

hostname

Signature	`hs.bonjour.service:hostname() -> string`
Type	Method
Description	Returns the hostname of the machine the service represented by the serviceObject belongs to.
Parameters	None
Returns	a string containing the hostname of the machine the service represented by the serviceObject belongs to.
Notes	for remote serviceObjects, this will be nil if this method is invoked before hs.bonjour.service:resolve. for local (published) serviceObjects, this method will always return nil.
Source	extensions/bonjour/service.m

includesPeerToPeer

Signature	`hs.bonjour.service:includesPeerToPeer([value]) -> boolean \| serviceObject`
Type	Method
Description	Get or set whether the service represented by the service object should be published or resolved over peer-to-peer Bluetooth and Wi-Fi, if available.
Parameters	`value` - an optional boolean, default false, specifying whether advertising and resoloving should occur over peer-to-peer Bluetooth and Wi-Fi, if available.
Returns	if `value` is provided, returns the serviceObject; otherwise returns the current value.
Notes	if you are changing the value of this property, you must call this method before invoking hs.bonjour.service:publish, or after stopping publishing or resolving with hs.bonjour.service:stop.
Source	extensions/bonjour/service.m

monitor

Signature	`hs.bonjour.service:monitor([callback]) -> serviceObject`
Type	Method
Description	Monitor the service for changes to its associated text records.
Parameters	`callback` - an optional callback function which should expect 3 arguments: the serviceObject userdata the string "txtRecord" a table containing key-value pairs specifying the new text records for the service
Returns	the serviceObject
Notes	When monitoring is active, hs.bonjour.service:txtRecord will return the most recent text records observed. If this is the only method by which you check the text records, but you wish to ensure you have the most recent values, you should invoke this method without specifying a callback.
Source	extensions/bonjour/service.m

name

Signature	`hs.bonjour.service:name() -> string`
Type	Method
Description	Returns the name of the service represented by the serviceObject.
Parameters	None
Returns	a string containing the name of the service represented by the serviceObject.
Source	extensions/bonjour/service.m

port

Signature	`hs.bonjour.service:port() -> integer`
Type	Method
Description	Returns the port the service represented by the serviceObject is available on.
Parameters	None
Returns	a number specifying the port the service represented by the serviceObject is available on.
Notes	for remote serviceObjects, this will be -1 if this method is invoked before hs.bonjour.service:resolve. for local (published) serviceObjects, this method will always return the number specified when the serviceObject was created with the hs.bonjour.service.new constructor.
Source	extensions/bonjour/service.m

publish

Signature	`hs.bonjour.service:publish([allowRename], [callback]) -> serviceObject`
Type	Method
Description	Begin advertising the specified local service.
Parameters	`allowRename` - an optional boolean, default true, specifying whether to automatically rename the service if the name and type combination is already being published in the service's domain. If renaming is allowed and a conflict occurs, the service name will have `-#` appended to it where `#` is an increasing integer starting at 2. `callback` - an optional callback function which should expect 2 or 3 arguments and return none. The arguments to the callback function will be one of the following sets: on successfull publishing: the serviceObject userdata the string "published" if an error occurs during publishing: the serviceObject userdata the string "error" * a string specifying the specific error that occurred
Returns	the serviceObject
Notes	this method should only be called on serviceObjects which were created with hs.bonjour.service.new.
Source	extensions/bonjour/service.m

resolve

Signature	`hs.bonjour.service:resolve([timeout], [callback]) -> serviceObject`
Type	Method
Description	Resolve the address and details for a discovered service.
Parameters	`timeout` - an optional number, default 0.0, specifying the maximum number of seconds to attempt to resolve the details for this service. Specifying 0.0 means that the resolution should not timeout and that resolution should continue indefinately. `callback` - an optional callback function which should expect 2 or 3 arguments and return none. on successfull resolution: the serviceObject userdata the string "resolved" if an error occurs during resolution: the serviceObject userdata the string "error" * a string specifying the specific error that occurred if `timeout` is specified and is any number other than 0.0, the following will be sent to the callback when the timeout has been reached: the serviceObject userdata the string "stop"
Returns	the serviceObject
Notes	this method should only be called on serviceObjects which were returned by an `hs.bonjour` browserObject or created with hs.bonjour.service.remote.
Source	extensions/bonjour/service.m

stop

Signature	`hs.bonjour.service:stop() -> serviceObject`
Type	Method
Description	Stop advertising or resolving the service specified by the serviceObject
Parameters	None
Returns	the serviceObject
Notes	this method will stop the advertising of a service which has been published with hs.bonjour.service:publish or is being resolved with hs.bonjour.service:resolve.
Source	extensions/bonjour/service.m

stopMonitoring

Signature	`hs.bonjour.service:stopMonitoring() -> serviceObject`
Type	Method
Description	Stop monitoring a service for changes to its text records.
Parameters	None
Returns	the serviceObject
Notes	This method will stop updating hs.bonjour.service:txtRecord and invoking the callback, if any, assigned with hs.bonjour.service:monitor.
Source	extensions/bonjour/service.m

txtRecord

Signature	`hs.bonjour.service:txtRecord([records]) -> table \| serviceObject \| false`
Type	Method
Description	Get or set the text records associated with the serviceObject.
Parameters	`records` - an optional table specifying the text record for the advertised service as a series of key-value entries. All keys and values must be specified as strings.
Returns	if an argument is provided to this method, returns the serviceObject or false if there was a problem setting the text record for this service. If no argument is provided, returns the current table of text records.
Notes	for remote serviceObjects, this method will return nil if invoked before hs.bonjour.service:resolve setting the text record for a service replaces the existing records for the serviceObject. If the serviceObject is remote, this change is only visible on the local machine. For a service you are advertising, this change will be advertised to other machines.
Source	extensions/bonjour/service.m

type

Signature	`hs.bonjour.service:type() -> string`
Type	Method
Description	Returns the type of service represented by the serviceObject.
Parameters	None
Returns	a string containing the type of service represented by the serviceObject.
Source	extensions/bonjour/service.m