22 releases (6 breaking)

new 0.7.1 Sep 20, 2021
0.6.4 Aug 30, 2021
0.6.3 Jul 20, 2021
0.4.2 Mar 10, 2021
0.1.1 Jul 25, 2020

#94 in Network programming

Download history 70/week @ 2021-06-01 23/week @ 2021-06-08 85/week @ 2021-06-15 18/week @ 2021-06-22 13/week @ 2021-06-29 19/week @ 2021-07-06 24/week @ 2021-07-13 73/week @ 2021-07-20 52/week @ 2021-07-27 52/week @ 2021-08-03 59/week @ 2021-08-10 48/week @ 2021-08-17 36/week @ 2021-08-24 16/week @ 2021-08-31 9/week @ 2021-09-07 41/week @ 2021-09-14

149 downloads per month
Used in 2 crates (via async-datachannel)

LGPL-2.1

4MB
108K SLoC

C 95K SLoC // 0.2% comments C++ 12K SLoC // 0.1% comments Rust 1.5K SLoC // 0.0% comments Shell 265 SLoC // 0.3% comments Python 151 SLoC // 0.1% comments Automake 145 SLoC // 0.4% comments Objective-C++ 21 SLoC // 0.1% comments INI 9 SLoC // 0.5% 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.

See also async-datachannel for an async-based implementation.

Building

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

Clone the repo recursively:

git clone --recursive https://github.com/lerouxrgd/datachannel-rs.git

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.

Ubuntu

Required dependencies:

# Needed to compile libdatachannel
sudo apt install build-essential cmake pkg-config libssl-dev clang

Dependencies

~4–7MB
~173K SLoC