webrtc.h File Reference

WebRTC DataChannel server (SDP + ICE-lite + DTLS + SCTP) interface. More...

#include <stddef.h>
#include <stdint.h>
#include <cwist/sys/io/reactor.h>

Include dependency graph for webrtc.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Typedefs
typedef struct cwist_webrtc_ctx	cwist_webrtc_ctx
typedef struct cwist_webrtc_conn	cwist_webrtc_conn
typedef void(*	cwist_webrtc_message_cb) (cwist_webrtc_conn *conn, uint16_t channel_id, const uint8_t *data, size_t len, cwist_webrtc_data_type type, void *user)
	DataChannel message callback, invoked on the ctx's reactor thread.
typedef void(*	cwist_webrtc_channel_cb) (cwist_webrtc_conn *conn, uint16_t channel_id, const char *label, void *user)
	Optional DataChannel open notification (remote peer opened a channel).
typedef void(*	cwist_webrtc_close_cb) (cwist_webrtc_conn *conn, void *user)
	Optional connection-closed notification. Runs once per connection whose SCTP association came up; after it returns, the conn pointer is only valid through references the application still holds.

Enumerations
enum	cwist_webrtc_data_type { CWIST_WEBRTC_DATA_BINARY = 0 , CWIST_WEBRTC_DATA_STRING = 1 }

Functions
cwist_webrtc_ctx *	cwist_webrtc_ctx_new (uint16_t port)
	Create a WebRTC context bound to a UDP port (0 picks an ephemeral port), running on its own reactor thread.
cwist_webrtc_ctx *	cwist_webrtc_ctx_new_on (cwist_reactor_t *reactor, uint16_t port)
	Create a WebRTC context on a reactor the caller runs.
uint16_t	cwist_webrtc_ctx_port (const cwist_webrtc_ctx *ctx)
	UDP port the context is bound to.
void	cwist_webrtc_ctx_set_message_handler (cwist_webrtc_ctx *ctx, cwist_webrtc_message_cb cb, void *user)
	Set the callback for incoming DataChannel messages. Set handlers before answering the first offer.
void	cwist_webrtc_ctx_set_channel_handler (cwist_webrtc_ctx *ctx, cwist_webrtc_channel_cb cb, void *user)
	Set the callback for incoming DataChannel open (DCEP) events.
void	cwist_webrtc_ctx_set_close_handler (cwist_webrtc_ctx *ctx, cwist_webrtc_close_cb cb, void *user)
	Set the callback for closed connections.
int	cwist_webrtc_handle_offer (cwist_webrtc_ctx *ctx, const char *offer, char *answer_out, size_t out_len)
	Answer a browser SDP offer (ICE-lite, setup:passive).
int	cwist_webrtc_ctx_connection_count (const cwist_webrtc_ctx *ctx)
	Number of connections whose SCTP association is up.
int	cwist_webrtc_conn_send (cwist_webrtc_conn *conn, uint16_t channel_id, const uint8_t *data, size_t len, cwist_webrtc_data_type type)
	Send a message on a DataChannel.
size_t	cwist_webrtc_conn_buffered_amount (const cwist_webrtc_conn *conn)
	Bytes accepted by cwist_webrtc_conn_send() and not yet handed to SCTP (like RTCDataChannel.bufferedAmount, summed over channels).
const char *	cwist_webrtc_ctx_fingerprint (const cwist_webrtc_ctx *ctx)
	Local certificate fingerprint (SHA-256, colon-separated hex).
void	cwist_webrtc_conn_retain (cwist_webrtc_conn *conn)
	Take a reference on conn so it stays valid outside a callback.
void	cwist_webrtc_conn_release (cwist_webrtc_conn *conn)
	Drop a reference taken with cwist_webrtc_conn_retain().
void	cwist_webrtc_conn_close (cwist_webrtc_conn *conn)
	Close a connection (SCTP abort, DTLS teardown). Safe from any thread; the close handler runs on the reactor thread.
void	cwist_webrtc_ctx_free (cwist_webrtc_ctx *ctx)
	Close every connection and free the context.

Detailed Description

WebRTC DataChannel server (SDP + ICE-lite + DTLS + SCTP) interface.

DataChannel-only WebRTC per RFC 8831/8832: the server acts as an ICE-lite endpoint, completes a DTLS handshake (BoringSSL, plain DTLS, no SRTP) over the nominated UDP path, and runs SCTP with DataChannel establishment over the DTLS connection via usrsctp.

Threading: a ctx runs on one cwist reactor. cwist_webrtc_ctx_new() creates a private reactor and thread; cwist_webrtc_ctx_new_on() attaches to a reactor the caller already runs. Every callback is invoked on that reactor's run thread. cwist_webrtc_conn_send(), cwist_webrtc_conn_close(), cwist_webrtc_handle_offer() and cwist_webrtc_ctx_free() may be called from any thread.

Processes: a ctx belongs to the process that created it. A forked child (e.g. a cwist_app_listen() worker) must create its own ctx; on an inherited one, cwist_webrtc_handle_offer() returns -1 and cwist_webrtc_ctx_free() does nothing.

Connection lifetime: a cwist_webrtc_conn pointer passed to a callback is valid for the duration of that callback. To use it later or from another thread, take a reference with cwist_webrtc_conn_retain() and drop it with cwist_webrtc_conn_release(). After the close handler runs, sends on a retained conn fail with -1.

Definition in file webrtc.h.

Typedef Documentation

cwist_webrtc_channel_cb

typedef void(* cwist_webrtc_channel_cb) (cwist_webrtc_conn *conn, uint16_t channel_id, const char *label, void *user)

Optional DataChannel open notification (remote peer opened a channel).

Definition at line 57 of file webrtc.h.

cwist_webrtc_close_cb

typedef void(* cwist_webrtc_close_cb) (cwist_webrtc_conn *conn, void *user)

Optional connection-closed notification. Runs once per connection whose SCTP association came up; after it returns, the conn pointer is only valid through references the application still holds.

Definition at line 65 of file webrtc.h.

cwist_webrtc_conn

typedef struct cwist_webrtc_conn cwist_webrtc_conn

Definition at line 36 of file webrtc.h.

cwist_webrtc_ctx

typedef struct cwist_webrtc_ctx cwist_webrtc_ctx

Definition at line 35 of file webrtc.h.

cwist_webrtc_message_cb

typedef void(* cwist_webrtc_message_cb) (cwist_webrtc_conn *conn, uint16_t channel_id, const uint8_t *data, size_t len, cwist_webrtc_data_type type, void *user)

DataChannel message callback, invoked on the ctx's reactor thread.

Parameters

channel_id	SCTP stream id (DataChannel id).
type	Whether the peer sent a string or binary message; echo it back with the same type to preserve it.

Definition at line 50 of file webrtc.h.

Enumeration Type Documentation

cwist_webrtc_data_type

enum cwist_webrtc_data_type

DataChannel message type (RFC 8831 section 8 payload protocol ids).

Enumerator
CWIST_WEBRTC_DATA_BINARY	PPID 53 (57 when empty); ArrayBuffer/Blob in a browser.
CWIST_WEBRTC_DATA_STRING	PPID 51 (56 when empty); UTF-8 string in a browser.

Definition at line 39 of file webrtc.h.

Function Documentation

cwist_webrtc_conn_buffered_amount()

size_t cwist_webrtc_conn_buffered_amount

(

const cwist_webrtc_conn *

conn

)

Bytes accepted by cwist_webrtc_conn_send() and not yet handed to SCTP (like RTCDataChannel.bufferedAmount, summed over channels).

Definition at line 1019 of file webrtc.c.

References cwist_webrtc_conn::buffered, and cap.

cwist_webrtc_conn_close()

void cwist_webrtc_conn_close

(

cwist_webrtc_conn *

conn

)

Close a connection (SCTP abort, DTLS teardown). Safe from any thread; the close handler runs on the reactor thread.

Definition at line 1227 of file webrtc.c.

References cap, cwist_reactor_post::cb, cwist_webrtc_conn::close_post, cwist_webrtc_conn::close_posted, cwist_webrtc_conn::close_requested, cwist_reactor_post::ctx, cwist_webrtc_conn::ctx, cwist_webrtc_conn_retain(), cwist_webrtc_on_owner(), cwist_webrtc_conn::detached, and cwist_webrtc_ctx::reactor.

cwist_webrtc_conn_release()

void cwist_webrtc_conn_release

(

cwist_webrtc_conn *

conn

)

Drop a reference taken with cwist_webrtc_conn_retain().

Definition at line 86 of file webrtc.c.

References cap, cwist_webrtc_conn::ch_bits, cwist_webrtc_conn::ctx, cwist_free(), cwist_webrtc_conn::refs, cwist_webrtc_conn::rx_partial, cwist_webrtc_conn::ssl, and SSL_free.

cwist_webrtc_conn_retain()

void cwist_webrtc_conn_retain

(

cwist_webrtc_conn *

conn

)

Take a reference on conn so it stays valid outside a callback.

Definition at line 82 of file webrtc.c.

References cap, and cwist_webrtc_conn::refs.

Referenced by cwist_webrtc_conn_close(), cwist_webrtc_conn_sctp_out(), cwist_webrtc_conn_send(), and cwist_webrtc_connect().

cwist_webrtc_conn_send()

int cwist_webrtc_conn_send	(	cwist_webrtc_conn *	conn,
		uint16_t	channel_id,
		const uint8_t *	data,
		size_t	len,
		cwist_webrtc_data_type	type
	)

Send a message on a DataChannel.

Safe from any thread. The message is queued if SCTP is not ready or its send buffer is full; queued bytes are reported by cwist_webrtc_conn_buffered_amount().

Returns

0 when sent or queued; -1 if the conn is closed, len exceeds 262144 bytes (the advertised max-message-size), or the queue already holds 4 MiB.

Definition at line 1158 of file webrtc.c.

References cwist_webrtc_conn::buffered, cap, cwist_reactor_post::cb, cwist_reactor_post::ctx, cwist_webrtc_conn::ctx, cwist_alloc(), cwist_sctp_send(), cwist_webrtc_conn_retain(), CWIST_WEBRTC_DATA_STRING, CWIST_WEBRTC_MAX_MESSAGE, cwist_webrtc_on_owner(), cwist_webrtc_conn::detached, head, cwist_webrtc_conn::kick_post, cwist_webrtc_conn::pending_head, cwist_webrtc_ctx::reactor, and cwist_webrtc_conn::sctp_ready.

cwist_webrtc_ctx_connection_count()

int cwist_webrtc_ctx_connection_count

(

const cwist_webrtc_ctx *

ctx

)

Number of connections whose SCTP association is up.

Definition at line 1015 of file webrtc.c.

References cap, and cwist_webrtc_ctx::ready_count.

cwist_webrtc_ctx_fingerprint()

const char * cwist_webrtc_ctx_fingerprint

(

const cwist_webrtc_ctx *

ctx

)

Local certificate fingerprint (SHA-256, colon-separated hex).

Definition at line 993 of file webrtc.c.

References cwist_webrtc_ctx::fingerprint.

cwist_webrtc_ctx_free()

void cwist_webrtc_ctx_free

(

cwist_webrtc_ctx *

ctx

)

Close every connection and free the context.

Safe from any thread. For a ctx made with cwist_webrtc_ctx_new_on() and called off the reactor thread, this waits for the reactor to finish the teardown, so the reactor must still be running.

Definition at line 944 of file webrtc.c.

References cap, cwist_reactor_post::cb, cwist_reactor_post::ctx, cwist_reactor_destroy(), cwist_webrtc_ctx::fd_closed, cwist_webrtc_ctx::free_cv, cwist_webrtc_ctx::free_mu, cwist_webrtc_ctx::free_post, cwist_webrtc_ctx::owner_pid, cwist_webrtc_ctx::owns_reactor, cwist_webrtc_ctx::reactor, cwist_webrtc_ctx::thread, cwist_webrtc_ctx::thread_running, and cwist_webrtc_ctx::udp_fd.

Referenced by cwist_webrtc_ctx_new().

cwist_webrtc_ctx_new()

cwist_webrtc_ctx * cwist_webrtc_ctx_new

(

uint16_t

port

)

Create a WebRTC context bound to a UDP port (0 picks an ephemeral port), running on its own reactor thread.

Returns

NULL on failure.

Definition at line 879 of file webrtc.c.

References cap, cwist_reactor_create(), cwist_reactor_destroy(), cwist_webrtc_ctx_free(), cwist_webrtc_ctx::thread, and cwist_webrtc_ctx::thread_running.

cwist_webrtc_ctx_new_on()

cwist_webrtc_ctx * cwist_webrtc_ctx_new_on	(	cwist_reactor_t *	reactor,
		uint16_t	port
	)

Create a WebRTC context on a reactor the caller runs.

The ctx registers its UDP socket and timers with reactor and does all of its work inside that reactor's callbacks; no thread is created. The reactor must keep running until cwist_webrtc_ctx_free() returns.

Returns

NULL on failure.

Definition at line 895 of file webrtc.c.

References cap, and cwist_webrtc_ctx::udp_fd.

cwist_webrtc_ctx_port()

uint16_t cwist_webrtc_ctx_port

(

const cwist_webrtc_ctx *

ctx

)

UDP port the context is bound to.

Definition at line 989 of file webrtc.c.

References cwist_webrtc_ctx::port.

cwist_webrtc_ctx_set_channel_handler()

void cwist_webrtc_ctx_set_channel_handler	(	cwist_webrtc_ctx *	ctx,
		cwist_webrtc_channel_cb	cb,
		void *	user
	)

Set the callback for incoming DataChannel open (DCEP) events.

Definition at line 1003 of file webrtc.c.

References cap, cwist_webrtc_ctx::ch_cb, and cwist_webrtc_ctx::ch_user.

cwist_webrtc_ctx_set_close_handler()

void cwist_webrtc_ctx_set_close_handler	(	cwist_webrtc_ctx *	ctx,
		cwist_webrtc_close_cb	cb,
		void *	user
	)

Set the callback for closed connections.

Definition at line 1009 of file webrtc.c.

References cap, cwist_webrtc_ctx::close_cb, and cwist_webrtc_ctx::close_user.

cwist_webrtc_ctx_set_message_handler()

void cwist_webrtc_ctx_set_message_handler	(	cwist_webrtc_ctx *	ctx,
		cwist_webrtc_message_cb	cb,
		void *	user
	)

Set the callback for incoming DataChannel messages. Set handlers before answering the first offer.

Definition at line 997 of file webrtc.c.

References cap, cwist_webrtc_ctx::msg_cb, and cwist_webrtc_ctx::msg_user.

cwist_webrtc_handle_offer()

int cwist_webrtc_handle_offer	(	cwist_webrtc_ctx *	ctx,
		const char *	offer,
		char *	answer_out,
		size_t	out_len
	)

Answer a browser SDP offer (ICE-lite, setup:passive).

Parameters

offer	The remote SDP offer.
answer_out	Buffer receiving the generated SDP answer.
out_len	Size of answer_out.

Returns

0 on success, -1 on error.

Safe from any thread. The connection completes asynchronously (ICE nomination, DTLS, SCTP) on the ctx's reactor thread. An answered offer whose peer never shows up is dropped after 30 seconds.

Definition at line 1042 of file webrtc.c.

References cap, cwist_reactor_post::cb, cwist_reactor_post::ctx, cwist_webrtc_conn::ctx, cwist_sdp_parse(), cwist_sdp_write_answer(), cwist_webrtc_ctx::fingerprint, cwist_webrtc_ctx::host_ip, cwist_webrtc_ctx::ice_lite_server, cwist_webrtc_ctx::ice_pwd, cwist_webrtc_ctx::ice_ufrag, cwist_sdp_info::mid, cwist_webrtc_ctx::owner_pid, cwist_webrtc_conn::peer_pwd, cwist_webrtc_conn::peer_ufrag, cwist_webrtc_ctx::port, cwist_webrtc_ctx::reactor, and cwist_webrtc_conn::reg_post.