iCloud Container(IOS)

Before

You maybe be frustrated if used wrong path format, should I add file schema or not, should I use relative or absolute path:

• icloudPath means you should pass a full icloud path without schema, for example:

  • /path/to/icloud-container/my/file.txt ✅
  • file:///path/to/icloud-container/my/file.txt ❌
  • my/file.txt ❌
  • /my/file.txt ❌

  Why not support relative path anymore? Because one APP may have multiple icloud containers, before we directly passed empty id which means system will choose the first container, now with the support of passing custom container id, we will not know which container you will use.

• localPath means you should pass a full file path with or without schema, for example:

  • /path/to/app/documents/my/file.txt ✅
  • file:///path/to/app/documents/my/file.txt ✅
  • /my/file.txt ❌

API

isICloudAvailable

If user disabled your app from accessing icloud drive, or user not logged in with apple id, this will return false

function isICloudAvailable(): Promise<boolean>

defaultICloudContainerPath

Get the default(the first icloud container selected in xcode settings) container url string, it would be empty string or undefined if we cannot get it, for example: get it under android platform, or your apple developer account did not create a container or not choose a container

import { defaultICloudContainerPath } from 'react-native-cloud-store'

getICloudURL

Get path from the specific container id

function getICloudURL(
  containerIdentifier?: string,
): Promise<string>

writeFile

function writeFile(
    icloudPath: string,
    content: string,
    options: {override: boolean}
): Promise<void>

readFile

function readFile(
  icloudPath: string
): Promise<string> // utf8

readDir

function readDir(
  icloudPath: string
): Promise<string[]>

createDir

function createDir(
  icloudPath: string
): Promise<void>

moveDir

function moveDir(
    icloudPathFrom: string,
    icloudPathTo: string
): Promise<void>

copy

Copy file or directory

function copy(
  icloudPathFrom: string,
  icloudPathTo: string,
  options: {override: boolean}
): Promise<void>

unlink

Remove file or directory

function unlink(
  icloudPath: string
): Promise<void>

exist

Check file or directory exists

function exist(
  icloudPath: string
): Promise<boolean>

stat

function stat(
  icloudPath: string
): Promise<{
  isInICloud?: boolean;
  containerDisplayName?: string;

  isDownloading?: boolean;
  hasCalledDownload?: boolean;
  downloadStatus?: string;
  downloadError?: string;

  isUploaded?: boolean;
  isUploading?: boolean;
  uploadError?: string;

  hasUnresolvedConflicts?: boolean;

  modifyTimestamp?: number;
  createTimestamp?: number;
  name?: string;
  localizedName?: string;
  fileSize?: number;
  isDirectory?: boolean;
}>

registerGlobalUploadEvent

You must call this function globally, or onProgress callback of upload will not be triggered

import { useEffect } from 'react';

useEffect(() => {
  const uploadEvent = registerGlobalUploadEvent()
  return () => {
    uploadEvent?.remove()
  }
}, [])

registerGlobalDownloadEvent

You must call this function globally, or onProgress callback of download will not be triggered

import { useEffect } from 'react';

useEffect(() => {
  const downloadEvent = registerGlobalDownloadEvent()
  return () => {
    downloadEvent?.remove()
  }
}, [])

upload

Upload app's local file to iCloud container, icloudPath should not exist before uploading, or it will throw error

info

This function will be resolved immediately, if your want to wait until uploaded, you can wrap it with Promise yourself

function upload(
  localPath: string,
  icloudPath: string,
  options?: {
    onProgress?: (data: {progress: number}) => void
  }
): Promise<void>

download

Download icloud file to local device, you can only move/copy file after downloading it

info

This function will be resolved immediately, if your want to wait until uploaded, you can wrap it with Promise yourself

function download(
  icloudPath: string,
  options?: {
    onProgress?: (data: {progress: number}) => void
  }
): Promise<void>

Events

onICloudDocumentsStartGathering

This event only be called at the first search phase

onICloudDocumentsGathering

This event only be called at the first search phase

onICloudDocumentsFinishGathering

This event only be called at the first search phase

onICloudDocumentsUpdateGathering

info

download and uplaod have supported onProgress, so this event is not needed if you don't have special needs

Use this event to listen upcoming upload/download progress

If you download a file that already exist locally, this event will not be called, because system don't need to download cloud file, first-phase related events will be triggered with related data (you can use downloadStatus property returned by stat() to check if file was in local)

onICloudIdentityDidChange

Rarely used

APPLE DOC: The system generates this notification when the user logs into or out of an iCloud account or enables or disables the syncing of documents and data. when the user logs into or out of an iCloud account or enables or disables the syncing of documents and data

This event callback data is {tokenChanged: boolean}, tokenChanged will be true if icloud info changed from initial start