PeerControl class
The peers of a session: every participant, devices and applications alike, this process
included. Reached through Session.Peers.
Namespace: Quaternar.Qaros · Assembly: Quaternar.Qaros.dll
public sealed class PeerControl
Remarks
Peers join, change and leave asynchronously, so PeerControl.GetAll is a snapshot of what
this session knows at that moment. To react to changes, subscribe with
PeerControl.SubscribeUpdates.
Methods
| Member | Description |
|---|---|
| GetMySpec() | This process' own peer, for example to learn its peer id. |
| GetAll() | Every peer this session knows now, this process' own included (see PeerControl.GetMySpec). |
| UpdateDisplayName(string) | Changes the display name other peers see for this process; any UTF-8. |
| SubscribeUpdates() | Starts delivering peer updates to PeerControl.Updated until the returned subscription is disposed. |
| SubscribeUpdates(CancellationToken) | Starts delivering peer updates to PeerControl.Updated until the returned subscription is disposed or cancellationToken is canceled. |
| SubscribeUpdates(EventHandler<PeerSpecUpdatedEventArgs>) | Calls handler for every peer that joins, leaves or changes its presentation or app state, until the returned subscription is disposed. The way to learn that an invited target app joined and reached AppState.Running. |
| SubscribeUpdates(EventHandler<PeerSpecUpdatedEventArgs>, CancellationToken) | PeerControl.SubscribeUpdates that also ends when cancellationToken is canceled. Still dispose the subscription. |
| WatchUpdatesAsync(CancellationToken) | Peer updates as an async stream, buffered in arrival order, until cancellationToken is canceled or the enumeration is abandoned. |
GetMySpec
This process' own peer, for example to learn its peer id.
public Result<PeerSpec> GetMySpec()
GetAll
Every peer this session knows now, this process' own included (see
PeerControl.GetMySpec).
public Result<PeerSpec[]> GetAll()
UpdateDisplayName
Changes the display name other peers see for this process; any UTF-8.
public Result<Unit> UpdateDisplayName(string name)
Parameters
| Name | Type | Description |
|---|---|---|
name | string |
SubscribeUpdates()
Starts delivering peer updates to PeerControl.Updated until the returned subscription is
disposed.
public Result<IDisposable> SubscribeUpdates()
Returns: Result<IDisposable>
SubscribeUpdates(CancellationToken)
Starts delivering peer updates to PeerControl.Updated until the returned subscription is
disposed or cancellationToken is canceled.
public Result<IDisposable> SubscribeUpdates(CancellationToken cancellationToken)
Parameters
| Name | Type | Description |
|---|---|---|
cancellationToken | CancellationToken |
Returns: Result<IDisposable>
SubscribeUpdates(EventHandler<PeerSpecUpdatedEventArgs>)
Calls handler for every peer that joins, leaves or changes its
presentation or app state, until the returned subscription is disposed. The way to learn
that an invited target app joined and reached AppState.Running.
public Result<IDisposable> SubscribeUpdates(EventHandler<PeerSpecUpdatedEventArgs> handler)
Parameters
| Name | Type | Description |
|---|---|---|
handler | EventHandler<PeerSpecUpdatedEventArgs> |
Returns: Result<IDisposable>
Remarks
The handler runs on a library thread: marshal to your own thread before touching single-threaded state, and do not make blocking QAROS calls from it. An exception it throws is swallowed.
When Dispose of the subscription returns, a handler call running on another thread
has finished and no further one starts. Disposing from inside the handler returns at once.
Never dispose while holding a lock the handler takes: that deadlocks.
SubscribeUpdates(EventHandler<PeerSpecUpdatedEventArgs>, CancellationToken)
PeerControl.SubscribeUpdates that also ends
when cancellationToken is canceled. Still dispose the subscription.
public Result<IDisposable> SubscribeUpdates(EventHandler<PeerSpecUpdatedEventArgs> handler, CancellationToken cancellationToken)
Parameters
| Name | Type | Description |
|---|---|---|
handler | EventHandler<PeerSpecUpdatedEventArgs> | |
cancellationToken | CancellationToken |
Returns: Result<IDisposable>
WatchUpdatesAsync
Peer updates as an async stream, buffered in arrival order, until
cancellationToken is canceled or the enumeration is abandoned.
public IAsyncEnumerable<PeerSpec> WatchUpdatesAsync(CancellationToken cancellationToken = default)
Parameters
| Name | Type | Description |
|---|---|---|
cancellationToken | CancellationToken |
Returns: IAsyncEnumerable<PeerSpec>
Exceptions
| Exception | Condition |
|---|---|
| NativeCallException | The subscription could not be started. |
Events
Updated
Raised for every peer update, but only while a subscription from
PeerControl.SubscribeUpdates or PeerControl.SubscribeUpdates is
alive: attaching a handler alone delivers nothing.
public event EventHandler<PeerSpecUpdatedEventArgs>? Updated
Event type: EventHandler<PeerSpecUpdatedEventArgs>
Remarks
Raised on a library thread, like every subscription handler.