File Provider Extension: ce este și cum funcționează furnizorul de fișiere iOS

Ce este File Provider Extension în iOS

File Provider Extension este o extensie de aplicație care adaugă noi surse de documente în aplicația Fișiere. Un serviciu cloud — Google Drive, Dropbox, OneDrive sau un depozit corporativ — poate afișa structura sa de fișiere direct în interfața de sistem, fără a deschide o aplicație separată.

Utilizatorul lucrează cu fișierele de la distanță exact ca și cu cele salvate pe dispozitiv: navighează prin foldere, trage documente, le deschide în orice aplicație compatibilă și salvează modificările înapoi în cloud. Potrivit WWDC 2025, File Provider Extension suportă până la 1000 de operații de sincronizare simultane și se adaptează la viteza rețelei prin gestionarea dinamică a priorităților.

Extensia funcționează în fundal — iOS o lansează atunci când este necesară sincronizarea și o poate termina forțat dacă resursele sunt insuficiente. Toate operațiile trebuie să fie idempotente și să suporte reluarea de la un punct de control.

Arhitectura și mecanismul de sincronizare a fișierelor

File Provider Extension are o arhitectură pe trei niveluri: procesul de sistem Files.app, extensia-furnizor și serverul de la distanță. Sistemul solicită date extensiei, extensia transformă cererile în apeluri API ale serviciului cloud și returnează rezultatele prin NSFileProviderItem.

Sincronizare incrementală

În loc să încarce întreaga structură de fișiere la fiecare actualizare, extensia transmite doar elementele modificate. NSFileProviderManager oferă metode pentru trimiterea actualizărilor incrementale — „fișierul A a fost adăugat”, „fișierul B a fost modificat”, „dosarul C a fost șters”. Aceasta reduce radical traficul și accelerează afișarea modificărilor.

Potrivit Apple Engineering, sincronizarea incrementală reduce volumul de date transmise cu 60–80% față de reîncărcarea completă. Se recomandă utilizarea NSFileProviderSyncAnchor pentru marcarea stării de sincronizare și minimizarea cererilor duplicate.

Cache pe dispozitiv

File Provider Extension poate stoca local fișiere în cache pentru acces offline. La deschiderea unui fișier, sistemul face o cerere extensiei, extensia decide — să descarce conținutul de pe server sau să returneze versiunea deja stocată în cache. NSFileProviderItem indică nivelul de cache prin câmpurile isDownloaded și isUploaded.

Apple recomandă configurarea unei politici de cache în funcție de dimensiunea fișierelor: pentru imagini și documente — cache complet, pentru video — doar previzualizare, pentru arhive — la cererea utilizatorului.

NSFileProviderManager: gestionarea furnizorului de fișiere

NSFileProviderManager este clasa centrală prin care extensia comunică cu sistemul. Oferă metode pentru notificarea sistemului despre modificări, crearea de elemente noi, gestionarea descărcărilor și gestionarea erorilor. Fiecare instanță NSFileProviderManager este asociată unui domeniu specific.

Metode cheie

signalEnumerator(for:) — notifică sistemul că conținutul unui dosar s-a schimbat și lista trebuie recitită. reimportItem(_:) — reimportă elementul indicat după o modificare pe server. registerURLSessionTask:forItemWithIdentifier: — leagă o descărcare în fundal de un fișier specific pentru urmărirea progresului.

O limitare importantă: NSFileProviderManager funcționează doar în procesul extensiei. Aplicația principală nu poate apela direct metodele sale pentru gestionarea structurii de fișiere — sincronizarea trebuie inițiată de extensie sau de sistem.

let manager = NSFileProviderManager.default()
manager.signalEnumerator(for: workingSet) { error in
    if let error = error {
        print("Signal failed: \(error)")
    }
}

Gestionarea descărcărilor

Pentru descărcarea fișierelor în fundal, NSFileProviderManager utilizează URLSession cu configurație de fundal. Extensia creează o sarcină de descărcare și o înregistrează în manager, care o leagă de elementul corespunzător. Sistemul urmărește automat progresul și prioritățile descărcărilor în funcție de activitatea utilizatorului.

Implementarea File Provider Extension

Crearea unei File Provider Extension începe cu adăugarea unui nou target în Xcode cu șablonul File Provider Extension. Xcode generează automat o clasă care moștenește NSFileProviderExtension și un set minim de metode pentru lucrul cu elementele.

NSFileProviderItem și metadate

Fiecare element al structurii de fișiere — fișier sau dosar — implementează protocolul NSFileProviderItem. Protocolul definește câmpurile obligatorii: itemIdentifier, parentItemIdentifier, filename, typeIdentifier și capabilities. Opțional se pot specifica dimensiunea, data modificării și flagurile de descărcare.

struct CloudItem: NSFileProviderItem {
    let itemIdentifier: NSFileProviderItemIdentifier
    let parentItemIdentifier: NSFileProviderItemIdentifier
    let filename: String
    let typeIdentifier: String
    let capabilities: NSFileProviderItemCapabilities
    let documentSize: NSNumber?
}

Gestionarea cererilor de enumerare

Metoda enumerator(for:) returnează un obiect care implementează NSFileProviderEnumerator, care furnizează conținutul dosarului la cererea sistemului. iOS poate solicita enumerarea pentru dosarul rădăcină, subdosare și setul de lucru — acesta din urmă este utilizat pentru afișarea fișierelor recente sau favorite.

Apple recomandă utilizarea metodelor asincrone de enumerare cu paginare prin NSFileProviderPage pentru a nu încărca mii de elemente simultan. Paginile de 50–100 de elemente sunt optime pentru performanță.

Domenii și arhitectură multi-cont

NSFileProviderDomain este un mecanism de separare a diferitelor conturi în cadrul aceleiași extensii. Dacă utilizatorul a autorizat mai multe conturi în aplicație — personal și corporativ Google Drive — fiecare cont creează un domeniu separat care se afișează ca o sursă distinctă în aplicația Fișiere.

Fiecare domeniu are un identificator unic, un nume afișat și o stare. Utilizatorul poate dezactiva temporar domeniile sau le poate șterge fără a afecta celelalte conturi. Sistemul lansează un proces separat de extensie pentru fiecare domeniu activ, asigurând izolarea datelor între conturi.

Potrivit Apple, se recomandă să nu se creeze mai mult de 10 domenii per extensie — un număr excesiv încetinește lansarea aplicației Fișiere și crește consumul de memorie. Pentru serviciile cu un număr mare de conturi, este mai bine să fie agregate într-un singur domeniu cu comutare de profil în cadrul extensiei.

let domain = NSFileProviderDomain(
    identifier: "work",
    displayName: "Corporate Drive"
)
NSFileProviderManager.add(domain) { error in
    if let error = error {
        print("Failed to add domain: \(error)")
    }
}