Pool How-To
While the API Reference is fairly thorough, it does not do much
in the way of describing the important events dispatched to
Pool.events
. This section will describe what events are
used, what data they receive, and so on. These events will be
important if you want to make effective use of RTCPool, so be
sure to make note of this content!
join
This event is dispatched when the Pool()
has successfully
connected to the pool on the server-side. Before this event is fired,
no connections are available, and attempting to create media with the
it will not work. If you wish to add media to a stream ASAP, wait until
this event has been fired and then do so. For example, do this:
const pool = new rtcpool.Pool({ /* TURN/STUN config */ }, signaller);
let media;
pool.events.onjoin = () => {
media = new rtcpool.media.ManagedStream(someMediaStream, pool);
};
NOT this:
const pool = new rtcpool.Pool({ /* TURN/STUN config */ }, signaller);
let media = new rtcpool.media.ManagedStream(someMediaStream, pool);
close
This event is dispatched when either another peer has closed, or when
this peer has been instructed to close. This event will be fired even
when Pool.close()
is called, so be aware. The connection that was
closed can be accessed in event.detail, as such:
pool.events.onclose = event => {
console.log("Closed connection to", event.detail);
};
If event.detail is null
, this indicates that this endpoint was the
peer that was closed.
stop
Like the close event, but called when the server force-closes the pool. event.detail will always be null.
Warning
In RTCPool 3.0.0, assigning Pool.events.onstop will NOT work. This
will be patched in version 3.0.1. For this event, it is best to simply
use addEventListener
.
peer
This event is dispatched when a new peer has joined the pool. The
ManagedConnection()
may be accessed in event.detail.connection
.
pool.events.onpeer = event => {
const peer = event.detail.connection;
console.log("I have a new friend! His name is " + peer.id);
};
describe
This event is dispatched when a peer’s description is changed.
Both the peer’s ManagedConnection()
and the description object
are included in event.detail
, as event.detail.connection
and
event.detail.description
respectively. Example:
pool.events.ondescribe = event => {
const { connection, description } = event.detail;
console.log("My friend " + connection.id + " got a car. It is a " + description.car);
};
Note
Recall that descriptions are arbitrary, so do not depend on data that might not be present. It is up to the developer how descriptions will be used and what information they will contain.