ICloudStorage class
The main class for the plugin. Provides streaming, file-path-only access to iCloud containers using Apple’s document APIs.
Overriding Goals
- Sync files to iCloud so users can retrieve them on other devices.
- Expose files in the Files app in iCloud Drive (when enabled by the app).
Transfer API (path-only)
For large files, prefer uploadFile and downloadFile. These methods pass only file paths over the platform channel (no file bytes), which avoids memory spikes and IPC limits.
In-place content API (small files)
For small text/binary files you can read/write in place using readInPlace/readInPlaceBytes and writeInPlace/writeInPlaceBytes. These methods transfer the full contents over the platform channel and load the whole file in memory.
Document IO Tier Rationale
The plugin uses the URL-tier document APIs (UIDocument/NSDocument) so
reads and writes are coordinated with iCloud and can stream efficiently
for large files.
iCloud Storage Locations
- Container Root: Syncs across devices but not visible in Files app.
- Documents/: Visible in Files app.
- Data/: App-private; should not sync.
Constructors
Properties
- hashCode → int
-
The hash code for this object.
no setterinherited
- runtimeType → Type
-
A representation of the runtime type of the object.
no setterinherited
Methods
-
noSuchMethod(
Invocation invocation) → dynamic -
Invoked when a nonexistent method or property is accessed.
inherited
-
toString(
) → String -
A string representation of this object.
inherited
Operators
-
operator ==(
Object other) → bool -
The equality operator.
inherited
Static Methods
-
copy(
{required String containerId, required String fromRelativePath, required String toRelativePath}) → Future< void> - Copy a file within the iCloud container.
-
delete(
{required String containerId, required String relativePath}) → Future< void> - Delete a file from the iCloud container.
-
documentExists(
{required String containerId, required String relativePath}) → Future< bool> - Check if a file or directory exists without downloading.
-
downloadFile(
{required String containerId, required String cloudRelativePath, required String localPath, StreamHandler< ICloudTransferProgress> ? onProgress}) → Future<void> - Download a file from iCloud, then copy it out to a local path.
-
gather(
{required String containerId, StreamHandler< GatherResult> ? onUpdate}) → Future<GatherResult> - Get all file metadata from the iCloud container.
-
getContainerPath(
{required String containerId}) → Future< String?> - Get the absolute path to the iCloud container.
-
getDocumentMetadata(
{required String containerId, required String relativePath}) → Future< Map< String, dynamic> ?> - Get raw metadata map for a file or directory.
-
getMetadata(
{required String containerId, required String relativePath}) → Future< ICloudFile?> - Get metadata for a file or directory without downloading content.
-
icloudAvailable(
) → Future< bool> - Check if iCloud is available and user is logged in.
-
move(
{required String containerId, required String fromRelativePath, required String toRelativePath}) → Future< void> - Move a file within the iCloud container.
-
readInPlace(
{required String containerId, required String relativePath, List< Duration> ? idleTimeouts, List<Duration> ? retryBackoff}) → Future<String?> - Read a file in place from the iCloud container using coordinated access.
-
readInPlaceBytes(
{required String containerId, required String relativePath, List< Duration> ? idleTimeouts, List<Duration> ? retryBackoff}) → Future<Uint8List?> - Read a file in place as bytes from the iCloud container using coordinated access.
-
rename(
{required String containerId, required String relativePath, required String newName}) → Future< void> - Rename a file in the iCloud container.
-
uploadFile(
{required String containerId, required String localPath, required String cloudRelativePath, StreamHandler< ICloudTransferProgress> ? onProgress}) → Future<void> - Copy a local file into the iCloud container (copy-in).
-
writeInPlace(
{required String containerId, required String relativePath, required String contents}) → Future< void> - Write a file in place inside the iCloud container using coordinated access.
-
writeInPlaceBytes(
{required String containerId, required String relativePath, required Uint8List contents}) → Future< void> - Write a file in place as bytes inside the iCloud container using coordinated access.
Constants
- dataDirectory → const String
- The directory name for temporary files that should not sync to iCloud.
- documentsDirectory → const String
- The directory name for files that should be visible in the Files app.