Session class

An active session, the entry point to peers, GUI panels, app volumes and senders. Only Runtime.Onboard and Runtime.Rejoin produce one, and there is no getter for a "current" session: keep the instance.

Namespace: Quaternar.Qaros · Assembly: Quaternar.Qaros.dll

public sealed class Session : IDisposable

Implements: IDisposable

Remarks

The caller owns the session. Session.Dispose tears the session down but keeps the persisted identity, so the next start can Runtime.Rejoin silently; erasing the identity is Runtime.Forget. Disposing ends every subscription of the session and waits for a handler running on another thread, so never dispose it from a QAROS callback or event handler, nor while holding a lock a handler takes.

Properties

Member	Description
Peers
GuiPanels
AppVolumes
RenderSenders
PrimarylessVideoSenders

Peers

public PeerControl Peers { get; }

Value: PeerControl

GuiPanels

public GuiPanelControl GuiPanels { get; }

Value: GuiPanelControl

AppVolumes

public AppVolumeControl AppVolumes { get; }

Value: AppVolumeControl

RenderSenders

public RenderSenderControl RenderSenders { get; }

Value: RenderSenderControl

PrimarylessVideoSenders

public PrimarylessVideoSenderControl PrimarylessVideoSenders { get; }

Value: PrimarylessVideoSenderControl

Methods

Member	Description
GetId()
GetGraphicsDeviceId()	The GPU adapter the session's graphics devices were created on, or null when it is not known. It is the one OnboardOptions.WithGraphicsDevice named, else the one QAROS selected for an app it launched, else the one the library picked. Create your own graphics device on it so the frames you render need no cross-GPU copy.
RequestOnboardingInvite(RequestOnboardingInviteOptions?, IProgress<ActionProgress>?, CancellationToken)	Asks the hub this session onboarded through for a fresh invite, to onboard another API instance (a helper process, a plugin sandbox) without a code. Blocks until the hub answers.
RequestOnboardingCodes(RequestOnboardingCodesOptions?, IProgress<ActionProgress>?, CancellationToken)	Ask the hub for a new set of one-time onboarding codes, for several devices to onboard at once. Codes other callers hold and the hub's onboarding screen code stay valid. The caller owns and disposes every returned invite.
RequestOnboardingInviteAsync(RequestOnboardingInviteOptions?, IProgress<ActionProgress>?, CancellationToken)	Async Session.RequestOnboardingInvite. Canceling cancellationToken cancels the task.
FindRenderTarget(string)	Finds an already-connected render target from its connection string.
InviteTargetApp(string, IProgress<ActionProgress>?, CancellationToken)	Asks this machine's hub to start the target app for one AR device and returns the target app's peer id once its peer joined the session - the id a render sender renders for. Build connectionString with TargetAppConnectionString; a malformed one or a device kind that cannot be invited fails with StatusCode.ArgumentNotSupported.
InviteTargetAppAsync(string, IProgress<ActionProgress>?, CancellationToken)	Async Session.InviteTargetApp.
KillTargetApp(PeerId, IProgress<ActionProgress>?, CancellationToken)	Asks this machine's hub to stop a target app it started, with the whole pipeline feeding it. A target app this hub did not start ends in StatusCode.Timeout.
KillTargetAppAsync(PeerId, IProgress<ActionProgress>?, CancellationToken)	Async Session.KillTargetApp.
Dispose()	Tears the session down but keeps its persisted identity for a later Runtime.Rejoin. Waits for subscription handlers running on other threads; do not call it from one.

GetId

public Result<SessionId> GetId()

Returns: Result<SessionId>

GetGraphicsDeviceId

The GPU adapter the session's graphics devices were created on, or null when it is not known. It is the one OnboardOptions.WithGraphicsDevice named, else the one QAROS selected for an app it launched, else the one the library picked. Create your own graphics device on it so the frames you render need no cross-GPU copy.

public Result<GraphicsDeviceId?> GetGraphicsDeviceId()

Returns: Result<GraphicsDeviceId>

RequestOnboardingInvite

Asks the hub this session onboarded through for a fresh invite, to onboard another API instance (a helper process, a plugin sandbox) without a code. Blocks until the hub answers.

public Result<OnboardingInvite> RequestOnboardingInvite(RequestOnboardingInviteOptions? options = null, IProgress<ActionProgress>? progress = null, CancellationToken cancellationToken = default)

Parameters

Name	Type	Description
options	RequestOnboardingInviteOptions
progress	IProgress<ActionProgress>
cancellationToken	CancellationToken

Returns: Result<OnboardingInvite>

Remarks

The caller owns and disposes the invite. Hand it over with OnboardingInvite.Serialize; the other instance, with a runtime and storage folder of its own, onboards with OnboardingInvite.Deserialize and OnboardOptions.UseInvite. Invites expire: mint one when it is needed. Fails with StatusCode.ArgumentNotSupported when the hub cannot be resolved from this session, for example while it is not connected.

RequestOnboardingCodes

Ask the hub for a new set of one-time onboarding codes, for several devices to onboard at once. Codes other callers hold and the hub's onboarding screen code stay valid. The caller owns and disposes every returned invite.

public Result<IReadOnlyList<OnboardingInvite>> RequestOnboardingCodes(RequestOnboardingCodesOptions? options = null, IProgress<ActionProgress>? progress = null, CancellationToken cancellationToken = default)

Parameters

Name	Type	Description
options	RequestOnboardingCodesOptions
progress	IProgress<ActionProgress>
cancellationToken	CancellationToken

Returns: Result<IReadOnlyList<OnboardingInvite>>

Remarks

Blocks until the hub answers. Each code works once (a failed attempt also uses it up) and is never shown on the hub's screen. Hand a device either its text (OnboardingInvite.GetCode, for OnboardOptions.UseCode) or the serialized invite (for OnboardOptions.UseInvite). Fails with StatusCode.ArgumentNotSupported for a count or lifetime out of range, or when the hub cannot be resolved from this session.

RequestOnboardingInviteAsync

Async Session.RequestOnboardingInvite. Canceling cancellationToken cancels the task.

public Task<Result<OnboardingInvite>> RequestOnboardingInviteAsync(RequestOnboardingInviteOptions? options = null, IProgress<ActionProgress>? progress = null, CancellationToken cancellationToken = default)

Parameters

Name	Type	Description
options	RequestOnboardingInviteOptions
progress	IProgress<ActionProgress>
cancellationToken	CancellationToken

Returns: Task<Result<OnboardingInvite>>

FindRenderTarget

Finds an already-connected render target from its connection string.

public Result<PeerId> FindRenderTarget(string connection)

Parameters

Name	Type	Description
connection	string

Returns: Result<PeerId>

Remarks

Takes the strings TargetAppConnectionString builds. It only looks at the peers this session knows now: it neither invites nor waits, and fails with StatusCode.ArgumentNotSupported when no peer matches. To start a target app, use Session.InviteTargetApp.

InviteTargetApp

Asks this machine's hub to start the target app for one AR device and returns the target app's peer id once its peer joined the session - the id a render sender renders for. Build connectionString with TargetAppConnectionString; a malformed one or a device kind that cannot be invited fails with StatusCode.ArgumentNotSupported.

public Result<PeerId> InviteTargetApp(string connectionString, IProgress<ActionProgress>? progress = null, CancellationToken cancellationToken = default)

Parameters

Name	Type	Description
connectionString	string
progress	IProgress<ActionProgress>
cancellationToken	CancellationToken

Returns: Result<PeerId>

InviteTargetAppAsync

Async Session.InviteTargetApp.

public Task<Result<PeerId>> InviteTargetAppAsync(string connectionString, IProgress<ActionProgress>? progress = null, CancellationToken cancellationToken = default)

Parameters

Name	Type	Description
connectionString	string
progress	IProgress<ActionProgress>
cancellationToken	CancellationToken

Returns: Task<Result<PeerId>>

KillTargetApp

Asks this machine's hub to stop a target app it started, with the whole pipeline feeding it. A target app this hub did not start ends in StatusCode.Timeout.

public Result<Unit> KillTargetApp(PeerId targetApp, IProgress<ActionProgress>? progress = null, CancellationToken cancellationToken = default)

Parameters

Name	Type	Description
targetApp	PeerId
progress	IProgress<ActionProgress>
cancellationToken	CancellationToken

Returns: Result<Unit>

KillTargetAppAsync

Async Session.KillTargetApp.

public Task<Result<Unit>> KillTargetAppAsync(PeerId targetApp, IProgress<ActionProgress>? progress = null, CancellationToken cancellationToken = default)

Parameters

Name	Type	Description
targetApp	PeerId
progress	IProgress<ActionProgress>
cancellationToken	CancellationToken

Returns: Task<Result<Unit>>

Dispose

Tears the session down but keeps its persisted identity for a later Runtime.Rejoin. Waits for subscription handlers running on other threads; do not call it from one.

public void Dispose()