Struct HostContext 

pub struct HostContext { /* private fields */ }

Explicit identity, authority and storage. Apps receive no ambient profile resolver.

Implementations

impl HostContext

pub fn reopener(&self) -> Reopener

What the component needs to open another record of its app in its window later (Reopener).

pub fn prepare( definition: &ApplicationDefinition, inputs: HostContextInputs, target: &LaunchTarget, ) -> Result<HostContext, LaunchError>

Reserve New or open Existing before the factory, using only supplied identities.

Errors

Rejects denied authority, invalid/foreign namespaces and unavailable records.

pub fn prepare_new_record( definition: &ApplicationDefinition, inputs: HostContextInputs, record_id: RecordId, ) -> Result<HostContext, LaunchError>

Reserve a host-named new record through the same checked construction path. Useful for a workspace’s default document, whose identity must survive a restart even before the first local View has been saved. Existing records are never adopted or reinitialized by this operation.

Errors

Rejects foreign namespaces, denied authority and occupied identities.

pub fn write_as_author(&mut self)

Commit this instance’s edits to its record under an actor of its author’s own (crate::record::author_writer) rather than the record’s writer, which every instance sharing the record’s store writes as. For a host that mounts several authors on one store (a page’s mounts of one profile and device), so history can tell whose edit each change is. The record’s writer, which the store persists, is unchanged, as is everything written outside the instance.

pub fn provide_content(&mut self, store: ContentStore)

Lend the component the host’s content store for this storage scope: opaque bytes addressed by hash that outlive the component and that other components of the same scope read too.

pub fn content(&self) -> Option<&ContentStore>

The content store the host lent, if any.

pub fn provide_open_file(&mut self, file: OpenFile)

Hand the component a file to open. ApplicationDefinition::instantiate refuses the launch unless the definition opens its media type.

pub fn take_open_file(&mut self) -> Option<OpenFile>

The file the host handed over to open, once.

pub fn provide_capture(&mut self, capture: Capture)

Prepare the instance for a screenshot of capture instead of a window someone uses.

pub fn capture(&self) -> Option<&Capture>

The screenshot this instance is prepared for, if it is one.

pub fn provide_launch_arguments(&mut self, arguments: Vec<String>)

Hand the component what its launch named besides a file: the arguments of a command line or an “open with” (paths, URLs), in order. The host has already checked how many the component accepts.

pub fn take_launch_arguments(&mut self) -> Vec<String>

The launch arguments the host handed over, once.

pub fn provide_handoff(&mut self, handoff: PlaybackHandoff)

Hand the component the playback another device or app handed over with the media its launch names.

pub fn take_handoff(&mut self) -> Option<PlaybackHandoff>

The playback handoff the host handed over, once.

pub fn lend<T>(&mut self, service: T)

where T: Any,

Lend the component a service of the host that mounts it in its own process: a connection to the session’s process supervisor for a terminal the shell hosts. The component takes it by type; a host that lends nothing leaves the app on its own services.

pub fn take_lent(&mut self) -> Vec<Box<dyn Any>>

The services the host lent, once.

pub fn provide_launch_options(&mut self, options: Vec<LaunchOption>)

Hand the component the options of its own that its launch named (--purpose number). The host has already checked that the component takes each of them.

pub fn take_launch_options(&mut self) -> Vec<LaunchOption>

The launch options the host handed over, once.

pub fn provide_private(&mut self)

Prepare the instance as a private window: its profile is thrown away with the process, and nothing it shows reaches the person’s other windows, devices or collaborators.

pub fn is_private(&self) -> bool

Whether the instance is a private window.

pub fn control_domain(&self) -> ControlDomain

Explicit owner-bound producer capability, available before factory work.

pub fn record(&self) -> &RecordCheckout

pub fn app_id(&self) -> &str

The application this context was prepared for.

pub fn author(&self) -> &UserId

pub fn permissions(&self) -> PermissionContext

A snapshot of the participant’s permissions at this moment.

pub fn live_permissions(&self) -> LivePermissions

The participant’s permissions as they change while the component runs (a role change, a revoked share). Components that present themselves read-only hold this instead of deciding once at launch.

pub fn action_context(&self) -> &ActionContext

pub fn wake_handle(&self) -> WakeHandle

pub fn services(&self) -> &HostServices

The host services this component was prepared under — the ones crate::host::current resolved when the host prepared it.

pub fn secrets(&self) -> SecretStore

This app’s secrets, in the store its host provides: the system’s (the Secret Service, the Keychain, the browser’s wrapped store) or a host’s own. Other apps’ secrets are out of reach.

pub fn files(&self) -> AppFiles

This app’s private file areas (data, config, cache, state): the per-user directories natively, the origin-private file system in a page. See crate::storage for what belongs where.

pub fn settings<T>(&self) -> Settings<T>

where T: SettingsSchema,

This app’s typed settings of type T, in the settings document the host gave it (Self::provide_settings); T declares how far they travel.

pub fn storage(&self) -> AppStorage

This app’s files, secrets and settings in one handle, as framework views and surfaces receive them.

pub fn provide_settings(&mut self, document: SettingsDocument)

Give the component this settings document instead of the person’s session document: a test or capture profile’s own.

pub fn provide_files(&mut self, files: AppFiles)

Give the component these file areas instead of the person’s: a test or capture profile’s own, so nothing it writes lands in theirs.

pub fn provide_person_records(&mut self, records: PersonRecords)

Give the component the person’s own records of this app (crate::record::person), kept beside the record it shows.

pub fn device_id(&self) -> &str

This device, as the host names it: stable across launches of the app on it, distinct on each of the person’s devices.

pub fn person_records(&self) -> Option<&PersonRecords>

The person’s own records of this app, when the host keeps them.

pub fn migrate_record( &self, migrate: impl FnOnce(&mut AutoCommit) -> Result<bool, String>, ) -> Result<bool, String>

Bring the record up to the storage version its app reads, before it is read: migrate makes at most one deterministic housekeeping change (two devices migrating the same document make the same one) and answers whether it changed anything.

Errors

The record is not open here, or the migration failed.

pub fn read_record<R>( &self, read: impl FnOnce(&AutoCommit) -> R, ) -> Result<R, RecordOpenError>

Read/project an existing or initialized document. No untracked sync mutation.

Errors

A reserved or missing record cannot be read.

pub fn merge_peer_document(&self, document: Vec<u8>) -> Result<bool, String>

Merge another participant’s copy of the record, as their changes arriving over sync are merged: validated first, attributed to them in history, and never on this participant’s undo stack. Returns whether anything changed.

Errors

The document is not a valid copy of this record, or it is not open.

pub fn initialize_new_record( &mut self, initialize: impl FnOnce(&mut AutoCommit) -> Result<(), String>, ) -> Result<(), RecordOpenError>

The unique owner transition from Reserved to Ready. Existing is never initialized.

Errors

Refuses repeated initialization and preserves the reservation on schema/storage failure.

pub fn initialize_new_record_seeded( &mut self, initialize: impl FnOnce(&mut AutoCommit) -> Result<(), String>, seed: impl FnOnce(&mut AutoCommit) -> Result<(), String>, ) -> Result<(), RecordOpenError>

Self::initialize_new_record, then seed the record as this author on this device. The genesis initialize writes is the same on every device; the seed is what depends on who creates the record or where, and is nobody’s undo step. See RecordReservation::initialize_seeded.

Errors

As Self::initialize_new_record; a failing seed fails it too.

pub fn creation_workspace(&self) -> Option<&CreationWorkspace>

The host-derived original creation scope, absent on every ordinary restore.

Trait Implementations

impl Drop for HostContext

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.