diff --git a/feeds/all.atom.xml b/feeds/all.atom.xml index 1ce798e09..fcc422ee8 100644 --- a/feeds/all.atom.xml +++ b/feeds/all.atom.xml @@ -1,2 +1,2 @@ -libdatachannelhttps://libdatachannel.org/2022-12-13T10:47:16Z \ No newline at end of file +libdatachannelhttps://libdatachannel.org/2023-05-11T11:26:10Z \ No newline at end of file diff --git a/index.html b/index.html index 72727c5f3..2b3f5937a 100644 --- a/index.html +++ b/index.html @@ -45,46 +45,46 @@

-
-

libdatachannel is an open-source software library implementing WebRTC Data Channels, WebRTC Media Transport, and WebSockets. It is written in C++17 and offers C bindings. The source code is available under MPL 2.0, and the library is on AUR, Vcpkg, and FreeBSD Ports.

- -
-
- -

Easy

-
    -
  • Simple API inspired by the JavaScript API including WebSocket for signaling
  • -
  • Minimal external dependencies (only OpenSSL or GnuTLS) -
  • Lightweight and way easier to compile and use than Google's reference library -
-
-
- -

Compatible

-
    -
  • Compatible with browsers Firefox, Chromium, and Safari, and other WebRTC libraries (see webrtc-echoes)
  • -
  • Licensed under MPL 2.0, meaning software with any license may use the library
  • -
  • Community-maintained bindings available for Rust, Node.js, and Unity
  • -
-
-
- -

Portable

-
    -
  • Support for POSIX platforms (including GNU/Linux, Android, FreeBSD, Apple macOS and iOS) and Microsoft Windows
  • -
  • Support for both OpenSSL and GnuTLS as TLS backend -
  • Code using Data Channels and WebSockets may be compiled as-is to WebAssembly for browsers with datachannel-wasm
  • -
-
-
back to top diff --git a/pages/reference.html b/pages/reference.html index 077e2ac9d..6ae6b82ae 100644 --- a/pages/reference.html +++ b/pages/reference.html @@ -58,9 +58,7 @@

General considerations

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)
-
- +

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.
  • @@ -74,20 +72,14 @@

    rtcInitLogger

  • message: a null-terminated string containing the log message

rtcPreload

-
void rtcPreload(void)
-
- +

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)
-
- +

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)
-
- +

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:

    @@ -96,30 +88,29 @@

    rtcSetUserPointer

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;
-
- +

``` +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:
  • +
  • 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)
    • @@ -131,19 +122,19 @@

      rtcCreatePeerConnection

    • 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 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)
-
- +

int rtcClosePeerConnection(int pc)

Closes the Peer Connection.

Arguments:

    @@ -151,9 +142,7 @@

    rtcClosePeerConnection

Return value: RTC_ERR_SUCCESS or a negative error code

rtcDeletePeerConnection

-
int rtcDeletePeerConnection(int pc)
-
- +

int rtcDeletePeerConnection(int pc)

Deletes the Peer Connection.

Arguments:

    @@ -163,36 +152,22 @@

    rtcDeletePeerConnection

    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)*
    -
    - +

    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)
    -
    - +

    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)
    -
    - +

    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 rtcSetGatheringStateChangeCallback(int pc, rtcGatheringStateCallbackFunc cb)
    -
    - +

    int rtcSetGatheringStateChangeCallback(int pc, rtcGatheringStateCallbackFunc cb)

    void myGatheringStateCallback(int pc, rtcGatheringState state, void *user_ptr)

    state will be RTC_GATHERING_INPROGRESS or RTC_GATHERING_COMPLETE.

    -
    int rtcSetDataChannelCallback(int pc, rtcDataChannelCallbackFunc cb)
    -
    - +

    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)
    -
    - +

    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)
    -
    - +

    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:

      @@ -200,9 +175,7 @@

      rtcSetLocalDescription

    • type (optional): type of the description ("offer", "answer", "pranswer", or "rollback") or NULL for autodetection.

    rtcSetRemoteDescription

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

    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:

      @@ -211,9 +184,7 @@

      rtcSetRemoteDescription

    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)
    -
    - +

    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:

      @@ -224,9 +195,7 @@

      rtcAddRemoteCandidate

      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)
      -
      - +

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

      Retrieves the current local description in SDP format.

      Arguments:

        @@ -237,9 +206,7 @@

        rtcGetLocalDescription

        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)
        -
        - +

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

        Retrieves the current remote description in SDP format.

        Arguments:

          @@ -250,9 +217,7 @@

          rtcGetRemoteDescription

          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)
          -
          - +

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

          Retrieves the current local description type as string.

          Arguments:

            @@ -263,9 +228,7 @@

            rtcGetLocalDescriptionType

            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 rtcGetRemoteDescriptionType(int pc, char *buffer, int size)
            -
            - +

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

            Retrieves the current remote description type as string.

            Arguments:

              @@ -276,9 +239,7 @@

              rtcGetRemoteDescription

              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)
              -
              - +

              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:

                @@ -289,9 +250,7 @@

                rtcGetLocalAddress

                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)
                -
                - +

                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:

                  @@ -302,9 +261,7 @@

                  rtcGetRemoteAddress

                  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)
                  -
                  - +

                  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:

                    @@ -317,9 +274,7 @@

                    rtcGetSelectedCandidatePair

                    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.

                    rtcGetMaxDataChannelStream

                    -
                    int rtcGetMaxDataChannelStream(int pc);
                    -
                    - +

                    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

                    @@ -328,41 +283,27 @@

                    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)
                    -
                    - +

                    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)
                    -
                    - +

                    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)
                    -
                    - +

                    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)
                    -
                    - +

                    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)
                    -
                    - +

                    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)
                    -
                    - +

                    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)
                    -
                    - +

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

                    Sends a message in the channel.

                    Arguments:

                      @@ -375,9 +316,7 @@

                      rtcSendMessage

                      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)
                      -
                      - +

                      int rtcClose(int id)

                      Close the channel.

                      Arguments:

                        @@ -386,9 +325,7 @@

                        rtcClose

                        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)
                        -
                        - +

                        int rtcDelete(int id)

                        Deletes the channel.

                        Arguments:

                          @@ -397,27 +334,21 @@

                          rtcDelete

                          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)
                          -
                          - +

                          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)
                          -
                          - +

                          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

                          rtcGetBufferedAmount

                          -
                          int rtcGetBufferedAmount(int id)
                          -
                          - +

                          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:

                            @@ -425,9 +356,7 @@

                            rtcGetBufferedAmount

                          Return value: the buffered amount or a negative error code

                          rtcSetBufferedAmountLowThreshold

                          -
                          int rtcSetBufferedAmountLowThreshold(int id, int amount)
                          -
                          - +

                          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:

                            @@ -436,9 +365,7 @@

                            rtcSetBufferedAmountLowThreshold

                          Return value: RTC_ERR_SUCCESS or a negative error code

                          rtcReceiveMessage

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

                          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:

                            @@ -450,9 +377,7 @@

                            rtcReceiveMessage

                            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)
                            -
                            - +

                            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:

                              @@ -461,31 +386,29 @@

                              rtcGetAvailableAmount

                              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;
                              -
                              - +

                              ``` +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:
                              • +
                              • 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
                                  • @@ -498,14 +421,14 @@

                                    rtcCreateDataChannel

                                  • 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)
                                -
                                - +

                                int rtcDeleteDataChannel(int dc)

                                Deletes a Data Channel.

                                Arguments:

                                  @@ -513,9 +436,7 @@

                                  rtcDeleteDataChannel

                                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)
                                -
                                - +

                                int rtcGetDataChannelStream(int dc)

                                Retrieves the stream ID of the Data Channel.

                                Arguments:

                                  @@ -523,9 +444,7 @@

                                  rtcGetDataChannelStream

                                Return value: the stream ID or a negative error code

                                rtcGetDataChannelLabel

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

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

                                Retrieves the label of a Data Channel.

                                Arguments:

                                  @@ -536,9 +455,7 @@

                                  rtcGetDataChannelLabel

                                  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)
                                  -
                                  - +

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

                                  Retrieves the protocol of a Data Channel.

                                  Arguments:

                                    @@ -549,9 +466,7 @@

                                    rtcGetDataChannelProtocol

                                    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)
                                    -
                                    - +

                                    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:

                                      @@ -561,9 +476,7 @@

                                      rtcGetDataChannelReliability

                                      Return value: RTC_ERR_SUCCESS or a negative error code

                                      Track

                                      rtcAddTrack

                                      -
                                      int rtcAddTrack(int pc, const char *mediaDescriptionSdp)
                                      -
                                      - +

                                      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:

                                        @@ -574,9 +487,7 @@

                                        rtcAddTrack

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

                                        The user must call rtcSetLocalDescription to negotiate the track.

                                        rtcDeleteTrack

                                        -
                                        int rtcDeleteTrack(int tr)
                                        -
                                        - +

                                        int rtcDeleteTrack(int tr)

                                        Deletes a Track.

                                        Arguments:

                                          @@ -584,9 +495,7 @@

                                          rtcDeleteTrack

                                        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)
                                        -
                                        - +

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

                                        Retrieves the SDP media description of a Track.

                                        Arguments:

                                          @@ -597,9 +506,7 @@

                                          rtcGetTrackDescription

                                          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)
                                          -
                                          - +

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

                                          Retrieves the mid (media indentifier) of a Track.

                                          Arguments:

                                            @@ -610,9 +517,7 @@

                                            rtcGetTrackMid

                                            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)
                                            -
                                            - +

                                            int rtcGetTrackDirection(int tr, rtcDirection *direction)

                                            Retrieves the direction of a Track.

                                            Arguments:

                                              @@ -624,44 +529,41 @@

                                              Media handling

                                              TODO

                                              WebSocket

                                              rtcCreateWebSocket

                                              -
                                              int rtcCreateWebSocket(const char *url)
                                              -int rtcCreateWebSocketEx(const char *url, const rtcWsConfiguration *config)
                                              -
                                              -typedef struct {
                                              -    bool disableTlsVerification;
                                              -    const char **protocols;
                                              -    int protocolsCount;
                                              -    int pingInterval;
                                              -    int maxOutstandingPings;
                                              -} rtcWsConfiguration;
                                              -
                                              - +

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

                                              +

                                              typedef struct { + bool disableTlsVerification; + const char **protocols; + int protocolsCount; + int pingInterval; + int maxOutstandingPings; +} 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:
                                              • +
                                              • config: a structure with the following parameters:
                                                • disableTlsVerification: if true, don't verify the TLS certificate, else try to verify it if possible
                                                • 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)
                                                • pingInterval (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)
                                                +
                                              • +

                                              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)
                                              -
                                              - +

                                              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)
                                              -
                                              - +

                                              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:

                                                @@ -672,9 +574,7 @@

                                                rtcGetWebSocketRemoteAddress

                                                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)
                                                -
                                                - +

                                                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:

                                                  @@ -686,44 +586,41 @@

                                                  rtcGetWebSocketPath

                                                  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;
                                                  -} rtcWsServerConfiguration;
                                                  -
                                                  - +

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

                                                  +

                                                  typedef struct { + uint16_t port; + bool enableTls; + const char certificatePemFile; + const char keyPemFile; + const char *keyPemPass; +} rtcWsServerConfiguration; +```

                                                  Creates a new WebSocket server.

                                                  Arguments:

                                                    -
                                                  • config: a structure with the following parameters:
                                                  • +
                                                  • 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)
                                                    • +
                                                    +
                                                  • 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)
                                                  -
                                                  - +

                                                  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);
                                                  -
                                                  - +

                                                  int rtcGetWebSocketServerPort(int wsserver);

                                                  Retrieves the port which the WebSocket Server is listening on.

                                                  Arguments: