magic-wormhole-kotlin/uno.lux.wormhole

Package-level declarations

Types

Stores received files, for ReceiveEvent.FileOffered.acceptInto. Use FileSaver.folder for a folder on the file system, or implement it for other storage, such as Android's MediaStore.

FolderUnpacker

interface FolderUnpacker

How a received directory (a zip) is unpacked. Set it in WormholeConfig.folderUnpacker.

IncomingFile

interface IncomingFile

A received file being written. The library writes to sink and closes it, then calls commit when all bytes arrived and were verified, or discard when the transfer failed.

IncomingFolder

interface IncomingFolder : UnzipTarget

A received directory being unpacked. The library calls createDirectory and createFile (paths are relative, use / and never contain ..), then commit when all files are written, or discard when unpacking failed.

InvalidCodeException

class InvalidCodeException(code: String) : WormholeException

The code does not have the form <number>-<word>[-<word>...].

InvalidZipException

class InvalidZipException(message: String) : WormholeException

The zip is damaged, unsafe (a path leaves the target folder) or larger than allowed.

OutgoingFile

class OutgoingFile(val name: String, val size: Long, val open: () -> RawSource)

A file to send. open returns a new source with the size bytes of the file each time it is called; the library calls it only when the transfer runs, and closes the source.

PeerErrorException

class PeerErrorException(val peerMessage: String) : WormholeException

The other side stopped with an error message.

ReceiveEvent

sealed interface ReceiveEvent

Progress of a receive.

SavedFile

data class SavedFile(val name: String, val location: String)

Where a received file or folder was saved. location is a path or URI to show or open.

SaveFailedException

class SaveFailedException(message: String, cause: Throwable? = null) : WormholeException

A received file could not be stored, for example because the disk is full.

SendEvent

sealed interface SendEvent

Progress of a send.

SendFileEvent

sealed interface SendFileEvent : SendEvent

Events emitted by Wormhole.sendFile and Wormhole.sendDirectory.

SendTextEvent

sealed interface SendTextEvent : SendEvent

Events emitted by Wormhole.sendText.

ServerConnectionException

class ServerConnectionException(message: String, cause: Throwable? = null) : WormholeException

The mailbox server could not be reached, or the connection was lost.

TransferRejectedException

class TransferRejectedException : WormholeException

The receiver declined the transfer.

TransitException

class TransitException(message: String, cause: Throwable? = null) : WormholeException

The data connection (direct or through the transit relay) failed.

UnzipTarget

interface UnzipTarget

Where unzip puts the files. Paths are relative, use / and never contain ...

Wormhole

class Wormhole

Entry point of the library. Each call returns a cold Flow: the transfer starts when you collect it and is cancelled when you stop collecting. Failures are thrown as WormholeException subclasses.

WormholeConfig

data class WormholeConfig(val rendezvousUrl: String = DEFAULT_RENDEZVOUS_URL, val transitRelay: String? = DEFAULT_TRANSIT_RELAY, val appId: String = DEFAULT_APP_ID, val codeLength: Int = 2, val folderUnpacker: FolderUnpacker = FolderUnpacker.streaming())

Settings for a Wormhole. The defaults are compatible with the wormhole CLI.

WormholeException

open class WormholeException(message: String, cause: Throwable? = null) : Exception

Base class for all errors reported by this library.

WormholeProtocolException

class WormholeProtocolException(message: String, cause: Throwable? = null) : WormholeException

The other side sent something that does not follow the protocol.

WormholeServerException

class WormholeServerException(val serverError: String) : WormholeException

The mailbox server reported an error, for example crowded or a welcome error.

WrongCodeException

class WrongCodeException : WormholeException

The two sides used different codes, so the keys do not match.

ZipReceiver

interface ZipReceiver

Receives the bytes of one zip for a FolderUnpacker.

Properties

DEFAULT_APP_ID

const val DEFAULT_APP_ID: String

Application ID used by the wormhole CLI and wormhole-william for text and file transfers.

DEFAULT_RENDEZVOUS_URL

const val DEFAULT_RENDEZVOUS_URL: String

Default Magic Wormhole rendezvous (mailbox) server, as used by the current wormhole CLI.

DEFAULT_TRANSIT_RELAY

const val DEFAULT_TRANSIT_RELAY: String

Default Magic Wormhole transit relay.

Functions

unzip

suspend fun unzip(zip: Path, folder: Path, maxBytes: Long = Long.MAX_VALUE, maxFiles: Int = Int.MAX_VALUE)

Unpacks the zip file zip into folder, which is created if needed. See the other unzip for the checks and for maxBytes and maxFiles.

suspend fun unzip(size: Long, open: (offset: Long) -> RawSource, target: UnzipTarget, maxBytes: Long = Long.MAX_VALUE, maxFiles: Int = Int.MAX_VALUE)

Unpacks a received directory (see ReceiveEvent.FileOffered.isDirectory) into target. Reads zips made by the wormhole CLI, wormhole-william and Wormhole.sendDirectory.