Class Swarm

Manages communication with other peers.

Inheritance

Object

Swarm

Implements

IService

Inherited Members

Object.Equals(Object)

Object.Equals(Object, Object)

Object.GetHashCode()

Object.GetType()

Object.MemberwiseClone()

Object.ReferenceEquals(Object, Object)

Object.ToString()

Namespace: PeerTalk

Assembly: PeerTalk.dll

Syntax

public class Swarm : IService, IPolicy<MultiAddress>, IPolicy<Peer>

Fields

Manager

Manages the swarm's peer connections.

Declaration

public ConnectionManager Manager

Field Value

Type	Description
ConnectionManager

TransportConnectionTimeout

The time to wait for a low level connection to be established.

Declaration

public TimeSpan TransportConnectionTimeout

Field Value

Type	Description
TimeSpan	Defaults to 30 seconds.

Properties

BlackList

The addresses that cannot be used.

Declaration

public MultiAddressBlackList BlackList { get; set; }

Property Value

Type	Description
MultiAddressBlackList

IsRunning

Determines if the swarm has been started.

Declaration

public bool IsRunning { get; }

Property Value

Type	Description
Boolean	true if the swarm has started; otherwise, false.

See Also

StartAsync()

StopAsync()

KnownPeerAddresses

Get the sequence of all known peer addresses.

Declaration

public IEnumerable<MultiAddress> KnownPeerAddresses { get; }

Property Value

Type	Description
IEnumerable<MultiAddress>	Contains any peer address that has been RegisterPeerAddress(MultiAddress).

See Also

RegisterPeerAddress(MultiAddress)

KnownPeers

Get the sequence of all known peers.

Declaration

public IEnumerable<Peer> KnownPeers { get; }

Property Value

Type	Description
IEnumerable<Peer>	Contains any peer that has been RegisterPeerAddress(MultiAddress).

See Also

RegisterPeerAddress(MultiAddress)

LocalPeer

The local peer.

Declaration

public Peer LocalPeer { get; set; }

Property Value

Type	Description
Peer	The local peer must have an Id and PublicKey.

LocalPeerKey

The private key of the local peer.

Declaration

public Key LocalPeerKey { get; set; }

Property Value

Type	Description
Key	Used to prove the identity of the LocalPeer.

NetworkProtector

Provides access to a private network of peers.

Declaration

public INetworkProtector NetworkProtector { get; set; }

Property Value

Type	Description
INetworkProtector

Router

Use to find addresses of a peer.

Declaration

public IPeerRouting Router { get; set; }

Property Value

Type	Description
IPeerRouting

WhiteList

The addresses that can be used.

Declaration

public MultiAddressWhiteList WhiteList { get; set; }

Property Value

Type	Description
MultiAddressWhiteList

Methods

AddProtocol(IPeerProtocol)

Add a protocol that is supported by the swarm.

Declaration

public void AddProtocol(IPeerProtocol protocol)

Parameters

Type	Name	Description
IPeerProtocol	protocol	The protocol to add.

ConnectAsync(MultiAddress, CancellationToken)

Connect to a peer using the specified MultiAddress.

Declaration

public Task<PeerConnection> ConnectAsync(MultiAddress address, CancellationToken cancel = default(CancellationToken))

Parameters

Type	Name	Description
MultiAddress	address	An ipfs MultiAddress, such as /ip4/104.131.131.82/tcp/4001/ipfs/QmaCpDMGvV2BGHeYERUEnRQAwe3N8SzbUtfsmvsqQLuvuJ.
CancellationToken	cancel	Is used to stop the task. When cancelled, the TaskCanceledException is raised.

Returns

Type	Description
Task<PeerConnection>	A task that represents the asynchronous operation. The task's result is the PeerConnection.

Remarks

If already connected to the peer and is active on any address, then the existing connection is returned.

ConnectAsync(Peer, CancellationToken)

Connect to a peer.

Declaration

public Task<PeerConnection> ConnectAsync(Peer peer, CancellationToken cancel = default(CancellationToken))

Parameters

Type	Name	Description
Peer	peer	A peer to connect to.
CancellationToken	cancel	Is used to stop the task. When cancelled, the TaskCanceledException is raised.

Returns

Type	Description
Task<PeerConnection>	A task that represents the asynchronous operation. The task's result is the PeerConnection.

Remarks

If already connected to the peer and is active on any address, then the existing connection is returned.

DeregisterPeer(Peer)

Deregister a peer.

Declaration

public void DeregisterPeer(Peer peer)

Parameters

Type	Name	Description
Peer	peer	The peer to remove..

Remarks

Remove all knowledge of the peer. The PeerRemoved event is raised.

DialAsync(Peer, String, CancellationToken)

Create a stream to the peer that talks the specified protocol.

Declaration

public Task<Stream> DialAsync(Peer peer, string protocol, CancellationToken cancel = default(CancellationToken))

Parameters

Type	Name	Description
Peer	peer	The remote peer.
String	protocol	The protocol name, such as "/foo/0.42.0".
CancellationToken	cancel	Is used to stop the task. When cancelled, the TaskCanceledException is raised.

Returns

Type	Description
Task<Stream>	A task that represents the asynchronous operation. The task's result is the new Stream to the peer.

Remarks

When finished, the caller must Dispose() the new stream.

DisconnectAsync(MultiAddress, CancellationToken)

Disconnect from a peer.

Declaration

public Task DisconnectAsync(MultiAddress address, CancellationToken cancel = default(CancellationToken))

Parameters

Type	Name	Description
MultiAddress	address	An ipfs MultiAddress, such as /ip4/104.131.131.82/tcp/4001/ipfs/QmaCpDMGvV2BGHeYERUEnRQAwe3N8SzbUtfsmvsqQLuvuJ.
CancellationToken	cancel	Is used to stop the task. When cancelled, the TaskCanceledException is raised.

Returns

Type	Description
Task	A task that represents the asynchronous operation.

Remarks

If the peer is not conected, then nothing happens.

HasPendingConnection(Peer)

Determines if a connection is being made to the peer.

Declaration

public bool HasPendingConnection(Peer peer)

Parameters

Type	Name	Description
Peer	peer	A Peer.

Returns

Type	Description
Boolean	true is the peer has a pending connection.

IsAllowed(MultiAddress)

Declaration

public bool IsAllowed(MultiAddress target)

Parameters

Type	Name	Description
MultiAddress	target

Returns

Type	Description
Boolean

IsAllowed(Peer)

Declaration

public bool IsAllowed(Peer peer)

Parameters

Type	Name	Description
Peer	peer

Returns

Type	Description
Boolean

RegisterPeer(Peer)

Register that a peer has been discovered.

Declaration

public Peer RegisterPeer(Peer peer)

Parameters

Type	Name	Description
Peer	peer	The newly discovered peer.

Returns

Type	Description
Peer	The registered peer.

Remarks

If the peer already exists, then the existing peer is updated with supplied information and is then returned. Otherwise, the peer is added to known peers and is returned.

If the peer already exists, then a union of the existing and new addresses is used. For all other information the peer's information is used if not null.

If peer does not already exist, then the PeerDiscovered event is raised.

Exceptions

Type	Condition
Exception	The BlackList or WhiteList policies forbid it.

RegisterPeerAddress(MultiAddress)

Register that a peer's address has been discovered.

Declaration

public Peer RegisterPeerAddress(MultiAddress address)

Parameters

Type	Name	Description
MultiAddress	address	An address to the peer. It must end with the peer ID.

Returns

Type	Description
Peer	The Peer that is registered.

Remarks

If the address is not already known, then it is added to the KnownPeerAddresses.

Exceptions

Type	Condition
Exception	The BlackList or WhiteList policies forbid it. Or the "p2p/ipfs" protocol name is missing.

See Also

RegisterPeer(Peer)

RemoveProtocol(IPeerProtocol)

Remove a protocol from the swarm.

Declaration

public void RemoveProtocol(IPeerProtocol protocol)

Parameters

Type	Name	Description
IPeerProtocol	protocol	The protocol to remove.

StartAsync()

Start the service.

Declaration

public Task StartAsync()

Returns

Type	Description
Task

StartListeningAsync(MultiAddress)

Start listening on the specified MultiAddress.

Declaration

public Task<MultiAddress> StartListeningAsync(MultiAddress address)

Parameters

Type	Name	Description
MultiAddress	address	Typically "/ip4/0.0.0.0/tcp/4001" or "/ip6/::/tcp/4001".

Returns

Type	Description
Task<MultiAddress>	A task that represents the asynchronous operation. The task's result is a MultiAddress than can be used by another peer to connect to tis peer.

Remarks

Allows other peers to ConnectAsync(MultiAddress, CancellationToken) to the address.

The Addresses of the LocalPeer are updated. If the address refers to any IP address ("/ip4/0.0.0.0" or "/ip6/::") then all network interfaces addresses are added. If the port is zero (as in "/ip6/::/tcp/0"), then the peer addresses contains the actual port number that was assigned.

Exceptions

Type	Condition
Exception	Already listening on address.
ArgumentException	address is missing a transport protocol (such as tcp or udp).

StopAsync()

Stop the service.

Declaration

public Task StopAsync()

Returns

Type	Description
Task

StopListeningAsync(MultiAddress)

Stop listening on the specified MultiAddress.

Declaration

public Task StopListeningAsync(MultiAddress address)

Parameters

Type	Name	Description
MultiAddress	address

Returns

Type	Description
Task	A task that represents the asynchronous operation.

Remarks

Allows other peers to ConnectAsync(MultiAddress, CancellationToken) to the address.

The addresses of the LocalPeer are updated.

Events

ConnectionEstablished

Raised when a connection to another peer is established.

Declaration

public event EventHandler<PeerConnection> ConnectionEstablished

Event Type

Type	Description
EventHandler<PeerConnection>

ListenerEstablished

Raised when a listener is establihed.

Declaration

public event EventHandler<Peer> ListenerEstablished

Event Type

Type	Description
EventHandler<Peer>

Remarks

Raised when StartListeningAsync(MultiAddress) succeeds.

PeerDisconnected

Raised when a peer's connection is closed.

Declaration

public event EventHandler<Peer> PeerDisconnected

Event Type

Type	Description
EventHandler<Peer>

PeerDiscovered

Raised when a new peer is discovered for the first time.

Declaration

public event EventHandler<Peer> PeerDiscovered

Event Type

Type	Description
EventHandler<Peer>

PeerNotReachable

Raised when a peer cannot be connected to.

Declaration

public event EventHandler<Peer> PeerNotReachable

Event Type

Type	Description
EventHandler<Peer>

PeerRemoved

Raised when a peer should no longer be used.

Declaration

public event EventHandler<Peer> PeerRemoved

Event Type

Type	Description
EventHandler<Peer>

Remarks

This event indicates that the peer has been removed from the KnownPeers and should no longer be used.

Implements

IService