SimpleStorage

A StorageFile is the unified interface for all file types in SimpleStorage v3. It abstracts away the differences between SAF (DocumentFile), MediaStore (MediaFile), and standard java.io.File.

Key Properties:

• name, mimeType, length, isDirectory, exists, lastModified, canRead, canWrite
• absolutePath and path: Return null if the file has no resolvable physical path.

Key Methods:

• list(): Lists contents.
• child(String): Accesses a sub-path.
• openInputStream() / openOutputStream(): Standard I/O access.
• asDocumentFile(), asMediaFile(), asRawFile(): Escape hatches to access the underlying implementation.

// Creating StorageFiles from various sources:
val a = StorageFile.from(context, uri)                  // SAF, file://, or MediaStore URI
val b = StorageFile.from(context, File("/storage/emulated/0/Download/movie.mp4"))
val c = StorageFile.fromPath(context, "/storage/emulated/0/Download/movie.mp4")
val d = StorageFile.fromPath(context, StoragePath(storageId = "AAAA-BBBB", basePath = "Download/movie.mp4"))
val e = StorageFile.fromPublicDirectory(context, PublicDirectory.DOWNLOADS, "movie.mp4")

// Conversions from 2.x:
val f = documentFile.toStorageFile(context)
val g = mediaFile.toStorageFile(context)

Version 3.0 introduces a unified abstraction (StorageFile) over Android's different file systems and a consistent vocabulary for long-running operations. While the 2.x API remains available (some parts marked @Deprecated) to allow for incremental migration, 3.0 simplifies threading and scope management.

Platform Requirements for 3.0

• minSdk: 26
• compileSdk / targetSdk: 37 (Android 17)

Key Improvements

• Unified Abstraction: Use StorageFile instead of managing DocumentFile or MediaFile separately.
• Simplified Threading: Operations in 3.0 can be called from any thread without manual scope juggling (e.g., no need to pass uiScope to conflict callbacks).
• Typed Results: Operations return TransferResult, which provides typed success (TransferResult.Success<StorageFile>) and failure (TransferResult.Failure) states.

// 2.x approach (requires scope juggling and complex callbacks)
ioScope.launch {
  file.copyFileTo(context, targetFolder, 
    onConflict = object : SingleFileConflictCallback<DocumentFile>(uiScope) {
      override fun onFileConflict(destFile: DocumentFile, action: FileConflictAction) {
        action.confirmResolution(ConflictResolution.REPLACE)
      }
    }
  ).collect { /* ... */ }
}

// 3.0 approach (cleaner, works from any thread)
val result = file.copyTo(targetFolder) {
  onConflict { ConflictResolution.REPLACE }
  onProgress { progressBar.progress = it.percent.toInt() }
}
when (result) {
  is TransferResult.Success -> toast("Copied ${result.result.name}")
  is TransferResult.Failure -> log(result.errorCode, result.cause)
}

If you prefer the modern ActivityResultLauncher pattern over SimpleStorageHelper, use the contracts provided in SimpleStorageResultContracts.kt. This approach avoids manual lifecycle management of a helper instance.

Available Contracts:

• RequestStorageAccessContract
• StoragePermissionContract
• FileCreationContract
• OpenFilePickerContract
• OpenFolderPickerContract

Example: Requesting Storage Access When using RequestStorageAccessContract, the result can be one of:

• RequestStorageAccessResult.RootPathNotSelected
• RequestStorageAccessResult.ExpectedStorageNotSelected
• RequestStorageAccessResult.RootPathPermissionGranted

val contract = RequestStorageAccessContract(
    expectedStorageId = StorageId.PRIMARY,
    expectedBasePath = "Documents"
)

requestStorageAccessLauncher = registerForActivityResult(contract) { result -> 
  when (result) {
    is RequestStorageAccessResult.RootPathNotSelected -> { /* ... */ }
    is RequestStorageAccessResult.ExpectedStorageNotSelected -> { /* ... */ }
    is RequestStorageAccessResult.RootPathPermissionGranted -> { /* ... */ }
  }
}

// To launch:
val options = RequestStorageAccessContract.Options(
  initialPath = FileFullPath(
    baseContext,
    storageId = StorageId.PRIMARY,
    basePath = "Documents"
  )
)
requestStorageAccessLauncher.launch(options)

Even with runtime permissions, your app may lack full storage access (needed for searching, moving, or copying). Use SimpleStorageHelper to facilitate the Storage Access Framework (SAF) flow.

Steps to implement:

1. Initialize SimpleStorageHelper(context).
2. Set up required callbacks: onStorageAccessGranted, onFolderSelected, onFileSelected, and onFileCreated.
3. Call the request methods (e.g., requestStorageAccess(), openFolderPicker(), openFilePicker(), or createFile()).
4. Mandatory Lifecycle Handling:
   • For AppCompatActivity or ComponentActivity, you must call storageHelper.storage.onActivityResult(...) and storageHelper.onRequestPermissionsResult(...) in their respective overrides.
   • You must also call storageHelper.onSaveInstanceState(outState) and storageHelper.onRestoreInstanceState(savedInstanceState) to maintain state.

class MainActivity : AppCompatActivity() {
    private val storageHelper = SimpleStorageHelper(this)

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        
        storageHelper.onStorageAccessGranted = { requestCode, root -> /* handle access */ }
        storageHelper.onFolderSelected = { requestCode, folder -> /* handle folder */ }
        storageHelper.onFileSelected = { requestCode, files -> /* handle files */ }
        storageHelper.onFileCreated = { requestCode, file -> /* handle file */ }

        btnRequestStorageAccess.setOnClickListener { storageHelper.requestStorageAccess() }
        btnOpenFolderPicker.setOnClickListener { storageHelper.openFolderPicker() }
        btnOpenFilePicker.setOnClickListener { storageHelper.openFilePicker() }
        btnCreateFile.setOnClickListener { storageHelper.createFile("text/plain", "Test create file") }
    }

    override fun onSaveInstanceState(outState: Bundle) {
        storageHelper.onSaveInstanceState(outState)
        super.onSaveInstanceState(outState)
    }

    override fun onRestoreInstanceState(savedInstanceState: Bundle) {
        storageHelper.onRestoreInstanceState(savedInstanceState)
        super.onRestoreInstanceState(savedInstanceState)
    }

    override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
        super.onActivityResult(requestCode, resultCode, data)
        storageHelper.storage.onActivityResult(requestCode, resultCode, data)
    }

    override fun onRequestPermissionsResult(requestCode: Int, permissions: Array<String>, grantResults: IntArray) {
        super.onRequestPermissionsResult(requestCode, permissions, grantResults)
        storageHelper.onRequestPermissionsResult(requestCode, permissions, grantResults)
    }
}

SimpleStorage is written in Kotlin but is compatible with Java. To use it in a Java project, you must interact with Kotlin's object classes and extension functions using specific Java syntax.

Accessing Utility Functions

Utility functions are stored in Kotlin object classes like DocumentFileCompat and MediaStoreCompat.

In Java, you must append .INSTANCE to the class name to access these functions, unless the function is annotated with @JvmStatic.

Accessing Extension Functions

Kotlin extension functions (e.g., those in DocumentFileExtKt or FileExtKt) are available in Java as static methods. Since version 0.4.2, these are typically accessed via classes renamed with the Utils suffix (e.g., DocumentFileUtils).

Version Compatibility Warning

Important: Long-running functions such as copy, move, search, compress, and unzip are only available in Kotlin. If you require these features in a Java project, you must use version 1.5.6 or earlier, as it is the last version providing Java support for these specific operations.

// Accessing a utility function from a Kotlin object
DocumentFile file = DocumentFileCompat.INSTANCE.fromSimplePath(context, "AAAA-BBBB", "Music/My Love.mp3");

// Accessing an extension function (renamed to Utils in Java)
String storageId = DocumentFileUtils.getStorageId(file, context);