esc

Sharing files

For add-ons that send files somewhere: a phone on the same network, a cloud folder, a printer. The person shares files with your add-on from the shelf or by dropping them on your page, and your add-on can ask before accepting files and put what it receives on the shelf. Needs LedgeKit 0.20.0.

Where files can go

Add "share-target" to surfaces and "shared-files" to capabilities, set kit.minAPI to 0.20.0, and send your destinations. Each shelf item then gets “Send with ‹title›”, with your destinations as its submenu. Send the target again as destinations come and go, such as devices appearing on the network, and send nil to take the menu away:

AddOnSession.show(shareTarget: ShareTarget(title: "LocalSend", destinations: devices.map {
    ShareDestination($0.id, title: $0.alias, subtitle: "\($0.model) · \($0.host)", symbol: "iphone")
}, emptyNote: "No devices nearby"))

handlers.onShare = { shared in
    // shared.destination is a destination's id, or the id of the list row the files were dropped on
    await send(shared.urls, to: shared.destination)
}

The same files can be dropped on your notch page: a list row made with ListRow(id, title:…, acceptsFiles: true) takes them, and onShare gets the row's id as the destination. Read the files when onShare runs; they stay the person's, so don't move or delete them.

Asking first, and the shelf

When something arrives from elsewhere, ask the person before you take it, and hand them the result:

let accept = try await LedgeHost.ask(HostQuestion(title: "Accept 3 files from Pixel 9?",
                                                  message: "photo.jpg, notes.txt, scan.pdf · 4.2 MB",
                                                  accept: "Accept", decline: "Decline", timeout: 60))
guard accept else { return refuse() }
…
try await LedgeHost.addToShelf(received)

Ledge asks in the notch, or in an alert when the notch is hidden, such as over a full-screen app. Ledge adds the add-on's name and how long it waits. No answer before the timeout is no, and only one add-on can ask at a time.

Call or surfaceDoesNeeds
share-targetYour destinations under “Send with ‹title›” on shelf itemsshared-files
ListRow(acceptsFiles:)A page row that takes dropped filesshared-files
LedgeHost.ask(_:)A yes-or-no question; true for yesquestions
LedgeHost.addToShelf(_:)Puts files on the shelf, which keeps its own copiesshelf-add

The local network

An add-on that finds or talks to other devices on the network declares local-network, so the person sees it before installing. Ledge can't limit an add-on to the local network; the capability only tells the person. macOS asks whether Ledge may use the local network the first time an add-on does. Until the person allows it, sends fail, with EHOSTUNREACH for multicast. Show that on your page rather than an empty list.

Limits

A target has a title of up to 40 characters and up to 24 destinations, each with an id up to 64 characters, a title up to 60 and a subtitle up to 80. A share or a shelf add carries 1 to 100 files. A question has a title up to 120 characters, a message up to 500, buttons up to 30, and waits 5 to 120 seconds. In ledgekit check, a {"share": ["/path/a.png"], "destination": "pixel"} step shares files as the person would, and every question is answered yes.