Implementing Immich Crosslink
For version 1.0
This page shows the platform parts: announcing the app, registering the scheme, finding the other participants and what they show, sending a link to one, and receiving one. What a link means, and what a receiver may and may not do with it, is in the protocol. The code is MIT-licensed; copy it freely.
Making links
A link is immich-crosslink://, the Immich path, and the
server’s address. Values are encoded as JavaScript’s
encodeURIComponent does, and a search is the JSON Immich’s
web app writes (see Immich
paths):
import Foundation
/// The characters `encodeURIComponent` leaves as they are.
private let unreserved = CharacterSet(charactersIn:
"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_.!~*'()")
func encodeComponent(_ value: String) -> String {
value.addingPercentEncoding(withAllowedCharacters: unreserved) ?? value
}
/// `path` is an Immich path; a search's `query` in it is already encoded.
func crosslink(path: String, server: String, user: String? = nil) -> URL? {
var link = "immich-crosslink://" + path + (path.contains("?") ? "&" : "?") + "server=" + encodeComponent(server)
if let user { link += "&user=" + encodeComponent(user) }
return URL(string: link)
}
/// A place's Immich path: `{"city":…,"country":…}` as `JSON.stringify` writes it.
func placePath(city: String?, country: String) -> String {
struct Search: Encodable { let city: String?; let country: String } // nil keys are left out
let encoder = JSONEncoder()
encoder.outputFormatting = [.sortedKeys, .withoutEscapingSlashes] // "city" sorts before "country"
let json = (try? encoder.encode(Search(city: city, country: country))).flatMap { String(data: $0, encoding: .utf8) } ?? "{}"
return "/search?query=" + encodeComponent(json)
}
placePath(city: "Aarhus", country: "Denmark") gives
/search?query=%7B%22city%22%3A%22Aarhus%22%2C%22country%22%3A%22Denmark%22%7D,
byte for byte what Immich’s web app writes for the same search.
Receivers decode values whichever way they were encoded.
Two ways to offer Show in
Two ways are known, and an app may use either, or its own, within the rules for sending:
- Show in app, one menu item per participant that shows the item, by the name and icon the system gives it. One click, and the user sees which apps take part before choosing. Immich Gallery’s menus work this way, and Immich Mount’s in Files and Dolphin. Use it wherever the menu is built when it opens.
- Show in Another App…, one menu item for all of them, where the menu cannot name apps: its items are fixed when the app is installed, or the app cannot list the others. With one participant it sends straight to it; with several it asks which, by names and icons, with Cancel. Immich Mount uses it in Finder, whose File Provider actions are fixed in the extension’s Info.plist, so their names cannot be an app’s found at run time; a Flatpak app uses it through the OpenURI portal (below).
The second exists for those limits. Where the first is possible, use the first.
Asking which, with several. Ask in the platform’s
own alert, with a button per participant (its icon and name) and Cancel:
one click, as a menu would have been. On macOS, NSAlert
stacks three or more buttons full width; make Return press the
participant chosen last time, not whichever is first, and Escape cancel.
Name the item in the alert’s text, since it appears away from the window
it was asked from. Past half a dozen participants, a list in the alert
with Show and Cancel reads better than a wall of buttons. Not a menu
popped up at the pointer: once the menu the action came from has closed,
a second one opening from nothing has no pattern on any desktop, and it
takes focus with no window to show for it (tried in Immich Mount’s
Finder action).
macOS
Announcing and registering. In the app’s Info.plist, the announcement and the scheme that delivers links:
<key>ImmichCrosslink</key>
<dict>
<key>Version</key>
<string>0.2</string>
<key>Shows</key>
<array>
<string>asset</string>
<string>album</string>
<string>person</string>
<string>place</string>
<string>page</string>
</array>
</dict>
<key>CFBundleURLTypes</key>
<array>
<dict>
<key>CFBundleURLName</key>
<string>immich-crosslink</string>
<key>CFBundleURLSchemes</key>
<array>
<string>immich-crosslink</string>
</array>
</dict>
</array>
Finding the others and sending to one:
import AppKit
struct Participant {
let name: String
let url: URL
let shows: Set<String>
}
/// The other apps that announce themselves and take crosslinks, by the system's name for them. Cheap enough to call
/// each time a menu is built: macOS gives no signal when apps are installed or removed.
func participants(version: String = "0.2") -> [Participant] {
guard let probe = URL(string: "immich-crosslink:///photos") else { return [] }
let ownID = Bundle.main.bundleIdentifier
return NSWorkspace.shared.urlsForApplications(toOpen: probe).compactMap { url in
guard let bundle = Bundle(url: url), bundle.bundleIdentifier != ownID,
let announcement = bundle.infoDictionary?["ImmichCrosslink"] as? [String: Any],
announcement["Version"] as? String == version,
let shows = announcement["Shows"] as? [String] else { return nil } // no announcement: not a participant
return Participant(name: FileManager.default.displayName(atPath: url.path), url: url, shows: Set(shows))
}
}
/// Sends the link to that app alone, never to the scheme's default handler.
func send(_ link: URL, to app: URL) {
NSWorkspace.shared.open([link], withApplicationAt: app, configuration: NSWorkspace.OpenConfiguration())
}
Offer Show in app only where
shows holds the item’s kind. The menu item’s name is the
bundle’s CFBundleDisplayName (its file name where it has
none), and its icon
NSWorkspace.shared.icon(forFile: app.path).
Found or not. Launch Services also lists copies that
were deleted or moved, and Bundle(url:) of a copy outside
/Applications reads as nothing to a sandboxed app. Keep an
app only when its bundle reads and its executable is there
(Contents/MacOS/<CFBundleExecutable>, read from the
disk each time: a Bundle once read is cached); every other
one it remembers is Not found in the settings. A
sandboxed app may not see apps outside /Applications.
Receiving, in the app delegate:
func application(_ application: NSApplication, open urls: [URL]) {
for url in urls where url.scheme == "immich-crosslink" {
// Check the path and ids, match `server` (and `user`) to an account, then only show the item.
}
}
Linux: GNOME, KDE and others
Announcing and registering. In the app’s desktop
entry: the announcement, and the scheme beside its other MIME types,
with %u in Exec so the link reaches the
app:
[Desktop Entry]
Name=Example Photos
Exec=example-photos %u
MimeType=x-scheme-handler/immich-crosslink;
X-Immich-Crosslink-Version=0.2
X-Immich-Crosslink-Shows=asset;album;person;place;page;
Packages run update-desktop-database after installing,
as they do for any MIME type.
gio mime x-scheme-handler/immich-crosslink lists the apps
that registered it.
An entry the app writes itself (Announcing) goes in
$XDG_DATA_HOME/applications
(~/.local/share/applications by default), with
NoDisplay=true where it should stay out of the app grid and
TryExec naming its program. Run
update-desktop-database on that folder after adding or
removing it: GIO lists the apps for a scheme from the folder’s
mimeinfo.cache. KDE notices the change by itself. Both list
entries with NoDisplay=true. Quote Exec’s
program only where its path needs it, as GIO’s
g_app_info_get_executable returns it with the quotes, and a
check that the program exists then fails.
Finding the others and sending to one, with GIO (C; the same calls exist in every GObject binding):
#include <gio/gio.h>
#include <gio/gdesktopappinfo.h>
/* Show in <app> for each participant but this one that shows the item's kind, by the system's name and icon. */
GList *apps = g_app_info_get_all_for_type ("x-scheme-handler/immich-crosslink");
for (GList *l = apps; l != NULL; l = l->next) {
GAppInfo *app = l->data;
if (!G_IS_DESKTOP_APP_INFO (app) || g_strcmp0 (g_app_info_get_id (app), "org.example.Photos.desktop") == 0)
continue;
GDesktopAppInfo *entry = G_DESKTOP_APP_INFO (app);
g_autofree char *version = g_desktop_app_info_get_string (entry, "X-Immich-Crosslink-Version");
g_auto (GStrv) shows = g_desktop_app_info_get_string_list (entry, "X-Immich-Crosslink-Shows", NULL);
if (g_strcmp0 (version, "0.2") != 0 || shows == NULL || !g_strv_contains ((const char * const *) shows, kind))
continue; /* no announcement, another version, or not this kind */
const char *name = g_app_info_get_display_name (app);
GIcon *icon = g_app_info_get_icon (app);
/* ... add a menu item; on activation: */
GList *uris = g_list_append (NULL, (gpointer) link);
g_app_info_launch_uris (app, uris, NULL, NULL);
g_list_free (uris);
}
g_list_free_full (apps, g_object_unref);
To keep the list between menus, drop it when the system says the installed apps may have changed:
g_signal_connect (g_app_info_monitor_get (), "changed", G_CALLBACK (forget_participants), NULL);
The signal fires once until the next g_app_info_* call,
and means “may have changed”: forget the list and read it again when it
is next needed.
With KDE Frameworks (C++):
#include <KApplicationTrader>
#include <KIO/ApplicationLauncherJob>
const KService::List apps = KApplicationTrader::queryByMimeType(
QStringLiteral("x-scheme-handler/immich-crosslink"));
for (const KService::Ptr &app : apps) {
if (app->desktopEntryName() == QLatin1String("org.example.photos"))
continue;
const QString version = app->property<QString>(QStringLiteral("X-Immich-Crosslink-Version"));
const QStringList shows = app->property<QString>(QStringLiteral("X-Immich-Crosslink-Shows"))
.split(QLatin1Char(';'), Qt::SkipEmptyParts);
if (version != QLatin1String("0.2") || !shows.contains(kind))
continue; // no announcement, another version, or not this kind
// app->name(), app->icon() for the menu item; on activation:
auto *job = new KIO::ApplicationLauncherJob(app);
job->setUrls({QUrl(link)});
job->start();
}
KDE’s database of desktop entries changes behind
KSycoca::databaseChanged, the place to forget a kept
list.
Found or not. GIO and KDE leave out an entry whose
TryExec is missing, but not one whose Exec
program is gone (an app removed by hand, an AppImage deleted): check it
too (g_app_info_get_executable with
g_find_program_in_path, or
QStandardPaths::findExecutable). An app the settings
remember that fails either is Not found.
Receiving: the link arrives as the %u
argument. Check it, match the account, and only show the item.
Flatpak. A Flatpak app’s exported desktop entry
carries its MimeType and its announcement, so it receives
links. From inside the sandbox it cannot list the other apps; offer one
Show in Another App… (the second way) that opens the
link through the OpenURI portal with ask set, so the user
chooses.
Testing
Test against the test links: the links to make for each item, and the result to reach for each link.
With a participant installed, open a link by hand:
open 'immich-crosslink:///photos?server=https%3A%2F%2Fdemo.immich.app' # macOS
xdg-open 'immich-crosslink:///photos?server=https%3A%2F%2Fdemo.immich.app' # Linux
With several participants installed this opens whichever the system picks, which is why participants send to one app by name. Add your app to the participants once it takes part.