webrtc_dcep (webrtc v0.1.0)

View Source

WebRTC data channels: the Data Channel Establishment Protocol (RFC 8832) and the data channel rules of RFC 8831 on top of webrtc_sctp_assoc.

The manager owns the SCTP association and is a sans-IO engine with the same contract: handle_packet/3, handle_timeout/2 and next_timeout/1 return {State, Actions} where actions are {send, Bin} (DTLS application data) and {event, Event}.

Events:

- {connected, Info}: the SCTP association is up (see webrtc_sctp_assoc). - {channel_open, Id, Label, Protocol, Opts}: a channel is usable, either opened by the peer with DATA_CHANNEL_OPEN, or created locally (sent once the association is up). Opts holds ordered, max_retransmits or max_packet_life_time when set, priority, negotiated and initiator (local or remote). - {channel_message, Id, text | binary, Data}. - {channel_closed, Id}: both directions of the stream were reset (RFC 8831 §6.7), the id can be reused. - {buffered_amount_low, Id}. - {channel_error, Id, message_too_large}: the peer sent a message over our max-message-size; the channel is being closed. - {closed, Reason} and {restarted, Info} from the association; every channel is reported closed first.

Options of new/1: role (client or server, the DTLS role, which selects even or odd stream ids, RFC 8832 §6, required), max_message_size (the peer's SDP max-message-size, RFC 8841 §6; 0 means no limit, default 65536), sctp (options of webrtc_sctp_assoc:new/1; its max_message_size bounds incoming messages).

Summary

Functions

Channels that opened and that closed so far.

Channels by id with their label, state and options.

Close a channel by resetting its outgoing stream (RFC 8831 §6.7).

Create a channel. Without negotiated a DATA_CHANNEL_OPEN is sent on a stream id of our parity; with negotiated => true the application agreed on id out of band and no DCEP message is used.

The lower layer moved to another path (see webrtc_sctp_assoc:path_changed/2).

The class of the highest priority among the channels not being closed (RFC 8831 §6.4): the association's DSCP (RFC 8837 §5).

Restart the association's congestion control: its DSCP changed (RFC 8837 §5).

Send a text (UTF-8) or binary message. Empty messages use the "empty" PPIDs and one zero byte (RFC 8831 §6.6).

Types

action/0

-type action() :: {send, binary()} | {event, term()}.

channel_opts/0

-type channel_opts() ::
          #{ordered => boolean(),
            max_retransmits => non_neg_integer(),
            max_packet_life_time => non_neg_integer(),
            priority => 0..65535 | very_low | low | medium | high,
            protocol => binary(),
            negotiated => boolean(),
            id => 0..65534}.

dcep/0

-opaque dcep()

message/0

-type message() ::
          {open,
           #{ordered := boolean(),
             reliability :=
                 reliable | {max_retransmits, 0..4294967295} | {max_packet_life_time, 0..4294967295},
             priority := 0..65535,
             label := binary(),
             protocol := binary()}} |
          ack.

Functions

buffered_amount(Id, Dc)

-spec buffered_amount(0..65534, dcep()) -> non_neg_integer().

channel_counts(Dc)

-spec channel_counts(dcep()) -> #{opened := non_neg_integer(), closed := non_neg_integer()}.

Channels that opened and that closed so far.

channels(Dc)

-spec channels(dcep()) -> #{0..65534 => map()}.

Channels by id with their label, state and options.

close_channel(Id, Now, Dc)

-spec close_channel(0..65534, integer(), dcep()) -> {ok, dcep(), [action()]} | {error, atom()}.

Close a channel by resetting its outgoing stream (RFC 8831 §6.7).

connect(Now, Dc)

-spec connect(integer(), dcep()) -> {dcep(), [action()]}.

decode(_)

-spec decode(binary()) -> {ok, message()} | {error, term()}.

encode(_)

-spec encode(message()) -> binary().

handle_packet(Bin, Now, Dc)

-spec handle_packet(binary(), integer(), dcep()) -> {dcep(), [action()]}.

handle_timeout(Now, Dc)

-spec handle_timeout(integer(), dcep()) -> {dcep(), [action()]}.

new(Opts)

-spec new(map()) -> dcep().

next_timeout(Dc)

-spec next_timeout(dcep()) -> integer() | infinity.

open_channel(Label, Opts, Now, Dc)

-spec open_channel(binary(), channel_opts(), integer(), dcep()) ->
                      {ok, 0..65534, dcep(), [action()]} | {error, atom()}.

Create a channel. Without negotiated a DATA_CHANNEL_OPEN is sent on a stream id of our parity; with negotiated => true the application agreed on id out of band and no DCEP message is used.

path_changed(Now, Dc)

-spec path_changed(integer(), dcep()) -> {dcep(), [action()]}.

The lower layer moved to another path (see webrtc_sctp_assoc:path_changed/2).

priority_class(Dc)

-spec priority_class(dcep()) -> webrtc_dscp:priority().

The class of the highest priority among the channels not being closed (RFC 8831 §6.4): the association's DSCP (RFC 8837 §5).

reset_congestion(Dc)

-spec reset_congestion(dcep()) -> dcep().

Restart the association's congestion control: its DSCP changed (RFC 8837 §5).

sctp(Dc)

-spec sctp(dcep()) -> webrtc_sctp_assoc:assoc().

send(Id, Type, Data, Now, Dc)

-spec send(0..65534, text | binary, binary(), integer(), dcep()) ->
              {ok, dcep(), [action()]} | {error, atom()}.

Send a text (UTF-8) or binary message. Empty messages use the "empty" PPIDs and one zero byte (RFC 8831 §6.6).

set_buffered_amount_low_threshold(Id, Low, Dc)

-spec set_buffered_amount_low_threshold(0..65534, non_neg_integer(), dcep()) -> dcep().