File Provider Extension: o que é, extensão de acesso a arquivos iOS

O que é File Provider Extension no iOS?

File Provider Extension é uma extensão de aplicativo no iOS e macOS que permite que um aplicativo forneça acesso a arquivos de fontes externas através do aplicativo Arquivos do sistema. Foi introduzido no iOS 11 e substituiu o mecanismo Document Provider, adicionando suporte para sincronização, pesquisa e tags.

A principal tarefa do File Provider Extension é atuar como uma ponte entre o armazenamento externo (servidor em nuvem, NAS corporativo, FTP) e o Files.app. O usuário vê arquivos e pastas como se estivessem armazenados localmente, embora os dados possam estar em um servidor remoto. A extensão funciona em segundo plano, sincronizando o conteúdo conforme necessário.

De acordo com a WWDC 2024, a Apple está desenvolvendo ativamente a API FileProvider: foi adicionado suporte para sincronização incremental, o desempenho para grandes diretórios foi melhorado e operações em lote agora estão disponíveis. Isso torna o File Provider Extension a maneira preferida de integrar arquivos externos ao ecossistema Apple.

Como funciona o File Provider Extension

A arquitetura do File Provider Extension consiste em dois componentes: a extensão principal (tipo provedor de arquivos) e uma extensão de interface de usuário opcional para autenticação e configuração. A extensão principal implementa o protocolo NSFileProviderExtension e lida com todas as solicitações do Files.app.

import FileProvider

class CloudFileProvider: NSFileProviderExtension {
    override func item(for identifier: NSFileProviderItemIdentifier) throws -> NSFileProviderItem {
        guard let item = storage
            .item(for: identifier) else {
            throw NSError(domain: NSFileProviderErrorDomain,
                              code: NSFileProviderError.noSuchItem.rawValue)
        }
        return item
    }

    override func urlForItem(with identifier: NSFileProviderItemIdentifier) -> URL {
        return fileCoordinator.urlForItem(with: identifier)
    }
}

Quando um usuário abre o Files.app e seleciona seu provedor, o sistema inicia a extensão em um processo em segundo plano. A extensão não tem interface de usuário — é um processo headless que lida com solicitações de leitura, escrita, renomeação e exclusão de arquivos. Todas as operações são realizadas de forma assíncrona através do NSFileProviderManager.

Nuance importante: o File Provider Extension vive em um processo separado e pode ser encerrado pelo sistema quando a memória estiver baixa. Portanto, o provedor deve ser capaz de restaurar o estado após uma reinicialização, salvando identificadores e cache de sincronização no armazenamento persistente.

Modelo NSFileProviderItem: arquivos e pastas

NSFileProviderItem é um protocolo que descreve um arquivo ou pasta individual na hierarquia do provedor. Cada item tem um identificador único, nome, tipo (arquivo ou pasta), datas de criação e modificação, tamanho e flags (disponível offline, somente leitura).

O protocolo também suporta capacidades estendidas através do NSFileProviderItemProtocol: tags (rótulos coloridos), ícones, versionamento e ações personalizadas. Para arquivos grandes, o suporte para transferências retomáveis é implementado através do NSFileProviderService.

De acordo com a WWDC 2023, a Apple recomenda usar closures (NSFileProviderItemFields) para atualizar apenas propriedades alteradas em vez de todo o objeto. Isso acelera significativamente a sincronização durante atualizações em lote — por exemplo, quando apenas o tamanho de um grupo de arquivos muda.

Mecanismo de sincronização e NSFileProviderManager

NSFileProviderManager é a classe central para gerenciar o ciclo de vida da extensão. Ele fornece métodos para sinalizar ao sistema sobre mudanças, lidar com conflitos colaborativos e gerenciar downloads. O gerenciador rastreia automaticamente as transferências ativas e prioriza os arquivos visíveis ao usuário.

class SyncManager {
    let providerManager = NSFileProviderManager.default

    func signalUpdate(for item: NSFileProviderItemIdentifier) {
        providerManager.signalEnumerator(
            for: item.parentItemIdentifier
        ) { error in
            if let error = error {
                Logger.sync.error(
                    "Failed to signal: \(error.localizedDescription)"
                )
            }
        }
    }

    func uploadItem(at url: URL, itemId: NSFileProviderItemIdentifier) {
        providerManager.registerURLBasedItem(
            with: itemId,
            url: url
        )
    }
}

O mecanismo de sincronização é a lógica que o desenvolvedor implementa de forma independente. A Apple não fornece um mecanismo de sincronização embutido — apenas a API para notificar o sistema sobre mudanças. O provedor decide como baixar arquivos do servidor, armazená-los em cache localmente e resolver conflitos de edição.

Conflitos: o sistema suporta detecção de conflitos de versão através do NSFileProviderSyncAnchor. Quando um arquivo é alterado simultaneamente local e remotamente, o provedor usa a âncora de sincronização para determinar a última versão sincronizada e resolve o conflito usando uma estratégia de último escritor vence ou criando uma cópia conflitante.

Segurança e sandbox da extensão

File Provider Extension opera dentro de uma sandbox rigorosa do iOS. A extensão não tem acesso direto ao sistema de arquivos do aplicativo host e, inversamente, o aplicativo não pode ler os arquivos do provedor diretamente. Todas as trocas de dados ocorrem através das APIs do sistema Files.app.

O acesso aos arquivos do usuário só é possível através de interação explícita: o usuário abre um arquivo do Files.app em um aplicativo, e o sistema cria uma cópia temporária do arquivo em um contêiner isolado. O aplicativo receptor trabalha com esta cópia, não com o original no armazenamento do provedor.

De acordo com o Apple Security Guide, 2024, o provedor deve implementar criptografia de dados durante a transmissão (TLS 1.3) e pode opcionalmente adicionar criptografia de disco para arquivos em cache. A autenticação do usuário é realizada através de um componente FileProviderUI separado, que é executado fora da sandbox da extensão para entrada segura de credenciais.

Limitação chave: a extensão não pode executar código arbitrário — ela processa apenas solicitações através do NSFileProviderManager. Qualquer lógica além das operações de arquivo deve ser implementada no aplicativo principal e invocada através de grupos de aplicativos ou serviços XPC.