ouisync/org.equalitie.ouisync.lib/Repository

Repository

A Ouisync repository.

Example usage:

// Create a new repo:
val repo = Repository.create(session, "path/to/the/repo.ouisyncdb")

// or open an existing one:
val repo = Repository.open(session, "path/to/the/repo.ouisyncdb")

// Enable syncing with other replicas

repo.setSyncEnabled(true)

// Access the repository files (see File, Directory) ...

val file = File.open(repo, "path/to/file")

// Close it when done:
repo.close()

Access repository content

For info about how to access and modify the repository content see File and Directory.

Share repository with peers

To share a repository, create the share token with createShareToken, send it to the peer (e.g., via a secure instant messenger, encode as QR code and scan, ...), then create a repository on the peer's device with create, passing the share token to it.

Sync repository with peers

Enable syncing with setSyncEnabled. Afterwards Ouisync will try to automatically find peers to sync with using various peer discovery methods (Local Discovery, DHT, PEX). Additionally, peers can be added manually with Session.addUserProvidedPeer.

Local secrets

Local secrets protect the repository against unauthorized access on the same device and should never be shared with anyone (to share the repository with peers, use the share token). To change the local secrets, use setAccess. To check whether the repository is read or write protected, use requiresLocalSecretForReading and requiresLocalSecretForWriting respectively.

Cache servers

Cache servers relay traffic between peers who can't directly connect to each other. They also temporarily cache the repository content in order to allow peers to sync even when they are not online at the same time. See createMirror, deleteMirror and mirrorExists for more details.

Types

Companion

object Companion

Functions

accessMode

suspend fun accessMode(): AccessMode

Returns the access mode (blind, read or write) the repo is opened in.

suspend fun close(): Any?

Closes the repository.

createMirror

suspend fun createMirror(host: String): Any?

Create mirror of this repository on the cache server.

createShareToken

suspend fun createShareToken(secret: LocalSecret? = null, accessMode: AccessMode = AccessMode.WRITE, name: String? = null): ShareToken

Creates a share token to share this repository with other devices.

credentials

suspend fun credentials(): ByteArray

Gets the current credentials of this repository. Can be used to restore access after closing and reopening the repository.

databaseId

suspend fun databaseId(): ByteArray

Returns the database id of this repository. A database id remains unchanged even when the repo is renamed or moved and so can be used e.g. as a key for storing any per-repo configuration, if needed.

deleteMirror

suspend fun deleteMirror(host: String): Any?

Delete mirror of this repository from the cache server.

entryType

suspend fun entryType(path: String): EntryType?

Returns the type (file or directory) of an entry at the given path, or null if no such entry exists.

infoHash

suspend fun infoHash(): String

Returns the info-hash used to announce the repo on the Bittorrent DHT.

isDhtEnabled

suspend fun isDhtEnabled(): Boolean

Is Bittorrent DHT enabled?

isPexEnabled

suspend fun isPexEnabled(): Boolean

Is Peer Exchange enabled?

isSyncEnabled

suspend fun isSyncEnabled(): Any?

Returns whether syncing with other replicas is enabled.

mirrorExists

suspend fun mirrorExists(host: String): Any?

Check if this repository is mirrored on the cache server.

moveEntry

suspend fun moveEntry(src: String, dst: String): Any?

Moves an entry (file or directory) from src to dst.

requiresLocalSecretForReading

suspend fun requiresLocalSecretForReading(): Boolean

Is local secret required to read this repo?

requiresLocalSecretForWriting

suspend fun requiresLocalSecretForWriting(): Boolean

Is local secret required to write to this repo?

setAccess

suspend fun setAccess(read: AccessChange? = null, write: AccessChange? = null): Any?

Sets, unsets or changes local secrets for accessing the repository or disables the given access mode.

setAccessMode

suspend fun setAccessMode(accessMode: AccessMode, secret: LocalSecret?): Any?

Switches the repository to the given access mode.

setCredentials

suspend fun setCredentials(credentials: ByteArray): Any?

Sets the current credentials of the repository.

setDhtEnabled

suspend fun setDhtEnabled(enabled: Boolean): Any?

Enables/disabled Bittorrent DHT (for peer discovery).

setPexEnabled

suspend fun setPexEnabled(enabled: Boolean): Any?

Enables/disables Peer Exchange (for peer discovery).

setSyncEnabled

suspend fun setSyncEnabled(enabled: Boolean): Any?

Enabled or disables syncing with other replicas.

suspend fun subscribe(): EventReceiver<Unit>

Subscribe to repository events.

syncProgress

suspend fun syncProgress(): Progress

Returns the synchronization progress of this repository as the number of bytes already synced (Progress.value) vs the total size of the repository in bytes (Progress.total).