Skip to content

API-functions.md

Latest commit

 

History

History
3762 lines (2695 loc) · 193 KB

API-functions.md

File metadata and controls

3762 lines (2695 loc) · 193 KB

SRT API Functions

Library Initialization

Function / Structure Description
srt_startup Called at the start of an application that uses the SRT library
srt_cleanup Cleans up global SRT resources before exiting an application

Creating and Configuring Sockets

Function / Structure Description
srt_socket Deprecated
srt_create_socket Creates an SRT socket
srt_bind Binds a socket to a local address and port
srt_bind_acquire Acquires a given UDP socket instead of creating one
srt_getsockstate Gets the current status of the socket
srt_getsndbuffer Retrieves information about the sender buffer
srt_getmaxpayloadsize Retrieves the information about the maximum payload size in a single packet
srt_close Closes the socket or group and frees all used resources
srt_close_withreason Closes the socket or group and frees all used resources (with setting the reason code)

Connecting

Function / Structure Description
srt_listen Sets up the listening state on a socket
srt_accept Accepts a connection; creates/returns a new socket or group ID
srt_accept_bond Accepts a connection pending on any sockets passed in the listeners array
of nlisteners size
srt_listen_callback Installs/executes a callback hook on a socket created to handle the incoming connection
on a listening socket
srt_connect Connects a socket or a group to a remote party with a specified address and port
srt_connect_bind Same as srt_bind then srt_connect if called with socket u
srt_connect_debug Same as srt_connectbut allows specifying ISN (developers only)
srt_rendezvous Performs a rendezvous connection
srt_connect_callback Installs/executes a callback hook on socket/group u after connection resolution/failure

Socket Group Management

Since SRT v1.5.0.

Function / Structure Description
SRT_GROUP_TYPE Group types collected in an SRT_GROUP_TYPE enum
SRT_SOCKGROUPCONFIG Structure used to define entry points for connections for srt_connect_group
SRT_SOCKGROUPDATA Most important structure for group member status
SRT_MEMBERSTATUS Enumeration type that defines the state of a member connection in the group
srt_create_group Creates a new group of type type
srt_groupof Returns the group ID of a socket, or SRT_INVALID_SOCK
srt_group_data Obtains the current member state of the group specified in socketgroup
srt_connect_group Similar to calling srt_connect or srt_connect_bind
in a loop for every item in an array.
srt_prepare_endpoint Prepares a default SRT_SOCKGROUPCONFIG object as an element of
an array for srt_connect_group
srt_create_config Creates a dynamic object for specifying socket options
srt_delete_config Deletes the configuration object
srt_config_add Adds a configuration option to the configuration object

Options and Properties

Function / Structure Description
srt_getpeername Retrieves the remote address to which the socket is connected
srt_getsockname Extracts the address to which the socket was bound
srt_getsockopt Gets the value of the given socket option (from a socket or a group)
srt_getsockflag Gets the value of the given socket option (from a socket or a group)
srt_setsockopt Sets a value for a socket option in the socket or group
srt_setsockflag Sets a value for a socket option in the socket or group
srt_getversion Get SRT version value

Helper Data Types for Transmission

Function / Structure Description
SRT_MSGCTRL Used in srt_sendmsg2 and srt_recvmsg2 calls;
specifies some extra parameters

Transmission

Function / Structure Description
srt_send Sends a payload to a remote party over a given socket
srt_sendmsg Sends a payload to a remote party over a given socket
srt_sendmsg2 Sends a payload to a remote party over a given socket
srt_recv Extracts the payload waiting to be received
srt_recvmsg Extracts the payload waiting to be received
srt_recvmsg2 Extracts the payload waiting to be received
srt_sendfile Function dedicated to sending a file
srt_recvfile Function dedicated to receiving a file

Performance Tracking

Function / Structure Description
srt_bstats Reports the current statistics
srt_bistats Reports the current statistics

Asynchronous Operations (Epoll)

Function / Structure Description
srt_epoll_create Creates a new epoll container
srt_epoll_add_usock Adds a user socket to a container, or updates an existing socket subscription
srt_epoll_add_ssock Adds a system socket to a container, or updates an existing socket subscription
srt_epoll_update_usock Adds a user socket to a container, or updates an existing socket subscription
srt_epoll_update_ssock Adds a system socket to a container, or updates an existing socket subscription
srt_epoll_remove_usock Removes a specified user socket from an epoll container; clears all readiness states for that socket
srt_epoll_remove_ssock Removes a specified system socket from an epoll container; clears all readiness states for that socket
srt_epoll_wait Blocks the call until any readiness state occurs in the epoll container
srt_epoll_uwait Blocks a call until any readiness state occurs in the epoll container
srt_epoll_clear_usocks removes all SRT ("user") socket subscriptions from the epoll container identified by eid
srt_epoll_set Allows setting or retrieving flags that change the default behavior of the epoll functions
srt_epoll_release Deletes the epoll container

Logging Control

Function / Structure Description
srt_setloglevel Sets the minimum severity for logging
srt_addlogfa Add a functional area (FA), which is an additional filtering mechanism for logging
srt_dellogfa Delete a functional area (FA), which is an additional filtering mechanism for logging
srt_resetlogfa Reset a functional area (FA), which is an additional filtering mechanism for logging
srt_setloghandler Replaces default standard stream for error logging
srt_setlogflags Allows configuring parts of log information that are not to be passed

Time Access

Function / Structure Description
srt_time_now Get time in microseconds elapsed since epoch using SRT internal clock
(steady or monotonic clock)
srt_connection_time Get connection time in microseconds elapsed since epoch using SRT internal clock
(steady or monotonic clock)
srt_clock_type Get the type of clock used internally by SRT

Diagnostics

Function / Structure Description
srt_getlasterror Get the numeric code of the last error
srt_strerror Returns a string message that represents a given SRT error code and possibly
the errno value, if not 0
srt_getlasterror_str Gets the text message for the last error
srt_clearlasterror Clears the last error
srt_rejectreason_str Returns a constant string for the reason of the connection rejected, as per given code ID
srt_setrejectreason Sets the rejection code on the socket
srt_getrejectreason Provides a detailed reason for a failed connection attempt
srt_close_getreason Provides a detailed reason for closing a socket

Rejection Reasons

Rejection Reason Since Description
SRT_REJ_UNKNOWN 1.3.4 A fallback value for cases when there was no connection rejected
SRT_REJ_SYSTEM 1.3.4 A system function reported a failure
SRT_REJ_PEER 1.3.4 The connection has been rejected by peer, but no further details are available
SRT_REJ_RESOURCE 1.3.4 A problem with resource allocation (usually memory)
SRT_REJ_ROGUE 1.3.4 The data sent by one party to another cannot be properly interpreted
SRT_REJ_BACKLOG 1.3.4 The listener's backlog has exceeded
SRT_REJ_IPE 1.3.4 Internal Program Error
SRT_REJ_CLOSE 1.3.4 The listener socket received a request as it is being closed
SRT_REJ_VERSION 1.3.4 A party did not satisfy the minimum version requirement that had been set up for a connection
SRT_REJ_RDVCOOKIE 1.3.4 Rendezvous cookie collision
SRT_REJ_BADSECRET 1.3.4 Both parties have defined a passphrase for connection and they differ
SRT_REJ_UNSECURE 1.3.4 Only one connection party has set up a password
SRT_REJ_MESSAGEAPI 1.3.4 The value for SRTO_MESSAGEAPI flag is different on the peer
SRT_REJ_FILTER 1.3.4 The SRTO_PACKETFILTER option is set differently on the peer
SRT_REJ_GROUP 1.4.2 The group type or some group settings are incompatible for both connection parties
SRT_REJ_TIMEOUT 1.4.2 The connection wasn't rejected, but it timed out
SRT_REJ_CRYPTO 1.5.2 The connection was rejected due to an unsupported or mismatching encryption mode
SRT_REJ_CONFIG 1.6.0 The connection was rejected because settings on both parties are in collision and cannot negotiate common values

See the full list in Rejection Reason Codes.

Error Codes

Error Code Description
SRT_EUNKNOWN Internal error when setting the right error code
SRT_SUCCESS The value set when the last error was cleared and no error has occurred since then
SRT_ECONNSETUP General setup error resulting from internal system state
SRT_ENOSERVER Connection timed out while attempting to connect to the remote address
SRT_ECONNREJ Connection has been rejected
SRT_ESOCKFAIL An error occurred when trying to call a system function on an internally used UDP socket
SRT_ESECFAIL A possible tampering with the handshake packets was detected, or encryption request
wasn't properly fulfilled.
SRT_ESCLOSED A socket that was vital for an operation called in blocking mode has been closed
during the operation
SRT_ECONNFAIL General connection failure of unknown details
SRT_ECONNLOST The socket was properly connected, but the connection has been broken
SRT_ENOCONN The socket is not connected
SRT_ERESOURCE System or standard library error reported unexpectedly for unknown purpose
SRT_ETHREAD System was unable to spawn a new thread when required
SRT_ENOBUF System was unable to allocate memory for buffers
SRT_ESYSOBJ System was unable to allocate system specific objects
SRT_EFILE General filesystem error (for functions operating with file transmission)
SRT_EINVRDOFF Failure when trying to read from a given position in the file
SRT_ERDPERM Read permission was denied when trying to read from file
SRT_EINVWROFF Failed to set position in the written file
SRT_EWRPERM Write permission was denied when trying to write to a file
SRT_EINVOP Invalid operation performed for the current state of a socket
SRT_EBOUNDSOCK The socket is currently bound and the required operation cannot be performed in this state
SRT_ECONNSOCK The socket is currently connected and therefore performing the required operation is not possible
SRT_EINVPARAM Call parameters for API functions have some requirements that were not satisfied
SRT_EINVSOCK The API function required an ID of an entity (socket or group) and it was invalid
SRT_EUNBOUNDSOCK The operation to be performed on a socket requires that it first be explicitly bound
SRT_ENOLISTEN The socket passed for the operation is required to be in the listen state
SRT_ERDVNOSERV The required operation cannot be performed when the socket is set to rendezvous mode
SRT_ERDVUNBOUND An attempt was made to connect to a socket set to rendezvous mode that was not first bound
SRT_EINVALMSGAPI The function was used incorrectly in the message API
SRT_EINVALBUFFERAPI The function was used incorrectly in the stream (buffer) API
SRT_EDUPLISTEN The port tried to be bound for listening is already busy
SRT_ELARGEMSG Size exceeded
SRT_EINVPOLLID The epoll ID passed to an epoll function is invalid
SRT_EPOLLEMPTY The epoll container currently has no subscribed sockets
SRT_EASYNCFAIL General asynchronous failure (not in use currently)
SRT_EASYNCSND Sending operation is not ready to perform
SRT_EASYNCRCV Receiving operation is not ready to perform
SRT_ETIMEOUT The operation timed out
SRT_ECONGEST With SRTO_TSBPDMODE and SRTO_TLPKTDROP set to true,
some packets were dropped by sender
SRT_EPEERERR Receiver peer is writing to a file that the agent is sending

Diagnostics and return types

The SRT API functions usually report a status of the operation that they attempt to perform. There are three general possibilities to report a success or failure, possibly with some extra information:

  1. SRTSTATUS is usually an integer value with two possible variants:

    • SRT_STATUS_OK (value: 0): the operation completed successfully
    • SRT_ERROR (value: -1): the operation failed

  2. SRTSOCKET can be returned by some of the functions, which can be:

    • A positive value greater than 0, which is a valid Socket ID value
    • SRT_SOCKID_CONNREQ for a success report when a Socket ID needs not be returned
    • SRT_INVALID_SOCK for a failure report

  3. A value of type int that should be a positive value or 0 in case of a success, and the value equal to SRT_ERROR (that is, -1) in case of failure.

In the below function description, functions returning SRTSTATUS will not have the provided return value description, as it always maches the one above. For all other types the function-specific return value description will be provided.

If the function returns SRT_ERROR, SRT_INVALID_SOCK or a value equal to -1 in case of returning an int value, additional error code can be obtained through the srt_getlasterror call. Possible codes for a particular function are listed in the Errors table.

Library Initialization

srt_startup

SRTRUNSTATUS srt_startup(void);

This function shall be called at the start of an application that uses the SRT library. It provides all necessary platform-specific initializations, sets up global data, and starts the SRT GC thread. If this function isn't explicitly called, it will be called automatically when creating the first socket. However, relying on this behavior is strongly discouraged.

Returns
SRT_RUN_OK (0) Successfully started
SRT_RUN_ALREADY (1) The GC thread is already running or it was called once already
SRT_RUN_ERROR (-1) Failed
Errors
SRT_ECONNSETUP With error code set, reported when required system resource(s) failed to initialize.
This is currently used only on Windows to report a failure from WSAStartup.

⬆️   Back to List of Functions & Structures

srt_cleanup

SRTSTATUS srt_cleanup(void);

This function cleans up all global SRT resources and shall be called just before exiting the application that uses the SRT library. This cleanup function will still be called from the C++ global destructor, if not called by the application, although relying on this behavior is strongly discouraged.

Currently this function can only return SRT_STATUS_OK and a possibility to return SRT_ERROR is reserved for future use.

IMPORTANT: Note that the startup/cleanup calls have an instance counter. This means that if you call srt_startup multiple times, you need to call the srt_cleanup function exactly the same number of times.

⬆️   Back to List of Functions & Structures

Creating and Configuring Sockets

srt_socket

SRTSOCKET srt_socket(int af, int type, int protocol);

Old and deprecated version of srt_create_socket. All arguments are ignored.

NOTE changes with respect to UDT version:

  • In UDT (and SRT versions before 1.4.2) the af parameter was specifying the socket family (AF_INET or AF_INET6). This is now not required; this parameter is decided at the call of srt_connect or srt_bind.

  • In UDT the type parameter was used to specify the file or message mode using SOCK_STREAM or SOCK_DGRAM symbols (with the latter being misleading, as the message mode has nothing to do with UDP datagrams and it's rather similar to the SCTP protocol). In SRT these two modes are available by setting SRTO_TRANSTYPE. The default is SRTT_LIVE. If, however, you set SRTO_TRANSTYPE to SRTT_FILE for file mode, you can then leave the SRTO_MESSAGEAPI option as false (default), which corresponds to "stream" mode (TCP-like), or set it to true, which corresponds to "message" mode (SCTP-like).

⬆️   Back to List of Functions & Structures

srt_create_socket

SRTSOCKET srt_create_socket();

Creates an SRT socket.

Note that socket IDs always have the SRTGROUP_MASK bit clear.

Returns
Socket ID A valid socket ID on success
SRT_INVALID_SOCK (-1) on error
Errors
SRT_ENOBUF Not enough memory to allocate required resources

NOTE: This is probably a design flaw (:warning:   BUG?). Usually underlying system errors are reported by SRT_ECONNSETUP.

⬆️   Back to List of Functions & Structures

srt_bind

SRTSTATUS srt_bind(SRTSOCKET u, const struct sockaddr* name, int namelen);

Binds a socket to a local address and port. Binding specifies the local network interface and the UDP port number to be used for the socket. When the local address is a wildcard (INADDR_ANY for IPv4 or in6addr_any for IPv6), then it's bound to all interfaces.

IMPORTANT: In the case of IPv6 wildcard address, this may mean either "all IPv6 interfaces" or "all IPv4 and IPv6 interfaces", depending on the value of SRTO_IPV6ONLY option. Therefore this option must be explicitly set to 0 or 1 prior to calling this function, otherwise (when the default -1 value of this option is left) this function will fail.

Binding is necessary for every socket to be used for communication. If the socket is to be used to initiate a connection to a listener socket, which can be done, for example, by the srt_connect function, the socket is bound implicitly to the wildcard address according to the IP family (INADDR_ANY for AF_INET or in6addr_any for AF_INET6) and port number 0. In all other cases, a socket must be bound explicitly by using the functionality of this function first.

When the port number parameter is 0, then the effective port number will be system-allocated. To obtain this effective port number you can use srt_getsockname.

This call is obligatory for a listening socket before calling srt_listen and for rendezvous mode before calling srt_connect; otherwise it's optional. For a listening socket it defines the network interface and the port where the listener should expect a call request.

In the case of rendezvous mode there are two parties that connect to one another. For every party there must be chosen a local binding endpoint (local address and port) to which they expect connection from the peer. Let's say, we have a Party 1 that selects an endpoint A and a Party 2 that selects an endpoint B. In this case the Party 1 binds the socket to the endpoint A and then connects to the endpoint B, and the Party 2 the other way around. Both sockets must be set SRTO_RENDEZVOUS to true to make this connection possible.

For a connecting socket the call to srt_bind is optional, but can be used to set up the outgoing port for communication as well as the local interface through which it should reach out to the remote endpoint, should that be necessary.

Whether binding is possible depends on some runtime conditions, in particular:

  • No socket in the system has been bound to this port ("free binding"), or

  • A socket bound to this port is bound to a certain address, and this binding is using a different non-wildcard address ("side binding"), or

  • A socket bound to this port is bound to a wildcard address for a different IP version than the version requested for this binding ("side wildcard binding", see also SRTO_IPV6ONLY socket option).

It is also possible to bind to the already busy port as long as the existing binding ("shared binding") is possessed by an SRT socket created in the same application, and:

  • Its binding address and UDP-related socket options match the socket to be bound.
  • Its SRTO_REUSEADDR is set to true (default).

If none of the free, side and shared binding options is currently possible, this function will fail. If the socket blocking the requested endpoint is an SRT socket in the current application, it will report the SRT_EBINDCONFLICT error, while if it was another socket in the system, or the problem was in the system in general, it will report SRT_ESOCKFAIL. Here is the table that shows possible situations:

Requested binding vs. Existing bindings...
A.B.C.D (explicit IPv4 addr.) 0.0.0.0 ::X (explicit IPv6 addr.) :: / V6ONLY=1 :: / V6ONLY=0
--------------------- --------------------------------- ----------- ----------------------------- --------------- ---------------
1.2.3.4 shareable if 1.2.3.4, else free blocked free free blocked
0.0.0.0 blocked shareable free free blocked
8080::1 free free 8080::1 sharable, else free blocked blocked
:: / V6ONLY=1 free free blocked sharable blocked
:: / V6ONLY=0 blocked blocked blocked blocked sharable

Where:

  • free: This binding can coexist with the requested binding.

  • blocked: This binding conflicts with the requested binding.

  • shareable: This binding can be shared with the requested binding if it's compatible.

  • shareable if (ADDRESS), else free: this binding is shareable if the existing binding address is equal to the requested ADDRESS. Otherwise it's free.

If the binding is shareable, then the operation will succeed if the socket that currently occupies the binding has the SRTO_REUSEADDR option set to true (default) and all UDP settings are the same as in the current socket. Otherwise it will fail. Shared binding means sharing the underlying UDP socket and communication queues between SRT sockets. If all existing bindings on the same port are "free" then the requested binding will allocate a distinct UDP socket for this SRT socket ("side binding").

NOTE: This function cannot be called on a socket group. If you need to have the group-member socket bound to the specified source address before connecting, use srt_connect_bind for that purpose or set the appropriate source address using srt_prepare_endpoint.

IMPORTANT information about IPv6: If you are going to bind to the in6addr_any IPv6 wildcard address (known as ::), the SRTO_IPV6ONLY option must be first set explicitly to 0 or 1, otherwise the binding will fail. In all other cases this option is meaningless. See SRTO_IPV6ONLY option for more information.

Errors
SRT_EINVSOCK Socket passed as u designates no valid socket
SRT_EINVOP Socket already bound
SRT_EINVPARAM Invalid name/namelen or invalid SRTO_IPV6ONLY flag in u
SRT_ECONNSETUP Internal creation of a UDP socket failed
SRT_ESOCKFAIL Internal configuration of a UDP socket (bind, setsockopt) failed
SRT_EBINDCONFLICT Binding specification conflicts with existing one

⬆️   Back to List of Functions & Structures

srt_bind_acquire

SRTSTATUS srt_bind_acquire(SRTSOCKET u, UDPSOCKET udpsock);

A version of srt_bind that acquires a given UDP socket instead of creating one.

The UDP socket being acquired MUST NOT be a connected socket (not associated with the socket name of a peer), because SRT needs to be able to set the destination address by itself. See #2178 for more information.

⬆️   Back to List of Functions & Structures

srt_getsockstate

SRT_SOCKSTATUS srt_getsockstate(SRTSOCKET u);

Gets the current status of the socket. Possible states are:

State Description
SRTS_INIT Created, but not bound.
SRTS_OPENED Created and bound, but not in use yet.
SRTS_LISTENING Socket is in listening state.
SRTS_CONNECTING The connect operation was initiated, but not yet finished. This may also mean that it has timed out;
you can only know that after getting a socket error report from srt_epoll_wait. In blocking mode
it's not possible because srt_connect does not return until the socket is connected or failed due
to timeout or interrupted call.
SRTS_CONNECTED The socket is connected and ready for transmission.
SRTS_BROKEN The socket was connected, but the connection was broken.
SRTS_CLOSING The socket may still be open and active, but closing is requested, so no further operations will
be accepted (active operations will be completed before closing)
SRTS_CLOSED The socket has been closed, but not yet removed by the GC thread.
SRTS_NONEXIST The specified number does not correspond to a valid socket.

⬆️   Back to List of Functions & Structures

srt_getsndbuffer

SRTSTATUS srt_getsndbuffer(SRTSOCKET sock, size_t* blocks, size_t* bytes);

Retrieves information about the sender buffer.

Arguments:

  • sock: Socket to test
  • blocks: Written information about buffer blocks in use
  • bytes: Written information about bytes in use

This function can be used for diagnostics. It is especially useful when the socket needs to be closed asynchronously.

⬆️   Back to List of Functions & Structures

srt_getmaxpayloadsize

int srt_getmaxpayloadsize(SRTSOCKET u);

Returns the maximum number of bytes that fit in a single packet. Useful only in live mode (when SRTO_TSBPDMODE is true). The socket must be bound (see srt_bind) or connected (see srt_connect) to use this function. Note that in case when the socket is bound to an IPv6 wildcard address and it is dual-stack (SRTO_IPV6ONLY is set to false), this function returns the correct value only if the socket is connected, otherwise it will return the value always as if the connection was made from an IPv6 peer (including when you call it on a listening socket).

This function is only useful for the application to check if it is able to use a payload of certain size in the live mode, or after connection, if the application can send payloads of certain size. This is useful only in assertions, as if the SRTO_PAYLOADSIZE option is to be set to a non-default value (for which the one returned by this function is the maximum value), this option should be modified before connection and on both parties, regarding the settings applied on the socket.

The returned value is the maximum number of bytes that can be put in a single packet regarding:

  • The current MTU size (SRTO_MSS)
  • The IP version (IPv4 or IPv6)
  • The SRTO_CRYPTOMODE setting (bytes reserved for AEAD authentication tag)
  • The SRTO_PACKETFILTER setting (bytes reserved for extra field in a FEC control packet)

With default options this value should be 1456 for IPv4 and 1444 for IPv6.

Returns
The maximum payload size (>0) If succeeded
SRT_ERROR Usage error
Errors
SRT_EINVSOCK Socket u indicates no valid socket ID
SRT_EUNBOUNDSOCK Socket u is not bound

⬆️   Back to List of Functions & Structures

srt_close, srt_close_withreason

SRTSTATUS srt_close(SRTSOCKET u);
SRTSTATUS srt_close_withreason(SRTSOCKET u, int reason);

Closes the socket or group and frees all used resources. Note that underlying UDP sockets may be shared between sockets, so these are freed only with the last user closed.

Arguments:

  • u: Socket or group to close
  • reason: Reason code for closing. You should use numbers from SRT_CLSC_USER up.
Errors
SRT_EINVSOCK Socket u indicates no valid socket ID

⬆️   Back to List of Functions & Structures

Connecting

srt_listen

SRTSTATUS srt_listen(SRTSOCKET u, int backlog);

This sets up the listening state on a socket with a backlog setting that defines how many sockets may be allowed to wait until they are accepted (excessive connection requests are rejected in advance).

The following important options may change the behavior of the listener socket and the srt_accept function:

Errors
SRT_EINVPARAM Value of backlog is 0 or negative.
SRT_EINVSOCK Socket u indicates no valid SRT socket.
SRT_EUNBOUNDSOCK srt_bind has not yet been called on that socket.
SRT_ERDVNOSERV SRTO_RENDEZVOUS flag is set to true on specified socket.
SRT_EINVOP Internal error (should not happen when SRT_EUNBOUNDSOCK is reported).
SRT_ECONNSOCK The socket is already connected.
SRT_EDUPLISTEN The address used in srt_bind by this socket is already occupied by another listening socket.
Binding multiple sockets to one IP address and port is allowed, as long as
SRTO_REUSEADDR is set to true, but only one of these sockets can be set up as a listener.

⬆️   Back to List of Functions & Structures

srt_accept

SRTSOCKET srt_accept(SRTSOCKET lsn, struct sockaddr* addr, int* addrlen);

Extracts the first connection request on the queue of pending connections for the listening socket, lsn, then creates and returns a new socket or group ID that handles this connection. The group and socket can be distinguished by checking the SRTGROUP_MASK bit on the returned ID. Note that by default group connections will be rejected - this feature can be only enabled on demand (see below).

  • lsn: the listening socket
  • addr: a location to store the remote IP address and port for the connection
  • addrlen: INPUT: size of addr pointed object. OUTPUT: real size of the returned object

General requirements for a parameter correctness:

  • lsn must be first bound and listening

  • addr may be NULL, or otherwise it must be a pointer to an object that can be treated as an instance of sockaddr_in or sockaddr_in6

  • addrlen should be a pointer to a variable set to the size of the object specified in addr, if addr is not NULL. Otherwise it's ignored.

If addr is not NULL, the information about the source IP address and port of the peer will be written into this object. Note that whichever type of object is expected here (sockaddr_in or sockaddr_in6), it depends on the address type used in the srt_bind call for lsn. If unsure in a particular situation, it is recommended that you use sockaddr_storage or srt::sockaddr_any.

If the lsn listener socket is in the blocking mode (if SRTO_RCVSYN is set to true, which is default), the call will block until the incoming connection is ready for extraction. Otherwise, the call always returns immediately, possibly with failure, if there was no pending connection waiting on the listening socket lsn.

The listener socket can be checked for any pending connections prior to calling srt_accept by checking the SRT_EPOLL_ACCEPT epoll event (which is an alias to SRT_EPOLL_IN). This event might be spurious in certain cases though, for example, when the connection has been closed by the peer or broken before the application extracts it. The call to srt_accept would then still fail in such a case.

In order to allow the listening socket lsn to accept a group connection, the SRTO_GROUPCONNECT socket option for the listening socket must be set to 1. Note that single socket connections can still be reported to that socket. The application can distinguish the socket and group connection by checking the SRTGROUP_MASK bit on the returned successful value. There are some important differences to single socket connections:

  1. Accepting a group connection can be done only once per connection, even though particular member connections can get broken or established while the group is connected. The actual connection reporter (listener) is a socket, like before, but once you call srt_accept and receive this group ID, it is the group considered connected, and any member connections of the same group will be handled in the background.

  2. If a group was extracted from the srt_accept call, the address reported in addr parameter is still the address of the connection that has triggered the group connection extraction. The information about all member links in the group at the moment can be obtained at any time through srt_group_data or the data filled by srt_sendmsg2 and srt_recvmsg2 in the SRT_MSGCTRL structure.

  3. Listening sockets are not bound to groups anyhow. You can allow multiple listening sockets to accept group connections and the connection extracted from the listener, if it is declared to be a group member, will join its group, no matter which of the listening sockets has received the connection request. This feature is prone to more tricky rules, however:

    • If you use multiple listener sockets, all of them in blocking mode, allowed for group connections, and receiving connection requests for the same group at the moment, and you run one thread per srt_accept call, it is undefined, which of them will extract the group ID for the connection, but still only one will, while the others will continue blocking. If you want to use only one thread for accepting connections from potentially multiple listening sockets in the blocking mode, you should use srt_accept_bond instead. Note though that this function is actually a wrapper that changes locally to the nonblocking mode on all these listeners and uses epoll internally.

    • If at the moment multiple listener sockets have received connection request and you query them all for readiness epoll flags (by calling an epoll waiting function), all of them will get the SRT_EPOLL_ACCEPT flag set, but still only one of them will return the group ID from the srt_accept call. After this call, from all listener sockets in the whole application the SRT_EPOLL_ACCEPT flag, that was set by the reason of a pending connection for the same group, will be withdrawn (that is, it will be cleared if there are no other pending connections). This is then yet another situation when this flag can be spurious.

  4. If you query a listening socket for epoll flags after the srt_accept function has once returned the group ID, the listening sockets that have received new member connection requests within that group will report only the SRT_EPOLL_UPDATE flag. This flag is edge-triggered-only because there is no operation you can perform in response in order to clear this flag. This flag is mostly used internally and the application may use it if it would like to trigger updating the current group information due to having one newly added member connection.

Returns
socket/group ID On success, a valid SRT socket or group ID to be used for transmission.
SRT_INVALID_SOCK (-1) on failure
Errors
SRT_EINVPARAM Invalid addr or addrlen (see requirements in the begininng)
SRT_EINVSOCK lsn designates no valid socket ID.
SRT_ENOLISTEN lsn is not set up as a listener (srt_listen not called).
SRT_EASYNCRCV No connection reported so far. This error is reported only in the non-blocking mode
SRT_ESCLOSED The lsn socket has been closed while the function was blocking the call. Including when the socket was closed just at the
moment when a connection was made (i.e., the socket got closed during processing)

⬆️   Back to List of Functions & Structures

srt_accept_bond

SRTSOCKET srt_accept_bond(const SRTSOCKET listeners[], int nlisteners, int msTimeOut);

Accepts a pending connection, like srt_accept, but pending on any of the listener sockets passed in the listeners array of nlisteners size.

Arguments:

  • listeners: array of listener sockets (all must be setup by srt_listen)
  • nlisteners: size of the listeners array
  • msTimeOut: timeout in [ms] or -1 to block forever

This function is for blocking mode only - for non-blocking mode you should simply call srt_accept on the first listener socket that reports readiness, and this function is actually a friendly shortcut that uses waiting on epoll and srt_accept internally. This function supports an important use case for accepting a group connection, for which every member connection is expected to be established over a different listener socket.

Note that there's no special set of settings required or rejected for this function. Group-member connections for the same group can always be established over various different listener sockets when all those listeners are hosted by the same application. The group management is global for the application, so a connection reporting in for an already connected group gets discovered, and the connection will be handled in the background. This occurs regardless of which listener socket the call was made to, as long as the connection is accepted according to any additional conditions.

This function has nothing to do with the groups. You can use it in any case when you have one service that accepts connections to multiple endpoints. Note also that the settings as to whether listeners should accept or reject socket or group connections should be applied to the listener sockets appropriately prior to calling this function.

Returns
SRT socket/group ID On success, a valid SRT socket or group ID to be used for transmission
SRT_INVALID_SOCK (-1) on failure
Errors
SRT_EINVPARAM NULL specified as listeners or nlisteners < 1
SRT_EINVSOCK Any socket in listeners designates no valid socket ID. Can also mean Internal Error when
an error occurred while creating an accepted socket (:warning:   BUG?)
SRT_ENOLISTEN Any socket in listeners is not set up as a listener (srt_listen not called, or the listener socket
has already been closed)
SRT_ETIMEOUT No connection reported on any listener socket as the timeout has been reached. This error is only
reported when msTimeOut is not -1

⬆️   Back to List of Functions & Structures

srt_listen_callback

SRTSTATUS srt_listen_callback(SRTSOCKET lsn, srt_listen_callback_fn* hook_fn, void* hook_opaque);

This call installs a callback hook, which will be executed on a socket that is automatically created to handle the incoming connection on the listening socket (and is about to be returned by srt_accept), but before the connection has been accepted.

Note the callback must be set before starting listening, i.e. before srt_listen is called.

Arguments:

  • lsn: Listening socket where you want to install the callback hook
  • hook_fn: The callback hook function pointer (or NULL to remove the callback)
  • hook_opaque: The pointer value that will be passed to the callback function
Errors
SRT_ECONNSOCK It can't be modified in a connected socket

The callback function has the signature as per this type definition:

typedef int srt_listen_callback_fn(void* opaque, SRTSOCKET ns, int hs_version
             const struct sockaddr* peeraddr, const char* streamid);

The callback function gets the following parameters passed:

  • opaque: The pointer passed as hook_opaque when registering
  • ns: The freshly created socket to handle the incoming connection
  • hs_version: The handshake version (usually 5, pre-1.3 versions of SRT use 4)
  • peeraddr: The address of the incoming connection
  • streamid: The value set to SRTO_STREAMID option set on the peer side

Note that SRT versions that use handshake version 4 are incapable of using any extensions, such as streamid. However they do support encryption. Note also that the SRT version isn't extracted at this point. However you can prevent connections with versions that are too old by using the SRTO_MINVERSION option.

The callback function is given an opportunity to:

  • use the passed information (streamid and peer address) to decide what to do with this connection
  • alter any options on the socket, which could not be set properly beforehand on the listening socket to be derived by the accepted socket, and won't be allowed to be altered after the socket is returned by srt_accept

Note that normally the returned socket has already set all derived options from the listener socket. The moment when this callback is called is when the conclusion handshake has been already received from the caller party, but not yet interpreted (the streamid field is extracted from it prematurely). When, for example, you set a passphrase on the socket at this point, the Key Material processing will happen against this passphrase, after the callback function is finished.

The callback function shall return 0, if the connection is to be accepted. If you return -1, or if the function throws an exception, this will be understood as a request to reject the incoming connection. In this case the about-to-be-accepted socket will be silently deleted and srt_accept will not report it. Note that in case of non-blocking mode the epoll bits for read-ready on the listener socket will not be set if the connection is rejected, including when rejected from this user function.

IMPORTANT: This function is called in the receiver worker thread, which means that it must do its checks and operations as quickly as possible. Every delay you create in this function will burden the processing of the incoming data on the associated UDP socket. In the case of a listener socket this means the listener socket itself and every socket accepted off this listener socket. Avoid any extensive search operations. It is best to cache in memory whatever database you have to check against the data received in streamid or peeraddr.

⬆️   Back to List of Functions & Structures

srt_connect

SRTSOCKET srt_connect(SRTSOCKET u, const struct sockaddr* name, int namelen);

Connects a socket or a group to a remote party with a specified address and port.

Arguments:

  • u: can be an SRT socket or SRT group, both freshly created and not yet used for any connection, except possibly srt_bind on the socket
  • name: specification of the remote address and port
  • namelen: size of the object passed by name

NOTES:

  1. The socket used here may be bound by srt_bind before connecting, or binding and connection can be done in one function (srt_connect_bind), such that it uses a predefined network interface or local outgoing port. This is optional in the case of a caller-listener arrangement, but obligatory for a rendezvous arrangement. If not used, the binding will be done automatically to a wildcard address and port 0. See `srt_bind for details.

  2. This function is used for both connecting to the listening peer in a caller-listener arrangement, and calling the peer in rendezvous mode. For the latter, the SRTO_RENDEZVOUS flag must be set to true prior to calling this function, and binding, as described in #1, is in this case obligatory (see SRT_ERDVUNBOUND below).

  3. When u is a group, then this call can be done multiple times, each time for another member connection, and a new member SRT socket will be created automatically for every call of this function.

  4. If you want to connect a group to multiple links at once and use blocking mode, you might want to use srt_connect_group instead. This function also allows you to use additional settings, available only for groups.

The returned value is a socket ID value. When u is a socket ID, the returned is a special value SRT_SOCKID_CONNREQ. When u is a group ID, the returned value is the socket ID of the newly created member for the requested link. In the case of failure, SRT_INVALID_SOCK is returned.

Returns
SRT_INVALID_SOCK (-1) in case of error
SRT_SOCKID_CONNREQ In case when used for u socket
Socket ID Created for connection for u group
Errors
SRT_EINVSOCK Socket u indicates no valid socket or group ID
SRT_ERDVUNBOUND Socket u is in rendezvous mode, but it wasn't bound (see note #2)
SRT_ECONNSOCK Socket u is already connected
SRT_ECONNREJ Connection has been rejected
SRT_ENOSERVER Connection has been timed out (see SRTO_CONNTIMEO)
SRT_ESCLOSED The socket u has been closed while the function was blocking the call

If the u socket is configured for blocking mode (when SRTO_RCVSYN is set to true, default), the call will block until the connection succeeds or fails. The "early" errors SRT_EINVSOCK, SRT_ERDVUNBOUND and SRT_ECONNSOCK are reported in both modes immediately. Other errors are "late" failures and can only be reported in blocking mode.

In non-blocking mode, a successful connection can be recognized by the SRT_EPOLL_OUT epoll event flag and a "late" failure by the SRT_EPOLL_ERR flag. Note that the socket state in the case of a failed connection remains SRTS_CONNECTING in that case.

In the case of "late" failures you can additionally call srt_getrejectreason to get detailed error information. Note that in blocking mode only for the SRT_ECONNREJ error this function may return any additional information. In non-blocking mode a detailed "late" failure cannot be distinguished, and therefore it can also be obtained from this function. Note that the connection timeout error can be also recognized through this call, even though it is reported by SRT_ENOSERVER in the blocking mode.

⬆️   Back to List of Functions & Structures

srt_connect_bind

SRTSOCKET srt_connect_bind(SRTSOCKET u, const struct sockaddr* source,
                     const struct sockaddr* target, int len);

This function does the same as first srt_bind then srt_connect, if called with u being a socket. If u is a group, then it will execute srt_bind first on the automatically created socket for the connection.

Arguments:

  • u: Socket or group to connect
  • source: Address to bind u to
  • target: Address to connect
  • len: size of the original structure of source and target
Returns
SRT_INVALID_SOCK (-1) in case of error
SRT_SOCKID_CONNREQ In case when used for u socket
Socket ID Created for connection for u group
Errors
SRT_EINVSOCK Socket passed as u designates no valid socket
SRT_EINVOP Socket already bound
SRT_ECONNSETUP Internal creation of a UDP socket failed
SRT_ESOCKFAIL Internal configuration of a UDP socket (bind, setsockopt) failed
SRT_ERDVUNBOUND Internal error (srt_connect should not report it after srt_bind was called)
SRT_ECONNSOCK Socket u is already connected
SRT_ECONNREJ Connection has been rejected
SRT_EBINDCONFLICT Binding specification conflicts with existing one

IMPORTANT: It's not allowed to bind and connect the same socket to two different families (that is, both source and target must be AF_INET or AF_INET6), although you may mix links over IPv4 and IPv6 in one group.

⬆️   Back to List of Functions & Structures

srt_connect_debug

SRTSOCKET srt_connect_debug(SRTSOCKET u, const struct sockaddr* name, int namelen, int forced_isn);

This function is for developers only and can be used for testing. It does the same thing as srt_connect, with the exception that it allows specifying the Initial Sequence Number for data transmission. Normally this value is generated randomly.

⬆️   Back to List of Functions & Structures

srt_rendezvous

SRTSTATUS srt_rendezvous(SRTSOCKET u, const struct sockaddr* local_name, int local_namelen,
        const struct sockaddr* remote_name, int remote_namelen);

Performs a rendezvous connection. This is a shortcut for doing bind locally, setting the SRTO_RENDEZVOUS option to true, and doing srt_connect.

Arguments:

  • u: socket to connect
  • local_name: specifies the local network interface and port to bind
  • remote_name: specifies the remote party's IP address and port
Errors
SRT_EINVSOCK Socket passed as u designates no valid socket
SRT_EINVOP Socket already bound
SRT_ECONNSETUP Internal creation of a UDP socket failed
SRT_ESOCKFAIL Internal configuration of a UDP socket (bind, setsockopt) failed
SRT_ERDVUNBOUND Internal error (srt_connect should not report it after srt_bind was called)
SRT_ECONNSOCK Socket u is already connected
SRT_ECONNREJ Connection has been rejected

IMPORTANT: Establishing a rendezvous connection to two different families is not allowed (that is, both local_name and remote_name must be AF_INET or AF_INET6).

⬆️   Back to List of Functions & Structures

srt_connect_callback

SRTSTATUS srt_connect_callback(SRTSOCKET u, srt_connect_callback_fn* hook_fn, void* hook_opaque);

This call installs a callback hook, which will be executed on a given u socket or all member sockets of a u group, just after a pending connection in the background has been resolved and the connection has failed. Note that this function is not guaranteed to be called if the u socket is set to blocking mode (SRTO_RCVSYN option set to true). It is guaranteed to be called when a socket is in non-blocking mode, or when you use a group.

Note the callback must be set before starting the connection procedure, i.e. before srt_connect, srt_connect_bind, etc. is called.

This function is mainly intended to be used with group connections. Note that even if you use a group connection in blocking mode, after the group is considered connected the member connections still continue in background. Also, when some connections are still pending and others have failed, the blocking call for srt_connect_group will not exit until at least one of them succeeds or all fail - in such a case those failures also happen only in the background, while the connecting function blocks until all connections are resolved. When all links fail, you will only get a general error code for the group. This mechanism allows you to get individual errors for particular member connection failures.

Arguments:

  • u: Socket or group that will be used for connecting and for which the hook is installed
  • hook_fn: The callback hook function pointer (or NULL to remove the callback)
  • hook_opaque: The pointer value that will be passed to the callback function
Errors
SRT_ECONNSOCK It can't be modified in a connected socket

The callback function signature has the following type definition:

typedef void srt_connect_callback_fn(void* opaq, SRTSOCKET ns, int errorcode, const struct sockaddr* peeraddr, int token);

Arguments:

  • opaq: The pointer passed as hook_opaque when registering
  • ns: The socket for which the connection process was resolved
  • errorcode: The error code, same as for srt_connect for blocking mode
  • peeraddr: The target address passed to srt_connect call
  • token: The token value, if it was used for group connection, otherwise -1

⬆️   Back to List of Functions & Structures

Socket Group Management

SRT_GROUP_TYPE

The following group types are collected in an SRT_GROUP_TYPE enum:

  • SRT_GTYPE_BROADCAST: broadcast type, all links are actively used at once;
  • SRT_GTYPE_BACKUP: backup type, idle links take over connection on disturbance.

⬆️   Back to List of Functions & Structures

SRT_SOCKGROUPCONFIG

This structure is used to define entry points for connections for the srt_connect_group function:

typedef struct SRT_GroupMemberConfig_
{
    SRTSOCKET id;
    struct sockaddr_storage srcaddr;
    struct sockaddr_storage peeraddr;
    uint16_t weight;
    SRT_SOCKOPT_CONFIG* config;
    int errorcode;
    int token;
} SRT_SOCKGROUPCONFIG;

where:

  • id: member socket ID (filled back as output)
  • srcaddr: address to which id should be bound
  • peeraddr: address to which id should be connected
  • weight: the weight parameter for the link (group-type dependent)
  • config: the configuration object, if used (see srt_create_config())
  • errorcode: status of the connecting operation
  • token: An integer value unique for every connection, or -1 if unused

The srt_prepare_endpoint sets these fields to default values. After that you can change the value of weight, config and token fields. The weight parameter's meaning is dependent on the group type:

  • BROADCAST: not used
  • BACKUP: positive value of link priority (the greater, the more preferred)

In any case, the allowed value for weight is between 0 and 32767.

The config parameter is used to provide options to be set separately on a socket for a particular connection (see srt_create_config()).

The token value is intended to allow the application to more easily identify a particular connection. If you don't use it and leave the default value of -1, the library will set a unique value for the next connection (a 32-bit unsigned number that will overflow by itself; the default value will be skipped). The application can also set a unique value by itself and keep the same value for the same connection.

⬆️   Back to List of Functions & Structures

SRT_SOCKGROUPDATA

The most important structure for the group member status is SRT_SOCKGROUPDATA:

typedef struct SRT_SocketGroupData_
{
    SRTSOCKET id;
    struct sockaddr_storage peeraddr;
    SRT_SOCKSTATUS sockstate;
    uint16_t weight;
    SRT_MEMBERSTATUS memberstate;
    int result;
    int token;
} SRT_SOCKGROUPDATA;

where:

  • id: member socket ID
  • peeraddr: address to which id should be connected
  • sockstate: current connection status (see srt_getsockstate
  • weight: current weight value set on the link
  • memberstate: current state of the member (see below)
  • result: result of the operation (if this operation recently updated this structure)
  • token: A token value set for that connection (see SRT_SOCKGROUPCONFIG)

The weight is set to 0 by default by srt_prepare_endpoint() - you can set it to a different value afterwards. The meaning of weight depends on the group type:

  1. Backup groups: in this case it defines the link priority. The default 0 value is the lowest priority and greater values declare higher priorities. The priority for the backup groups determines which link is activated first when the currently active link is unstable, and which should keep transmitting when multiple active links are currently stable, or when a new link becomes connected.

  2. Balancing groups with "fixed" algorithm: in this case it defines the desired link load share. You can think of it as a percentage of link load, but indeed a load percentage is defined as this weight value divided by a sum of all weight values from all member links. Note however that the sum is calculated out of all links that have been successfully connected. The default 0 is also a special value that defines an "equalized" load share (it's set to the arithmetic average of the weights from all links).

The SRT_SOCKGROUPDATA structure is used in multiple purposes:

  • Prepare data for connection
  • Getting the current member status

⬆️   Back to List of Functions & Structures

SRT_MEMBERSTATUS

The enumeration type that defines the state of a member connection in a group:

  • SRT_GST_PENDING: The connection is in progress, so the socket is not currently being used for transmission, even potentially, and still has a chance to fail and transit into SRT_GST_BROKEN without turning into SRT_GST_IDLE

  • SRT_GST_IDLE: The connection is established and ready to take over transmission, but it's not used for transmission at the moment. This state may last for a short moment in the case of broadcast group. In backup group this state defines a backup link that is ready to take over when the currently active (running) link becomes unstable.

  • SRT_GST_RUNNING: The connection is established and at least one packet has already been sent or received over it.

  • SRT_GST_BROKEN: The connection was broken. Broken connections are not to be revived. Note also that it is only possible to see this state if it is read by srt_sendmsg2 or srt_recvmsg2 just after the link failure has been detected. Otherwise, the broken link simply disappears from the member list.

Note that internally the member state is separate for sending and receiving. If the memberstate field of SRT_SOCKGROUPDATA is SRT_GST_RUNNING, it means that this is the state in at least one direction, while in the other direction it may be SRT_GST_IDLE. In all other cases the states should be the same in both directions.

States should normally start with SRT_GST_PENDING and then turn into SRT_GST_IDLE. Once a new link is used for sending data, the state becomes SRT_GST_RUNNING. In the case of the SRT_GTYPE_BACKUP type group, if a link is in the SRT_GST_RUNNING state, but another link is chosen to remain as the only active one, this link will be "silenced" (its state will become SRT_GST_IDLE).

⬆️   Back to List of Functions & Structures

Functions to Be Used on Groups

srt_create_group

SRTSOCKET srt_create_group(SRT_GROUP_TYPE type);

Creates a new group of type type. Is typically called on the caller side to be next used for connecting to a remote SRT listener. The group ID is of the same domain as the socket ID, with the exception that the SRTGROUP_MASK bit is set on it, unlike for socket ID.

Returns
SRTSOCKET Group SRT socket ID.
SRT_INVALID_SOCK On error or if bonding API is disabled.

⬆️   Back to List of Functions & Structures

srt_groupof

SRTSOCKET srt_groupof(SRTSOCKET member);

Retrieves the group SRT socket ID that corresponds to the member socket ID member.

Returns
SRTSOCKET Corresponding group SRT socket ID of the member socket.
SRT_INVALID_SOCK The socket doesn't exist, it is not a member of any group, or bonding API is disabled.

In the case of SRT_INVALID_SOCK, the error is set to SRT_EINVPARAM.

⬆️   Back to List of Functions & Structures

srt_group_data

SRTSTATUS srt_group_data(SRTSOCKET socketgroup, SRT_SOCKGROUPDATA output[], size_t* inoutlen);

Arguments:

  • socketgroup an existing socket group ID
  • output points to an output array
  • inoutlen points to a variable that stores the size of the output array, and is set to the filled array's size

This function obtains the current member state of the group specified in socketgroup.

The inoutlen should point to a variable initially set to the size of the output array. The current number of members will be written back to the variable specified in inoutlen. This paramterer cannot be NULL.

If output is specified and the size of the array is at least equal to the number of group members, the output array will be filled with group data.

If output is NULL then the function will only retrieve the number of elements in inoutlen.

This call will fail and return SRT_ERROR if:

  • The socketgroup parameter is invalid

  • The inoutlen parameter is NULL

  • The size specified in a variable passed via inoutlen is less than the number of group members

Errors
SRT_EINVPARAM Reported if socketgroup is not an existing group ID. Or if bonding API is disabled.
SRT_ELARGEMSG Reported if inoutlen if less than the size of the group
in:output in:inoutlen returns out:output out:inoutlen Error
ptr ≥ group.size SRT_STATUS_OK group.data group.size() ✖️
NULL ptr SRT_STATUS_OK (unused) group.size() ✖️
NULL NULL SRT_ERROR (unused) (not filled) SRT_EINVPARAM
ptr NULL SRT_ERROR (unused) (not filled) SRT_EINVPARAM
ptr < group.size SRT_ERROR (unused) group.size() SRT_ELARGEMSG

⬆️   Back to List of Functions & Structures

srt_connect_group

SRTSOCKET srt_connect_group(SRTSOCKET group,
                      SRT_SOCKGROUPCONFIG links [], int arraysize);

This function does almost the same as calling srt_connect or srt_connect_bind (when the source was specified for srt_prepare_endpoint) in a loop for every item specified in the links array. However if blocking mode is being used, the first call to srt_connect would block until the connection is established, whereas this function blocks until any of the specified connections is established.

If the group nonblocking mode is set (SRTO_RCVSYN option), there's no difference, except that the SRT_SOCKGROUPCONFIG structure allows adding extra configuration data used by groups. Note also that this function accepts only groups, not sockets.

The elements of the links array need to be prepared with the use of the srt_prepare_endpoint function. Note that it is NOT required that every target address specified is of the same family.

Return value and errors in this function are the same as in srt_connect, although this function reports success when at least one connection has succeeded. If none has succeeded, this function reports an SRT_ECONNLOST error. Particular connection states can be obtained from the links array upon return from the errorcode field.

The fields of SRT_SOCKGROUPCONFIG structure have the following meaning:

Input:

  • id: unused, should be SRT_INVALID_SOCK (default when created by srt_prepare_endpoint)
  • srcaddr: address to bind before connecting, if specified (see below for details)
  • peeraddr: target address to connect
  • weight: weight value to be set on the link
  • config: socket options to be set on the socket before connecting
  • errorcode: unused, should be SRT_SUCCESS (default)
  • token: An integer value unique for every connection, or -1 if unused

Output:

  • id: The socket created for that connection (SRT_INVALID_SOCK if failed to create)
  • srcaddr: unchanged
  • peeraddr: unchanged
  • weight: unchanged
  • config: unchanged (the object should be manually deleted upon return)
  • errorcode: status of connection for that link (SRT_SUCCESS if succeeded)
  • token: same as in input, or a newly created token value if input was -1
Returns
Socket ID The socket ID of the first connected member.
SRT_INVALID_SOCK Error
Errors
SRT_EINVPARAM Reported if socketgroup is not an existing group ID. Or if bonding API is disabled.
SRT_ECONNLOST Reported if none of member sockets has connected.

The procedure of connecting for every connection definition specified in the links array is performed the following way:

  1. The socket for this connection is first created

  2. Socket options derived from the group are set on that socket.

  3. If config is not NULL, configuration options stored there are set on that socket.

  4. If source address is specified (that is srcaddr value is not default empty, as described in SRT_SOCKGROUPCONFIG, then the binding operation is done on the socket (see srt_bind).

  5. The socket is added to the group as a member.

  6. The socket is connected to the target address, as specified in the peeraddr field.

During this process there can be errors at any stage. There are two possibilities as to what may happen in this case:

  1. If creation of a new socket has failed, which may only happen due to problems with system resources, then the whole loop is interrupted and no further items in the array are processed. All sockets that got created until then, and for which the connection attempt has at least successfully started, remain group members, although the function will return immediately with an error status (that is, without waiting for the first successful connection). If your application wants to do any partial recovery from this situation, it can only check the current member status via srt_group_data and wait for group's write readiness (SRT_EPOLL_OUT) by using epoll.

  2. In any other case, if an error occurs at any stage of the above process, the processing is interrupted for this very array item only, the socket used for it is immediately closed, and the processing of the next elements continues. In the case of a connection process, it also passes two stages - parameter check and the process itself. Failure at the parameter check breaks this process, while if the check passes, this item is considered correctly processed, even if the connection attempt is going to fail later.

If this function is called in blocking mode, it then blocks until at least one connection reports success, or if all of them fail. The status of connections that continue in the background after this function exits can then be checked by srt_group_data.

As member socket connections are running in the background, for determining if a particular connection has succeeded or failed it is recommended to use srt_connect_callback. In this case the token callback function parameter will be the same as the token value used for the particular item in the links connection array.

The token value doesn't have any limitations except that the -1 value is a "trap representation", that is, when set on input it will make the internals define a unique value for the token. Your application can also set unique values, in which case the token value will be preserved.

⬆️   Back to List of Functions & Structures

srt_prepare_endpoint

SRT_SOCKGROUPCONFIG srt_prepare_endpoint(const struct sockaddr* src /*nullable*/,
                                       const struct sockaddr* dst, int namelen);

This function prepares a default SRT_SOCKGROUPCONFIG object as an element of the array you can prepare for srt_connect_group function, filled with additional data:

Arguments:

  • src: address to which the newly created socket should be bound
  • dst: address to which the newly created socket should connect
  • namelen: size of both src and dst

The following fields are set by this function:

  • id: -1 (unused for input)
  • srcaddr: default empty (see below) or copied from src
  • peeraddr: copied from dst
  • weight: 0
  • config: NULL
  • errorcode: SRT_SUCCESS

The default empty srcaddr is set the following way:

  • ss_family set to the same value as dst->sa_family
  • empty address (INADDR_ANY for IPv4 and in6addr_any for IPv6)
  • port number 0

If src is not NULL, then srcaddr is copied from src. Otherwise it will remain as default empty.

The dst parameter is obligatory. If src parameter is not NULL, then both dst and src must have the same value of sa_family.

Note though that this function has no possibility of reporting errors - these would be reported only by srt_connect_group, separately for every individual connection, and the status can be obtained from the errorcode field.

Note that the errorcode field of the SRT_SOCKGROUPCONFIG returned would be set to SRT_EINVOP if the bonding API is disabled (ENABLE_BONDING=OFF).

⬆️   Back to List of Functions & Structures

srt_create_config

SRT_SOCKOPT_CONFIG* srt_create_config();

Creates a dynamic object for specifying the socket options. You can add options to be set on the socket by srt_config_add and then mount this object into the config field in SRT_SOCKGROUPCONFIG object for that particular connection. After the object is no longer needed, you should delete it using srt_delete_config.

Returns
Pointer The pointer to the created object (memory allocation errors apply)
NULL If bonding API is disabled.

⬆️   Back to List of Functions & Structures

srt_delete_config

void srt_delete_config(SRT_SOCKOPT_CONFIG* c);

Deletes the configuration object.

⬆️   Back to List of Functions & Structures

srt_config_add

SRTSTATUS srt_config_add(SRT_SOCKOPT_CONFIG* c, SRT_SOCKOPT opt, void* val, int len);

Adds a configuration option to the configuration object.

Parameters have meanings similar to srt_setsockflag. Note that not every option is allowed to be set this way. However, the option (if allowed) isn't checked if it doesn't violate other preconditions. This will be checked when the option is being set on the socket, which may fail as a part of the connection process done by srt_connect_group.

This function should be used when this option must be set individually on a socket and differently for a particular link. If you need to set some option the same way on every socket, you should instead set this option on the whole group.

The following options are allowed to be set on the member socket:

Errors
SRT_EINVPARAM This option is not allowed to be set on a socket being a group member. Or if bonding API is disabled.

⬆️   Back to List of Functions & Structures

Options and Properties

NOTE: For more information, see SRT API Socket Options, Getting and Setting Options.

srt_getpeername

SRTSTATUS srt_getpeername(SRTSOCKET u, struct sockaddr* name, int* namelen);

Retrieves the remote address to which the socket is connected.

Errors
SRT_EINVSOCK Socket u indicates no valid socket ID
SRT_ENOCONN Socket u isn't connected, so there's no remote address to return

⬆️   Back to List of Functions & Structures

srt_getsockname

SRTSTATUS srt_getsockname(SRTSOCKET u, struct sockaddr* name, int* namelen);

Extracts the address to which the socket was bound. Although you should know the address(es) that you have used for binding yourself, this function can be useful for extracting the local outgoing port number when it was specified as 0 with binding for system autoselection. With this function you can extract the port number after it has been autoselected.

Errors
SRT_EINVSOCK Socket u indicates no valid socket ID
SRT_ENOCONN Socket u isn't bound, so there's no local address to return
(:warning:   BUG? It should rather be SRT_EUNBOUNDSOCK)

Example

sockaddr_storage name;
int namelen = sizeof sockaddr_storage;
int res = srt_getsockname(m_listener_sock, (sockaddr*) &name, &namelen);
// IPv4: namelen == sockaddr_in.
// IPv6: namelen == sockaddr_in6.
if (res < 0) {
    std::cerr << "Error " << srt_getlasterror_str() << '\n';
}

⬆️   Back to List of Functions & Structures

srt_getsockopt

srt_getsockflag

SRTSTATUS srt_getsockopt(SRTSOCKET u, int level /*ignored*/, SRT_SOCKOPT opt, void* optval, int* optlen);
SRTSTATUS srt_getsockflag(SRTSOCKET u, SRT_SOCKOPT opt, void* optval, int* optlen);

Gets the value of the given socket option (from a socket or a group).

The first version (srt_getsockopt) follows the BSD socket API convention, although the "level" parameter is ignored. The second version (srt_getsockflag) omits the "level" parameter completely.

Options correspond to various data types (see API-socket-options.md). A variable optval of the appropriate data type has to be passed. The integer value of optlen should originally contain the size of the optval type provided; on return, it will be set to the size of the value returned. For most options, it will be the size of an integer. Some options, however, use types bool, int64_t, C string, etc. (see API-socket-options.md).

The application is responsible for allocating sufficient memory space as defined and pointed to by optval.

Errors
SRT_EINVSOCK Socket u indicates no valid socket ID
SRT_EINVOP Option opt indicates no valid option

⬆️   Back to List of Functions & Structures

srt_setsockopt

srt_setsockflag

SRTSTATUS srt_setsockopt(SRTSOCKET u, int level /*ignored*/, SRT_SOCKOPT opt, const void* optval, int optlen);
SRTSTATUS srt_setsockflag(SRTSOCKET u, SRT_SOCKOPT opt, const void* optval, int optlen);

Sets a value for a socket option in the socket or group.

The first version (srt_setsockopt) follows the BSD socket API convention, although the "level" parameter is ignored. The second version (srt_setsockflag) omits the "level" parameter completely.

Options correspond to various data types, so you need to know what data type is assigned to a particular option, and to pass a variable of the appropriate data type with the option value to be set.

Please note that some of the options can only be set on sockets or only on groups, although most of the options can be set on the groups so that they are then derived by the member sockets.

Errors
SRT_EINVSOCK Socket u indicates no valid socket ID
SRT_EINVPARAM Option opt indicates no valid option
SRT_EBOUNDSOCK Tried to set an option with PRE_BIND restriction on a bound socket.
SRT_ECONNSOCK Tried to set an option with PRE_BIND or PRE restriction on a socket in connecting/listening/connected state.

NOTE: Various other errors may result from problems when setting a specific option (see option description in API-socket-options.md for details).

⬆️   Back to List of Functions & Structures

srt_getversion

uint32_t srt_getversion();

Get SRT version value. The version format in hex is 0xXXYYZZ for x.y.z in human readable form. E.g. 0x012033 means version 1.20.33.

Returns
SRT Version Unsigned 32-bit integer

⬆️   Back to List of Functions & Structures

Helper Data Types for Transmission

NOTE: There might be a difference in terminology used in Internet Draft and current documentation. Please consult Data Transmission Modes and Best Practices and Configuration Tips for Data Transmission via SRT sections of the Internet Draft additionally. The current section is going to be reworked accordingly.

SRT_MSGCTRL

The SRT_MSGCTRL structure:

typedef struct SRT_MsgCtrl_
{
   int flags;                   // Left for future
   int msgttl;                  // TTL for a message, default -1 (no TTL limitation)
   int inorder;                 // Whether a message is allowed to supersede a partially lost one. Unused in stream and live mode
   int boundary;                // 0:mid pkt, 1(01b):end of frame, 2(11b):complete frame, 3(10b): start of frame
   int64_t srctime;             // Source time, in microseconds since SRT internal clock epoch
   int32_t pktseq;              // Sequence number of the first packet in received message (unused for sending)
   int32_t msgno;               // Message number (output value for both sending and receiving)
   SRT_SOCKGROUPDATA* grpdata;  // Pointer to group data array
   size_t grpdata_size;         // Size of the group array
} SRT_MSGCTRL;

The SRT_MSGCTRL structure is used in srt_sendmsg2 and srt_recvmsg2 calls and specifies some special extra parameters:

  • flags: [IN, OUT]. RESERVED FOR FUTURE USE (should be 0). This is intended to specify some special options controlling the details of how the called function should work.

  • msgttl: [IN]. In message and live mode only, specifies the TTL for sending messages (in [ms]). Not used for receiving messages. If this value is not negative, it defines the maximum time up to which this message should stay scheduled for sending. If TTL has expired, the message sending and further retransmissions are discarded, even if it has never been sent so far.

  • inorder: [IN]. In message mode only, specifies that sent messages should be extracted by the receiver in the order of sending. This can be meaningful if a packet loss has happened, and a particular message must wait for retransmission so that it can be reassembled and then delivered. When this flag is false, the message can be delivered even if there are any previous messages still waiting for completion.

  • boundary: RESERVED FOR FUTURE USE. Intended to be used in a special mode when you are allowed to send or retrieve a part of the message.

  • srctime:

    • [OUT] Receiver only. Specifies the time when the packet was intended to be delivered to the receiving application (in microseconds since SRT clock epoch).
    • [IN] Sender only. Specifies the application-provided timestamp to be associated with the packet. If not provided (specified as 0), the current time of SRT internal clock is used.
    • For details on how to use srctime please refer to the Time Access section.

  • pktseq: Receiver only. Reports the sequence number for the packet carrying out the payload being returned. If the payload is carried out by more than one UDP packet, only the sequence of the first one is reported. Note that in live mode there's always one UDP packet per message.

  • msgno: Message number that can be sent by both sender and receiver, although it is required that this value remain monotonic in subsequent send calls. Normally message numbers start with 1 and increase with every message sent.

  • grpdata and grpdata_size: Pointer and size of the group array. For single socket connections these values should remain NULL and 0 respectively. When you call srt_sendmsg2 or srt_recvmsg2 function for a group, you should pass an array here so that you can retrieve the status of particular member sockets. If you pass an array that is too small, your grpdata_size field will be rewritten with the current number of members, but without filling in the array; otherwise both fields are updated to reflect the current connection state of the group. For details, see the SRT Connection Bonding: Quick Start and SRT Connection Bonding: Socket Groups documents.

For more information about SRT_SOCKGROUPDATA and obtaining the group data, please refer to srt_group_data. Note that the group data filling by srt_sendmsg2 and srt_recvmsg2 calls differs in one aspect to srt_group_data: member sockets that were found broken after the operation will appear in the group data with SRTS_BROKEN state once after the operation was done, although the sockets assigned to these members are already closed and they are removed as members already. In case of srt_group_data they will not appear at all.

Helpers for SRT_MSGCTRL:

void srt_msgctrl_init(SRT_MSGCTRL* mctrl);
const SRT_MSGCTRL srt_msgctrl_default;

Helpers for getting an object of SRT_MSGCTRL type ready to use. The first is a function that fills the object with default values. The second is a constant object and can be used as a source for assignment. Note that you cannot pass this constant object into any of the API functions because they require it to be mutable, as they use some fields to output values.

⬆️   Back to List of Functions & Structures

Transmission

NOTE: There might be a difference in terminology used in Internet Draft and current documentation. Please consult Data Transmission Modes and Best Practices and Configuration Tips for Data Transmission via SRT sections of the Internet Draft additionally. The current section is going to be reworked accordingly.

srt_send

srt_sendmsg

srt_sendmsg2

int srt_send(SRTSOCKET u, const char* buf, int len);
int srt_sendmsg(SRTSOCKET u, const char* buf, int len, int ttl/* = -1*/, int inorder/* = false*/);
int srt_sendmsg2(SRTSOCKET u, const char* buf, int len, SRT_MSGCTRL *mctrl);

Sends a payload to a remote party over a given socket.

Arguments:

  • u: Socket used to send. The socket must be connected for this operation.
  • buf: Points to the buffer containing the payload to send.
  • len: Size of the payload specified in buf.
  • ttl: Time (in [ms]) to wait for a successful delivery. See description of the SRT_MSGCTRL::msgttl field.
  • inorder: Required to be received in the order of sending. See SRT_MSGCTRL::inorder.
  • mctrl: An object of SRT_MSGCTRL type that contains extra parameters, including ttl and inorder.

The way this function works is determined by the mode set in options, and it has specific requirements:

  1. In file/stream mode, the payload is byte-based. You are not required to know the size of the data, although they are only guaranteed to be received in the same byte order.

  2. In file/message mode, the payload that you send using this function is a single message that you intend to be received as a whole. In other words, a single call to this function determines a message's boundaries.

  3. In live mode, you are only allowed to send up to the length of SRTO_PAYLOADSIZE, which can't be larger than 1456 bytes (1316 default).

Returns
Size Size of the data sent, if successful
SRT_ERROR In case of error (-1)

NOTE: Note that in file/stream mode the returned size may be less than len, which means that it didn't send the whole contents of the buffer. You would need to call this function again with the rest of the buffer next time to send it completely. In both file/message and live mode the successful return is always equal to len.

Errors
SRT_ENOCONN Socket u used when the operation is not connected.
SRT_ECONNLOST Socket u used for the operation has lost its connection.
SRT_EINVALMSGAPI Incorrect API usage in message mode:
live mode: trying to send more bytes at once than SRTO_PAYLOADSIZE or wrong source time
was provided.
SRT_EINVALBUFFERAPI Incorrect API usage in stream mode (reserved for future use):
The congestion controller object used for this mode doesn't use any restrictions on this call,
but this may change.
SRT_ELARGEMSG Message to be sent can't fit in the sending buffer (that is, it exceeds the current total space in the
sending buffer in bytes). This means that the sender buffer is too small, or the application is
trying to send a larger message than initially predicted.
SRT_EASYNCSND There's no free space currently in the buffer to schedule the payload. This is only reported in
non-blocking mode (SRTO_SNDSYN set to false); in blocking mode the call is blocked until
enough free space in the sending buffer becomes available.
SRT_ETIMEOUT The condition described above still persists and the timeout has passed. This is only reported in
blocking mode when SRTO_SNDTIMEO is set to a value other than -1.
SRT_EPEERERR This is reported only in the case where, as a stream is being received by a peer, the
srt_recvfile function encounters an error during a write operation on a file. This is reported by
a UMSG_PEERERROR message from the peer, and the agent sets the appropriate flag internally.
This flag persists up to the moment when the connection is broken or closed.

⬆️   Back to List of Functions & Structures

srt_recv

srt_recvmsg

srt_recvmsg2

int srt_recv(SRTSOCKET u, char* buf, int len);
int srt_recvmsg(SRTSOCKET u, char* buf, int len);
int srt_recvmsg2(SRTSOCKET u, char *buf, int len, SRT_MSGCTRL *mctrl);

Extracts the payload waiting to be received. Note that srt_recv and srt_recvmsg are identical functions, two different names being kept for historical reasons. In the UDT predecessor the application was required to use either the UDT::recv version for stream mode and UDT::recvmsg for message mode. In SRT this distinction is resolved internally by the SRTO_MESSAGEAPI flag.

Arguments:

  • u: Socket used to send. The socket must be connected for this operation.
  • buf: Points to the buffer to which the payload is copied.
  • len: Size of the payload specified in buf.
  • mctrl: An object of SRT_MSGCTRL type that contains extra parameters.

The way this function works is determined by the mode set in options, and it has specific requirements:

  1. In file/stream mode, as many bytes as possible are retrieved, that is, only so many bytes that fit in the buffer and are currently available. Any data that is available but not extracted this time will be available next time.

  2. In file/message mode, exactly one message is retrieved, with the boundaries defined at the moment of sending. If some parts of the messages are already retrieved, but not the whole message, nothing will be received (the function blocks or returns SRT_EASYNCRCV). If the message to be returned does not fit in the buffer, nothing will be received and the error is reported.

  3. In live mode, the function behaves as in file/message mode, although the number of bytes retrieved will be at most the maximum payload of one MTU. The SRTO_PAYLOADSIZE value configured by the sender is not negotiated, and not known to the receiver. The SRTO_PAYLOADSIZE value set on the SRT receiver is mainly used for heuristics. However, the receiver is prepared to receive the whole MTU as configured with SRTO_MSS. In this mode, however, with default settings of SRTO_TSBPDMODE and SRTO_TLPKTDROP, the message will be received only when its time to play has come, and until then it will be kept in the receiver buffer. Also, when the time to play has come for a message that is next to the currently lost one, it will be delivered and the lost one dropped.

Returns
Size value > 0 Size of the data received, if successful.
0 If the connection has been closed
SRT_ERROR (-1) when an error occurs
Errors
SRT_ENOCONN Socket u used for the operation is not connected.
SRT_ECONNLOST Socket u used for the operation has lost connection (this is reported only if the connection
was unexpectedly broken, not when it was closed by the foreign host).
SRT_EINVALMSGAPI Incorrect API usage in message mode:
-- live mode: size of the buffer is less than SRTO_PAYLOADSIZE
SRT_EINVALBUFFERAPI Incorrect API usage in stream mode:
• Currently not in use. File congestion control used for stream mode does not restrict
the parameters. ⚠️   ???
SRT_ELARGEMSG Message to be sent can't fit in the sending buffer (that is, it exceeds the current total space in
the sending buffer in bytes). This means that the sender buffer is too small, or the application
is trying to send a larger message than initially intended.
SRT_EASYNCRCV There are no data currently waiting for delivery. This happens only in non-blocking mode
(when SRTO_RCVSYN is set to false). In blocking mode the call is blocked until the data are ready.
How this is defined, depends on the mode:
• In live mode (with SRTO_TSBPDMODE on), at least one packet must be present in the receiver
buffer and its time to play be in the past
• In file/message mode, one full message must be available, the next one waiting if there are no
messages with inorder = false, or possibly the first message ready with inorder = false
• In file/stream mode, it is expected to have at least one byte of data still not extracted
SRT_ETIMEOUT The readiness condition described above is still not achieved and the timeout has passed.
This is only reported in blocking mode whenSRTO_RCVTIMEO is set to a value other than -1.

⬆️   Back to List of Functions & Structures

srt_sendfile

srt_recvfile

int64_t srt_sendfile(SRTSOCKET u, const char* path, int64_t* offset, int64_t size, int block);
int64_t srt_recvfile(SRTSOCKET u, const char* path, int64_t* offset, int64_t size, int block);

These are functions dedicated to sending and receiving a file. You need to call this function just once for the whole file, although you need to know the size of the file prior to sending, and also define the size of a single block that should be internally retrieved and written into a file in a single step. This influences only the performance of the internal operations; from the application perspective you just have one call that exits only when the transmission is complete.

Arguments:

  • u: Socket used for transmission. The socket must be connected.
  • path: Path to the file that should be read or written.
  • offset: Needed to pass or retrieve the offset used to read or write to a file
  • size: Size of transfer (file size, if offset is at 0)
  • block: Size of the single block to read at once before writing it to a file

The following values are recommended for the block parameter:

#define SRT_DEFAULT_SENDFILE_BLOCK 364000
#define SRT_DEFAULT_RECVFILE_BLOCK 7280000

You need to pass them to the srt_sendfile or srt_recvfile function if you don't know what value to chose.

Returns
Size value > 0 The size of the transmitted data of a file. It may be less than size, if the size was greater
than the free space in the buffer, in which case you have to send rest of the file next time.
-1 in case of error
Errors
SRT_ENOCONN Socket u used for the operation is not connected.
SRT_ECONNLOST Socket u used for the operation has lost its connection.
SRT_EINVALBUFFERAPI When socket has SRTO_MESSAGEAPI = true or SRTO_TSBPDMODE = true.
(:warning:   BUG?: Looxlike MESSAGEAPI isn't checked)
SRT_EINVRDOFF There is a mistake in offset or size parameters, which should match the index availability
and size of the bytes available since offset index. This is actually reported for srt_sendfile
when the seekg or tellg operations resulted in error.
SRT_EINVWROFF Like above, reported for srt_recvfile and seekp/tellp.
SRT_ERDPERM The read from file operation has failed (srt_sendfile).
SRT_EWRPERM The write to file operation has failed (srt_recvfile).

⬆️   Back to List of Functions & Structures

Performance Tracking

Sequence Numbers: The sequence numbers used in SRT are 32-bit "circular numbers" with the most significant bit not included. For example 0x7FFFFFFF shifted forward by 3 becomes 2. As far as any comparison is concerned, it can be thought of as a "distance" which is an integer value expressing an offset to be added to one sequence number in order to get the second one. This distance is only valid as long as the threshold value isn't exceeded, so it's understood that all sequence numbers that are anywhere taken into account are systematically updated and kept in the range between 0 and half of the maximum 0x7FFFFFFF. Hence, the distance counting procedure always assumes that the sequence number are in the required range already, so for a numbers like 0x7FFFFFF0 and 0x10, for which the "numeric difference" would be 0x7FFFFFE0, the "distance" is 0x20.

srt_bstats

srt_bistats

// Performance monitor with Byte counters for better bitrate estimation.
SRTSTATUS srt_bstats(SRTSOCKET u, SRT_TRACEBSTATS * perf, int clear);

// Performance monitor with Byte counters and instantaneous stats instead of moving averages for Snd/Rcvbuffer sizes.
SRTSTATUS srt_bistats(SRTSOCKET u, SRT_TRACEBSTATS * perf, int clear, int instantaneous);

Reports the current statistics

Arguments:

  • u: Socket from which to get statistics
  • perf: Pointer to an object to be written with the statistics
  • clear: 1 if the statistics should be cleared after retrieval
  • instantaneous: 1 if the statistics should use instant data, not moving averages

SRT_TRACEBSTATS is an alias to struct CBytePerfMon. For a complete description of the fields please refer to SRT Statistics.

Errors
SRT_EINVSOCK Invalid socket ID provided.
SRT_ECONNLOST Connection lost (group socket).
SRT_ENOCONN Not connected (group socket).

⬆️   Back to List of Functions & Structures

Asynchronous Operations (Epoll)

The epoll system is currently the only method for using multiple sockets in one thread with having the blocking operation moved to epoll waiting so that it can block on multiple sockets at once. That is, instead of blocking a single reading or writing operation, as it's in blocking mode, it blocks until at least one of the sockets subscribed for a single waiting call in given operation mode is ready to do this operation without blocking. It's usually combined with setting the nonblocking mode on a socket. In SRT this is set separately for reading and writing (SRTO_RCVSYN and SRTO_SNDSYN respectively). This is to ensure that if there is internal error in the application (or even possibly a bug in SRT that has reported a spurious readiness report) the operation will end up with an error rather than cause blocking, which would be more dangerous for the application (SRT_EASYNCRCV and SRT_EASYNCSND respectively).

The epoll system, similar to the one on Linux, relies on eid objects managed internally in SRT, which can be subscribed to particular sockets and the readiness status of particular operations. The srt_epoll_wait function can then be used to block until any readiness status in the whole eid is set.

srt_epoll_create

int srt_epoll_create(void);

Creates a new epoll container and returns its identifier (EID).

Returns
valid EID >= 0 Success
-1 Failure
Errors
SRT_ECONNSETUP System operation failed or not enough space to create a new epoll. System error might happen on
systems that use a special method for the system part of epoll (epoll_create(), kqueue()),
and therefore associated resources, like epoll on Linux.

⬆️   Back to List of Functions & Structures

srt_epoll_add_usock

srt_epoll_add_ssock

srt_epoll_update_usock

srt_epoll_update_ssock

SRTSTATUS srt_epoll_add_usock(int eid, SRTSOCKET u, const int* events);
SRTSTATUS srt_epoll_add_ssock(int eid, SYSSOCKET s, const int* events);
SRTSTATUS srt_epoll_update_usock(int eid, SRTSOCKET u, const int* events);
SRTSTATUS srt_epoll_update_ssock(int eid, SYSSOCKET s, const int* events);

Adds a socket to a container, or updates an existing socket subscription.

The _usock suffix refers to a user socket (SRT socket). The _ssock suffix refers to a system socket.

The _add_ functions add new sockets. The _update_ functions act on a socket that is in the container already and just allow changes in the subscription details. For example, if you have already subscribed a socket with SRT_EPOLL_OUT to wait until it's connected, to change it into poll for read-readiness, you use this function on that same socket with a variable set to SRT_EPOLL_IN. This will not only change the event type which is polled on the socket, but also remove any readiness status for flags that are no longer set. It is discouraged to perform socket removal and adding back (instead of using _update_) because this way you may miss an event that could happen in the brief moment between these two calls.

Arguments:

  • eid: epoll container id
  • u: SRT socket
  • s(#s): system socket
  • events: points to
    • a variable set to epoll flags (see below) to use only selected events
    • NULL if you want to subscribe a socket for all events in level-triggered mode

Possible epoll flags are the following:

All flags except SRT_EPOLL_ET are event type flags (important for functions that expect only event types and not other flags).

The SRT_EPOLL_IN, SRT_EPOLL_OUT and SRT_EPOLL_ERR events are by default level-triggered. With SRT_EPOLL_ET flag they become edge-triggered.

The SRT_EPOLL_UPDATE flag is always edge-triggered. It designates a special event that happens on a group, or on a listener socket that has the SRTO_GROUPCONNECT flag set to allow group connections. This flag is triggered in the following situations:

  • for group connections, when a new link has been established for a group that is already connected (that is, has at least one connection established), SRT_EPOLL_UPDATE is reported for the listener socket accepting the connection. This is intended for internal use only. An initial connection results in reporting the group connection on that listener. But when the group is already connected, SRT_EPOLL_UPDATE is reported instead.

  • when one of a group's member connection has been broken

Note that at this time the edge-triggered mode is supported only for SRT sockets, not for system sockets.

In the edge-triggered mode the function will only return socket states that have changed since the last call of the waiting function. All events reported in a particular call of the waiting function will be cleared in the internal flags and will not be reported until the internal signalling logic clears this state and raises it again.

In the level-triggered mode the function will always return the readiness state as long as it lasts, until the internal signalling logic clears it.

Note that when you use SRT_EPOLL_ET flag in one subscription call, it defines edge-triggered mode for all events passed together with it. However, if you want to have some events reported as edge-triggered and others as level-triggered, you can do two separate subscriptions for the same socket.

IMPORTANT: The srt_epoll_wait function does not report SRT_EPOLL_UPDATE events. If you need the ability to get any possible flag, you must use srt_epoll_uwait. Note that this function doesn't work with system file descriptors.

Errors
SRT_EINVPOLLID eid parameter doesn't refer to a valid epoll container

⚠️   BUG?: for add_ssock the system error results in an empty CUDTException() call which actually results in SRT_SUCCESS. For cases like that the SRT_ECONNSETUP code is predicted.

⬆️   Back to List of Functions & Structures

srt_epoll_remove_usock

srt_epoll_remove_ssock

SRTSTATUS srt_epoll_remove_usock(int eid, SRTSOCKET u);
SRTSTATUS srt_epoll_remove_ssock(int eid, SYSSOCKET s);

Removes a specified socket from an epoll container and clears all readiness states recorded for that socket.

The _usock suffix refers to a user socket (SRT socket). The _ssock suffix refers to a system socket.

Errors
SRT_EINVPOLLID eid parameter doesn't refer to a valid epoll container

⬆️   Back to List of Functions & Structures

srt_epoll_wait

int srt_epoll_wait(int eid, SRTSOCKET* readfds, int* rnum, SRTSOCKET* writefds, int* wnum, int64_t msTimeOut,
                        SYSSOCKET* lrfds, int* lrnum, SYSSOCKET* lwfds, int* lwnum);

Blocks the call until any readiness state occurs in the epoll container.

Readiness can be on a socket in the container for the event type as per subscription. Note that in the case when a particular event was subscribed with SRT_EPOLL_ET flag, this event, once reported in this function, will be cleared internally.

The first readiness state causes this function to exit, but all ready sockets are reported. This function blocks until the timeout specified in the msTimeOut parameter. If timeout is 0, it exits immediately after checking. If timeout is -1, it blocks indefinitely until a readiness state occurs.

Arguments:

  • eid: epoll container
  • readfds and rnum: A pointer and length of an array to write SRT sockets that are read-ready
  • writefds and wnum: A pointer and length of an array to write SRT sockets that are write-ready
  • msTimeOut: Timeout specified in milliseconds, or special values (0 or -1)
  • lwfds and lwnum: A pointer and length of an array to write system sockets that are read-ready
  • lwfds and lwnum: A pointer and length of an array to write system sockets that are write-ready

Note that the following flags are reported:

There is no space here to report sockets for which it's already known that the operation will end up with error (although such a state is known internally). If an error occurred on a socket then that socket is reported in both read-ready and write-ready arrays, regardless of what event types it was subscribed for. Usually then you subscribe the given socket for only read readiness, for example (SRT_EPOLL_IN), but pass both arrays for read and write readiness.This socket will not be reported in the write readiness array even if it's write ready (because this isn't what it was subscribed for), but it will be reported there, if the next operation on this socket is about to be erroneous. On such sockets you can still perform an operation, just you should expect that it will always report an error. On the other hand that's the only way to know what kind of error has occurred on the socket.

Returns
Number > 0 The number of ready sockets, of whatever kind (if any)
-1 Error
Errors
SRT_EINVPOLLID eid parameter doesn't refer to a valid epoll container
SRT_ETIMEOUT Up to msTimeOut no sockets subscribed in eid were ready. This is reported only if msTimeOut
was >=0, otherwise the function waits indefinitely.

⬆️   Back to List of Functions & Structures

srt_epoll_uwait

int srt_epoll_uwait(int eid, SRT_EPOLL_EVENT* fdsSet, int fdsSize, int64_t msTimeOut);

This function blocks a call until any readiness state occurs in the epoll container. Unlike srt_epoll_wait, it can only be used with eid subscribed to user sockets (SRT sockets), not system sockets.

This function blocks until the timeout specified in msTimeOut parameter. If timeout is 0, it exits immediately after checking. If timeout is -1, it blocks indefinitely until a readiness state occurs.

Arguments:

  • eid: epoll container
  • fdsSet : A pointer to an array of SRT_EPOLL_EVENT
  • fdsSize : The size of the fdsSet array
  • msTimeOut : Timeout specified in milliseconds, or special values (0 or -1):
    • 0: Don't wait, return immediately (report any sockets currently ready)
    • -1: Wait indefinitely.
Returns
Number > 0 The number of user socket (SRT socket) state changes that have been reported in fdsSet,
if this number isn't greater than fdsSize
fdsSize + 1 This means that there was not enough space in the output array to report all events.
For events subscribed with the SRT_EPOLL_ET flag only those will be cleared that were reported.
Others will wait for the next call.
0 If no readiness state was found on any socket and the timeout has passed
(this is not possible when waiting indefinitely)
-1 Error
Errors
SRT_EINVPOLLID eid parameter doesn't refer to a valid epoll container
SRT_EINVPARAM Usage error (see below)

Usage errors reported as SRT_EINVPARAM:

  • fdsSize is < 0
  • fdsSize is > 0 and fdsSet is a null pointer
  • eid was subscribed to any system socket

IMPORTANT: This function reports timeout by returning 0, not by SRT_ETIMEOUT error.

The SRT_EPOLL_EVENT structure:

typedef struct SRT_EPOLL_EVENT_
{
    SRTSOCKET fd;
    int       events;
} SRT_EPOLL_EVENT;

Note that when SRT_EPOLL_ERR is set, the underlying socket error can't be retrieved with srt_getlasterror(). The socket will be automatically closed and its state can be verified with a call to srt_getsockstate.

⬆️   Back to List of Functions & Structures

srt_epoll_clear_usocks

SRTSTATUS srt_epoll_clear_usocks(int eid);

This function removes all SRT ("user") socket subscriptions from the epoll container identified by eid.

Errors
SRT_EINVPOLLID eid parameter doesn't refer to a valid epoll container

⬆️   Back to List of Functions & Structures

srt_epoll_set

int32_t srt_epoll_set(int eid, int32_t flags);

This function allows setting or retrieving flags that change the default behavior of the epoll functions. All default values for these flags are 0. The following flags are available:

  • SRT_EPOLL_ENABLE_EMPTY: allows the srt_epoll_wait and srt_epoll_uwait functions to be called with the EID not subscribed to any socket. The default behavior of these function is to report error in this case.

  • SRT_EPOLL_ENABLE_OUTPUTCHECK: Forces the srt_epoll_wait and srt_epoll_uwait functions to check if the output array is not empty. For srt_epoll_wait it is still allowed that either system or user array is empty, as long as EID isn't subscribed to this type of socket/fd. srt_epoll_uwait only checks if the general output array is not empty.

Arguments:

  • eid: the epoll container id
  • flags: a nonzero set of the above flags, or special values:
    • 0: clear all flags (set all defaults)
    • -1: do not modify any flags
Returns
This function returns the state of the flags at the time before the call
SRT_ERROR (-1) Special value in case when an error occurred
Errors
SRT_EINVPOLLID eid parameter doesn't refer to a valid epoll container

⬆️   Back to List of Functions & Structures

srt_epoll_release

SRTSTATUS srt_epoll_release(int eid);

Deletes the epoll container.

Errors
SRT_EINVPOLLID eid parameter doesn't refer to a valid epoll container

⬆️   Back to List of Functions & Structures

Logging Control

SRT has a widely used system of logs, as this is usually the only way to determine how the internals are working without changing the rules by the act of tracing. Logs are split into levels (5 levels out of those defined by syslog are in use) and additional filtering is possible on an FA (functional area). By default only entries up to the Note log level are displayed and from all FAs.

Logging can only be manipulated globally, with no regard to a specific socket. This is because lots of operations in SRT are not dedicated to any particular socket, and some are shared between sockets.

srt_setloglevel

void srt_setloglevel(int ll);

Sets the minimum severity for logging. A particular log entry is displayed only if it has a severity greater than or equal to the minimum. Setting this value to LOG_DEBUG turns on all levels.

The constants for this value are those from <sys/syslog.h> (for Windows, refer to common/win/syslog_defs.h). The only meaningful ones are:

  • LOG_DEBUG: Highly detailed and very frequent messages
  • LOG_NOTICE: Occasionally displayed information
  • LOG_WARNING: Unusual behavior
  • LOG_ERR: Abnormal behavior
  • LOG_CRIT: Error that makes the current socket unusable

⬆️   Back to List of Functions & Structures

srt_addlogfa

srt_dellogfa

srt_resetlogfa

void srt_addlogfa(int fa);
void srt_dellogfa(int fa);
void srt_resetlogfa(const int* fara, size_t fara_size);

A functional area (FA) is an additional filtering mechanism for logging. You can set up logging to display logs only from selected FAs. The list of FAs is collected in the srt.h file, as identified by the SRT_LOGFA_ prefix. They are not enumerated here because they may be changed very often.

All FAs are turned on by default, except potentially dangerous ones (such as SRT_LOGFA_HAICRYPT). The reason is that they may display either some security information that shall remain in memory only (so, only if strictly required for development), or some duplicated information (so you may want to turn one FA on, while turning off the others).

⬆️   Back to List of Functions & Structures

srt_setloghandler

void srt_setloghandler(void* opaque, SRT_LOG_HANDLER_FN* handler);
typedef void SRT_LOG_HANDLER_FN(void* opaque, int level, const char* file, int line, const char* area, const char* message);

By default logs are printed to standard error stream. This function replaces the sending to a stream with a handler function that will receive them.

⬆️   Back to List of Functions & Structures

srt_setlogflags

void srt_setlogflags(int flags);

When you set a log handler with srt_setloghandler, you may also want to configure which parts of the log information you do not wish to be passed in the log line (the message parameter). A user's logging facility may, for example, not wish to get the current time or log level marker, as it will provide this information on its own.

The following flags are available, as collected in the logging_api.h public header:

  • SRT_LOGF_DISABLE_TIME: Do not provide the time in the header
  • SRT_LOGF_DISABLE_THREADNAME: Do not provide the thread name in the header
  • SRT_LOGF_DISABLE_SEVERITY: Do not provide severity information in the header
  • SRT_LOGF_DISABLE_EOL: Do not add the end-of-line character to the log line

⬆️   Back to List of Functions & Structures

Time Access

The following set of functions is intended to retrieve timestamps from the clock used by SRT.

The sender can pass the timestamp in MSGCTRL::srctime of the srt_sendmsg2(..) function together with the packet being submitted to SRT. If the srctime value is not provided (the default value of 0 is set), SRT will use the internal clock and assign packet submission time as the packet timestamp. If the sender wants to explicitly assign a timestamp to a certain packet this timestamp MUST be taken from SRT Time Access functions. The time value provided MUST equal or exceed the connection start time (srt_connection_time(..)) of the SRT socket passed to srt_sendmsg2(..).

The current time value of the SRT internal clock can be retrieved using the srt_time_now() function.

There are two known cases where you might want to use srctime:

  1. SRT passthrough (for stream gateways). You may wish to simply retrieve packets from an SRT source and pass them transparently to an SRT output (possibly re-encrypting). In that case, every packet you read should preserve the original value of srctime as obtained from srt_recvmsg2, and the original srctime for each packet should be then passed to srt_sendmsg2. This mechanism could be used to avoid jitter resulting from varying differences between the time of receiving and sending the same packet.

  2. Stable timing source. In the case of a live streaming procedure, when spreading packets evenly into the stream, you might want to predefine times for every single packet to keep time intervals perfectly equal. Or, if you believe that your input signal delivers packets at the exact times that should be assigned to them, you might want to preserve these times at the SRT receiving side to avoid jitter that may result from varying time differences between the packet arrival and the moment when sending it over SRT. In such cases you might do the following:

    • At the packet arrival time, grab the current time at that moment using srt_time_now().

    • When you want a pre-calculated packet time, use a private relative time counter set at the moment when the connection was made. From the moment when your first packet is ready, start pre-calculating packet times relative to the connection start time obtained from srt_connection_time(). Although you still have to synchronize sending times with these predefined times, by explicitly specifying the source time you avoid the jitter resulting from a lost accuracy due to waiting time and unfortunate thread scheduling.

Note that srctime uses an internally defined clock that is intended to be monotonic (the definition depends on the build flags, see below). Because of that the application should not define this time basing on values obtained from the system functions for getting the current system time (such as time, ftime or gettimeofday). To avoid problems and misunderstanding you should rely exclusively on time values provided by the srt_time_now() and srt_connection_time() functions.

The clock used by the SRT internal clock is determined by the following build flags:

  • ENABLE_MONOTONIC makes use of CLOCK_MONOTONIC with clock_gettime function.
  • ENABLE_STDXXX_SYNC makes use of std::chrono::steady_clock.

The default is currently to use the system clock as the internal SRT clock, although it's highly recommended to use one of the above monotonic clocks, as system clock is vulnerable to time modifications during transmission.

srt_time_now

int64_t srt_time_now();

Get time in microseconds elapsed since epoch using SRT internal clock (steady or monotonic clock).

Returns
Current time in microseconds elapsed since epoch of SRT internal clock.

⬆️   Back to List of Functions & Structures

srt_connection_time

int64_t srt_connection_time(SRTSOCKET sock);

Get connection time in microseconds elapsed since epoch using SRT internal clock (steady or monotonic clock). The connection time represents the time when SRT socket was open to establish a connection. Milliseconds elapsed since connection start time can be determined using Performance tracking functions and msTimeStamp value of the SRT_TRACEBSTATS (see SRT Statistics).

Returns
Connection time in microseconds elapsed since epoch of SRT internal clock
SRT_ERROR (-1) Error
Errors
SRT_EINVSOCK Socket sock is not an ID of a valid SRT socket

⬆️   Back to List of Functions & Structures

srt_clock_type

int srt_clock_type(void);

Get the type of clock used internally by SRT to be used only for informational purposes. Using any time source except for srt_time_now() and srt_connection_time(SRTSOCKET) to timestamp packets submitted to SRT is not recommended and must be done with awareness and at your own risk.

Returns Clock Type Description
0 SRT_SYNC_CLOCK_STDCXX_STEADY C++11 std::chrono::steady_clock
1 SRT_SYNC_CLOCK_GETTIME_MONOTONIC clock_gettime with CLOCK_MONOTONIC
2 SRT_SYNC_CLOCK_WINQPC Windows QueryPerformanceCounter(..)
3 SRT_SYNC_CLOCK_MACH_ABSTIME mach_absolute_time()
4 SRT_SYNC_CLOCK_POSIX_GETTIMEOFDAY POSIX gettimeofday(..)
5 SRT_SYNC_CLOCK_AMD64_RDTSC asm("rdtsc" ..)
6 SRT_SYNC_CLOCK_IA32_RDTSC asm volatile("rdtsc" ..)
7 SRT_SYNC_CLOCK_IA64_ITC asm("mov %0=ar.itc" ..)
Errors
None

⬆️   Back to List of Functions & Structures

Diagnostics

General notes concerning the getlasterror diagnostic functions: when an API function ends up with error, this error information is stored in a thread-local storage. This means that you'll get the error of the operation that was last performed as long as you call this diagnostic function just after the failed function has returned. In any other situation the information provided by the diagnostic function is undefined.

NOTE: There are lists of rejection reasons and error codes at the bottom of this section.

srt_getlasterror

int srt_getlasterror(int* errno_loc);

Get the numeric code of the last error. Additionally, in the variable passed as errno_loc the system error value is returned, or 0 if there was no system error associated with the last error. The system error is:

  • On POSIX systems, the value from errno
  • On Windows, the result from GetLastError() call

⬆️   Back to List of Functions & Structures

srt_strerror

const char* srt_strerror(int code, int errnoval);

Returns a string message that represents a given SRT error code and possibly the errno value, if not 0.

NOTE: This function isn't thread safe. It uses a static variable to hold the error description. There's no problem with using it in a multithreaded environment, as long as only one thread in the whole application calls this function at the moment

⬆️   Back to List of Functions & Structures

srt_getlasterror_str

const char* srt_getlasterror_str(void);

Get the text message for the last error. It's a shortcut to calling first srt_getlasterror and then passing the returned value into srt_strerror. Note that, contrary to srt_strerror, this function is thread safe.

⬆️   Back to List of Functions & Structures

srt_clearlasterror

void srt_clearlasterror(void);

This function clears the last error. After this call, srt_getlasterror will report a "successful" code.

⬆️   Back to List of Functions & Structures

srt_rejectreason_str

const char* srt_rejectreason_str(enum SRT_REJECT_REASON id);

Returns a constant string for the reason of the connection rejected, as per given code ID. It provides a system-defined message for values below SRT_REJ_E_SIZE. For other values below SRT_REJC_PREDEFINED it returns the string for SRT_REJ_UNKNOWN. For values since SRT_REJC_PREDEFINED on, returns "Application-defined rejection reason".

⬆️   Back to List of Functions & Structures

srt_setrejectreason

SRTSTATUS srt_setrejectreason(SRTSOCKET sock, int value);

Sets the rejection code on the socket. This call is only useful in the listener callback. The code from value set this way will be set as a rejection reason for the socket. After the callback rejects the connection, the code will be passed back to the caller peer with the handshake response.

Note that allowed values for this function begin with SRT_REJC_PREDEFINED (that is, you cannot set a system rejection code). For example, your application can inform the calling side that the resource specified under the r key in the StreamID string (see SRTO_STREAMID) is not available - it then sets the value to SRT_REJC_PREDEFINED + 404.

Errors
SRT_EINVSOCK Socket sock is not an ID of a valid socket
SRT_EINVPARAM value is less than SRT_REJC_PREDEFINED

⬆️   Back to List of Functions & Structures

srt_getrejectreason

int srt_getrejectreason(SRTSOCKET sock);

This function provides a more detailed reason for a failed connection attempt. It shall be called after a connecting function (such as srt_connect) has returned an error, the code for which is SRT_ECONNREJ. If SRTO_RCVSYN has been set on the socket used for the connection, the function should also be called when the SRT_EPOLL_ERR event is set for this socket. It returns a numeric code, which can be translated into a message by srt_rejectreason_str.

The returned value is one of the values listed in enum SRT_REJECT_REASON. For an invalid value of sock the SRT_REJ_UNKNOWN is returned.

⬆️   Back to List of Functions & Structures

srt_close_getreason

int srt_close_getreason(SRTSOCKET u, SRT_CLOSE_INFO* info);

Retrieves the reason code for closing the socket. This designates the very first reason of closing the socket or group (if there could have been multiple reasons for closing it, only the first one counts).

Note that this information may be retrieved even if the socket is already physically closed, but only for up to 10 seconds after that happens (more precisely, 10 cycles of GC, which run every 1 second) and only up to 10 such records are remembered (newer closed ones push off the oldest one).

Arguments:

  • u: Socket or group that you believe is closed or broken
  • info: The structure where the reason is written, see SRT_CLOSE_INFO

Returns 0 in case of success. Returns SRT_ERROR (-1) in case of error, which may be because:

  • info is a NULL pointer
  • u is an SRT_INVALID_SOCK value
  • u was not found in the closed socket database (expired or was pushed off)

⬆️   Back to List of Functions & Structures

Rejection Reasons

SRT_REJ_UNKNOWN

A fallback value for cases when there was no connection rejected or the reason cannot be obtained.

SRT_REJ_SYSTEM

One system function reported a failure. Usually this means some system error or lack of system resources to complete the task.

SRT_REJ_PEER

The connection has been rejected by peer, but no further details are available. This usually means that the peer doesn't support rejection reason reporting.

SRT_REJ_RESOURCE

A problem with resource allocation (usually memory).

SRT_REJ_ROGUE

The data sent by one party to another cannot be properly interpreted. This should not happen during normal usage, unless it's a bug, or some weird events are happening on the network.

SRT_REJ_BACKLOG

The listener's backlog has exceeded its queue limit (there are many other callers waiting for the opportunity of being connected and wait in the queue, which has reached its limit).

SRT_REJ_IPE

Internal Program Error. This should not happen during normal usage and it usually means a bug in the software (although this can be reported by both local and foreign host).

SRT_REJ_CLOSE

The listener socket was able to receive your request, but at this moment it is being closed. It's likely that your next attempt will result in a timeout.

SRT_REJ_VERSION

One party of the connection has set up a minimum version that is required for that connection, but the other party didn't satisfy this requirement.

SRT_REJ_RDVCOOKIE

Rendezvous cookie collision. This normally should never happen, or the probability that it will happen is negligible. However this can also be a result of a misconfiguration in that you are trying to make a rendezvous connection where both parties try to bind to the same IP address, or both are local addresses of the same host. In such a case the sent handshake packets are returning to the same host as if they were sent by the peer (i.e. a party is sending to itself). When this happens, this reject reason will be reported by every attempt.

SRT_REJ_BADSECRET

Both parties have defined a passphrase for connection, but they differ.

SRT_REJ_UNSECURE

Only one connection party has set up a password. See also the SRTO_ENFORCEDENCRYPTION flag.

SRT_REJ_MESSAGEAPI

The value of the SRTO_MESSAGEAPI flag is different on both connection parties.

SRT_REJ_CONGESTION

The SRTO_CONGESTIONoption has been set up differently on both connection parties.

SRT_REJ_FILTER

The SRTO_PACKETFILTER option has been set differently on both connection parties.

SRT_REJ_GROUP

The group type or some group settings are incompatible for both connection parties. While every connection within a bonding group may have different target addresses, they should all designate the same endpoint and the same SRT application. If this condition isn't satisfied, then the peer will respond with a different peer group ID for the connection that is trying to contact a machine/application that is completely different from the existing connections in the bonding group.

SRT_REJ_TIMEOUT

The connection wasn't rejected, but it timed out. This code is always set on connection timeout, but this is the only way to get this state in non-blocking mode (see SRTO_RCVSYN).

There may also be server and user rejection codes, as defined by the SRT_REJC_INTERNAL, SRT_REJC_PREDEFINED and SRT_REJC_USERDEFINED constants. Note that the number space from the value of SRT_REJC_PREDEFINED and above is reserved for "predefined codes" (SRT_REJC_PREDEFINED value plus adopted HTTP codes). Values above SRT_REJC_USERDEFINED are freely defined by the application.

SRT_REJ_CRYPTO

Settings for SRTO_CRYPTOMODE on both parties are not compatible with one another. See SRTO_CRYPTOMODE for details.

SRT_REJ_CONFIG

Settings for various transmission parameters that are supposed to be negotiated during the handshake (in order to agree upon a common value) are under restrictions that make finding common values for them impossible. Cases include:

  • SRTO_PAYLOADSIZE, which is nonzero in live mode, is set to a value that exceeds the free space in a single packet that results from the value of the negotiated MSS value

⬆️   Back to List of Functions & Structures

SRT_CLOSE_INFO

This structure can be used to get the closing reason (simplified definition):

struct SRT_CLOSE_INFO
{
    SRT_CLOSE_REASON agent;
    SRT_CLOSE_REASON peer;
    int64_t time;
};

Where:

  • agent: The reason code set on the agent ("this machine") side of the connection if the very first reason of closing has happened on the agent. If the closing was initiated by the peer, this field contains SRT_CLS_PEER value

  • peer: If agent == SRT_CLS_PEER, then closing was initiated by peer and this field contains the value of this reason

  • time: Time when closing has happened, in the same convention as the time value supplied by srt_time_now

The values for agent and peer can be internal, out of the below shown list, or it can be a user code, if the value is at least SRT_CLSC_USER.

Closing reasons

SRT_CLS_UNKNOWN

The reason not set. The value is used as a fallback if the reason wasn't properly set.

SRT_CLS_INTERNAL

Closed by internal reasons during connection attempt.

SRT_CLS_PEER

Closed by the peer (the value is to be used on agent). This happens when the closing action has been initiated by peer through sending the UMSG_SHUTDOWN message.

SRT_CLS_RESOURCE

A problem with resource allocation.

SRT_CLS_ROGUE

Received wrong data in the packet. This happens when the socket was closed due to security reasons, when the data in the packet do not match the expected protocol specification.

SRT_CLS_OVERFLOW

Emergency close due to receiver buffer's double overflow that has lead to an irrecoverable situation. This happens when too slow reading data by the application has caused that first, incoming packets cannot be inserted into the buffer because the position in the buffer mapped to their sequence number locates them outside the buffer. If this situation isn't quickly recovered from, it causes eventually that the sequence number distance between the last packet still stored in the buffer and the newly incoming packet exceeds the size of the receiver buffer. This is then an irrecoverable situation and in result the socket is closed with this code as a reason.

SRT_CLS_IPE

Internal program error. Currently used if the incoming acknowledge packet represents the sequence number that has never been sent, or the value is out of any valid range.

SRT_CLS_API

The socket has been closed by the API call of srt_close(). This code is set also if the reason value used in srt_close_withreason() is less than SRT_CLSC_USER.

SRT_CLS_FALLBACK

This value is set on the peer field in case when the peer runs the SRT version that does not support this feature. If this feature is supported, then the peer should send UMSG_SHUTDOWN message with the reason value, which will be then set on the peer field.

SRT_CLS_LATE

Accepted-socket late-rejection or in-handshake rollback. The late rejection is something that may happen when the listener side responds to the caller with a proper handshake message, but the caller rejects that message by some reason. This way, the caller gets closed with a rejection reason, but at this moment the accepted socket on the listener side considers itself connected. Therefore the caller socket in this situation sends first the UMSG_SHUTDOWN message to the peer (that is, the accepted socket) and in result the accepted socket gets closed with this reason code.

SRT_CLS_CLEANUP

All sockets are being closed due to srt_cleanup() call.

SRT_CLS_DEADLSN

This is an accepted socket off a dead listener. If the listener socket has been closed before the accepted socket could be completed, the socket can be returned as valid, but could not be used due to having the listener socket closed too early.

SRT_CLS_PEERIDLE

Peer didn't send any packet for a time of SRTO_PEERIDLETIMEO. This means that the peer idle timeout has been reached while waiting for any packet incoming from the peer.

SRT_CLS_UNSTABLE

Requested to be broken as unstable in Backup group. This happens exclusively in the group of type SRT_GTYPE_BACKUP in case when the link that was used so far for transmission, has become too slowly responsive, which caused activation of one of the backup links, and then this link didn't get back to stability in a given time (the minimum is configured in SRTO_GROUPMINSTABLETIMEO), which caused that the newly activated link has taken over transmission and the socket using the unstable link has been closed with this reason code.

⬆️   Back to List of Functions & Structures

Error Codes

All functions that return the status via int value return -1 (designated as SRT_ERROR) always when the call has failed (in case of resource creation functions an appropriate symbol is defined, like SRT_INVALID_SOCK for SRTSOCKET). When this happens, the error code can be obtained from the srt_getlasterror function. The values for the error are collected in an SRT_ERRNO enum:

SRT_EUNKNOWN

Internal error when setting the right error code.

SRT_SUCCESS

The value set when the last error was cleared and no error has occurred since then.

SRT_ECONNSETUP

General setup error resulting from internal system state.

SRT_ENOSERVER

Connection timed out while attempting to connect to the remote address. Note that when this happens, srt_getrejectreason also reports the timeout reason.

SRT_ECONNREJ

Connection has been rejected. Additional reject reason can be obtained through srt_getrejectreason (see above).

SRT_ESOCKFAIL

An error occurred when trying to call a system function on an internally used UDP socket. Note that the detailed system error is available in the extra variable passed by pointer to srt_getlasterror.

SRT_ESECFAIL

A possible tampering with the handshake packets was detected, or an encryption request wasn't properly fulfilled.

SRT_ESCLOSED

A socket that was vital for an operation called in blocking mode has been closed during the operation. Please note that this situation is handled differently than the system calls for connect and accept functions for TCP, which simply block indefinitely (or until the standard timeout) when the key socket was closed during an operation. When this error is reported, it usually means that the socket passed as the first parameter to srt_connect* or srt_accept is no longer usable.

SRT_ECONNFAIL

General connection failure of unknown details (currently is not reported directly by any API function and it's reserved for future use).

SRT_ECONNLOST

The socket was properly connected, but the connection has been broken. This specialization is reported from the transmission functions.

SRT_ENOCONN

The socket is not connected. This can be reported also when the connection was broken for a function that checks some characteristic socket data.

SRT_ERESOURCE

System or standard library error reported unexpectedly for unknown purpose. Usually it means some internal error.

SRT_ETHREAD

System was unable to spawn a new thread when required.

SRT_ENOBUF

System was unable to allocate memory for buffers.

SRT_ESYSOBJ

System was unable to allocate system specific objects (such as sockets, mutexes or condition variables).

SRT_EFILE

General filesystem error (for functions operating with file transmission).

SRT_EINVRDOFF

Failure when trying to read from a given position in the file (file could be modified while it was read from).

SRT_ERDPERM

Read permission was denied when trying to read from file.

SRT_EINVWROFF

Failed to set position in the written file.

SRT_EWRPERM

Write permission was denied when trying to write to a file.

SRT_EINVOP

Invalid operation performed for the current state of a socket. This mainly concerns performing srt_bind* operations on a socket that is already bound. Once a socket has been been bound, it cannot be bound again.

SRT_EBOUNDSOCK

The socket is currently bound and the required operation cannot be performed in this state. Usually it's about an option that can only be set on the socket before binding (srt_bind*). Note that a socket that is currently connected is also considered bound.

SRT_ECONNSOCK

The socket is currently connected and therefore performing the required operation is not possible. Usually concerns setting an option that must be set before connecting (although it is allowed to be altered after binding), or when trying to start a connecting operation (srt_connect*) while the socket isn't in a state that allows it (only SRTS_INIT or SRTS_OPENED are allowed).

SRT_EINVPARAM

This error is reported in a variety of situations when call parameters for API functions have some requirements defined and these were not satisfied. This error should be reported after an initial check of the parameters of the call before even performing any operation. This error can be easily avoided if you set the values correctly.

SRT_EINVSOCK

The API function required an ID of an entity (socket or group) and it was invalid. Note that some API functions work only with socket or only with group, so they would also return this error if inappropriate type of entity was passed, even if it was valid.

SRT_EUNBOUNDSOCK

The operation to be performed on a socket requires that it first be explicitly bound (using srt_bind* functions). Currently it applies when calling srt_listen, which cannot work with an implicitly bound socket.

SRT_ENOLISTEN

The socket passed for the operation is required to be in the listen state (srt_listen must be called first).

SRT_ERDVNOSERV

The required operation cannot be performed when the socket is set to rendezvous mode (SRTO_RENDEZVOUS set to true). Usually applies when trying to call srt_listen on such a socket.

SRT_ERDVUNBOUND

An attempt was made to connect to a socket set to rendezvous mode (SRTO_RENDEZVOUS set to true) that was not first bound. A rendezvous connection requires setting up two addresses and ports on both sides of the connection, then setting the local one with srt_bind and using the remote one with srt_connect (or you can simply use srt_rendezvous). Calling srt_connect* on an unbound socket (in SRTS_INIT state) that is to be bound implicitly is only allowed for regular caller sockets (not rendezvous).

SRT_EINVALMSGAPI

The function was used incorrectly in the message API. This can happen if:

  • The parameters specific for the message API in SRT_MSGCTRL type parameter were incorrectly specified.

  • The extra parameter check performed by the congestion controller has failed.

  • The socket is a member of a self-managing group, therefore you should perform the operation on the group, not on this socket.

SRT_EINVALBUFFERAPI

The function was used incorrectly in the stream (buffer) API, that is, either the stream-only functions were used with set message API (srt_sendfile/srt_recvfile) or TSBPD mode was used with buffer API (SRTO_TSBPDMODE set to true) or the congestion controller has failed to check call parameters.

SRT_EDUPLISTEN

The port tried to be bound for listening is already busy. Note that binding to the same port is allowed in general (when SRTO_REUSEADDR is true on every socket that has bound it), but only one such socket can be a listener.

SRT_ELARGEMSG

Size exceeded. This is reported in the following situations:

  • Trying to receive a message, but the read-ready message is larger than the buffer passed to the receiving function.

  • Trying to send a message, but the size of this message exceeds the size of the preset sender buffer, so it cannot be stored in the sender buffer.

  • When getting group data, the array to be filled is too small.

SRT_EINVPOLLID

The epoll ID passed to an epoll function is invalid.

SRT_EPOLLEMPTY

The epoll container currently has no subscribed sockets. This is reported by an epoll waiting function that would in this case block forever. This problem might be reported both in a situation where you have created a new epoll container and didn't subscribe any sockets to it, or you did, but these sockets have been closed (including when closed in a separate thread while the waiting function was blocking). Note that this situation can be prevented by setting the SRT_EPOLL_ENABLE_EMPTY flag, which may be useful when you use multiple threads and start waiting without subscribed sockets, so that you can subscribe them later from another thread.

SRT_EBINDCONFLICT

The binding you are attempting to set up a socket with, using the srt_bind call, cannot be completed because it conflicts with another existing binding.

An attempt of binding a socket, in the conditions of having some other socket already bound to the same port number, can result in one of three possibilities:

  1. The binding is separate to the existing one (succeeds).
  2. The binding intersects with the exiting one (fails).
  3. The binding is exactly identical to the existing one (see below).

See the srt_bind for a reference about what kinds of binding addresses can coexist without conflicts.

A binding is considered intersecting if the existing binding has the same port and covers at least partially the range as that of the attempted binding. These ranges can be split in three groups:

  1. An explicitly specified IP address (both IPv4 and IPv6) covers this address only.
  2. An IPv4 wildcard 0.0.0.0 covers all IPv4 addresses (but not IPv6).
  3. An IPv6 wildcard :: covers:
    • if SRTO_IPV6ONLY is true - all IPv6 addresses (but not IPv4)
    • if SRTO_IPV6ONLY is false - all IP addresses.

Example 1:

  • Socket 1: bind to IPv4 0.0.0.0
  • Socket 2: bind to IPv6 :: with SRTO_IPV6ONLY = true
  • Result: NOT intersecting, allowed to proceed

Example 2:

  • Socket 1: bind to IPv4 1.2.3.4
  • Socket 2: bind to IPv4 0.0.0.0
  • Result: failure: 0.0.0.0 encloses 1.2.3.4, so they are in conflict

Example 3:

  • Socket 1: bind to IPv4 1.2.3.4
  • Socket 2: bind to IPv6 :: with SRTO_IPV6ONLY = false
  • Result: failure: this encloses all IPv4, so it conflicts with 1.2.3.4

Binding another socket to an endpoint that is already bound by another socket is possible, and results in a shared binding, as long as the binding address that is enclosed by this existing binding is exactly identical to the specified one and all of the following conditions must be satisfied between them:

  1. The SRTO_REUSEADDR must be true (default) in both the attempted and existing bindings.

  2. The IP address specification, also as a wildcard (in case of IPv6, also including the value of SRTO_IPV6ONLY flag), must be exactly identical.

  3. The UDP-specific settings (SRT options that map to UDP options) must be identical.

If any of these conditions isn't satisfied, the srt_bind function results in conflict and report this error.

SRT_EASYNCFAIL

General asynchronous failure (not in use currently).

SRT_EASYNCSND

Sending operation is not ready to perform. This error is reported when trying to perform a sending operation on a socket that is not ready for sending, but SRTO_SNDSYN was set to false (when true, the function would block the call otherwise).

SRT_EASYNCRCV

Receiving operation is not ready to perform. This error is reported when trying to perform a receiving operation or accept a new socket from the listener socket, when the socket is not ready for that operation, but SRTO_RCVSYN was set to false (when true, the function would block the call otherwise).

SRT_ETIMEOUT

The operation timed out. This can happen if you have a timeout set by an option (SRTO_RCVTIMEO or SRTO_SNDTIMEO), or passed as an extra argument (srt_epoll_wait or srt_accept_bond) and the function call was blocking, but the required timeout time has passed.

SRT_ECONGEST

NOTE: This error is used only in an experimental version that requires setting the SRT_ENABLE_ECN macro at compile time. Otherwise the situation described below results in the usual successful report.

This error should be reported by the sending function when, with SRTO_TSBPDMODE and SRTO_TLPKTDROP set to true, some packets were dropped at the sender side (see the description of SRTO_TLPKTDROP for details). This doesn't concern the data that were passed for sending by the sending function (these data are placed at the back of the sender buffer, while the dropped packets are at the front). In other words, the operation done by the sending function is successful, but the application might want to slow down the sending rate to avoid congestion.

SRT_EPEERERR

This error is reported when a receiver peer is writing to a file that an agent is sending. When the peer encounters an error when writing the received data to a file, it sends the UMSG_PEERERROR message back to the sender, and the sender reports this error from the API sending function.

Return to Top of Page