DOC.md

libdatachannel - C API Documentation

The following details the C API of libdatachannel. The C API is available by including the rtc/rtc.h header.

General considerations

Unless stated otherwise, functions return RTC_ERR_SUCCESS, defined as 0, on success.

All functions can return the following negative error codes:

• RTC_ERR_INVALID: an invalid argument was provided
• RTC_ERR_FAILURE: a runtime error happened
• RTC_ERR_NOT_AVAIL: an element is not available at the moment
• RTC_ERR_TOO_SMALL: a user-provided buffer is too small

All functions taking pointers as arguments (excepted the opaque user pointer) need the memory to be accessible until the call returns, but it can be safely discarded afterwards.

Common

rtcInitLogger

void rtcInitLogger(rtcLogLevel level, rtcLogCallbackFunc cb)

Arguments:

• level: the log level. It must be one of the following: RTC_LOG_NONE, RTC_LOG_FATAL, RTC_LOG_ERROR, RTC_LOG_WARNING, RTC_LOG_INFO, RTC_LOG_DEBUG, RTC_LOG_VERBOSE.
• cb (optional): the callback to pass the log lines to. If the callback is already set, it is replaced. If NULL after a callback is set, the callback is unset. If NULL on first call, the library will log to stdout instead.

cb must have the following signature: void myLogCallback(rtcLogLevel level, const char *message)

Arguments:

• level: the log level for the current message. It will be one of the following: RTC_LOG_FATAL, RTC_LOG_ERROR, RTC_LOG_WARNING, RTC_LOG_INFO, RTC_LOG_DEBUG, RTC_LOG_VERBOSE.
• message: a null-terminated string containing the log message

rtcPreload

void rtcPreload(void)

An optional call to rtcPreload preloads the global resources used by the library. If it is not called, resources are lazy-loaded when they are required for the first time by a PeerConnection, which for instance prevents from properly timing connection establishment (as the first one will take way more time). The call blocks until preloading is finished. If resources are already loaded, the call has no effect.

rtcCleanup

void rtcCleanup(void)

An optional call to rtcCleanup unloads the global resources used by the library. The call will block until unloading is done. If Peer Connections, Data Channels, Tracks, or WebSockets created through this API still exist, they will be destroyed. If resources are already unloaded, the call has no effect.

Warning: This function requires all Peer Connections, Data Channels, Tracks, and WebSockets to be destroyed before returning, meaning all callbacks must return before this function returns. Therefore, it must never be called from a callback.

rtcSetUserPointer

void rtcSetUserPointer(int id, void *user_ptr)

Sets a opaque user pointer for a Peer Connection, Data Channel, Track, or WebSocket. The user pointer will be passed as last argument in each corresponding callback. It will never be accessed in any way. The initial user pointer of a Peer Connection or WebSocket is NULL, and the initial one of a Data Channel or Track is the one of the Peer Connection at the time of creation.

Arguments:

• id: the identifier of Peer Connection, Data Channel, Track, or WebSocket
• user_ptr: an opaque pointer whose meaning is up to the user

rtcGetUserPointer

void *rtcGetUserPointer(int id)

Retrieves the opaque user pointer previously set for a Peer Connection, Data Channel, Track, or WebSocket.

Arguments:

• id: the identifier of Peer Connection, Data Channel, Track, or WebSocket

Return value: the user pointer previously set by rtcSetUserPointer, or NULL if unset or id is invalid

PeerConnection

rtcCreatePeerConnection

int rtcCreatePeerConnection(const rtcConfiguration *config)

typedef struct {
	const char **iceServers;
	int iceServersCount;
	const char *proxyServer;
	const char *bindAddress;
	rtcCertificateType certificateType;
	rtcTransportPolicy iceTransportPolicy;
	bool enableIceTcp;
	bool enableIceUdpMux;
	bool disableAutoNegotiation;
	bool forceMediaTransport;
	uint16_t portRangeBegin;
	uint16_t portRangeEnd;
	int mtu;
	int maxMessageSize;
} rtcConfiguration;

Creates a Peer Connection.

Arguments:

• config: the configuration structure, containing:
  • iceServers (optional): an array of pointers on null-terminated ICE server URIs (NULL if unused)
  • iceServersCount (optional): number of URLs in the array pointed by iceServers (0 if unused)
  • proxyServer (optional): if non-NULL, specifies the proxy server URI to use for TURN relaying (ignored with libjuice as ICE backend)
  • bindAddress (optional): if non-NULL, bind only to the given local address (ignored with libnice as ICE backend)
  • certificateType (optional): certificate type, either RTC_CERTIFICATE_ECDSA or RTC_CERTIFICATE_RSA (0 or RTC_CERTIFICATE_DEFAULT if default)
  • iceTransportPolicy (optional): ICE transport policy, if set to RTC_TRANSPORT_POLICY_RELAY, the PeerConnection will emit only relayed candidates (0 or RTC_TRANSPORT_POLICY_ALL if default)
  • enableIceTcp: if true, generate TCP candidates for ICE
  • enableIceUdpMux: if true, connections are multiplexed on the same UDP port (should be combined with portRangeBegin and portRangeEnd, ignored with libnice as ICE backend)
  • disableAutoNegotiation: if true, the user is responsible for calling rtcSetLocalDescription after creating a Data Channel and after setting the remote description
  • forceMediaTransport: if true, the connection allocates the SRTP media transport even if no tracks are present (necessary to add tracks during later renegotiation)
  • portRangeBegin (optional): first port (included) of the allowed local port range (0 if unused)
  • portRangeEnd (optional): last port (included) of the allowed local port (0 if unused)
  • mtu (optional): manually set the Maximum Transfer Unit (MTU) for the connection (0 if automatic)
  • maxMessageSize (optional): manually set the local maximum message size for Data Channels (0 if default)

Return value: the identifier of the new Peer Connection or a negative error code.

The Peer Connection must be deleted with rtcDeletePeerConnection.

Each entry in iceServers must match the format [("stun"|"turn"|"turns") (":"|"://")][username ":" password "@"]hostname[":" port]["?transport=" ("udp"|"tcp"|"tls")]. The default scheme is STUN, the default port is 3478 (5349 over TLS), and the default transport is UDP. For instance, a STUN server URI could be mystunserver.org, and a TURN server URI could be turn:myuser:12345678@turnserver.org. Note transports TCP and TLS are only available for a TURN server with libnice as ICE backend and govern only the TURN control connection, meaning relaying is always performed over UDP.

The proxyServer URI, if present, must match the format [("http"|"socks5") (":"|"://")][username ":" password "@"]hostname[" :" port]. The default scheme is HTTP, and the default port is 3128 for HTTP or 1080 for SOCKS5.

If the username or password of an URI contains reserved special characters, they must be percent-encoded. In particular, ":" must be encoded as "%3A" and "@" must by encoded as "%40".

rtcClosePeerConnection

int rtcClosePeerConnection(int pc)

Closes the Peer Connection.

Arguments:

• pc: the Peer Connection identifier

Return value: RTC_ERR_SUCCESS or a negative error code

rtcDeletePeerConnection

int rtcDeletePeerConnection(int pc)

Deletes the Peer Connection.

Arguments:

• pc: the Peer Connection identifier

Return value: RTC_ERR_SUCCESS or a negative error code

If it is not already closed, the Peer Connection is implicitly closed before being deleted. After this function has been called, pc must not be used in a function call anymore. This function will block until all scheduled callbacks of pc return (except the one this function might be called in) and no other callback will be called for pc after it returns.

rtcSetXCallback

These functions set, change, or unset (if cb is NULL) the different callbacks of a Peer Connection.

int rtcSetLocalDescriptionCallback(int pc, rtcDescriptionCallbackFunc cb)*

cb must have the following signature: void myDescriptionCallback(int pc, const char *sdp, const char *type, void *user_ptr)

int rtcSetLocalCandidateCallback(int pc, rtcCandidateCallbackFunc cb)

cb must have the following signature: void myCandidateCallback(int pc, const char *cand, const char *mid, void *user_ptr)

int rtcSetStateChangeCallback(int pc, rtcStateChangeCallbackFunc cb)

cb must have the following signature: void myStateChangeCallback(int pc, rtcState state, void *user_ptr)

state will be one of the following: RTC_CONNECTING, RTC_CONNECTED, RTC_DISCONNECTED, RTC_FAILED, or RTC_CLOSED.

int rtcSetIceStateChangeCallback(int pc, rtcIceStateChangeCallbackFunc cb)

cb must have the following signature: void myIceStateChangeCallback(int pc, rtcIceState state, void *user_ptr)

state will be one of the following: RTC_ICE_CHECKING, RTC_ICE_CONNECTED, RTC_ICE_COMPLETED, RTC_ICE_FAILED, RTC_ICE_DISCONNECTED, or RTC_ICE_CLOSED.

int rtcSetGatheringStateChangeCallback(int pc, rtcGatheringStateCallbackFunc cb)

cb must have the following signature: void myGatheringStateCallback(int pc, rtcGatheringState state, void *user_ptr)

state will be RTC_GATHERING_INPROGRESS or RTC_GATHERING_COMPLETE.

int rtcSetSignalingStateChangeCallback(int pc, rtcSignalingStateCallbackFunc cb)

cb must have the following signature: void mySignalingStateCallback(int pc, rtcSignalingState state, void *user_ptr)

state will be one of the following: RTC_SIGNALING_STABLE, RTC_SIGNALING_HAVE_LOCAL_OFFER, RTC_SIGNALING_HAVE_REMOTE_OFFER, RTC_SIGNALING_HAVE_LOCAL_PRANSWER, or RTC_SIGNALING_HAVE_REMOTE_PRANSWER.

int rtcSetDataChannelCallback(int pc, rtcDataChannelCallbackFunc cb)

cb must have the following signature: void myDataChannelCallback(int pc, int dc, void *user_ptr)

int rtcSetTrackCallback(int pc, rtcTrackCallbackFunc cb)

cb must have the following signature: void myTrackCallback(int pc, int tr, void *user_ptr)

rtcSetLocalDescription

int rtcSetLocalDescription(int pc, const char *type)

Initiates the handshake process. Following this call, the local description callback will be called with the local description, which must be sent to the remote peer by the user's method of choice. Note this call is implicit after rtcSetRemoteDescription and rtcCreateDataChannel if disableAutoNegotiation was not set on Peer Connection creation.

Arguments:

• pc: the Peer Connection identifier
• type (optional): type of the description ("offer", "answer", "pranswer", or "rollback") or NULL for automatic (recommended).

Warning: This function expects the optional type for the local description and not an SDP description. It is not possible to set an existing SDP description.

rtcSetRemoteDescription

int rtcSetRemoteDescription(int pc, const char *sdp, const char *type)

Sets the remote description received from the remote peer by the user's method of choice. The remote description may have candidates or not.

Arguments:

• pc: the Peer Connection identifier
• sdp: the remote description in SDP format
• type (optional): type of the description ("offer", "answer", "pranswer", or "rollback") or NULL for automatic (not recommended).

If the remote description is an offer and disableAutoNegotiation was not set in rtcConfiguration, the library will automatically answer by calling rtcSetLocalDescription internally. Otherwise, the user must call it to answer the remote description.

rtcAddRemoteCandidate

int rtcAddRemoteCandidate(int pc, const char *cand, const char *mid)

Adds a trickled remote candidate received from the remote peer by the user's method of choice.

Arguments:

• pc: the Peer Connection identifier
• cand: a null-terminated SDP string representing the candidate (with or without the "a=" prefix)
• mid (optional): a null-terminated string representing the mid of the candidate in the remote SDP description or NULL for autodetection

The Peer Connection must have a remote description set.

Return value: RTC_ERR_SUCCESS or a negative error code

rtcGetLocalDescription

int rtcGetLocalDescription(int pc, char *buffer, int size)

Retrieves the current local description in SDP format.

Arguments:

• pc: the Peer Connection identifier
• buffer: a user-supplied buffer to store the description
• size: the size of buffer

Return value: the length of the string copied in buffer (including the terminating null character) or a negative error code

If buffer is NULL, the description is not copied but the size is still returned.

rtcGetRemoteDescription

int rtcGetRemoteDescription(int pc, char *buffer, int size)

Retrieves the current remote description in SDP format.

Arguments:

• pc: the Peer Connection identifier
• buffer: a user-supplied buffer to store the description
• size: the size of buffer

Return value: the length of the string copied in buffer (including the terminating null character) or a negative error code

If buffer is NULL, the description is not copied but the size is still returned.

rtcGetLocalDescriptionType

int rtcGetLocalDescriptionType(int pc, char *buffer, int size)

Retrieves the current local description type as string.

Arguments:

• pc: the Peer Connection identifier
• buffer: a user-supplied buffer to store the type
• size: the size of buffer

Return value: the length of the string copied in buffer (including the terminating null character) or a negative error code

If buffer is NULL, the description is not copied but the size is still returned.

rtcGetRemoteDescriptionType

int rtcGetRemoteDescriptionType(int pc, char *buffer, int size)

Retrieves the current remote description type as string.

Arguments:

• pc: the Peer Connection identifier
• buffer: a user-supplied buffer to store the type
• size: the size of buffer

Return value: the length of the string copied in buffer (including the terminating null character) or a negative error code

If buffer is NULL, the description is not copied but the size is still returned.

rtcCreateOffer/rtcCreateAnswer

int rtcCreateOffer(int pc, char *buffer, int size)
int rtcCreateAnswer(int pc, char *buffer, int size)

Create a local offer or answer description in SDP format. These functions are intended only for specific use cases where the application needs to generate a description without setting it. It is useless to call them before rtcSetLocalDescription as it doesn't expect the user to supply a description.

• pc: the Peer Connection identifier
• buffer: a user-supplied buffer to store the description
• size: the size of buffer

Return value: the length of the string copied in buffer (including the terminating null character) or a negative error code

If buffer is NULL, the description is not copied but the size is still returned.

rtcGetLocalAddress

int rtcGetLocalAddress(int pc, char *buffer, int size)

Retrieves the current local address, i.e. the network address of the currently selected local candidate. The address will have the format "IP_ADDRESS:PORT", where IP_ADDRESS may be either IPv4 or IPv6. The call might fail if the PeerConnection is not in state RTC_CONNECTED, and the address might change after connection.

Arguments:

• pc: the Peer Connection identifier
• buffer: a user-supplied buffer to store the address
• size: the size of buffer

Return value: the length of the string copied in buffer (including the terminating null character) or a negative error code

If buffer is NULL, the address is not copied but the size is still returned.

rtcGetRemoteAddress

int rtcGetRemoteAddress(int pc, char *buffer, int size)

Retrieves the current remote address, i.e. the network address of the currently selected remote candidate. The address will have the format "IP_ADDRESS:PORT", where IP_ADDRESS may be either IPv4 or IPv6. The call may fail if the state is not RTC_CONNECTED, and the address might change after connection.

Arguments:

• pc: the Peer Connection identifier
• buffer: a user-supplied buffer to store the address
• size: the size of buffer

Return value: the length of the string copied in buffer (including the terminating null character) or a negative error code

If buffer is NULL, the address is not copied but the size is still returned.

rtcGetSelectedCandidatePair

int rtcGetSelectedCandidatePair(int pc, char *local, int localSize, char *remote, int remoteSize)

Retrieves the currently selected candidate pair. The call may fail if the state is not RTC_CONNECTED, and the selected candidate pair might change after connection.

Arguments:

• pc: the Peer Connection identifier
• local: a user-supplied buffer to store the local candidate
• localSize: the size of local
• remote: a user-supplied buffer to store the remote candidate
• remoteSize: the size of remote

Return value: the maximun length of strings copied in buffers (including the terminating null character) or a negative error code

If local, remote, or both, are NULL, the corresponding candidate is not copied, but the maximum length is still returned.

rtcIsNegotiationNeeded

bool rtcIsNegotiationNeeded(int pc);

Return true if negotiation needs to be started or restarted, for instance to signal new tracks. If so, the user may call rtcSetLocalDescription() to start it.

Arguments:

• pc: the Peer Connection identifier

Return value: true if negotiation is needed

rtcGetMaxDataChannelStream

int rtcGetMaxDataChannelStream(int pc);

Retrieves the maximum stream ID a Data Channel may use. It is useful to create user-negotiated Data Channels with negotiated=true and manualStream=true. The maximum is negotiated during connection, therefore the final value after connection might be lower than before connection if the remote maximum is lower.

Arguments:

• pc: the Peer Connection identifier

Return value: the maximum stream ID (stream for a Data Channel may be set from 0 to this value included) or a negative error code

rtcGetRemoteMaxMessageSize

int rtcGetRemoteMaxMessageSize(int pc)

Retrieves the maximum message size for data channels on the peer connection as negotiated with the remote peer.

Arguments:

• pc: the Peer Connection identifier

Return value: the maximum message size for data channels or a negative error code

Channel (Common API for Data Channel, Track, and WebSocket)

The following common functions might be called with a generic channel identifier. It may be the identifier of either a Data Channel, a Track, or a WebSocket.

rtcSetXCallback

These functions set, change, or unset (if cb is NULL) the different callbacks of a channel identified by the argument id.

int rtcSetOpenCallback(int id, rtcOpenCallbackFunc cb)

cb must have the following signature: void myOpenCallback(int id, void *user_ptr)

It is called when the channel was previously connecting and is now open.

int rtcSetClosedCallback(int id, rtcClosedCallbackFunc cb)

cb must have the following signature: void myClosedCallback(int id, void *user_ptr)

It is called when the channel was previously open and is now closed.

int rtcSetErrorCallback(int id, rtcErrorCallbackFunc cb)

cb must have the following signature: void myErrorCallback(int id, const char *error, void *user_ptr)

It is called when the channel experience an error, either while connecting or open.

int rtcSetMessageCallback(int id, rtcMessageCallbackFunc cb)

cb must have the following signature: void myMessageCallback(int id, const char *message, int size, void *user_ptr)

It is called when the channel receives a message. While it is set, messages can't be received with rtcReceiveMessage.

Track: By default, the track receives data as RTP packets.

int rtcSetBufferedAmountLowCallback(int id, rtcBufferedAmountLowCallbackFunc cb)

cb must have the following signature: void myBufferedAmountLowCallback(int id, void *user_ptr)

It is called when the buffered amount was strictly higher than the threshold (see rtcSetBufferedAmountLowThreshold) and is now lower or equal than the threshold.

int rtcSetAvailableCallback(int id, rtcAvailableCallbackFunc cb)

cb must have the following signature: void myAvailableCallback(int id, void *user_ptr)

It is called when messages are now available to be received with rtcReceiveMessage.

rtcSendMessage

int rtcSendMessage(int id, const char *data, int size)

Sends a message in the channel.

Arguments:

• id: the channel identifier
• data: the message data
• size: if size >= 0, data is interpreted as a binary message of length size, otherwise it is interpreted as a null-terminated UTF-8 string.

Return value: RTC_ERR_SUCCESS or a negative error code

The message is sent immediately if possible, otherwise it is buffered to be sent later.

Data Channel and WebSocket: If the message may not be sent immediately due to flow control or congestion control, it is buffered until it can actually be sent. You can retrieve the current buffered data size with rtcGetBufferedAmount.

Track: By default, the track expects RTP packets. There is no flow or congestion control, packets are never buffered and rtcGetBufferedAmount always returns 0.

rtcClose

int rtcClose(int id)

Close the channel.

Arguments:

• id: the channel identifier

Return value: RTC_ERR_SUCCESS or a negative error code

WebSocket: Like with the JavaScript API, the state will first change to closing, then closed only after the connection has been actually closed.

rtcDelete

int rtcDelete(int id)

Deletes the channel.

Arguments:

• id: the channel identifier

Return value: RTC_ERR_SUCCESS or a negative error code

If it is not already closed, the channel is implicitly closed before being deleted. After this function has been called, id must not be used in a function call anymore. This function will block until all scheduled callbacks of id return (except the one this function might be called in) and no other callback will be called for id after it returns.

rtcIsOpen

bool rtcIsOpen(int id)

Arguments:

• id: the channel identifier

Return value: true if the channel exists and is open, false otherwise

rtcIsClosed

bool rtcIsClosed(int id)

Arguments:

• id: the channel identifier

Return value: true if the channel exists and is closed (not open and not connecting), false otherwise

rtcMaxMessageSize

int rtcMaxMessageSize(int id)

Retrieves the maximum message size for the channel.

Arguments:

• id: the channel identifier

Return value: the maximum message size or a negative error code

rtcGetBufferedAmount

int rtcGetBufferedAmount(int id)

Retrieves the current buffered amount, i.e. the total size of currently buffered messages waiting to be actually sent in the channel. This does not account for the data buffered at the transport level.

Arguments:

• id: the channel identifier

Return value: the buffered amount or a negative error code

rtcSetBufferedAmountLowThreshold

int rtcSetBufferedAmountLowThreshold(int id, int amount)

Changes the buffered amount threshold under which BufferedAmountLowCallback is called. The callback is called when the buffered amount was strictly superior and gets equal to or lower than the threshold when a message is sent. The initial threshold is 0, meaning the the callback is called each time the buffered amount goes back to zero after being non-zero.

Arguments:

• id: the channel identifier
• amount: the new buffer level threshold

Return value: RTC_ERR_SUCCESS or a negative error code

rtcReceiveMessage

int rtcReceiveMessage(int id, char *buffer, int *size)

Receives a pending message if possible. The function may only be called if MessageCallback is not set.

Arguments:

• id: the channel identifier
• buffer: a user-supplied buffer where to write the message data
• size: a pointer to a user-supplied int which must be initialized to the size of buffer. On success, the function will write the size of the message to it before returning (positive size if binary, negative size including terminating 0 if string).

Return value: RTC_ERR_SUCCESS or a negative error code (In particular, RTC_ERR_NOT_AVAIL is returned when there are no pending messages)

If buffer is NULL, the message is not copied and kept pending but the size is still written to size.

Track: By default, the track receives data as RTP packets.

rtcGetAvailableAmount

int rtcGetAvailableAmount(int id)

Retrieves the available amount, i.e. the total size of messages pending reception with rtcReceiveMessage. The function may only be called if MessageCallback is not set.

Arguments:

• id: the channel identifier

Return value: the available amount or a negative error code

Data Channel

rtcCreateDataChannel

int rtcCreateDataChannel(int pc, const char *label)
int rtcCreateDataChannelEx(int pc, const char *label, const rtcDataChannelInit *init)

typedef struct {
	bool unordered;
	bool unreliable;
	unsigned int maxPacketLifeTime;
	unsigned int maxRetransmits;
} rtcReliability;

typedef struct {
	rtcReliability reliability;
	const char *protocol;
	bool negotiated;
	bool manualStream;
	uint16_t stream;
} rtcDataChannelInit;

Adds a Data Channel on a Peer Connection. The Peer Connection does not need to be connected, however, the Data Channel will be open only when the Peer Connection is connected.

Arguments:

• pc: identifier of the PeerConnection on which to add a Data Channel
• label: a user-defined UTF-8 string representing the Data Channel name
• init: a structure of initialization settings containing:
  • reliability: a structure of reliability settings containing:
    • unordered: if true, the Data Channel will not enforce message ordering, else it will be ordered
    • unreliable: if true, the Data Channel will not enforce strict reliability, else it will be reliable
    • maxPacketLifeTime: if unreliable, time window in milliseconds during which transmissions and retransmissions may occur
    • maxRetransmits: if unreliable and maxPacketLifeTime is 0, maximum number of attempted retransmissions (0 means no retransmission)
  • protocol (optional): a user-defined UTF-8 string representing the Data Channel protocol, empty if NULL
  • negotiated: if true, the Data Channel is assumed to be negotiated by the user and won't be negotiated by the WebRTC layer
  • manualStream: if true, the Data Channel will use stream as stream ID, else an available id is automatically selected
  • stream: if manualStream is true, the Data Channel will use it as stream ID, else it is ignored

rtcDataChannel() is equivalent to rtcDataChannelEx() with settings set to ordered, reliable, non-negotiated, with automatic stream ID selection (all flags set to false), and protocol set to an empty string.

Return value: the identifier of the new Data Channel or a negative error code.

The Data Channel must be deleted with rtcDeleteDataChannel (or rtcDelete).

If disableAutoNegotiation was not set in rtcConfiguration, the library will automatically initiate the negotiation by calling rtcSetLocalDescription internally. Otherwise, the user must call rtcSetLocalDescription to initiate the negotiation after creating the first Data Channel.

rtcDeleteDataChannel

int rtcDeleteDataChannel(int dc)

Deletes a Data Channel.

Arguments:

• dc: the Data Channel identifier

After this function has been called, dc must not be used in a function call anymore. This function will block until all scheduled callbacks of dc return (except the one this function might be called in) and no other callback will be called for dc after it returns.

rtcGetDataChannelStream

int rtcGetDataChannelStream(int dc)

Retrieves the stream ID of the Data Channel.

Arguments:

• dc: the Data Channel identifier

Return value: the stream ID or a negative error code

rtcGetDataChannelLabel

int rtcGetDataChannelLabel(int dc, char *buffer, int size)

Retrieves the label of a Data Channel.

Arguments:

• dc: the Data Channel identifier
• buffer: a user-supplied buffer to store the label
• size: the size of buffer

Return value: the length of the string copied in buffer (including the terminating null character) or a negative error code

If buffer is NULL, the label is not copied but the size is still returned.

rtcGetDataChannelProtocol

int rtcGetDataChannelProtocol(int dc, char *buffer, int size)

Retrieves the protocol of a Data Channel.

Arguments:

• dc: the Data Channel identifier
• buffer: a user-supplied buffer to store the protocol
• size: the size of buffer

Return value: the length of the string copied in buffer (including the terminating null character) or a negative error code

If buffer is NULL, the protocol is not copied but the size is still returned.

rtcGetDataChannelReliability

int rtcGetDataChannelReliability(int dc, rtcReliability *reliability)

Retrieves the reliability settings of a Data Channel. The function may be called irrelevant of how the Data Channel was created.

Arguments:

• dc: the Data Channel identifier
• reliability a user-supplied structure to fill

Return value: RTC_ERR_SUCCESS or a negative error code

Track

rtcAddTrack

int rtcAddTrack(int pc, const char *mediaDescriptionSdp)

Adds a new Track on a Peer Connection. The Peer Connection does not need to be connected, however, the Track will be open only when the Peer Connection is connected.

Arguments:

• pc: the Peer Connection identifier
• mediaDescriptionSdp: a null-terminated string specifying the corresponding media SDP. It must start with a m-line and include a mid parameter.

Return value: the identifier of the new Track or a negative error code

The new track must be deleted with rtcDeleteTrack (or rtcDelete).

The user must call rtcSetLocalDescription to negotiate the track.

rtcAddTrackEx

int rtcAddTrackEx(int pc, const rtcTrackInit *init)

typedef struct {
	rtcDirection direction;
	rtcCodec codec;
	int payloadType;
	uint32_t ssrc;
	const char *mid;
	const char *name;    // optional
	const char *msid;    // optional
	const char *trackId; // optional, track ID used in MSID
	const char *profile; // optional, codec profile
} rtcTrackInit;

Adds a new Track on a Peer Connection using a simplified initialization structure rather than a raw SDP media description. The function will generate the appropriate SDP media description from the provided codec and parameters.

Arguments:

• pc: the Peer Connection identifier
• init: a structure of initialization settings containing:
  • direction: the direction of the track, one of RTC_DIRECTION_SENDONLY, RTC_DIRECTION_RECVONLY, RTC_DIRECTION_SENDRECV, RTC_DIRECTION_INACTIVE, or RTC_DIRECTION_UNKNOWN
  • codec: the codec to use, one of the following:
    • Video: RTC_CODEC_H264, RTC_CODEC_VP8, RTC_CODEC_VP9, RTC_CODEC_H265, RTC_CODEC_AV1
    • Audio: RTC_CODEC_OPUS, RTC_CODEC_PCMU, RTC_CODEC_PCMA, RTC_CODEC_AAC, RTC_CODEC_G722
  • payloadType: the RTP payload type number
  • ssrc: the SSRC of the track
  • mid (optional): a null-terminated string for the media identifier (if NULL, defaults to "video" or "audio" based on the codec)
  • name (optional): a null-terminated CNAME string for the SSRC (NULL if unused)
  • msid (optional): a null-terminated MSID string for the SSRC (NULL if unused)
  • trackId (optional): a null-terminated track ID string used in the MSID (NULL if unused)
  • profile (optional): a null-terminated codec profile string (NULL if unused)

Return value: the identifier of the new Track or a negative error code

The new track must be deleted with rtcDeleteTrack (or rtcDelete).

The user must call rtcSetLocalDescription to negotiate the track.

rtcDeleteTrack

int rtcDeleteTrack(int tr)

Deletes a Track.

Arguments:

• tr: the Track identifier

After this function has been called, tr must not be used in a function call anymore. This function will block until all scheduled callbacks of tr return (except the one this function might be called in) and no other callback will be called for tr after it returns.

rtcGetTrackDescription

int rtcGetTrackDescription(int tr, char *buffer, int size)

Retrieves the SDP media description of a Track.

Arguments:

• tr: the Track identifier
• buffer: a user-supplied buffer to store the description
• size: the size of buffer

Return value: the length of the string copied in buffer (including the terminating null character) or a negative error code

If buffer is NULL, the description is not copied but the size is still returned.

rtcGetTrackMid

int rtcGetTrackMid(int tr, char *buffer, int size)

Retrieves the mid (media indentifier) of a Track.

Arguments:

• tr: the Track identifier
• buffer: a user-supplied buffer to store the mid
• size: the size of buffer

Return value: the length of the string copied in buffer (including the terminating null character) or a negative error code

If buffer is NULL, the mid is not copied but the size is still returned.

rtcGetTrackDirection

int rtcGetTrackDirection(int tr, rtcDirection *direction)

Retrieves the direction of a Track.

Arguments:

• tr: the Track identifier
• direction: a pointer to a rtcDirection enum to store the result

On success, the value pointed by direction will be set to one of the following: RTC_DIRECTION_SENDONLY, RTC_DIRECTION_RECVONLY, RTC_DIRECTION_SENDRECV, RTC_DIRECTION_INACTIVE, or RTC_DIRECTION_UNKNOWN.

rtcRequestKeyframe

int rtcRequestKeyframe(int tr)

Requests a keyframe from the remote peer for the Track by sending a PLI (Picture Loss Indication) RTCP message.

Arguments:

• tr: the Track identifier

Return value: RTC_ERR_SUCCESS or a negative error code

rtcRequestBitrate

int rtcRequestBitrate(int tr, unsigned int bitrate)

Requests a bitrate change from the remote peer for the Track by sending a REMB (Receiver Estimated Maximum Bitrate) RTCP message.

Arguments:

• tr: the Track identifier
• bitrate: the requested bitrate in bits per second

Return value: RTC_ERR_SUCCESS or a negative error code

rtcSetFrameCallback

int rtcSetFrameCallback(int tr, rtcFrameCallbackFunc cb)

typedef struct {
	uint32_t timestamp;
	uint8_t payloadType;
	double timestampSeconds; // negative means not available
} rtcFrameInfo;

Sets, changes, or unsets (if cb is NULL) the frame callback on a Track. This callback is designed to receive depacketized media frames rather than raw RTP packets.

cb must have the following signature: void myFrameCallback(int tr, const char *data, int size, const rtcFrameInfo *info, void *user_ptr)

Arguments:

• tr: the Track identifier
• cb: the frame callback, or NULL to unset

Return value: RTC_ERR_SUCCESS or a negative error code

The rtcFrameInfo structure provides additional metadata about the received frame:

• timestamp: RTP timestamp of the frame
• payloadType: RTP payload type
• timestampSeconds: the timestamp converted to seconds using the track's clock rate (negative value means not available)

Media handling

The Media handling API is available when the library is compiled with media support (RTC_ENABLE_MEDIA). It provides packetizers and depacketizers for common audio and video codecs, as well as RTCP handlers that can be chained on tracks.

rtcPacketizerInit

typedef enum {
	RTC_OBU_PACKETIZED_OBU = 0,
	RTC_OBU_PACKETIZED_TEMPORAL_UNIT = 1,
} rtcObuPacketization;

typedef enum {
	RTC_NAL_SEPARATOR_LENGTH = 0,               // first 4 bytes are NAL unit length
	RTC_NAL_SEPARATOR_LONG_START_SEQUENCE = 1,   // 0x00, 0x00, 0x00, 0x01
	RTC_NAL_SEPARATOR_SHORT_START_SEQUENCE = 2,  // 0x00, 0x00, 0x01
	RTC_NAL_SEPARATOR_START_SEQUENCE = 3,        // long or short start sequence
} rtcNalUnitSeparator;

typedef struct {
	uint32_t ssrc;
	const char *cname;
	uint8_t payloadType;
	uint32_t clockRate;
	uint16_t sequenceNumber;
	uint32_t timestamp;
	uint16_t maxFragmentSize;            // Maximum fragment size, 0 means default
	rtcNalUnitSeparator nalSeparator;    // H264/H265 only
	rtcObuPacketization obuPacketization; // AV1 only
	uint8_t playoutDelayId;
	uint16_t playoutDelayMin;
	uint16_t playoutDelayMax;
	uint8_t colorSpaceId;
	uint8_t colorChromaSitingHorz;
	uint8_t colorChromaSitingVert;
	uint8_t colorRange;
	uint8_t colorPrimaries;
	uint8_t colorTransfer;
	uint8_t colorMatrix;
} rtcPacketizerInit;

The rtcPacketizerInit structure is used to configure packetizers set on tracks. Its fields are:

• ssrc: the SSRC of the track
• cname: a null-terminated CNAME string (must not be NULL)
• payloadType: the RTP payload type number
• clockRate: the clock rate for the codec (e.g. 90000 for video, 48000 for Opus)
• sequenceNumber: the initial RTP sequence number
• timestamp: the initial RTP timestamp
• maxFragmentSize (optional): the maximum fragment size in bytes (0 for default)
• nalSeparator (H264/H265 only): the NAL unit separator type
• obuPacketization (AV1 only): the OBU packetization mode
• playoutDelayId (optional): the RTP extension ID for playout delay
• playoutDelayMin (optional): minimum playout delay in ms
• playoutDelayMax (optional): maximum playout delay in ms
• colorSpaceId (optional): the RTP extension ID for color space
• colorChromaSitingHorz (optional): horizontal chroma siting
• colorChromaSitingVert (optional): vertical chroma siting
• colorRange (optional): color range
• colorPrimaries (optional): color primaries
• colorTransfer (optional): color transfer characteristics
• colorMatrix (optional): color matrix coefficients

rtcSetXxxPacketizer

int rtcSetH264Packetizer(int tr, const rtcPacketizerInit *init)
int rtcSetH265Packetizer(int tr, const rtcPacketizerInit *init)
int rtcSetAV1Packetizer(int tr, const rtcPacketizerInit *init)
int rtcSetVP8Packetizer(int tr, const rtcPacketizerInit *init)
int rtcSetOpusPacketizer(int tr, const rtcPacketizerInit *init)
int rtcSetAACPacketizer(int tr, const rtcPacketizerInit *init)
int rtcSetPCMUPacketizer(int tr, const rtcPacketizerInit *init)
int rtcSetPCMAPacketizer(int tr, const rtcPacketizerInit *init)
int rtcSetG722Packetizer(int tr, const rtcPacketizerInit *init)

Sets a packetizer on a Track, which will transform media frames sent via rtcSendMessage into RTP packets before sending them. The packetizer is set as the media handler on the track.

Arguments:

• tr: the Track identifier
• init: a pointer to the rtcPacketizerInit structure (must not be NULL)

Return value: RTC_ERR_SUCCESS or a negative error code

rtcSetXxxDepacketizer

int rtcSetH264Depacketizer(int tr, rtcNalUnitSeparator nalSeparator)
int rtcSetH265Depacketizer(int tr, rtcNalUnitSeparator nalSeparator)
int rtcSetOpusDepacketizer(int tr)
int rtcSetAACDepacketizer(int tr)

Sets a depacketizer on a Track, which will reassemble incoming RTP packets into media frames. The depacketizer is set as the media handler on the track.

Arguments:

• tr: the Track identifier
• nalSeparator (H264/H265 only): the NAL unit separator to use in the output

Return value: RTC_ERR_SUCCESS or a negative error code

rtcSetMediaInterceptorCallback

int rtcSetMediaInterceptorCallback(int pc, rtcInterceptorCallbackFunc cb)

Sets, changes, or unsets (if cb is NULL) a media interceptor on a Peer Connection. The interceptor allows inspecting and modifying incoming RTP traffic on all tracks of the Peer Connection.

cb must have the following signature: void *myInterceptorCallback(int pc, const char *message, int size, void *user_ptr)

The callback should return:

• The original message pointer to forward the packet unchanged
• A pointer to an opaque message created with rtcCreateOpaqueMessage to replace the packet
• NULL to drop the packet

Arguments:

• pc: the Peer Connection identifier
• cb: the interceptor callback, or NULL to unset

Return value: RTC_ERR_SUCCESS or a negative error code

rtcCreateOpaqueMessage / rtcDeleteOpaqueMessage

rtcMessage *rtcCreateOpaqueMessage(void *data, int size)
void rtcDeleteOpaqueMessage(rtcMessage *msg)

rtcCreateOpaqueMessage allocates a new opaque message from a data buffer. The message must be explicitly freed with rtcDeleteOpaqueMessage unless it is returned by a media interceptor callback (in which case ownership is transferred).

rtcDeleteOpaqueMessage frees an opaque message previously created with rtcCreateOpaqueMessage.

Arguments:

• data: a pointer to the message data
• size: the size of the data in bytes
• msg: the opaque message to free

rtcChainRtcpReceivingSession

int rtcChainRtcpReceivingSession(int tr)

Chains an RTCP receiving session handler on a Track. This handler processes incoming RTCP packets.

Arguments:

• tr: the Track identifier

Return value: RTC_ERR_SUCCESS or a negative error code

rtcChainRtcpSrReporter

int rtcChainRtcpSrReporter(int tr)

Chains an RTCP Sender Report (SR) reporter handler on a Track. This handler automatically sends RTCP Sender Reports. A packetizer must be set on the track before calling this function.

Arguments:

• tr: the Track identifier

Return value: RTC_ERR_SUCCESS or a negative error code

rtcChainRtcpNackResponder

int rtcChainRtcpNackResponder(int tr, unsigned int maxStoredPacketsCount)

Chains an RTCP NACK responder handler on a Track. This handler stores sent packets and retransmits them when a NACK is received from the remote peer.

Arguments:

• tr: the Track identifier
• maxStoredPacketsCount: the maximum number of sent packets to store for potential retransmission

Return value: RTC_ERR_SUCCESS or a negative error code

rtcChainPliHandler

int rtcChainPliHandler(int tr, rtcPliHandlerCallbackFunc cb)

Chains a PLI (Picture Loss Indication) handler on a Track. The callback is called when a PLI RTCP message is received from the remote peer, indicating that the remote peer has lost some video data and is requesting a keyframe.

cb must have the following signature: void myPliHandlerCallback(int tr, void *user_ptr)

Arguments:

• tr: the Track identifier
• cb: the PLI handler callback

Return value: RTC_ERR_SUCCESS or a negative error code

rtcChainRembHandler

int rtcChainRembHandler(int tr, rtcRembHandlerCallbackFunc cb)

Chains a REMB (Receiver Estimated Maximum Bitrate) handler on a Track. The callback is called when a REMB RTCP message is received from the remote peer.

cb must have the following signature: void myRembHandlerCallback(int tr, unsigned int bitrate, void *user_ptr)

Arguments:

• tr: the Track identifier
• cb: the REMB handler callback

Return value: RTC_ERR_SUCCESS or a negative error code

rtcChainPacingHandler

int rtcChainPacingHandler(int tr, double bitsPerSecond, int sendIntervalMs)

Chains a pacing handler on a Track. This handler paces the sending of RTP packets to control outgoing bitrate.

Arguments:

• tr: the Track identifier
• bitsPerSecond: the target bitrate in bits per second
• sendIntervalMs: the send interval in milliseconds

Return value: RTC_ERR_SUCCESS or a negative error code

rtcTransformSecondsToTimestamp

int rtcTransformSecondsToTimestamp(int id, double seconds, uint32_t *timestamp)

Transforms a time value in seconds to an RTP timestamp using the track's clock rate. The track must have a packetizer set.

Arguments:

• id: the Track identifier
• seconds: the time value in seconds
• timestamp: a pointer to a uint32_t to store the result

Return value: RTC_ERR_SUCCESS or a negative error code

rtcTransformTimestampToSeconds

int rtcTransformTimestampToSeconds(int id, uint32_t timestamp, double *seconds)

Transforms an RTP timestamp to a time value in seconds using the track's clock rate. The track must have a packetizer set.

Arguments:

• id: the Track identifier
• timestamp: the RTP timestamp
• seconds: a pointer to a double to store the result

Return value: RTC_ERR_SUCCESS or a negative error code

rtcGetCurrentTrackTimestamp

int rtcGetCurrentTrackTimestamp(int id, uint32_t *timestamp)

Retrieves the current RTP timestamp for a track. The track must have a packetizer set.

Arguments:

• id: the Track identifier
• timestamp: a pointer to a uint32_t to store the result

Return value: RTC_ERR_SUCCESS or a negative error code

rtcSetTrackRtpTimestamp

int rtcSetTrackRtpTimestamp(int id, uint32_t timestamp)

Sets the RTP timestamp for a track. The track must have a packetizer set.

Arguments:

• id: the Track identifier
• timestamp: the RTP timestamp to set

Return value: RTC_ERR_SUCCESS or a negative error code

rtcGetLastTrackSenderReportTimestamp

int rtcGetLastTrackSenderReportTimestamp(int id, uint32_t *timestamp)

Retrieves the timestamp of the last RTCP Sender Report sent for the track. The track must have an RTCP SR reporter chained.

Arguments:

• id: the Track identifier
• timestamp: a pointer to a uint32_t to store the result

Return value: RTC_ERR_SUCCESS or a negative error code

rtcGetTrackRtcpSyncTimestamps

int rtcGetTrackRtcpSyncTimestamps(int tr, uint64_t *rtpTimestamp, uint64_t *ntpTimestamp)

Retrieves the RTP and NTP synchronization timestamps from the RTCP receiving session chained on the track. These timestamps are extracted from incoming RTCP Sender Reports and can be used to synchronize media streams. The track must have an RTCP receiving session chained (see rtcChainRtcpReceivingSession).

Arguments:

• tr: the Track identifier
• rtpTimestamp: a pointer to a uint64_t to store the RTP timestamp (may be NULL)
• ntpTimestamp: a pointer to a uint64_t to store the NTP timestamp (may be NULL)

Return value: RTC_ERR_SUCCESS or a negative error code

rtcGetTrackPayloadTypesForCodec

int rtcGetTrackPayloadTypesForCodec(int tr, const char *ccodec, int *buffer, int size)

Retrieves all available RTP payload types for a given codec name on the track.

Arguments:

• tr: the Track identifier
• ccodec: the codec name as a null-terminated string (case-insensitive)
• buffer: a user-supplied buffer to store payload types (may be NULL)
• size: the number of elements buffer can hold

Return value: the number of payload types found or a negative error code

If buffer is NULL, the payload types are not stored but the count is still returned.

rtcGetSsrcsForTrack

int rtcGetSsrcsForTrack(int tr, uint32_t *buffer, int count)

Retrieves all SSRCs declared for a given track.

Arguments:

• tr: the Track identifier
• buffer: a user-supplied buffer to store SSRCs (may be NULL)
• count: the number of elements buffer can hold

Return value: the number of SSRCs found or a negative error code

If buffer is NULL, the SSRCs are not stored but the count is still returned.

rtcGetCNameForSsrc

int rtcGetCNameForSsrc(int tr, uint32_t ssrc, char *cname, int cnameSize)

Retrieves the CNAME associated with a given SSRC on a track.

Arguments:

• tr: the Track identifier
• ssrc: the SSRC to look up
• cname: a user-supplied buffer to store the CNAME
• cnameSize: the size of cname

Return value: the length of the string copied (including the terminating null character), 0 if no CNAME was found, or a negative error code

rtcGetSsrcsForType

int rtcGetSsrcsForType(const char *mediaType, const char *sdp, uint32_t *buffer, int bufferSize)

Retrieves all SSRCs for a given media type (e.g. "video" or "audio") from an SDP description string.

Arguments:

• mediaType: the media type string (case-insensitive), e.g. "video" or "audio"
• sdp: the SDP description string
• buffer: a user-supplied buffer to store SSRCs (may be NULL)
• bufferSize: the number of elements buffer can hold

Return value: the number of SSRCs found or a negative error code

If buffer is NULL, the SSRCs are not stored but the count is still returned.

rtcSetSsrcForType

int rtcSetSsrcForType(const char *mediaType, const char *sdp, char *buffer, const int bufferSize, rtcSsrcForTypeInit *init)

typedef struct {
	uint32_t ssrc;
	const char *name;    // optional
	const char *msid;    // optional
	const char *trackId; // optional, track ID used in MSID
} rtcSsrcForTypeInit;

Sets the SSRC for a given media type in an SDP description string and writes the modified SDP to buffer.

Arguments:

• mediaType: the media type string (case-insensitive), e.g. "video" or "audio"
• sdp: the original SDP description string
• buffer: a user-supplied buffer to store the modified SDP
• bufferSize: the size of buffer
• init: a structure containing:
  • ssrc: the SSRC to set
  • name (optional): a CNAME string (NULL if unused)
  • msid (optional): an MSID string (NULL if unused)
  • trackId (optional): a track ID string used in MSID (NULL if unused)

Return value: the length of the string copied in buffer (including the terminating null character) or a negative error code

WebSocket

rtcCreateWebSocket

int rtcCreateWebSocket(const char *url)
int rtcCreateWebSocketEx(const char *url, const rtcWsConfiguration *config)

typedef struct {
	bool disableTlsVerification;
	const char *proxyServer;
	const char **protocols;
	int protocolsCount;
	int connectionTimeoutMs;
	int pingIntervalMs;
	int maxOutstandingPings;
	int maxMessageSize;
} rtcWsConfiguration;

Creates a new client WebSocket.

Arguments:

• url: a null-terminated string representing the fully-qualified URL to open.
• config: a structure with the following parameters:
  • disableTlsVerification: if true, don't verify the TLS certificate, else try to verify it if possible
  • proxyServer (optional): if non-NULL, specifies the proxy server URI to use (only non-authenticated HTTP proxies are supported for now)
  • protocols (optional): an array of pointers on null-terminated protocol names (NULL if unused)
  • protocolsCount (optional): number of URLs in the array pointed by protocols (0 if unused)
  • connectionTimeoutMs (optional): connection timeout in milliseconds (0 if default, < 0 if disabled)
  • pingIntervalMs (optional): ping interval in milliseconds (0 if default, < 0 if disabled)
  • maxOutstandingPings (optional): number of unanswered pings before declaring failure (0 if default, < 0 if disabled)
  • maxMessageSize (optional): maximum message size in bytes (<= 0 if default)

Return value: the identifier of the new WebSocket or a negative error code

The new WebSocket must be deleted with rtcDeleteWebSocket (or rtcDelete). The scheme of the URL must be either ws or wss.

rtcDeleteWebSocket

int rtcDeleteWebSocket(int ws)

Arguments:

• ws: the identifier of the WebSocket to delete

After this function has been called, ws must not be used in a function call anymore. This function will block until all scheduled callbacks of ws return (except the one this function might be called in) and no other callback will be called for ws after it returns.

rtcGetWebSocketRemoteAddress

int rtcGetWebSocketRemoteAddress(int ws, char *buffer, int size)

Retrieves the remote address, i.e. the network address of the remote endpoint. The address will have the format "HOST:PORT". The call may fail if the underlying TCP transport of the WebSocket is not connected. This function is useful for a client WebSocket received by a WebSocket Server.

Arguments:

• ws: the identifier of the WebSocket
• buffer: a user-supplied buffer to store the description
• size: the size of buffer

Return value: the length of the string copied in buffer (including the terminating null character) or a negative error code

If buffer is NULL, the address is not copied but the size is still returned.

rtcGetWebSocketPath

int rtcGetWebSocketPath(int ws, char *buffer, int size)

Retrieves the path of the WebSocket, i.e. the HTTP requested path. This function is useful for a client WebSocket received by a WebSocket Server. Warning: The WebSocket must be open for the call to succeed.

Arguments:

• ws: the identifier of the WebSocket
• buffer: a user-supplied buffer to store the description
• size: the size of buffer

Return value: the length of the string copied in buffer (including the terminating null character) or a negative error code

If buffer is NULL, the path is not copied but the size is still returned.

WebSocket Server

rtcCreateWebSocketServer

int rtcCreateWebSocketServer(const rtcWsServerConfiguration *config, rtcWebSocketClientCallbackFunc cb);

typedef struct {
	uint16_t port;
	bool enableTls;
	const char *certificatePemFile;
	const char *keyPemFile;
	const char *keyPemPass;
	const char *bindAddress;
	int connectionTimeoutMs;
	int maxMessageSize;
} rtcWsServerConfiguration;

Creates a new WebSocket server.

Arguments:

• config: a structure with the following parameters:
  • port: the port to listen on (if 0, automatically select an available port)
  • enableTls: if true, enable the TLS layer (WSS)
  • certificatePemFile (optional): PEM certificate or path of the file containing the PEM certificate (NULL for an autogenerated certificate)
  • keyPemFile (optional): PEM key or path of the file containing the PEM key (NULL for an autogenerated certificate)
  • keyPemPass (optional): PEM key file passphrase (NULL if no passphrase)
  • bindAddress (optional): if non-NULL, bind only to the given local address (NULL for any)
  • connectionTimeoutMs (optional): connection timeout in milliseconds (0 if default, < 0 if disabled)
  • maxMessageSize (optional): maximum message size in bytes (<= 0 if default)
• cb: the callback for incoming client WebSocket connections (must not be NULL)

cb must have the following signature: void rtcWebSocketClientCallbackFunc(int wsserver, int ws, void *user_ptr)

Return value: the identifier of the new WebSocket Server or a negative error code

The new WebSocket Server must be deleted with rtcDeleteWebSocketServer.

rtcDeleteWebSocketServer

int rtcDeleteWebSocketServer(int wsserver)

Arguments:

• wsserver: the identifier of the WebSocket Server to delete

After this function has been called, wsserver must not be used in a function call anymore. This function will block until all scheduled callbacks of wsserver return (except the one this function might be called in) and no other callback will be called for wsserver after it returns.

rtcGetWebSocketServerPort

int rtcGetWebSocketServerPort(int wsserver);

Retrieves the port which the WebSocket Server is listening on.

Arguments:

• wsserver: the identifier of the WebSocket Server

Return value: The port of the WebSocket Server or a negative error code

Global settings

rtcSetThreadPoolSize

int rtcSetThreadPoolSize(unsigned int count)

Sets the number of threads used for the internal thread pool. The change is applied when threads are spawned (typically when the first Peer Connection is created).

Arguments:

• count: the number of threads to use (0 means using the hardware concurrency)

Return value: RTC_ERR_SUCCESS or a negative error code

rtcSetSctpSettings

int rtcSetSctpSettings(const rtcSctpSettings *settings)

typedef struct {
	int recvBufferSize;             // in bytes, <= 0 means optimized default
	int sendBufferSize;             // in bytes, <= 0 means optimized default
	int maxChunksOnQueue;           // in chunks, <= 0 means optimized default
	int initialCongestionWindow;    // in MTUs, <= 0 means optimized default
	int maxBurst;                   // in MTUs, 0 means optimized default, < 0 means disabled
	int congestionControlModule;    // 0: RFC2581 (default), 1: HSTCP, 2: H-TCP, 3: RTCC
	int delayedSackTimeMs;          // in milliseconds, 0 means optimized default, < 0 means disabled
	int minRetransmitTimeoutMs;     // in milliseconds, <= 0 means optimized default
	int maxRetransmitTimeoutMs;     // in milliseconds, <= 0 means optimized default
	int initialRetransmitTimeoutMs; // in milliseconds, <= 0 means optimized default
	int maxRetransmitAttempts;      // number of retransmissions, <= 0 means optimized default
	int heartbeatIntervalMs;        // in milliseconds, <= 0 means optimized default
} rtcSctpSettings;

Sets the SCTP settings for the library. SCTP settings apply to newly-created PeerConnections only and do not affect existing ones.

Arguments:

• settings: a structure with the SCTP configuration parameters:
  • recvBufferSize (optional): receive buffer size in bytes (<= 0 for optimized default)
  • sendBufferSize (optional): send buffer size in bytes (<= 0 for optimized default)
  • maxChunksOnQueue (optional): maximum number of chunks on the send queue (<= 0 for optimized default)
  • initialCongestionWindow (optional): initial congestion window in MTUs (<= 0 for optimized default)
  • maxBurst (optional): maximum burst size in MTUs (0 for optimized default, < 0 to disable)
  • congestionControlModule (optional): congestion control module (0: RFC2581, 1: HSTCP, 2: H-TCP, 3: RTCC)
  • delayedSackTimeMs (optional): delayed SACK time in milliseconds (0 for optimized default, < 0 to disable)
  • minRetransmitTimeoutMs (optional): minimum retransmit timeout in milliseconds (<= 0 for optimized default)
  • maxRetransmitTimeoutMs (optional): maximum retransmit timeout in milliseconds (<= 0 for optimized default)
  • initialRetransmitTimeoutMs (optional): initial retransmit timeout in milliseconds (<= 0 for optimized default)
  • maxRetransmitAttempts (optional): maximum number of retransmission attempts (<= 0 for optimized default)
  • heartbeatIntervalMs (optional): heartbeat interval in milliseconds (<= 0 for optimized default)

Return value: RTC_ERR_SUCCESS or a negative error code