uploadFile static method

Future<void> uploadFile({ required String containerId, required String localPath, required String cloudRelativePath, StreamHandler<ICloudTransferProgress>? onProgress, })

Copy a local file into the iCloud container (copy-in).

localPath is the absolute path to a local file to copy. cloudRelativePath is the path within the iCloud container. Use 'Documents/' prefix for Files app visibility.

This does not keep the local file in sync. After the copy completes, iCloud uploads the container file automatically in the background.

Trailing slashes are rejected here because transfers are file-centric and coordinated through UIDocument/NSDocument (directories are not supported).

If onProgress is provided, attach a listener immediately inside the callback. Progress streams are listener-driven (not buffered), so delaying listen() may miss early progress events.

Implementation

static Future<void> uploadFile({
  required String containerId,
  required String localPath,
  required String cloudRelativePath,
  StreamHandler<ICloudTransferProgress>? onProgress,
}) async {
  if (localPath.trim().isEmpty) {
    throw InvalidArgumentException('invalid localPath: $localPath');
  }

  // Transfers are file-centric (UIDocument/NSDocument). A trailing slash
  // indicates a directory path and would be ambiguous or fail natively.
  if (cloudRelativePath.endsWith('/')) {
    throw InvalidArgumentException(
      'invalid cloudRelativePath: $cloudRelativePath',
    );
  }

  if (!_validateRelativePath(cloudRelativePath)) {
    throw InvalidArgumentException(
      'invalid cloudRelativePath: $cloudRelativePath',
    );
  }

  await ICloudStoragePlatform.instance.uploadFile(
    containerId: containerId,
    localPath: localPath,
    cloudRelativePath: cloudRelativePath,
    onProgress: onProgress,
  );
}