API Docs

HSSharingService

Type

A configured sharing service, wrapping NSSharingService.

Create instances via hs.sharing.createShare() or hs.sharing.servicesFor(). Configure with setCallback(), recipients, and subject as needed, then call shareItems().

  • Example:
hs.sharing.createShare(hs.sharing.builtinServices.mail)
    .setCallback((event, items, error) => {
        if (event === 'didShare') console.log('Shared!')
        else if (event === 'didFail') console.error('Failed: ' + error)
    })
    .shareItems(['Check this out', 'https://www.hammerspoon.org'])

Properties

identifier

string
A unique identifier for this share object (UUID string).
Hammerspoon 2/Modules/hs.sharing/HSSharingService.swift:30

title

string
The user-visible title of the service, e.g. "Mail" or "AirDrop".
Hammerspoon 2/Modules/hs.sharing/HSSharingService.swift:37

alternateImage

HSImage
An alternate icon for the service, if one is provided, otherwise null.
Hammerspoon 2/Modules/hs.sharing/HSSharingService.swift:47

recipients

string[]
Recipients (e.g. email addresses) for services that support them, such as Mail or Messages.
Hammerspoon 2/Modules/hs.sharing/HSSharingService.swift:54

subject

string
The subject line, for services that support one, such as Mail.
Hammerspoon 2/Modules/hs.sharing/HSSharingService.swift:61

messageBody

string
The message body, populated once the share is in progress. Empty until then.
Hammerspoon 2/Modules/hs.sharing/HSSharingService.swift:64

accountName

string
The account name used to perform the share, if applicable. Populated once the share is in progress; otherwise null.
Hammerspoon 2/Modules/hs.sharing/HSSharingService.swift:72

attachments

string[]
File paths of any attachments included in the share, populated once the share completes. Empty until then.
Hammerspoon 2/Modules/hs.sharing/HSSharingService.swift:76

Methods

canShareItems(items) -> boolean

Checks whether this service can share the given items. Items may be strings (treated as a web/mailto URL if they parse as one, a file path if they start with `/` or `~` and the file exists, otherwise plain text) or `HSImage` objects.
Declaration
canShareItems(items) -> boolean
Parameters
Name Type Description
items any[] The items to check
Returns
boolean
true if this service can share all of the given items
Notes
Unsupported items will be ignored
Example
if (share.canShareItems(['hello'])) { ... }
Hammerspoon 2/Modules/hs.sharing/HSSharingService.swift:90

shareItems(items) -> boolean

Attempts to share the given items with this service. If the service cannot handle the items, this logs a warning and returns `false` without doing anything further. Otherwise the share is started; it is asynchronous — use `setCallback()` to find out when it completes.
Declaration
shareItems(items) -> boolean
Parameters
Name Type Description
items any[] The items to share
Returns
boolean
true if the share was started
Notes
Unsupported items will be ignored
Example
share.shareItems(['Check this out', 'https://www.hammerspoon.org'])
Hammerspoon 2/Modules/hs.sharing/HSSharingService.swift:104

setCallback(fn) -> HSSharingService

Registers a callback for share lifecycle events.
Declaration
setCallback(fn) -> HSSharingService
Parameters
Name Type Description
fn function Called with the lifecycle event name, items, and optional error message
Returns
HSSharingService
this share object, for chaining
Example
share.setCallback((event, items, error) => console.log(event))
Hammerspoon 2/Modules/hs.sharing/HSSharingService.swift:118