docs » hs.urlevent

A function that should handle http:// and https:// URL events

• The function should handle four arguments:
• scheme - A string containing the URL scheme (i.e. "http")
• host - A string containing the host requested (e.g. "www.hammerspoon.org")
• params - A table containing the key/value pairs of all the URL parameters
• fullURL - A string containing the full, original URL
• senderPID - An integer containing the PID of the application that opened the URL, if available (otherwise -1)

A function that should handle mailto: URL events

• The function should handle four arguments:
• scheme - A string containing the URI scheme (i.e. "mailto")
• host - A string containing the host requested (typically nil)
• params - A table containing the key/value pairs of all the URL parameters, typically empty
• fullURL - A string containing the full, original URI
• senderPID - An integer containing the PID of the application that opened the URI, if available (otherwise -1)

Registers a callback for a hammerspoon:// URL event

• eventName - A string containing the name of an event
• callback - A function that will be called when the specified event is received, or nil to remove an existing callback

• None

• The callback function should accept two parameters:
• eventName - A string containing the name of the event
• params - A table containing key/value string pairs containing any URL parameters that were specified in the URL
• senderPID - An integer containing the PID of the sending application, if available (otherwise -1)
• Given the URL hammerspoon://doThingA?value=1 The event name is doThingA and the callback's params argument will be a table containing {["value"] = "1"}

Gets all of the application bundle identifiers of applications able to handle a URL scheme

• scheme - A string containing a URL scheme (e.g. 'http')

• A table containing the bundle identifiers of all applications that can handle the scheme

Gets the application bundle identifier of the application currently registered to handle a URL scheme

• scheme - A string containing a URL scheme (e.g. 'http')

• A string containing the bundle identifier of the current default application

Opens a URL with the default application

• url - A string containing a URL, which must contain a scheme and '://'

• A boolean, true if the URL was opened successfully, otherwise false

Opens a URL with a specified application

• url - A string containing a URL
• bundleID - A string containing an application bundle identifier (e.g. "com.apple.Safari")

• True if the application was launched successfully, otherwise false

Sets the default system handler for URLs of a given scheme

• scheme - A string containing the URL scheme to change. This must be 'http' or 'https' (although entering either will change the handler for both)
• bundleID - An optional string containing an application bundle identifier for the application to set as the default handler. Defaults to org.hammerspoon.Hammerspoon.

• None

• Changing the default handler for http/https URLs will display a system prompt asking the user to confirm the change

Stores a URL handler that will be restored when Hammerspoon or reloads its config

• scheme - A string containing the URL scheme to change. This must be 'http' (although both http:// and https:// URLs will be affected)
• bundleID - A string containing an application bundle identifier (e.g. 'com.apple.Safari') for the application to set as the default handler when Hammerspoon exits or reloads its config

• None

• You don't have to call this function if you want Hammerspoon to permanently be your default handler. Only use this if you want the handler to be automatically reverted to something else when Hammerspoon exits/reloads.