Bookmark data

Keep access to user-picked files and folders across app restarts

A file the user picked can become unreachable after a restart: Android revokes content:// access and sandboxed Apple apps lose their security scope. bookmarkData() turns a PlatformFile into bytes you can store, and PlatformFile.fromBookmarkData(bytes) gives the file back, with its access, on the next launch.

Usage

nonWebMain

// After the user picks a file
val bytes: ByteArray = file.bookmarkData().bytes
// Store the bytes: a file, DataStore, a database...

// On the next launch
val restored: PlatformFile = PlatformFile.fromBookmarkData(bytes)

Both functions are declared in nonWebMain. bookmarkData() is a suspend function. Bookmark bytes are platform-specific: don’t share them between operating systems or apps.

Restore a bookmark safely

A bookmark breaks when the user deletes the file, revokes your app’s access, or (on path-based platforms) moves it. Handle failure and ask the user to pick the file again. This helper stores one bookmark in your app’s files directory:

nonWebMain

// A getter, so FileKit.filesDir is only read after FileKit.init on desktop
private val bookmarkFile get() = FileKit.filesDir / "last-file.bookmark"

suspend fun saveLastFile(file: PlatformFile) {
    bookmarkFile.write(file.bookmarkData().bytes)
}

suspend fun loadLastFile(): PlatformFile? {
    if (!bookmarkFile.exists()) return null
    val bytes = bookmarkFile.readBytes()
    val resolution = runCatching { PlatformFile.resolveBookmarkData(bytes) }.getOrNull()
    if (resolution == null || !resolution.file.exists()) {
        bookmarkFile.delete() // gone or no longer accessible: ask the user again
        return null
    }
    if (resolution.shouldRefresh) {
        // Best effort: keep the old bookmark if the refresh fails
        try {
            saveLastFile(resolution.file)
        } catch (e: CancellationException) {
            throw e
        } catch (e: Exception) {
            // Ignore and retry on the next launch
        }
    }
    return resolution.file
}

resolveBookmarkData returns a BookmarkResolution with the file and two flags:

Property	Meaning
isStale	The operating system resolved the bookmark but asks you to recreate it.
shouldRefresh	FileKit recommends replacing the stored bytes. true when isStale is, and when the bytes come from an older FileKit format.

Refreshing is best effort: the old bytes may still work, and bookmarkData() can fail if the file disappeared or macOS already revoked access. Use fromBookmarkData when you only need the file.

Platform notes

Platform	Stored as	Security-scoped	Survives a move
Android, regular path	The path	Not needed	No
Android, content://	The URI, plus a persisted URI permission	Not needed (the permission persists)	Depends on the document provider
iOS	Foundation bookmark	Yes	Yes
watchOS	Foundation bookmark	No	Yes
macOS, JVM on macOS	Native bookmark in a versioned FileKit wrapper	Yes when the app is sandboxed	Yes
JVM on Linux and Windows, Linux native, Windows native	The path	No	No

On Android, releaseBookmark() releases the persisted URI permission. Android limits how many URI permissions an app can persist, so release the ones you no longer need.

Set up the macOS App Sandbox

FileKit reads your app’s App Sandbox entitlement at runtime. When it is present, FileKit creates security-scoped bookmarks and reports a failure instead of falling back to a bookmark that can’t restore access.

1. Enable the sandbox and user-selected file access

   Add these entitlements to the signed app:

   entitlements.plist

   <key>com.apple.security.app-sandbox</key>
   <true/>
   <key>com.apple.security.files.user-selected.read-write</key>
   <true/>
   <key>com.apple.security.files.bookmarks.app-scope</key>
   <true/>
   
2. Test the packaged app

   Entitlements only apply to a signed build. Pick a file, quit, relaunch, and restore the bookmark.

Keep security-scoped access

On iOS and in sandboxed macOS apps, a file outside your container is readable only while its security-scoped access is active. FileKit starts and stops access around its own operations, and keeps it active until returned sources and sinks are closed.

Derive files from the restored PlatformFile with /, resolve(), or list() so they share its access:

nonWebMain

val folder = PlatformFile.fromBookmarkData(savedFolderBookmark)
source.atomicMove(folder / "backup.db")

A PlatformFile rebuilt from a path string or toKotlinxIoPath() loses that access, and so does one restored by PlatformFileSerializer, which stores only the path. Persist bookmark data instead.

When you hand a file to another library, wrap the call in withScopedAccess. It calls startAccessingSecurityScopedResource() and stopAccessingSecurityScopedResource() for you, and is a no-op on platforms without security scopes:

file.withScopedAccess { scoped ->
    thirdPartyLibrary.open(scoped.path)
}

Call releaseBookmark() once you are done with a restored bookmark and every file derived from it. Already-open sources and sinks still close cleanly, but new scoped operations then throw a FileKitException.

Upgrading from older versions

• macOS bookmark format: new bookmarks on macOS (native and JVM) are wrapped in a versioned FileKit format. Unwrapped Kotlin/Native bookmarks and JVM path bytes written by earlier versions remain readable, and resolveBookmarkData reports shouldRefresh = true for them.
• iOS security scope: restored bookmarks now keep the security-scoped URL for the bookmarked item and its descendants, including after a device restart. Stored bookmarks get this behavior without a migration.
• iOS releaseBookmark(): it was a no-op in FileKit 0.15.0 and 0.16.0 and now releases access. Calling startAccessingSecurityScopedResource() on a released bookmark throws instead of returning false.
• fromBookmarkData is not deprecated. resolveBookmarkData was added for refresh metadata.

Related

• Directory picker to let users pick a folder worth bookmarking.
• App directories for files your app owns, which need no bookmark.