# Iceblock SDK, library 0.16.9 > Every call of Iceblock's SDK: the Rust crate `iceblock-sdk` and the Flutter package `iceblock_flutter` (the same calls, as methods of `IceblockApp`), both version 0.16.9, from the iceblock organisation's registries on git.tricauda.com. Generated from the code. Each call says what it needs (a permission an app asks the user's Iceblock for), where it works (the app's own network, the user's Iceblock, or both) and the release it arrived in. Guides and design: https://iceblock.tricauda.com/sdk/ . The same as JSON: https://iceblock.tricauda.com/sdk/api.json ## Collection ### Collection::hide_from_files - Rust: `pub fn hide_from_files(&self) -> Result<()>` - Dart: `Future hideFromFiles({required String collection});` - Needs: nothing. Where: both. Since: r76. Asks the user's Iceblock to keep this Collection out of their Files and Collections: it's shown under the app instead, in My network, where the user can put it back. Done at once in the app's own network. ### Collection::id - Rust: `pub fn id(&self) -> &str` - Dart: `Future ownCollection();` - Needs: nothing. Where: both. Since: r76. Its id: the same on every device that holds it, and in every network that holds it together. ### Collection::name - Rust: `pub fn name(&self) -> String` - Dart: `Future ownCollection();` - Needs: nothing. Where: both. Since: r76. Its name. ### Collection::write - Rust: `pub fn write(&self, path: &str, bytes: &[u8]) -> Result<()>` - Dart: `Future write({required String collection, required String path, required List bytes});` - Needs: nothing. Where: both. Since: r76. Writes `bytes` to `path`: a new file, or a new version of it. ### Collection::write_from - Rust: `pub fn write_from(&self, path: &str, source: &Path) -> Result<()>` - Dart: `Future writeFrom({required String collection, required String path, required String source});` - Needs: nothing. Where: both. Since: r76. Writes the file at `source` on disk to `path`, a block at a time, however large it is. ### Collection::read - Rust: `pub fn read(&self, path: &str) -> Result>` - Dart: `Future read({required String collection, required String path});` - Needs: nothing. Where: both. Since: r76. Reads `path`'s current content, fetching from the devices holding it whatever isn't here. ### Collection::read_to - Rust: `pub fn read_to(&self, path: &str, out: &mut (impl Write + Send)) -> Result` - Dart: `Future readTo({required String collection, required String path, required String out});` - Needs: nothing. Where: both. Since: r76. Writes `path`'s current content to `out`, a block at a time, fetching first whatever isn't here. ### Collection::read_range - Rust: `pub fn read_range(&self, path: &str, offset: u64, len: u64) -> Result>` - Dart: `Future readRange({required String collection, required String path, required BigInt offset, required BigInt len});` - Needs: nothing. Where: both. Since: r76. Bytes `offset` to `offset + len` of `path` (fewer at its end), fetching only the blocks they're in. ### Collection::read_version - Rust: `pub fn read_version(&self, path: &str, index: usize) -> Result>` - Dart: `Future readVersion({required String collection, required String path, required int index});` - Needs: nothing. Where: both. Since: r76. A past version's content. ### Collection::list - Rust: `pub fn list(&self, folder: &str) -> Vec` - Dart: `Future> list({required String collection, required String folder});` - Needs: nothing. Where: both. Since: r76. What's in the folder `folder` (`""` for the top), one level down: folders first, then files, each by name. ### Collection::files - Rust: `pub fn files(&self) -> Vec` - Dart: `Future> files({required String collection});` - Needs: nothing. Where: both. Since: r76. Every file's path in the Collection, at every depth. ### Collection::info - Rust: `pub fn info(&self, path: &str) -> Option` - Dart: `Future info({required String collection, required String path});` - Needs: nothing. Where: both. Since: r76. What's known of the file at `path`, if there is one. ### Collection::versions - Rust: `pub fn versions(&self, path: &str) -> Result>` - Dart: `Future> versions({required String collection, required String path});` - Needs: nothing. Where: both. Since: r76. The file at `path`'s versions, oldest first. ### Collection::restore - Rust: `pub fn restore(&self, path: &str, index: usize) -> Result<()>` - Dart: `Future restore({required String collection, required String path, required int index});` - Needs: nothing. Where: both. Since: r76. Makes the version `index` of `path` its current one again, as a new version: nothing's lost. ### Collection::rename - Rust: `pub fn rename(&self, from: &str, to: &str) -> Result<()>` - Dart: `Future rename({required String collection, required String from, required String to});` - Needs: nothing. Where: both. Since: r76. Moves the file or folder at `from` to `to`, both in this Collection. ### Collection::delete - Rust: `pub fn delete(&self, path: &str) -> Result<()>` - Dart: `Future delete({required String collection, required String path});` - Needs: nothing. Where: both. Since: r76. Deletes the file at `path`, to the trash: it can be restored for a while (`restore_deleted`), and is purged after. ### Collection::restore_deleted - Rust: `pub fn restore_deleted(&self, path: &str) -> Result<()>` - Dart: `Future restoreDeleted({required String collection, required String path});` - Needs: nothing. Where: both. Since: r76. Brings a deleted file back from the trash. ### Collection::create_folder - Rust: `pub fn create_folder(&self, path: &str) -> Result<()>` - Dart: `Future createFolder({required String collection, required String path});` - Needs: nothing. Where: both. Since: r76. Makes an empty folder at `path`, which every device shows. ### Collection::sync - Rust: `pub fn sync(&self)` - Dart: `Future syncCollection({required String collection});` - Needs: nothing. Where: both. Since: r76. Syncs this Collection soon, alone: for a change that should reach the others promptly. ### Collection::watch - Rust: `pub fn watch(&self) -> Watch` - Dart: `Stream> watch({required String collection});` - Needs: nothing. Where: both. Since: r76. Watches the Collection: what's added, changed and removed, here or on another device, from now on. ## Group ### Group::id - Rust: `pub fn id(&self) -> &str` - Dart: `Future> groups();` - Needs: nothing. Where: both. Since: r76. ### Group::name - Rust: `pub fn name(&self) -> String` - Dart: `Future> groups();` - Needs: nothing. Where: both. Since: r76. Its name. ### Group::is_home - Rust: `pub fn is_home(&self) -> bool` - Dart: `Future> groups();` - Needs: nothing. Where: both. Since: r76. Whether this network is the group's home, which keeps its Collections safe and its roster. ### Group::synced_secs - Rust: `pub fn synced_secs(&self) -> Option` - Dart: `Future groupSyncedSecs({required String group});` - Needs: nothing. Where: both. Since: r79. When this network last heard from the group's home, in seconds since the epoch: whichever of its devices did, as each sync with the home brings the roster; now, at the home. `None` if it never has, or if it says a time still to come, as a clock that was ahead recorded it. To be sure it's fresh, [`Group::sync`] first. ### Group::home - Rust: `pub fn home(&self) -> String` - Dart: `Future> groups();` - Needs: nothing. Where: both. Since: r78. Its home network's fingerprint: the one that keeps it, whose files in the group's Collections have no [`crate::FileInfo::network`] of their own. It can change, as a group's handed on. ### Group::successions - Rust: `pub fn successions(&self) -> Vec<(String, String)>` - Dart: `Future> groupSuccessions({required String group});` - Needs: nothing. Where: both. Since: r78. The networks of the group that were succeeded by others (#733), as an app's own network is when the user's Iceblock adopts it: each old network's fingerprint and its successor's, every one checked against the old network's own signature. What the old one wrote is the successor's. ### Group::current - Rust: `pub fn current(&self, network: &str) -> String` - Dart: `Future groupCurrent({required String group, required String network});` - Needs: nothing. Where: both. Since: r78. The network `network` (a fingerprint) is now: the last of the successions from it, or itself. ### Group::members - Rust: `pub fn members(&self) -> Vec` - Dart: `Future> groupMembers({required String group});` - Needs: nothing. Where: both. Since: r76. Its members, as this network last heard from the home. ### Group::role - Rust: `pub fn role(&self) -> Option` - Dart: `Future> groups();` - Needs: nothing. Where: both. Since: r76. This network's role in it. ### Group::collections - Rust: `pub fn collections(&self) -> Vec` - Dart: `Future> groupCollections({required String group});` - Needs: nothing. Where: both. Since: r76. Its Collections that this network holds now: a member's devices take each in at a round after they hear of it. ### Group::new_collection - Rust: `pub fn new_collection(&self, name: &str) -> Result` - Dart: `Future groupNewCollection({required String group, required String name});` - Needs: `group:` in the user's Iceblock, where it goes as a request the user approves. Where: both. Since: r76. Makes a new Collection of the group's, named `name`: an Owner's or Caretaker's to do. With this app in the group, it's the app's: only the members that use the app have it. ### Group::add_collection - Rust: `pub fn add_collection(&self, collection: &Collection) -> Result<()>` - Dart: `Future groupAddCollection({required String group, required String collection});` - Needs: `group:` in the user's Iceblock, where it goes as a request the user approves. Where: both. Since: r76. Gives one of this network's Collections to the group: it's the group's from then on, kept by its home, with the group's roles. At once for an Owner or Caretaker; a member below asks them. ### Group::invite - Rust: `pub fn invite(&self, role: Role) -> Result` - Dart: `Future groupInvite({required String group, required String role});` - Needs: `group:` in the user's Iceblock, where it goes as a request the user approves. Where: both. Since: r76. An invitation to the group with `role`, for whoever opens it first: its link, to send or show as a QR code, to the app's link address ([`crate::Config::link_base`]) or Iceblock's website, with the invitation after the `#`. ### Group::set_role - Rust: `pub fn set_role(&self, network: &str, role: Role) -> Result<()>` - Dart: `Future groupSetRole({required String group, required String network, required String role});` - Needs: `group:` in the user's Iceblock, where it goes as a request the user approves. Where: both. Since: r76. Gives the member `network` (a fingerprint) `role`, as this network's own role allows. ### Group::remove - Rust: `pub fn remove(&self, network: &str) -> Result<()>` - Dart: `Future groupRemove({required String group, required String network});` - Needs: `group:` in the user's Iceblock, where it goes as a request the user approves. Where: both. Since: r76. Takes the member `network` out of the group, as this network's role allows. ### Group::leave - Rust: `pub fn leave(&self) -> Result<()>` - Dart: `Future groupLeave({required String group});` - Needs: `group:` in the user's Iceblock, where it goes as a request the user approves. Where: both. Since: r76. Leaves the group, and with it its Collections. The last Owner can't. ### Group::has_app - Rust: `pub fn has_app(&self) -> bool` - Dart: `Future groupHasApp({required String group});` - Needs: nothing. Where: both. Since: r76. Whether this app is in the group: an Owner adds it for everyone in it, each choosing whether to use it. A group the app makes has it. ### Group::add_app - Rust: `pub fn add_app(&self) -> Result<()>` - Dart: `Future groupAddApp({required String group});` - Needs: `group:` in the user's Iceblock, where it goes as a request the user approves. Where: both. Since: r76. Adds this app to the group, for everyone in it (an Owner's), as its manifest says: the least role its Collections need, and what it asks of `group-contact`. This network uses it. ### Group::uses_app - Rust: `pub fn uses_app(&self) -> bool` - Dart: `Future groupUsesApp({required String group});` - Needs: nothing. Where: both. Since: r76. Whether this network uses this app in the group: only then are the app's Collections there this network's. ### Group::use_app - Rust: `pub fn use_app(&self, accept: bool, contact: bool) -> Result<()>` - Dart: `Future groupUseApp({required String group, required bool accept, required bool contact});` - Needs: `group:` in the user's Iceblock, where it goes as a request the user approves. Where: both. Since: r76. Uses this app in the group, or stops, as the user chose; with `contact`, agreeing to the app knowing when the group's home hasn't heard from this network in two days or more. An app that requires that can't be used without it ([`Group::contact_required`]). ### Group::contact_required - Rust: `pub fn contact_required(&self) -> bool` - Dart: `Future groupContactRequired({required String group});` - Needs: nothing. Where: both. Since: r76. Whether this app requires its members to agree to `group-contact` to use it, as its manifest said when it was added. ### Group::contact_shared - Rust: `pub fn contact_shared(&self) -> bool` - Dart: `Future groupContactShared({required String group});` - Needs: nothing. Where: both. Since: r76. Whether this network agrees to `group-contact` for this app. ### Group::out_of_touch - Rust: `pub fn out_of_touch(&self) -> Vec` - Dart: `Future> groupOutOfTouch({required String group});` - Needs: `group-contact:` in the user's Iceblock. Where: both. Since: r76. The members the group's home hasn't heard from in two days or more, of those that agreed to `group-contact` for this app, and nothing finer: as the home last said, or, at the home, now. ### Group::presence_shared - Rust: `pub fn presence_shared(&self) -> bool` - Dart: `Future groupPresenceShared({required String group});` - Needs: nothing. Where: both. Since: r83. Whether this network lets this app know when it's around, in the group (#755). ### Group::share_presence - Rust: `pub fn share_presence(&self, share: bool) -> Result<()>` - Dart: `Future groupSharePresence({required String group, required bool share});` - Needs: `group:` in the user's Iceblock, where it goes as a request the user approves. Where: both. Since: r83. Lets this app know when this network is around, in the group, or stops, as the user chose (#755): the members that do see each other's [`Group::presence`]. ### Group::presence - Rust: `pub fn presence(&self) -> Result>` - Dart: `Future> groupPresence({required String group});` - Needs: `group-presence:` in the user's Iceblock. Where: both. Since: r83. Whether the members that let this app know are around (#755): from their use of any app built on Iceblock or Iceblock itself, passed on by the group's home. Coarsened to five minutes, unknown after two hours. In the user's Iceblock only with `group-presence:` ([`Permission::GroupPresence`]). ### Group::propose_app_out - Rust: `pub fn propose_app_out(&self, to: Option<&Group>) -> Result<()>` - Dart: `Future groupProposeAppOut({required String group, String? to});` - Needs: `group:` in the user's Iceblock, where it goes as a request the user approves. Where: both. Since: r76. Proposes taking this app out of the group (an Owner's): its Collections stay the group's, as ordinary ones, until it's added again. Or, with `to`, moving it there, with its Collections and their files: a group with the same home, of which this network is an Owner too. It goes once every Owner agrees, or in 14 days with none declining. ### Group::sync - Rust: `pub fn sync(&self)` - Dart: `Future groupSync({required String group});` - Needs: nothing. Where: both. Since: r76. Brings its roster up to date from its home now. ## Manifest ### Manifest::new - Rust: `pub fn new(permissions: impl IntoIterator) -> Self` - Dart: `static Future start({required IceblockConfig config}) => RustLib.instance.api.crateApiIceblockAppStart(config: config);` - Needs: nothing. Where: both. Since: r76. A manifest asking for `permissions`. ### Manifest::requiring - Rust: `pub fn requiring(mut self, permissions: impl IntoIterator) -> Self` - Dart: `static Future start({required IceblockConfig config}) => RustLib.instance.api.crateApiIceblockAppStart(config: config);` - Needs: nothing. Where: both. Since: r76. And requiring `permissions`: taking part means granting them. ### Manifest::needing_group_role - Rust: `pub fn needing_group_role(mut self, role: group::Role) -> Self` - Dart: `static Future start({required IceblockConfig config}) => RustLib.instance.api.crateApiIceblockAppStart(config: config);` - Needs: nothing. Where: both. Since: r76. And, in a group, needing at least `role` in its Collections (#737): every member that uses it has that there, whatever its role in the group (`group-role:contributor`). Owner isn't one to ask for. ## Iceblock ### Iceblock::start - Rust: `pub fn start(config: Config) -> Result` - Dart: `static Future start({required IceblockConfig config}) => RustLib.instance.api.crateApiIceblockAppStart(config: config);` - Needs: nothing. Where: both. Since: r76. Opens the device in `config.data_dir`, making it and a network of its own the first time, with keys in files there readable only by the app, and starts serving it. ### Iceblock::start_with_keystore - Rust: `pub fn start_with_keystore(config: Config, keystore: K) -> Result` - Dart: not carried (for tests, keeping keys in memory: a Dart app keeps them where the platform does) - Needs: nothing. Where: both. Since: r76. As [`Iceblock::start`], with keys kept by `keystore` rather than in files: an in-memory one for tests (`iceblock_crypto::InMemoryKeystore`). ### Iceblock::set_log - Rust: `pub fn set_log(sink: impl Fn(LogLevel, &str) + Send + Sync + 'static)` - Dart: `Stream logStream();` - Needs: nothing. Where: both. Since: r100. Where the library's log goes (#800): each line, with how much it matters, as the library works (syncs, devices out of reach, its relay, shares served). Once, before the first [`Iceblock::start`]: later calls are ignored. Without it, warnings and errors go to standard error, marked `iceblock:`, and the rest nowhere. ### Iceblock::recent_log - Rust: `pub fn recent_log(&self, after: u64) -> Vec` - Dart: `List recentLog({required BigInt after});` - Needs: nothing. Where: both. Since: r100. The library's latest log lines after `after` (0 for all it keeps, up to 2,000), oldest first (#800): for the app's own debug report. ### Iceblock::port - Rust: `pub fn port(&self) -> Option` - Dart: `Future port();` - Needs: nothing. Where: both. Since: r81. The port it serves on, TCP and UDP, while it serves: the same after it joins another network (#733), so its old network's members still reach it there, to be shown where that network went. ### Iceblock::stop - Rust: `pub fn stop(&self)` - Dart: `Future stop();` - Needs: nothing. Where: both. Since: r76. Stops serving. The device and its files stay; [`Iceblock::start`] opens them again. Dropping the last clone stops it too. ### Iceblock::status - Rust: `pub fn status(&self) -> Status` - Dart: `Future status();` - Needs: nothing. Where: both. Since: r76. Where the device stands, and how it's going. ### Iceblock::devices - Rust: `pub fn devices(&self) -> Result>` - Dart: `Future> devices();` - Needs: `devices` in the user's Iceblock. Where: both. Since: r82. The devices of the network this device is in, the user's: each by its fingerprint, with its name. In the user's Iceblock (as an app device), only with the `devices` permission ([`Permission::Devices`]), and otherwise refused; alone, or in the app's own network, they're the app's own installs. ### Iceblock::used - Rust: `pub fn used(&self)` - Dart: `Future used();` - Needs: nothing. Where: both. Since: r83. Says the person is using the app now (SDK stage 3, #755): call it while the app is in front and being used, every few minutes at most. It counts towards whether they're around, never saying which app; nothing is noted unless an app of theirs holds `presence`. When it picks the machine up, after a while unused, it syncs at once, so apps on the machine holding `device-presence` hear (#769). ### Iceblock::presence - Rust: `pub fn presence(&self) -> Result` - Dart: `Future presence();` - Needs: `presence` in the user's Iceblock; `machine_last_used` also `device-presence`, `machine_last_active` also `device-activity`. Where: both. Since: r83. Whether the person is around (#755): the network's state, from their use of any app built on Iceblock or Iceblock itself, and, for each of this app's own installs, when it was last used and last heard from. Coarsened to five minutes, unknown after two hours. In the user's Iceblock only with `presence` ([`Permission::Presence`]). ### Iceblock::report_activity - Rust: `pub fn report_activity(&self, on: bool) -> Result<()>` - Dart: `Future reportActivity({required bool on_});` - Needs: nothing. Where: own network. Since: r95. Turns on (or off) checking when the person's at their computer (#772), for the app in a network of its own, once it has asked them in its own words: there's no Iceblock to grant `device-activity`. While it's on, the SDK asks the computer every half a minute, on computers (Linux, for now), and each install's [`InstallPresence::machine_last_active`] says. Refused in the user's Iceblock, where it's the `device-activity` permission, and Iceblock checks wherever it's installed. When the user's Iceblock adopts the app, it offers to keep it. ### Iceblock::reports_activity - Rust: `pub fn reports_activity(&self) -> bool` - Dart: `bool reportsActivity();` - Needs: nothing. Where: own network. Since: r95. Whether the app, in a network of its own, checks when the person's at their computer ([`Iceblock::report_activity`]). ### Iceblock::collection - Rust: `pub fn collection(&self) -> Result` - Dart: `Future ownCollection();` - Needs: nothing. Where: both. Since: r76. The app's own Collection: made the first time, named after the app. ### Iceblock::collections - Rust: `pub fn collections(&self) -> Vec` - Dart: `Future> collections();` - Needs: nothing: in the user's Iceblock, the Collections it's been given. Where: both. Since: r76. Every Collection the app can reach: its own, those it made, its groups', and, as an app device, those it's been given. ### Iceblock::collection_by_id - Rust: `pub fn collection_by_id(&self, id: &str) -> Option` - Dart: `Future write({required String collection, required String path, required List bytes});` - Needs: nothing: in the user's Iceblock, a Collection it's been given. Where: both. Since: r76. A Collection by its id, if the app can reach it. ### Iceblock::create_collection - Rust: `pub fn create_collection(&self, name: &str) -> Result` - Dart: `Future createCollection({required String name});` - Needs: nothing. Where: both. Since: r76. Makes another Collection of the app's, named `name`: personal, its user's own data, which stays on the user's network (#777). As an app device of the user's Iceblock, the user's network makes it: this asks, and waits, syncing, until one of their Full-trust devices has (up to a minute); if none could be reached, it errs, and the network makes it when one is ([`Iceblock::collection_by_id`] then finds it). ### Iceblock::set_conditions - Rust: `pub fn set_conditions(&self, conditions: Conditions)` - Dart: `Future setConditions({required bool vpn, required bool metered, required bool onPower, String? gateway, required bool batterySaver});` - Needs: nothing. Where: both. Since: r76. Passes on what the platform says ([`Conditions`]), as it changes: on a metered network the device syncs only if the user allowed it ([`Iceblock::set_metered_allowed`]), bulk transfers wait for an unmetered one and power, and with the battery saver on nothing syncs by itself. Coming off a metered network syncs at once; a new gateway is asked to forward the port. ### Iceblock::metered_allowed - Rust: `pub fn metered_allowed(&self) -> Option` - Dart: `bool? meteredAllowed();` - Needs: nothing. Where: both. Since: r76. Whether the user lets the device sync on a metered connection (mobile data, a metered Wi-Fi): `None` until they've said. Until they allow it, it doesn't, so the app asks them. ### Iceblock::set_metered_allowed - Rust: `pub fn set_metered_allowed(&self, allowed: bool) -> Result<()>` - Dart: `Future setMeteredAllowed({required bool allowed});` - Needs: nothing. Where: both. Since: r76. The user's answer: sync on metered connections, or not. ### Iceblock::set_owner_name - Rust: `pub fn set_owner_name(&self, name: &str) -> Result<()>` - Dart: `Future setOwnerName({required String name});` - Needs: nothing. Where: both. Since: r76. Sets the user's name, as other networks (a group's members) see it. Until it's set, nothing involving another network happens. ### Iceblock::sync_now - Rust: `pub fn sync_now(&self)` - Dart: `Future syncNow();` - Needs: nothing. Where: both. Since: r76. Syncs now: with the network's other devices and every group's home, rather than at the next scheduled round. ### Iceblock::sync_and_wait - Rust: `pub fn sync_and_wait(&self, timeout: Duration) -> bool` - Dart: `Future syncAndWait({required int timeoutSecs});` - Needs: nothing. Where: both. Since: r76. Syncs now, as [`Iceblock::sync_now`], and waits for it, up to `timeout`: whether it finished. For work in the background, which ends when it's done. ### Iceblock::set_events - Rust: `pub fn set_events(&self, events: Arc)` - Dart: `Stream eventStream();` - Needs: nothing. Where: both. Since: r76. Tells the app of what happens that needs it: a device asking to join. Replaces any handler set before. ### Iceblock::invite_device - Rust: `pub fn invite_device(&self) -> Result` - Dart: `Future inviteDevice();` - Needs: nothing. Where: own network. Since: r76. An invitation for the app on another of the user's devices: valid for a few minutes, for one device. Joining asks this device's [`Events::join_asked`]. ### Iceblock::join - Rust: `pub fn join(&self, invitation: &str) -> Result<()>` - Dart: `Future join({required String invitation});` - Needs: nothing. Where: own network. Since: r76. Joins the network an invitation (its link or token) is from: the app's network on another of the user's devices, or the user's own Iceblock. Alone and with no files, this device simply joins. With files, it brings them: into the app's network, as one of its devices; into the user's Iceblock, as an app device whose files the user's device carries in (a pulled merge, technical-spec §3.8). ### Iceblock::permissions - Rust: `pub fn permissions(&self) -> Vec` - Dart: `Future> permissions();` - Needs: nothing. Where: both. Since: r76. Whether this device can make and run groups: it's Full trust in its network. An app device of the user's Iceblock can't. What this app holds in the user's Iceblock, once it's joined it: its Collections (`collection:`) and the permissions it's been granted. Alone, or in the app's own network, it holds everything of its own, and this is empty. ### Iceblock::request - Rust: `pub fn request(&self, permission: Permission) -> Result<()>` - Dart: `Future request({required String permission});` - Needs: nothing. Where: user's Iceblock. Since: r76. Asks the user's Iceblock for `permission`, which the manifest must list (a Collection's needn't be). The user answers there; the answer shows in [`Iceblock::permissions`], and comes as [`Events::granted`] or [`Events::denied`]. Only once the app has joined the user's Iceblock. ### Iceblock::open_requests - Rust: `pub fn open_requests(&self) -> Result<()>` - Dart: `Future openRequests();` - Needs: nothing. Where: user's Iceblock. Since: r85. Opens the user's Iceblock, running on this computer, at what this app has asked for (#759), for the user to answer there now rather than when they next look: sends what's waiting first. On Linux, through Iceblock's control socket, which only the same user can reach; on Android, the platform package's `openIceblockRequests` does it. Errs if Iceblock isn't running here. ### Iceblock::join_on_this_device - Rust: `pub fn join_on_this_device(&self) -> Result<()>` - Dart: `Future joinOnThisDevice();` - Needs: nothing. Where: own network. Since: r85. Joins the user's Iceblock running on this computer (#759), with no invitation to pass and no fingerprints to compare: Iceblock shows the user this app, its name and what its manifest may ask for, and once they approve, invites this device alone, which joins as [`Iceblock::join`] does, bringing its files. On Linux, through Iceblock's control socket, which only the same user can reach (the app's id can't be checked there, as Android checks it); on Android, the platform package's `joinIceblock` gives the invitation to join with. Errs if Iceblock isn't running here, or the user said no. ### Iceblock::removed - Rust: `pub fn removed(&self) -> bool` - Dart: `Future status();` - Needs: nothing. Where: user's Iceblock. Since: r86. Whether the user removed this device from their Iceblock (#659): it's cut off, keeping what it had, and nothing new reaches it; its syncs are refused. [`Events::removed`] says so as it happens. Joining again (a new invitation) ends it. ### Iceblock::request_collection - Rust: `pub fn request_collection(&self, id: &str) -> Result<()>` - Dart: `Future requestCollection({required String id});` - Needs: nothing. Where: user's Iceblock. Since: r76. Asks for the Collection `id`'s files: as [`Iceblock::request`]. ### Iceblock::can_group - Rust: `pub fn can_group(&self) -> bool` - Dart: `bool canGroup();` - Needs: nothing. Where: both. Since: r76. ### Iceblock::groups - Rust: `pub fn groups(&self) -> Vec` - Dart: `Future> groups();` - Needs: nothing. Where: both. Since: r76. The groups this network is in. ### Iceblock::create_group - Rust: `pub fn create_group(&self, name: &str) -> Result` - Dart: `Future createGroup({required String name});` - Needs: nothing. Where: both. Since: r76. Makes a group, named `name`, with this network its home and its one Owner. ### Iceblock::accept_invitation - Rust: `pub fn accept_invitation(&self, link: &str) -> Result` - Dart: `Future acceptGroupInvitation({required String link});` - Needs: nothing. Where: both. Since: r76. Uses an invitation to a group: joins it, or asks to, if it needs approval. ### Iceblock::settings - Rust: `pub fn settings(&self) -> Result` - Dart: `Future setting({required String key, required bool here});` - Needs: nothing. Where: both. Since: r102. The app's settings: made the first time. As an app device of the user's Iceblock, the user's network makes their store, as for [`Iceblock::create_collection`]: this waits for it, syncing. ## Settings ### Settings::get - Rust: `pub fn get(&self, key: &str) -> Option` - Dart: `Future setting({required String key, required bool here});` - Needs: nothing. Where: both. Since: r102. A setting, kept for every device. ### Settings::set - Rust: `pub fn set(&self, key: &str, value: SettingValue) -> Result<()>` - Dart: `Future setSetting({required String key, required SettingValueInfo value, required bool here});` - Needs: nothing. Where: both. Since: r102. Sets a setting for every device. ### Settings::remove - Rust: `pub fn remove(&self, key: &str) -> Result<()>` - Dart: `Future removeSetting({required String key, required bool here});` - Needs: nothing. Where: both. Since: r102. Removes a setting kept for every device. ### Settings::all - Rust: `pub fn all(&self) -> BTreeMap` - Dart: `Future> settings({required bool here});` - Needs: nothing. Where: both. Since: r102. Every setting kept for every device, by key. ### Settings::keys - Rust: `pub fn keys(&self) -> Vec` - Dart: `Future> settings({required bool here});` - Needs: nothing. Where: both. Since: r102. The keys of the settings kept for every device. ### Settings::get_here - Rust: `pub fn get_here(&self, key: &str) -> Option` - Dart: `Future setting({required String key, required bool here});` - Needs: nothing. Where: both. Since: r102. A setting kept for this device alone. ### Settings::set_here - Rust: `pub fn set_here(&self, key: &str, value: SettingValue) -> Result<()>` - Dart: `Future setSetting({required String key, required SettingValueInfo value, required bool here});` - Needs: nothing. Where: both. Since: r102. Sets a setting for this device alone. ### Settings::remove_here - Rust: `pub fn remove_here(&self, key: &str) -> Result<()>` - Dart: `Future removeSetting({required String key, required bool here});` - Needs: nothing. Where: both. Since: r102. Removes a setting kept for this device alone. ### Settings::all_here - Rust: `pub fn all_here(&self) -> BTreeMap` - Dart: `Future> settings({required bool here});` - Needs: nothing. Where: both. Since: r102. Every setting kept for this device alone, by key. ### Settings::watch - Rust: `pub fn watch(&self) -> SettingsWatch` - Dart: `Stream> watchSettings();` - Needs: nothing. Where: both. Since: r102. Watches the settings: each that changes, here or on another of the app's installs, from now on. ## SettingsWatch ### SettingsWatch::changes - Rust: `pub fn changes(&mut self) -> Vec` - Dart: `Stream> watchSettings();` - Needs: nothing. Where: both. Since: r102. The settings changed since the watch was made, or last looked. ### SettingsWatch::wait - Rust: `pub fn wait(&mut self, timeout: Duration) -> Vec` - Dart: `Stream> watchSettings();` - Needs: nothing. Where: both. Since: r102. Waits, up to `timeout`, for a setting to change, and says which. Empty if none did. ## Watch ### Watch::changes - Rust: `pub fn changes(&mut self) -> Vec` - Dart: `Stream> watch({required String collection});` - Needs: nothing. Where: both. Since: r76. What's changed since the watch was made, or last looked: added and changed files, then removed ones, each by path. ### Watch::wait - Rust: `pub fn wait(&mut self, timeout: Duration) -> Vec` - Dart: `Stream> watch({required String collection});` - Needs: nothing. Where: both. Since: r76. Waits, up to `timeout`, for something to change, and says what. Empty if nothing did. ## Types ### Collection (struct) One of the app's Collections. Paths are inside it, `/`-separated, without a leading `/`. ### Entry (struct) A file or a folder, one level down. - `name`: Its name, the last part of its path. - `path`: Its path inside the Collection. - `kind` ### EntryKind (enum) - `File` - `Folder` ### FileInfo (struct) What's known of a file. - `path` - `size`: Its current version's size, in bytes. - `modified_secs`: When its current version was written, in seconds since the epoch, by the writing device's clock as Iceblock keeps it (§13.1). - `writer`: The device that wrote its current version, by its id. In this network, checked: a device below Full trust can write only as itself. In another network, as that network said. - `network`: The network that wrote its current version, by fingerprint, in a Collection held together with other networks (a group's): checked by the Collection's home, which takes each network's versions only signed by it. `None`: the Collection's own network (its home), or a Collection this network keeps alone. - `versions`: How many versions it has. - `here`: Whether all of it is on this device now; otherwise reading it fetches what's missing from the devices holding it. ### Version (struct) One version of a file, oldest first. - `index`: Its index, for [`Collection::read_version`] and [`Collection::restore`]. - `size` - `modified_secs` - `writer` - `network`: As [`FileInfo::network`]. ### JoinAsk (struct) A device asking to join the app's network, through an invitation this device made ([`crate::Iceblock::invite_device`]). - `name`: Its name, as it says. - `fingerprint`: Its fingerprint: the app shows it, and the user checks it's the one the other device shows. ### Role (enum) A member's role in a group, or in one of its Collections. - `Member`: Reads. - `Contributor`: Also adds, changes and deletes files (to the trash). - `Caretaker`: Also makes Collections, invites, and manages members below it. - `Owner`: Everything: deleting Collections, purging the trash, the group. ### Member (struct) A member of a group: a network, one person's. - `network`: The network's fingerprint. - `name`: Its owner's name, as it says. - `role` - `me`: This network. ### MemberPresence (struct) Whether a group's member is around ([`Group::presence`]). - `member` - `state` - `last_used`: When it was last used, and when the group's home last heard from it, coarsened: `None` if not known. - `last_contact` ### Joining (enum) What using an invitation to a group came to. - `Joined`: Joined. - `Asked`: The invitation needs an Owner's or Caretaker's approval: asked, and asked again as the device syncs, until it's answered. The group's id. ### Group (struct) A group this network is in. ### Error (struct) What went wrong, as a sentence for the user or the app's log. ### Config (struct) How the app starts the library. - `data_dir`: The app's own directory for it, private to the app: keys, the store and the metadata go here. - `app_id`: The app's id, the same on every install and platform, in reverse-domain form (`com.example.notes`); on Android, the app's package name, which Iceblock on the same phone checks against the app's signing certificate. The user's Iceblock knows the app by it: its permissions, and its place in the Applications section. - `manifest`: What the app may ask the user's Iceblock for, and what it can't do without: shown to the user when they pair it. - `app_name`: The app's Collection's name, as the user's Iceblock shows it, and the device's owner's name until the user gives one. - `owner_name`: The user's name, if the app knows it: the network is shown as theirs to the other networks it shares with, and groups need it. Without it, [`Iceblock::set_owner_name`] before making or joining a group. - `port`: The port to serve on, TCP and UDP; `None` for any free one. - `link_base`: Where the app's invitation links point, so they open the app rather than Iceblock: an origin only (`https://app.example`), as everything else goes after the `#`, which browsers never send to a server. `None`: Iceblock's website, which opens Iceblock. ### Manifest (struct) What an app may ask the user's Iceblock for ([`Permission`]s, written as `devices`, `wake`, `group-contact:`...), and of those, what it requires. A kind of group permission (`group`, `group-presence`, `group-devices`, `group-contact`) covers it for any group. A Collection's files needn't be listed: an app may always ask for one. - `asks` - `requires` ### LogLine (struct) A line of the library's log, as kept (#800): numbered, so the next ask is for those after it. - `seq` - `secs`: When, in seconds since the epoch. - `level` - `line` ### Presence (struct) Whether the person is around ([`Iceblock::presence`]). - `state`: Their network's, from the most recent use on any device. - `installs`: Each of this app's own installs. ### InstallPresence (struct) One of the app's installs' presence: its device's fingerprint, and when it was last used and heard from (seconds since the epoch, coarsened), where known. - `device` - `this_device` - `last_used` - `last_contact` - `machine_last_used`: When any app built on Iceblock, Iceblock included, was last used on this install's machine, never saying which (#769): with `device-presence` ([`Permission::DevicePresence`]), where Iceblock knows which devices share the machine. `None` otherwise. - `machine_last_active`: When the person was last at this install's computer, from the computer itself (#772): recent input, the session unlocked and the one at the screen, never what was done. With `device-activity` ([`Permission::DeviceActivity`]) in the user's Iceblock; in the app's own network, once it's turned on ([`Iceblock::report_activity`]). Computers only, Linux for now; `None` otherwise. ### Device (struct) One of the network's devices ([`Iceblock::devices`]). - `fingerprint`: Its fingerprint, as the user's Iceblock shows it to compare. - `name` - `this_device`: This device. - `app`: An app device, as this one is in the user's Iceblock. ### Standing (enum) Where this device stands. - `Alone`: A network of its own, of this device alone. - `OwnNetwork`: A network of its own with others: the app on the user's other devices. How many devices, this one included. - `App`: An app device of the user's Iceblock (Scoped trust): holds only the Collections it's been given. ### Status (struct) How it's going. - `standing` - `network_name`: The network's name, as its devices and other networks see it. - `network`: The network's fingerprint: as a group's members and a file's [`FileInfo::network`] name it. - `device`: This device's fingerprint, shown on both devices while pairing. - `device_id`: This device's id, as a file's writer gives it ([`FileInfo::writer`]). - `syncing`: Syncing now. - `serving`: Serving: listening, and syncing with the network's other devices. ### Conditions (struct) What the platform says that the library can't see for itself (Android: `iceblock_platform`'s conditions). `None` for anything it doesn't say, which the library then looks for itself. - `on_vpn` - `metered`: On a metered network: mobile data, a metered Wi-Fi, a hotspot. - `on_power` - `gateway`: The network's IPv4 gateway, its router, to ask for a port forward. - `battery_saver` ### Invitation (struct) An invitation for one of the user's other devices to join the app's network (the app, installed there too): show the link, or its QR code. - `link`: The pairing link, to the Iceblock website's page for it. - `token`: The token alone, as [`Iceblock::join`] takes it too. ### Iceblock (struct) The library, started: one device. Clone it freely; every clone is the same device. ### Settings (struct) The app's settings. ### SettingChange (struct) A setting that changed, here or on another of the app's installs. - `key` - `here`: Kept for this device alone. ### SettingsWatch (struct) Watches the app's settings from when it's made. ### Change (struct) A change to a file in a watched Collection. - `path` - `kind` ### ChangeKind (enum) - `Added`: A new file, or one back from the trash. - `Changed`: A new version of a file. - `Removed`: Deleted, or moved away (a move is a removal and an addition). ### Watch (struct) Watches a Collection from when it's made: [`Watch::changes`] says what's changed since it last looked.