materialize method

  1. @override
Future<MaterializedFile> materialize(
  1. String key, {
  2. bool decrypt = true,
  3. bool exclusive = false,
})
override

Make a stored object available as a platform-local accessible resource.

Returns a MaterializedFile whose localPath is a filesystem path on native (usable for FFI, platform channels, native plugins taking a File/path, OS file dialogs, mmap) or a Blob URL on web (usable in <audio>/<img>/<video> src, fetch(), anchor downloads, Web Workers). The path is LOCAL to this device — it MUST NOT be persisted, synced, or shared across devices.

Parameters

decrypt — if true and the underlying file is encrypted, the materialized file contains plaintext. If false, the raw stored bytes (possibly ciphertext) are returned. For unencrypted files the flag has no effect. Default: true (callers usually want readable content).

exclusive — if true, the caller gets a private copy they may modify or delete. If false, the caller gets shared access; on local backends this returns the original file path (zero copy). Default: false.

Behavior matrix

Backend encrypted? decrypt exclusive Result
Local no any false Original path (zero copy)
Local no any true Copy to temp
Local yes true false Decrypt to cache (reusable)
Local yes true true Decrypt to temp (caller owns)
Local yes false false Original encrypted path
Local yes false true Copy encrypted to temp
IndexedDB no any any Blob URL
IndexedDB yes true any Decrypt + blob URL
IndexedDB yes false any Raw blob URL

Lifecycle

Call MaterializedFile.release when done.

  • Local, exclusive: false, unencrypted: no-op (original stays).
  • Local, exclusive: false, decrypted: cached; cleaned on eviction.
  • Local, exclusive: true: temp deleted.
  • IndexedDB: blob URL revoked.

Implementation

@override
Future<MaterializedFile> materialize(
  String key, {
  bool decrypt = true,
  bool exclusive = false,
}) {
  checkNotDisposed();
  throw UnimplementedError(
    'ChunkedBackend does not implement materialize directly. '
    'Subclass it with a platform-specific materialize (Blob URL on '
    'web, file path on native) or wrap it in a decorator.',
  );
}