libdatachannel 快速入门

精简版快速入门，只保留核心概念与上手步骤。ICE/DTLS/SCTP、媒体 Track、WebSocket 内部实现、线程与调试等见 libdatachannel完整文档.md。

[一句话了解 libdatachannel](#一句话了解 libdatachannel)
[核心概念（信令 → P2P 连接）](#核心概念（信令 → P2P 连接）)
环境要求与构建
[5 分钟上手：Data Channel](#5 分钟上手：Data Channel)
[C API 与 C++ API](#C API 与 C++ API)
配置与后端速览
常见问题
下一步

1. 一句话了解 libdatachannel

libdatachannel 是轻量级 C/C++ WebRTC 库 ：实现 Data Channel 、媒体传输（RTP/RTCP） 与 WebSocket，依赖少，可与 Firefox/Chromium/Safari 等浏览器互通。适合原生 App 与浏览器点对点实时通信，无需引入完整 Google libwebrtc。

为什么用 libdatachannel？

轻量：模块化，可只用 Data Channel 或 WebSocket
跨平台：Linux、macOS、Windows、iOS、Android
双 API：C 与 C++；TLS/ICE 后端可换（OpenSSL、Mbed TLS、libjuice 等）

2. 核心概念（信令 → P2P 连接）

WebRTC 不负责信令------你需要自建通道交换 SDP 与 ICE Candidate（常用 WebSocket/HTTP）。

阶段	做什么
1. 信令	交换 Offer/Answer（SDP）与 ICE 候选
2. ICE	NAT 穿透，选出可用路径
3. DTLS	建立加密通道
4. SCTP / RTP	Data Channel 或媒体流

#mermaid-svg-J1BghoIeD9XUX2qN{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-J1BghoIeD9XUX2qN .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-J1BghoIeD9XUX2qN .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-J1BghoIeD9XUX2qN .error-icon{fill:#552222;}#mermaid-svg-J1BghoIeD9XUX2qN .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-J1BghoIeD9XUX2qN .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-J1BghoIeD9XUX2qN .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-J1BghoIeD9XUX2qN .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-J1BghoIeD9XUX2qN .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-J1BghoIeD9XUX2qN .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-J1BghoIeD9XUX2qN .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-J1BghoIeD9XUX2qN .marker{fill:#333333;stroke:#333333;}#mermaid-svg-J1BghoIeD9XUX2qN .marker.cross{stroke:#333333;}#mermaid-svg-J1BghoIeD9XUX2qN svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-J1BghoIeD9XUX2qN p{margin:0;}#mermaid-svg-J1BghoIeD9XUX2qN .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-J1BghoIeD9XUX2qN .cluster-label text{fill:#333;}#mermaid-svg-J1BghoIeD9XUX2qN .cluster-label span{color:#333;}#mermaid-svg-J1BghoIeD9XUX2qN .cluster-label span p{background-color:transparent;}#mermaid-svg-J1BghoIeD9XUX2qN .label text,#mermaid-svg-J1BghoIeD9XUX2qN span{fill:#333;color:#333;}#mermaid-svg-J1BghoIeD9XUX2qN .node rect,#mermaid-svg-J1BghoIeD9XUX2qN .node circle,#mermaid-svg-J1BghoIeD9XUX2qN .node ellipse,#mermaid-svg-J1BghoIeD9XUX2qN .node polygon,#mermaid-svg-J1BghoIeD9XUX2qN .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-J1BghoIeD9XUX2qN .rough-node .label text,#mermaid-svg-J1BghoIeD9XUX2qN .node .label text,#mermaid-svg-J1BghoIeD9XUX2qN .image-shape .label,#mermaid-svg-J1BghoIeD9XUX2qN .icon-shape .label{text-anchor:middle;}#mermaid-svg-J1BghoIeD9XUX2qN .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-J1BghoIeD9XUX2qN .rough-node .label,#mermaid-svg-J1BghoIeD9XUX2qN .node .label,#mermaid-svg-J1BghoIeD9XUX2qN .image-shape .label,#mermaid-svg-J1BghoIeD9XUX2qN .icon-shape .label{text-align:center;}#mermaid-svg-J1BghoIeD9XUX2qN .node.clickable{cursor:pointer;}#mermaid-svg-J1BghoIeD9XUX2qN .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-J1BghoIeD9XUX2qN .arrowheadPath{fill:#333333;}#mermaid-svg-J1BghoIeD9XUX2qN .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-J1BghoIeD9XUX2qN .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-J1BghoIeD9XUX2qN .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-J1BghoIeD9XUX2qN .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-J1BghoIeD9XUX2qN .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-J1BghoIeD9XUX2qN .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-J1BghoIeD9XUX2qN .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-J1BghoIeD9XUX2qN .cluster text{fill:#333;}#mermaid-svg-J1BghoIeD9XUX2qN .cluster span{color:#333;}#mermaid-svg-J1BghoIeD9XUX2qN div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-J1BghoIeD9XUX2qN .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-J1BghoIeD9XUX2qN rect.text{fill:none;stroke-width:0;}#mermaid-svg-J1BghoIeD9XUX2qN .icon-shape,#mermaid-svg-J1BghoIeD9XUX2qN .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-J1BghoIeD9XUX2qN .icon-shape p,#mermaid-svg-J1BghoIeD9XUX2qN .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-J1BghoIeD9XUX2qN .icon-shape .label rect,#mermaid-svg-J1BghoIeD9XUX2qN .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-J1BghoIeD9XUX2qN .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-J1BghoIeD9XUX2qN .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-J1BghoIeD9XUX2qN :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 信令服务器
ICE + DTLS + SCTP
Peer A
Peer B

主要类 ：PeerConnection（连接）、DataChannel（可靠/不可靠数据）、Track（音视频）、WebSocket（独立信令或实时通道）。

3. 环境要求与构建

项	说明
构建	CMake 3.13+、C++17 编译器
子模块	`git clone --recursive`
可选	OpenSSL / GnuTLS / Mbed TLS；libjuice（默认 ICE）或 libnice

bash 复制代码

git clone --recursive https://github.com/paullouisageneau/libdatachannel.git
cd libdatachannel
mkdir build && cd build
cmake ..
cmake --build . -j
sudo cmake --install .   # 可选

示例在 examples/（client、server、streamer 等），常配合 examples/signaling-server-* 做信令。

4. 5 分钟上手：Data Channel

4.1 最小 C++ 流程

cpp 复制代码

#include "rtc/rtc.hpp"

rtc::Configuration config;
config.iceServers.emplace_back("stun:stun.l.google.com:19302");

rtc::PeerConnection pc(config);

pc.onLocalDescription([](rtc::Description sdp) {
    // 通过信令发给对端
});
pc.onLocalCandidate([](rtc::Candidate candidate) {
    // 通过信令发给对端
});

auto dc = pc.createDataChannel("chat");
dc->onOpen([]() { /* 可发送 */ });
dc->onMessage([](auto msg) { /* 处理消息 */ });

// 对端 SDP/Answer 与远端 Candidate 通过 pc.setRemoteDescription / addRemoteCandidate 注入

4.2 跑官方示例

启动信令服务（如 examples/signaling-server-node）
终端 A：examples/client 或 examples/copy-paste
终端 B：浏览器打开对应 Web 示例，或第二个 native client

看到 DataChannel open 后即可 send() 文本或二进制（单条最大约 16KB，大文件需分片）。

5. C API 与 C++ API

	C (`rtc.h`)	C++ (`rtc.hpp`)
风格	句柄 + 回调	RAII、 `std::function`
适用	嵌入 C 项目、FFI	新 C++ 项目首选

两者能力等价；C API 需关注 rtcDelete* 与回调线程。

6. 配置与后端速览

配置项	典型值
`iceServers`	`stun:...`、`turn:...`（复杂 NAT 需 TURN）
TLS 后端	CMake `-DUSE_GNUTLS=1` / OpenSSL / Mbed TLS
ICE	默认 libjuice；可选 libnice

7. 常见问题

现象	处理
一直 `connecting`	检查信令是否交换完整；STUN/TURN 是否可达
浏览器连不上	SDP 方向、mid、候选格式需与浏览器一致
仅局域网通	配置 TURN 服务器
链接错误	确认 `cmake --install` 与 `find_package(datachannel)`

8. 下一步

官方：paullouisageneau/libdatachannel --- README、examples/、pages/ 文档。
建议顺序：数据通道 Hello World → PeerConnection 架构 → 信令工作流 → Data Channel 深入。

libdatachannel 快速入门