urtc.h File Reference

liburtc header file. More...

Go to the source code of this file.

Typedefs
typedef struct peerconn	urtc_peerconn_t
	Opque peer connection structure. More...
typedef int()	urtc_on_ice_candidate(const char *cand, void *arg)
	(callback) Called for each new local ICE candidate discovered More...
typedef void()	urtc_force_idr()
	(callback) Called to request that video encoder immediately generate an IDR More...

Functions
urtc_peerconn_t *	urtc_peerconn_create (const char *stun[])
	Create a new peer connection. More...
int	urtc_set_on_ice_candidate (urtc_peerconn_t *pc, urtc_on_ice_candidate *cb)
	Sets onIceCandidate callback function. More...
int	urtc_add_ice_candidate (urtc_peerconn_t *pc, const char *cand)
	Adds received remote ICE candidate to peer connection. More...
int	urtc_create_answer (urtc_peerconn_t *pc, char **answer)
	Creates local description for an answering peer connection. More...
int	urtc_create_offer (urtc_peerconn_t *pc, char **offer)
	Creates a local description for an offering peer connection. More...
int	urtc_set_local_description (urtc_peerconn_t *pc, const char *desc)
	Sets local description for peer connection. More...
int	urtc_set_remote_description (urtc_peerconn_t *pc, const char *desc)
	Sets remote description. More...
void	urtc_peerconn_destroy (urtc_peerconn_t *pc)
	Tears down peer connection, closing and freeing all resources. More...

Detailed Description

liburtc header file.

Copyright 2020 Chris Hiszpanski

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Typedef Documentation

urtc_force_idr

typedef void() urtc_force_idr()

(callback) Called to request that video encoder immediately generate an IDR

H.264 video encoders produce I-frames and P-frames. Only I-frames can be decoded independently. To minimize the time-to-first-frame (TTFF), an I-frame should be sent as soon as a peer connection is established. In the event of picture loss, an I-frame should be sent as soon as possible to re-establish picture.

This is an optional callback. If set, it improves the TTFF and picture recovery time from loss of picture.

urtc_on_ice_candidate

typedef int() urtc_on_ice_candidate(const char *cand, void *arg)

(callback) Called for each new local ICE candidate discovered

The local candidate should be relayed to the remote peer. Note that callback executes on peer connection event loop – do not block or do other expensive work within the callback.

Akin to the onicecandidate event handler in RTCPeerConnection.

Parameters

cand	Discovered local candidate string.
arg	User specified argument, see urtc_set_on_ice_candidate().

Returns

0 on success, negative on error.

urtc_peerconn_t

typedef struct peerconn urtc_peerconn_t

Opque peer connection structure.

Instantiate via urtc_peerconn_create(). Each peer connection creates its own single thread for processing events in a runloop.

Function Documentation

urtc_add_ice_candidate()

int urtc_add_ice_candidate	(	urtc_peerconn_t *	pc,
		const char *	cand
	)

Adds received remote ICE candidate to peer connection.

For each ICE candidate received from the remote peer via some external signaling channel, use this function to add the candidate to the peer connection. Candidates are asynchronously used to check for direct peer-to-peer connectivity with the remote peer.

Akin to addIceCandidate method of RTCPeerConnection in the WebRTC JS API.

Parameters

pc	Peer connection.
cand	An ICE candidate string from remote peer.

Returns

0 on success, negative on error.

urtc_create_answer()

int urtc_create_answer	(	urtc_peerconn_t *	pc,
		char **	answer
	)

Creates local description for an answering peer connection.

When a peer connection is the answering party, generates a local description (in Session Description Protocol). This description should be both sent to remote peer connection via some external signaling channel as well as added to the local peer connection via urtc_set_local_description().

Akin to createAnswer method of RTCPeerConnection in WebRTC JS API.

Parameters

pc	Peer connection
answer	Pointer to string pointer pointing to generated answer. Memory internally managed (caller need not and must not free).

Returns

0 on success, negative on error.

urtc_create_offer()

int urtc_create_offer	(	urtc_peerconn_t *	pc,
		char **	offer
	)

Creates a local description for an offering peer connection.

When a peer connection is the offering party, this function generates a local description (in Session Description Protocol). This description should be both sent to the remote peer connection via some external signaling channel as well as added to the local peer connection via urtc_set_local_description().

Akin to createOffer method of RTCPeerConnection in WebRTC JS API.

Parameters

pc	Peer connection
offer	Pointer to string pointer pointing to generated offer. Memory interally managed (caller need no and must not free).

Returns

0 on success, negative on error.

urtc_peerconn_create()

urtc_peerconn_t* urtc_peerconn_create

(

const char *

stun[]

)

Create a new peer connection.

Note that the new peer connection is not yet connected to a peer.

Akin to RTCPeerConnection() in the WebRTC JS API.

Parameters

stun

Array of STUN servers to use for discovery of server-reflexive ICE candidates. Each entry should be a string of the form hostname[:port] (e.g. "stun.l.google.com:19302"). The port is optional – if omitted, 3478 is assumed. The final entry in the array must be NULL. If no STUN servers are provided, only local area network peers will be discoverable.

Returns

On success, a pointer to new peer connection object is returned. The peer connection must be destroyed with urtc_peerconn_destroy() when no longer needed. On error, NULL is returned.

urtc_peerconn_destroy()

void urtc_peerconn_destroy

(

urtc_peerconn_t *

pc

)

Tears down peer connection, closing and freeing all resources.

Parameters

pc	Peer connection.

urtc_set_local_description()

int urtc_set_local_description	(	urtc_peerconn_t *	pc,
		const char *	desc
	)

Sets local description for peer connection.

The local description is a Session Description Protocol string, typically generated by urtc_create_offer() or urtc_create_answer(), depending on whether the local peer connection is the offering or answering party, respectively. Setting the local description begins local ICE candidate discovery.

Akin to setLocalDescription method of RTCPeerConnection in WebRTC JS API.

Parameters

pc	Peer connection previously created via urtc_peerconn_create().
desc	Local description in Session Description Protocol (SDP)

Returns

0 on success, negative on error.

urtc_set_on_ice_candidate()

int urtc_set_on_ice_candidate	(	urtc_peerconn_t *	pc,
		urtc_on_ice_candidate *	cb
	)

Sets onIceCandidate callback function.

Callback function will be called when a new local ICE candidate is discovered.

urtc_set_remote_description()

int urtc_set_remote_description	(	urtc_peerconn_t *	pc,
		const char *	desc
	)

Sets remote description.

The remote description is a Session Description Protocol string, received from the remote peer via some external signaling channel. Amongst other things, it defines the set of media codecs the remote peer supports.

Akin to setRemoteDescription method of RTCPeerConnection in WebRTC JS API.

Parameters

pc	Peer connection created by urtc_peerconn_create().
desc	Session description protocol.

Returns

0 on success, negative on error.