DocumentProvider — 정의, 제공자 생성 및 파일 작업

DocumentProvider란?

DocumentsProvider는 ContentProvider를 확장하는 Android 기본 클래스로, 애플리케이션이 시스템 SAF 인터페이스를 통해 다른 애플리케이션에 파일을 제공할 수 있게 합니다. 제공자는 사용자가 문서 선택 대화상자에서 보는 가상 파일 시스템을 생성합니다.

각 제공자는 파일을 루트(roots) — 최상위 진입점으로 구성합니다. 예를 들어, Google Drive에는 “내 드라이브”와 ”공유 문서함“이라는 루트가 있습니다. 루트 내에서 제공자는 문서 트리를 반환하며, 각 문서는 특정 MIME 유형, 크기 및 날짜를 가진 파일 또는 디렉토리입니다.

DocumentProvider는 android.provider 패키지의 일부이며 Android 4.4 (API 19)부터 사용할 수 있습니다. 이 제공자는 클라우드 서비스, 비밀번호 관리자, 메모 앱 및 자체 형식으로 파일을 저장하는 모든 프로그램에서 사용됩니다.

사용자 정의 DocumentProvider 만드는 방법

자체 DocumentProvider를 만들려면 DocumentsProvider 클래스를 확장하고 네 가지 필수 메서드를 구현하는 것부터 시작합니다. 제공자는 파일 선택 시 시스템 SAF 선택기에 표시되는 파일 구조를 정의합니다.

첫 번째 메서드는 queryRoots로, Root.COLUMN_ROOT_ID, Root.COLUMN_TITLE, Root.COLUMN_SUMMARY 및 Root.COLUMN_FLAGS 열이 있는 커서를 반환합니다. 각 루트는 FLAG_SUPPORTS_CREATE, FLAG_SUPPORTS_SEARCH 및 FLAG_SUPPORTS_IS_CHILD 플래그를 지원할 수 있습니다.

두 번째 필수 메서드는 queryChildDocuments로, 지정된 URI의 하위 문서를 반환합니다. 이 메서드는 사용자가 선택기에서 디렉토리를 열 때 호출됩니다. 각 문서에는 Document.COLUMN_DOCUMENT_ID, COLUMN_DISPLAY_NAME, COLUMN_MIME_TYPE, COLUMN_SIZE 및 COLUMN_LAST_MODIFIED 열이 포함됩니다.

DocumentsProvider의 필수 메서드

DocumentsProvider는 선택기를 위한 파일 구조를 형성하는 네 가지 메서드의 구현이 필요합니다. 이것들이 없으면 제공자가 작동하지 않습니다 — 시스템 SAF 대화상자가 파일을 표시할 수 없습니다.

• queryRoots — 저장소에 대한 루트 진입점을 반환합니다. 각 루트는 ID, 이름 및 아이콘이 있는 커서의 행으로 표시됩니다.
• queryDocument — ID로 단일 문서를 반환합니다. 특정 파일에 대한 정보를 얻는 데 사용됩니다.
• queryChildDocuments — 지정된 부모 디렉토리 URI에 대한 하위 문서를 반환합니다.
• openDocument — ID로 문서를 열고 읽기 또는 쓰기를 위한 ParcelFileDescriptor를 반환합니다.

추가로 새 파일을 만들기 위한 createDocument, 삭제를 위한 deleteDocument, 이름 변경을 위한 renameDocument를 구현할 수 있습니다. 이러한 메서드는 루트에 FLAG_SUPPORTS_CREATE 플래그가 필요합니다.

AndroidManifest에 제공자 등록

DocumentProvider는 추가 인텐트 필터 및 플래그와 함께 일반 ContentProvider로 AndroidManifest.xml에 등록됩니다. 제공자는 권한을 통해 직접 접근으로부터 보호되어야 합니다 — 명시적 권한과 함께 android:exported="true"를 사용하는 것이 좋습니다.

<provider
    android:name=".provider.CustomDocumentProvider"
    android:authorities="com.example.app.documents"
    android:exported="true"
    android:grantUriPermissions="true"
    android:permission="android.permission.MANAGE_DOCUMENTS">
    <intent-filter>
        <action
            android:name="android.content.action.DOCUMENTS_PROVIDER" />
    </intent-filter>
    <meta-data
        android:name="android.content.documents.roots"
        android:resource="@xml/file_paths" />
</provider>

grantUriPermissions 플래그는 SAF가 호출 애플리케이션에 일시적으로 접근 권한을 위임할 수 있게 합니다. authorities 속성은 고유해야 합니다 — 일반적으로 .documents 접미사가 있는 패키지 이름이 사용됩니다. 루트 구성을 위한 XML 리소스와 함께 메타데이터를 지정하는 것도 좋습니다.

코드 예제: DocumentsProvider 구현

DocumentsProvider 구현은 openDocument 메서드에서 ParcelFileDescriptor를 반환해야 합니다. 로컬 파일의 경우 ParcelFileDescriptor.open이 사용되고, 클라우드 파일의 경우 스트리밍을 위해 Pipe와 함께 ParcelFileDescriptor.open이 사용됩니다. 코드는 접근 오류 및 누락된 파일을 처리해야 합니다.

class CustomDocumentProvider : DocumentsProvider() {

    override fun queryRoots(): Cursor {
        val matrix = MatrixCursor(Root.COLUMNS)
        matrix.newRow().add(Root.COLUMN_ROOT_ID, "local")
            .add(Root.COLUMN_TITLE, "My Files")
            .add(Root.COLUMN_SUMMARY, "Local documents")
            .add(Root.COLUMN_FLAGS, Root.FLAG_SUPPORTS_CREATE)
        return matrix
    }

    override fun openDocument(
        documentId: String, flags: Int, cursor: CancellationSignal?
    ): ParcelFileDescriptor {
        val file = File(context.filesDir, documentId)
        val accessMode = ParcelFileDescriptor.parseMode(flags)
        return ParcelFileDescriptor.open(file, accessMode)
    }
}

가상 문서 처리

DocumentProvider는 가상 파일 — 디스크에 별도의 파일로 존재하지 않는 문서를 반환할 수 있습니다. 예를 들어, 데이터베이스 노트를 가상 PDF로 제공할 수 있습니다. 이를 위해 FLAG_VIRTUAL_DOCUMENT 플래그가 있는 MIME 유형을 사용하고, openDocument는 전송 전에 데이터를 요청된 형식으로 변환합니다.

iOS의 DocumentProvider: UIDocumentPickerViewController

iOS에도 유사한 메커니즘인 UIDocumentPickerViewController가 있으며, 통합된 파일 선택 인터페이스를 제공합니다. 그러나 iOS에서는 문서 제공자가 UIDocumentPickerDelegate 및 Document Provider 유형의 앱 확장(App Extensions)을 통해 구현됩니다.

Android DocumentsProvider와 달리, iOS UIDocumentPickerViewController는 로컬 파일을 위한 사용자 정의 제공자가 필요하지 않습니다 — 시스템 선택기는 기본적으로 iCloud Drive 및 로컬 저장소를 지원합니다. 타사 클라우드 서비스는 Info.plist 키 NSExtensionFileProviderDocumentInterface와 함께 Document Provider 확장을 통해 등록됩니다.

주요 차이점: Android에서는 DocumentProvider가 SAF Intent를 통해 적극적으로 호출되며 자체적으로 탐색을 구현해야 합니다. iOS에서는 UIDocumentPickerViewController가 내장된 시스템 파일 브라우저를 사용하며, 확장 제공자는 요청 시 콘텐츠를 제공하는 역할만 합니다.