File Transfer

A File Transfer is a file, with optional metadata, queued for background delivery to the Watch. The Watch doesn't have to be reachable.

Each file you send is a Transfer until it's delivered:

• transferFile starts one and returns its Transfer snapshot.
• outstandingFileTransfers lists the ones not delivered yet, with their progress.
• cancelFileTransfer cancels one by its id.
• onFileTransferFinished fires exactly once per Transfer: when it's delivered, fails or is cancelled.

Files the Watch sends you are Received files. They arrive through onFileReceived, or through onFileReceiveFailed when one couldn't be kept.

transferFileCopy Anchor Link

transferFile(file: string, metadata?: Record<string, any>): FileTransfer

Queues a file for delivery to the Watch and returns at once. The Watch app receives it in session(_:didReceive:).

WatchConnectivity keeps its own copy of the file, so you can delete yours right after calling transferFile. That doesn't stop or fail the Transfer.

Parameters

Returns the Transfer snapshot, FileTransfer, in the same shape as outstandingFileTransfers:

Throws (synchronously):

Its error message starts with Expo's prefix, "Calling the 'transferFile' function has failed", so match on code. Delivery failures don't throw here: they arrive later, in onFileTransferFinished.

Example

import RnWatchConnect, { type WatchConnectErrorCode } from "rn-watch-connect";

const uri = "file:///path/to/Documents/route.gpx";

try {
  const transfer = RnWatchConnect.transferFile(uri, { name: "route.gpx" });
  console.log("Queued Transfer", transfer.id);
} catch (error) {
  const code = (error as { code?: WatchConnectErrorCode }).code;
  if (code === "ERR_FILE_NOT_FOUND") {
    // The file was moved or deleted before you could send it.
  }
}

cancelFileTransferCopy Anchor Link

cancelFileTransfer(transferId: string): { id: string }

Cancels an outstanding File Transfer. Its onFileTransferFinished event is sent immediately, with error.code "ERR_TRANSFER_CANCELLED".

Parameters

Returns { id: string }: the id of the cancelled Transfer.

Throws (synchronously):

Its error message starts with Expo's prefix, "Calling the 'cancelFileTransfer' function has failed", so match on code.

If the Transfer was delivered just before you cancel, the cancel throws ERR_INVALID_TRANSFER_ID and the finish event reports the delivery, with error: null.

Example

import RnWatchConnect from "rn-watch-connect";

// Cancel every File Transfer still waiting.
for (const transfer of RnWatchConnect.outstandingFileTransfers) {
  RnWatchConnect.cancelFileTransfer(transfer.id);
}

outstandingFileTransfersCopy Anchor Link

readonly outstandingFileTransfers: FileTransfer[]

The File Transfers that haven't been delivered yet, as Transfer snapshots (id, isTransferring, progress, file). It's [] when there are none, and on platforms other than iOS.

WatchConnectivity has no progress event. To show progress, read this property every so often, and use onFileTransferFinished to know when a Transfer is done.

Example

import RnWatchConnect from "rn-watch-connect";

const timer = setInterval(() => {
  for (const { id, progress } of RnWatchConnect.outstandingFileTransfers) {
    console.log(id, `${Math.round(progress.fractionCompleted * 100)}%`);
  }
}, 1000);

// Later: clearInterval(timer);

onFileReceivedCopy Anchor Link

onFileReceived: (file: File) => void

Fires when a Received file arrives from the Watch.

Event

The file is yours from this event on. The library moves each Received file into your app's temporary directory, then never moves, overwrites or deletes it again.

• iOS can delete files in the temporary directory while your app isn't running. Move or copy the file somewhere permanent if you need to keep it, and delete it when you're done.
• Received files never overwrite each other. If the name is taken, the new file is numbered the way Finder does it: photo.jpg, then photo(1).jpg, photo(2).jpg, and so on. metadata is passed through unchanged, so you can still read the original name if the Watch sent it there.

Example

import { useEventListener } from "expo";
import RnWatchConnect from "rn-watch-connect";

export function FileInbox() {
  useEventListener(RnWatchConnect, "onFileReceived", ({ fileURL, metadata }) => {
    const name = metadata.name ?? fileURL.split("/").pop();
    console.log(`Received ${name} at ${fileURL}`);
    // Move or copy it somewhere permanent here if you need to keep it.
  });
  return null;
}

onFileReceiveFailedCopy Anchor Link

onFileReceiveFailed: (event: FileReceiveFailedEvent) => void

Fires when a file from the Watch arrived but couldn't be kept, for example because the iPhone is out of storage. The file is lost: WatchConnectivity has already deleted it, and onFileReceived doesn't fire for it. Use fileName and metadata to tell which file it was, for example to ask the Watch to send it again.

Event

Example

import { useEventListener } from "expo";
import RnWatchConnect from "rn-watch-connect";

export function LostFileWarning() {
  useEventListener(RnWatchConnect, "onFileReceiveFailed", ({ code, fileName }) => {
    if (code === "ERR_INSUFFICIENT_SPACE") {
      console.warn(`Not enough storage to keep ${fileName} from the Watch.`);
    } else {
      console.warn(`Couldn't keep ${fileName} from the Watch.`);
    }
  });
  return null;
}

onFileTransferFinishedCopy Anchor Link

onFileTransferFinished: (event: FileTransferFinishedEvent) => void

Fires exactly once per File Transfer, however it ends. The event is the Transfer snapshot (id, isTransferring, progress, file) plus error:

If your Watch app is uninstalled during a Transfer, the Transfer stays outstanding and no finish event is sent, even after a reinstall. Cancel it to end it, for example when onWatchAppInstallChanged reports isWatchAppInstalled: false.

Example

import { useEventListener } from "expo";
import RnWatchConnect from "rn-watch-connect";

export function FileTransferLog() {
  useEventListener(RnWatchConnect, "onFileTransferFinished", (transfer) => {
    if (transfer.error?.code === "ERR_TRANSFER_CANCELLED") {
      console.log("Cancelled:", transfer.id);
    } else if (transfer.error) {
      console.log("Failed:", transfer.id, transfer.error.code);
    } else {
      console.log("Delivered:", transfer.file.fileURL);
    }
  });
  return null;
}