# hs.urlevent

Allows CommandPost to respond to URLs CommandPost is configured to react to URLs that start with commandpost:// when they are opened by OS X. This extension allows you to register callbacks for these URL events and their parameters, offering a flexible way to receive events from other applications.

You can also choose to make CommandPost the default for http:// and https:// URLs, which lets you route the URLs in your Lua code

Given a URL such as commandpost://someEventToHandle?someParam=things&otherParam=stuff, in the literal, RFC1808 sense of the URL, someEventToHandle is the hostname (or net_loc) of the URL, but given that these are not network resources, we consider someEventToHandle to be the name of the event. No path should be specified in the URL - it should consist purely of a hostname and, optionally, query parameters.

See also hs.ipc for a command line IPC mechanism that is likely more appropriate for shell scripts or command line use. Unlike hs.ipc, hs.urlevent is not able to return any data to its caller.

NOTE: If CommandPost is not running when a commandpost:// URL is opened, CommandPost will be launched, but it will not react to the URL event. Nor will it react to any events until this extension is loaded and event callbacks have been bound. NOTE: Any event which is received, for which no callback has been bound, will be logged to the CommandPost Console NOTE: When you trigger a URL from another application, it is usually best to have the URL open in the background, if that option is available. Otherwise, OS X will activate CommandPost (i.e. give it focus), which makes URL events difficult to use for things like window management.

# API Overview

Variables - Configurable values

httpCallback
mailtoCallback

Functions - API calls offered directly by the extension

bind
getAllHandlersForScheme
getDefaultHandler
openURL
openURLWithBundle
setDefaultHandler
setRestoreHandler

# API Documentation

# Variables

# httpCallback


Signature	`hs.urlevent.httpCallback`
Type	Variable
Description	A function that should handle http:// and https:// URL events
Notes	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.commandpost.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)
Source	extensions/urlevent/urlevent.lua line 21

# mailtoCallback


Signature	`hs.urlevent.mailtoCallback`
Type	Variable
Description	A function that should handle mailto: URL events
Notes	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)
Source	extensions/urlevent/urlevent.lua line 34

# Functions

# bind


Signature	`hs.urlevent.bind(eventName, callback)`
Type	Function
Description	Registers a callback for a commandpost:// URL event
Parameters	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
Returns	None
Notes	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 `commandpost://doThingA?value=1` The event name is `doThingA` and the callback's `params` argument will be a table containing `{["value"] = "1"}`
Examples	None
Source	extensions/urlevent/urlevent.lua line 88

# getAllHandlersForScheme


Signature	`hs.urlevent.getAllHandlersForScheme(scheme) -> table`
Type	Function
Description	Gets all of the application bundle identifiers of applications able to handle a URL scheme
Parameters	scheme - A string containing a URL scheme (e.g. 'http')
Returns	A table containing the bundle identifiers of all applications that can handle the scheme
Notes	None
Examples	None
Source	extensions/urlevent/liburlevent.m line 269

# getDefaultHandler


Signature	`hs.urlevent.getDefaultHandler(scheme) -> string`
Type	Function
Description	Gets the application bundle identifier of the application currently registered to handle a URL scheme
Parameters	scheme - A string containing a URL scheme (e.g. 'http')
Returns	A string containing the bundle identifier of the current default application
Notes	None
Examples	None
Source	extensions/urlevent/liburlevent.m line 244

# openURL


Signature	`hs.urlevent.openURL(url)`
Type	Function
Description	Opens a URL with the default application
Parameters	url - A string containing a URL, which must contain a scheme and '://'
Returns	A boolean, true if the URL was opened successfully, otherwise false
Notes	None
Examples	None
Source	extensions/urlevent/urlevent.lua line 109

# openURLWithBundle


Signature	`hs.urlevent.openURLWithBundle(url, bundleID) -> boolean`
Type	Function
Description	Opens a URL with a specified application
Parameters	url - A string containing a URL bundleID - A string containing an application bundle identifier (e.g. "com.apple.Safari")
Returns	True if the application was launched successfully, otherwise false
Notes	None
Examples	None
Source	extensions/urlevent/liburlevent.m line 300

# setDefaultHandler


Signature	`hs.urlevent.setDefaultHandler(scheme[, bundleID])`
Type	Function
Description	Sets the default system handler for URLs of a given scheme
Parameters	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.latenitefilms.CommandPost`.
Returns	None
Notes	Changing the default handler for http/https URLs will display a system prompt asking the user to confirm the change
Examples	None
Source	extensions/urlevent/liburlevent.m line 196

# setRestoreHandler


Signature	`hs.urlevent.setRestoreHandler(scheme, bundleID)`
Type	Function
Description	Stores a URL handler that will be restored when CommandPost or reloads its config
Parameters	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 CommandPost exits or reloads its config
Returns	None
Notes	You don't have to call this function if you want CommandPost to permanently be your default handler. Only use this if you want the handler to be automatically reverted to something else when CommandPost exits/reloads.
Examples	None
Source	extensions/urlevent/liburlevent.m line 173