11 unstable releases (3 breaking)

0.4.1 Feb 24, 2021
0.4.0 Feb 21, 2021
0.3.1 Feb 13, 2021
0.2.1 Nov 30, 2020
0.1.1 Jul 25, 2020

#156 in Network programming

Download history 14/week @ 2020-11-13 4/week @ 2020-11-20 24/week @ 2020-11-27 22/week @ 2020-12-04 5/week @ 2020-12-11 3/week @ 2020-12-18 1/week @ 2020-12-25 14/week @ 2021-01-01 3/week @ 2021-01-08 3/week @ 2021-01-15 3/week @ 2021-01-22 13/week @ 2021-01-29 11/week @ 2021-02-05 80/week @ 2021-02-12 36/week @ 2021-02-19 15/week @ 2021-02-26

69 downloads per month

LGPL-2.1

4MB
104K SLoC

C 92K SLoC // 0.2% comments C++ 10K SLoC // 0.1% comments Rust 1K SLoC // 0.0% comments Shell 265 SLoC // 0.3% comments Automake 145 SLoC // 0.4% comments Objective-C++ 21 SLoC // 0.1% comments Python 17 SLoC // 0.1% comments

datachannel-rs   latest doc

Rust wrappers for libdatachannel, a WebRTC Data Channels standalone implementation in C++.

Usage

This crate provides two traits that end user must implement, DataChannelHandler and PeerConnectionHandler, which defined all callbacks for RtcPeerConnection and RtcDataChannel structs respectively.

Aforementioned traits are defined as follows:

pub trait DataChannelHandler {
    fn on_open(&mut self) {}
    fn on_closed(&mut self) {}
    fn on_error(&mut self, err: &str) {}
    fn on_message(&mut self, msg: &[u8]) {}
    fn on_buffered_amount_low(&mut self) {}
    fn on_available(&mut self) {}
}

pub trait PeerConnectionHandler {
    type DCH;

    fn data_channel_handler(&mut self) -> Self::DCH;

    fn on_description(&mut self, sess_desc: SessionDescription) {}
    fn on_candidate(&mut self, cand: IceCandidate) {}
    fn on_connection_state_change(&mut self, state: ConnectionState) {}
    fn on_gathering_state_change(&mut self, state: GatheringState) {}
    fn on_data_channel(&mut self, data_channel: Box<RtcDataChannel<Self::DCH>>) {}
}

Note that all on_* methods have a default no-operation implementation.

The main struct, RtcPeerconnection, takes a RtcConfig (which defines ICE servers) and a instance of PeerConnectionHandler.

Here is the basic workflow:

use datachannel::{DataChannelHandler, PeerConnectionHandler, RtcConfig, RtcPeerConnection};

struct MyChannel;

impl DataChannelHandler for MyChannel {
    fn on_open(&mut self) {
        // TODO: notify that the data channel is ready (optional)
    }

    fn on_message(&mut self, msg: &[u8]) {
        // TODO: process the received message
    }
}

struct MyConnection;

impl PeerConnectionHandler for MyConnection {
    type DCH = MyChannel;

    /// Used to create the `RtcDataChannel` received through `on_data_channel`.
    fn data_channel_handler(&mut self) -> Self::DCH {
        MyChannel
    }

    fn on_data_channel(&mut self, mut dc: Box<RtcDataChannel<Self::DCH>>) {
        // TODO: store `dc` to keep receiving its messages (otherwise it will be dropped)
    }
}

let ice_servers = vec!["stun:stun.l.google.com:19302"];
let conf = RtcConfig::new(&ice_servers);

let mut pc = RtcPeerConnection::new(&conf, MyConnection)?;

let mut dc = pc.create_data_channel("test-dc", MyChannel)?;
// TODO: exchange `SessionDescription` and `IceCandidate` with remote peer
// TODO: wait for `dc` to be opened (should be signaled through `on_open`)
// ...
// Then send a message
dc.send("Hello Peer!".as_bytes())?;

Complete implementation example can be found in the tests.

Building

Note that CMake is required to compile libdatachannel through datachannel-sys.

Static build

By default libdatachannel will be built and linked dynamically. However there is a static Cargo feature that will build and link it statically (with all its dependencies, including OpenSSL).

Apple macOS

You probably need to set the following environment variables if your build fails with an OpenSSL related error.

export OPENSSL_ROOT_DIR=/usr/local/Cellar/openssl@1.1/1.1.1i/
export OPENSSL_LIBRARIES=/usr/local/Cellar/openssl@1.1/1.1.1i/lib

With the paths of your local OpenSSL installation.

Dependencies

~4–6.5MB
~159K SLoC