Background Execution

// FieldNotes/Background/SyncFinisher.swift
#if os(iOS) || os(visionOS)
import UIKit
import FieldNotesServices

@MainActor
final class SyncFinisher {
    private var taskID: UIBackgroundTaskIdentifier = .invalid

    /// Keeps the process alive until the current sync finishes or the system runs out of patience.
    func finishSync(of store: NoteStore) {
        guard taskID == .invalid else { return }
        taskID = UIApplication.shared.beginBackgroundTask(withName: "Finish FieldNotes sync") {
            self.end()   // time is up: stop cleanly rather than be terminated
        }
        Task {
            try? await store.refresh()
            end()
        }
    }

    private func end() {
        guard taskID != .invalid else { return }
        UIApplication.shared.endBackgroundTask(taskID)
        taskID = .invalid
    }
}
#endif

<!-- FieldNotes/Info.plist (iOS, iPadOS and visionOS app target) -->
<key>UIBackgroundModes</key>
<array>
    <string>fetch</string>               <!-- BGAppRefreshTask: com.example.fieldnotes.refresh -->
    <string>processing</string>          <!-- BGProcessingTask: com.example.fieldnotes.reindex -->
    <string>remote-notification</string> <!-- background pushes that announce a shared note -->
    <string>location</string>            <!-- recording a field trip's route with the screen off -->
</array>
<key>BGTaskSchedulerPermittedIdentifiers</key>
<array>
    <string>com.example.fieldnotes.refresh</string>
    <string>com.example.fieldnotes.reindex</string>
    <string>com.example.fieldnotes.export</string>
</array>

// Inside LocationService (Location and Maps), while a field trip is recording.
#if os(iOS) || os(watchOS)
import CoreLocation

// Holding the session keeps location updates flowing while FieldNotes is in the background,
// and the system shows the location indicator so the person knows why.
let backgroundSession = CLBackgroundActivitySession()

// When the trip ends:
backgroundSession.invalidate()
#endif

#if os(iOS)
import AVFAudio
import PushKit

// Audio mode: playback continues in the background only with a playback category.
func configureVoiceMemoPlayback() throws {
    try AVAudioSession.sharedInstance().setCategory(.playback, mode: .spokenAudio)
    try AVAudioSession.sharedInstance().setActive(true)
}

// VoIP mode: the registry delivers VoIP pushes; each must be reported to CallKit.
func makeVoIPRegistry(delegate: any PKPushRegistryDelegate) -> PKPushRegistry {
    let registry = PKPushRegistry(queue: .main)
    registry.delegate = delegate
    registry.desiredPushTypes = [.voIP]
    return registry
}
#endif

// FieldNotes/Export/NotebookExportController.swift
#if os(iOS)
import BackgroundTasks
import FieldNotesModel
import FieldNotesServices

@MainActor
final class NotebookExportController {
    static let identifier = "com.example.fieldnotes.export"

    private var isRegistered = false
    private var pending: (notebook: Notebook, notes: [Note], destination: URL)?

    /// Called from the Export button: the person started this job, so continued processing fits.
    func export(_ notebook: Notebook, notes: [Note], to destination: URL) throws {
        if !isRegistered {
            isRegistered = BGTaskScheduler.shared.register(
                forTaskWithIdentifier: Self.identifier, using: .main
            ) { task in
                guard let task = task as? BGContinuedProcessingTask else { return }
                self.run(task)
            }
        }
        pending = (notebook, notes, destination)
        let request = BGContinuedProcessingTaskRequest(
            identifier: Self.identifier,
            title: "Exporting \(notebook.name)",
            subtitle: "Preparing \(notes.count) notes"
        )
        request.strategy = .queue
        try BGTaskScheduler.shared.submit(request)
    }

    private func run(_ task: BGContinuedProcessingTask) {
        guard let job = pending else {
            task.setTaskCompleted(success: false)
            return
        }
        pending = nil
        task.progress.totalUnitCount = Int64(job.notes.count)

        let work = Task {
            // Measured as a MetricKit interval; MetricsReporter is on Logging, MetricKit, Crash Reports and Organizer.
            MetricsReporter.shared.exportIntervalDidChange(started: true)
            defer { MetricsReporter.shared.exportIntervalDidChange(started: false) }
            do {
                let writer = try NotebookArchiveWriter(destination: job.destination)
                for (index, note) in job.notes.enumerated() {
                    try Task.checkCancellation()        // the person tapped Stop in the system UI
                    try await writer.append(note)
                    task.progress.completedUnitCount = Int64(index + 1)
                    task.updateTitle(task.title, subtitle: "\(index + 1) of \(job.notes.count) notes")
                }
                try await writer.close()
                task.setTaskCompleted(success: true)
            } catch {
                task.setTaskCompleted(success: false)
            }
        }
        task.expirationHandler = { @Sendable in work.cancel() }
    }
}
#endif

// Packages/FieldNotesKit/Sources/FieldNotesServices/Export/NotebookArchiveWriter.swift
import Foundation
import FieldNotesModel

public actor NotebookArchiveWriter {
    private let handle: FileHandle

    public init(destination: URL) throws {
        FileManager.default.createFile(atPath: destination.path(), contents: nil)
        handle = try FileHandle(forWritingTo: destination)
    }

    public func append(_ note: Note) throws {
        let markdown = "# \(note.title)\n\n\(note.body)\n\n"
        try handle.write(contentsOf: Data(markdown.utf8))
    }

    public func close() throws {
        try handle.close()
    }
}

// FieldNotes/Intents/ExportNotebookIntent.swift
import AppIntents
import Foundation
import FieldNotesModel
import FieldNotesServices

@available(iOS 27, macOS 27, visionOS 27, watchOS 27, *)
struct ExportNotebookIntent: LongRunningIntent {
    static let title: LocalizedStringResource = "Export Notebook"

    @Parameter(title: "Notebook Name")
    var notebookName: String

    @Dependency private var store: NoteStore

    func perform() async throws -> some IntentResult & ProvidesDialog {
        let store = store
        let name = notebookName
        let notes = await MainActor.run { () -> [Note]? in
            guard let notebook = store.notebooks.first(where: { $0.name == name }) else { return nil }
            return store.notes.filter { $0.notebookID == notebook.id }
        }
        guard let notes else {
            // Never fall back to "notes without a notebook": an unknown name is an error the person can fix.
            throw $notebookName.needsValueError("There's no notebook named \(name). Which notebook?")
        }
        let destination = URL.documentsDirectory.appending(path: "\(notebookName).md")

        let written = try await performBackgroundTask {
            progress.totalUnitCount = Int64(notes.count)
            progress.localizedDescription = "Exporting \(notebookName)"
            let writer = try NotebookArchiveWriter(destination: destination)
            for (index, note) in notes.enumerated() {
                try Task.checkCancellation()
                try await writer.append(note)
                progress.completedUnitCount = Int64(index + 1)
            }
            try await writer.close()
            return notes.count
        }
        return .result(dialog: "Exported \(written) notes from \(notebookName).")
    }
}

// FieldNotesWatch/ObservationTimer.swift
#if os(watchOS)
import WatchKit

@MainActor
final class ObservationTimer: NSObject, WKExtendedRuntimeSessionDelegate {
    private var session: WKExtendedRuntimeSession?

    func start() {
        let session = WKExtendedRuntimeSession()
        session.delegate = self
        session.start()
        self.session = session
    }

    func stop() {
        session?.invalidate()
        session = nil
    }

    nonisolated func extendedRuntimeSessionDidStart(_ extendedRuntimeSession: WKExtendedRuntimeSession) {
        // Start the countdown UI; the app keeps running with the screen down.
    }

    nonisolated func extendedRuntimeSessionWillExpire(_ extendedRuntimeSession: WKExtendedRuntimeSession) {
        // Save the observation now: the session is about to end.
    }

    nonisolated func extendedRuntimeSession(
        _ extendedRuntimeSession: WKExtendedRuntimeSession,
        didInvalidateWith reason: WKExtendedRuntimeSessionInvalidationReason,
        error: (any Error)?
    ) {
        Task { @MainActor in self.session = nil }
    }
}
#endif

// FieldNotes/macOS/MacReindexScheduler.swift
#if os(macOS)
import Foundation

@MainActor
final class MacReindexScheduler {
    private let scheduler = NSBackgroundActivityScheduler(identifier: "com.example.fieldnotes.reindex")

    func start() {
        scheduler.repeats = true
        scheduler.interval = 24 * 60 * 60
        scheduler.tolerance = 60 * 60
        scheduler.qualityOfService = .background
        scheduler.schedule { completion in
            // Rebuild the Spotlight entries here, then report back.
            completion(.finished)
        }
    }
}
#endif

(lldb) e -l objc -- (void)[[BGTaskScheduler sharedScheduler] _simulateLaunchForTaskWithIdentifier:@"com.example.fieldnotes.refresh"]
(lldb) continue

(lldb) e -l objc -- (void)[[BGTaskScheduler sharedScheduler] _simulateExpirationForTaskWithIdentifier:@"com.example.fieldnotes.reindex"]
(lldb) continue