# SRT API
The SRT C API (defined in `srt.h` file) is largely based in design on the legacy
UDT API, with some important changes. The `udt.h` file contains the legacy UDT API
plus some minor optional functions that require the C++ standard library to be used.
There are a few optional C++ API functions stored there, as there is no real C++ API
for SRT. These functions may be useful in certain situations.
There are some example applications so that you can see how the API is being used,
including `srt-live-transmit` and `srt-file-transmit`. All SRT related material is contained
in `transmitmedia.*` files in the `apps` directory
which is used by all applications. See `SrtSource::Read` and `SrtTarget::Write`
as examples of how data are read and written in SRT.
- [Setup and teardown](#setup-and-teardown)
- [Creating and destroying a socket](#creating-and-destroying-a-socket)
- [Synopsis](#synopsis)
- [Usage](#usage)
- [Important Remarks](#important-remarks)
- [Binding and connecting](#binding-and-connecting)
- [Synopsis](#synopsis)
- [SRT Usage - listener (server)](#srt-usage---listener-server)
- [SRT Usage - rendezvous](#srt-usage---rendezvous)
- [Sending and Receiving](#sending-and-receiving)
- [Synopsis](#synopsis)
- [Usage](#usage)
- [Transmission types available in SRT](#transmission-types-available-in-srt)
- [Blocking and Non-blocking Mode](#blocking-and-non-blocking-mode)
- [EPoll (Non-blocking Mode Events)](#epoll-non-blocking-mode-events))
- [Synopsis](#synopsis)
- [SRT Usage](#srt-usage)
- [Transmission types](#transmission-types)
- [Terminology](#terminology)
- [Transmission method: Live](#transmission-method-live)
- [Transmission method: Buffer](#transmission-method-buffer)
- [Transmission method: Message](#transmission-method-message)
**NOTE**: The socket option descriptions originally contained in this document
have been moved to [APISocketOptions.md](https://github.com/Haivision/srt/blob/master/docs/APISocketOptions.md)
Setup and teardown
==================
Before any part of the SRT C API can be used, the user should call the `srt_startup()`
function. Likewise, before the application exits, the `srt_cleanup()` function
should be called. Note that one of the things the startup function does is to create
a new thread, so choose the point of execution for these functions carefully.
Creating and destroying a socket
================================
To do anything with SRT, you first have to create an SRT socket. The term "socket"
in this case is used because of its logical similarity to system-wide sockets.
An SRT socket is not directly related to system sockets, but like a system socket
it is used to define a point of communication.
Synopsis
--------
SRTSOCKET srt_socket(int af, int, int);
int srt_close(SRTSOCKET s);
The `srt_socket` function is based on the legacy UDT API except
the first parameter. The other two are ignored.
Note that `SRTSOCKET` is just an alias for `int`; this is a legacy naming convention
from UDT, which is here only for clarity.
Usage
-----
sock = srt_socket(AF_INET, SOCK_DGRAM, 0);
This creates a socket, which can next be configured and then used for communication.
srt_close(sock);
This closes the socket and frees all its resources. Note that the true life of the
socket does not end exactly after this function exits - some details are being
finished in a separate "SRT GC" thread. Still, at least all shared system resources
(such as listener port) should be released after this function exits.
Important Remarks
-----------------
1. Please note that the use of SRT with `AF_INET6` has not been fully tested;
use at your own risk.
2. SRT uses the system UDP protocol as an underlying communication layer, and so
it uses also UDP sockets. The underlying communication layer is used only
instrumentally, and SRT manages UDP sockets as its own system resource as it
pleases - so in some cases it may be reasonable for multiple SRT sockets to share
one UDP socket, or for one SRT socket to use multiple UDP sockets.
3. The term "port" used in SRT is occasionally identical to the term "UDP
port". However SRT offers more flexibility than UDP (or TCP, the more logical
similarity) because it manages ports as its own resources. For example, one port
may be shared between various services.
Binding and connecting
======================
Connections are established using the same philosophy as TCP, using functions
with names and signatures similar to the BSD Socket API. What is new here is
the _rendezvous_ mode.
Synopsis
--------
int srt_bind(SRTSOCKET u, const struct sockaddr* name, int namelen);
int srt_bind_peerof(SRTSOCKET u, UDPSOCKET udpsock);
This function sets up the "sockname" for the socket, that is, the local IP address
of the network device (use `INADDR_ANY` for using any device) and port. Note that
this can be done on both listening and connecting sockets; for the latter it will
define the outgoing port. If you don't set up the outgoing port by calling this
function (or use port number 0), a unique port number will be selected automatically.
The `*_peerof` version simply copies the bound address setting from an existing
UDP socket.
int srt_listen(SRTSOCKET u, int backlog);
This sets the backlog (maximum allowed simultaneously pending connections) and
puts the socket into a listening state -- that is, incoming connections will be
accepted in the call `srt_accept`.
SRTSOCKET srt_accept(SRTSOCKET u, struct sockaddr* addr, int* addrlen);
This function accepts the incoming connection (the peer should do
`srt_connect`) and returns a socket that is exclusively bound to an opposite
socket at the peer. The peer's address is returned in the `addr`
argument.
int srt_connect(SRTSOCKET u, const struct sockaddr* name, int namelen);
int srt_connect_debug(SRTSOCKET u, const struct sockaddr* name, int namelen, int forced_isn);
This function initiates the connection of a given socket with its peer's counterpart
(the peer gets the new socket for this connection from `srt_accept`). The
address for connection is passed in 'name'. The `connect_debug` version allows
for enforcing the ISN (initial sequence number); this is used only for
debugging or unusual experiments.
int srt_rendezvous(SRTSOCKET u, const struct sockaddr* local_name, int local_namelen,
const struct sockaddr* remote_name, int remote_namelen);
A convenience function that combines the calls to bind, setting the `SRTO_RENDEZVOUS` flag,
and connecting to the rendezvous counterpart. For simplest usage, the `local_name` should
be set to `INADDR_ANY` (or a specified adapter's IP) and port. Note that both `local_name`
and `remote_name` must use the same port. The peer to which this is going to connect
should call the same function, with appropriate local and remote addresses. A rendezvous
connection means that both parties connect to one another simultaneously.
SRT Usage - listener (server)
-----------------------------
sockaddr_in sa = { ... }; // set local listening port and possibly interface's IP
int st = srt_bind(sock, (sockaddr*)&sa, sizeof sa);
srt_listen(sock, 5);
while ( !finish ) {
int sa_len = sizeof sa;
newsocket = srt_accept(sock, (sockaddr*)&sa, &sa_len);
HandleNewClient(newsocket, sa);
}
SRT Usage - caller (client)
---------------------------
sockaddr_in sa = { ... }; // set target IP and port
int st = srt_connect(sock, (sockaddr*)&sa, sizeof sa);
HandleConnection(sock);
SRT Usage - rendezvous
----------------------
sockaddr_in lsa = { ... }; // set local listening IP/port
sockaddr_in rsa = { ... }; // set remote IP/port
srt_setsockopt(m_sock, 0, SRTO_RENDEZVOUS, &yes, sizeof yes);
int stb = srt_bind(sock, (sockaddr*)&lsa, sizeof lsa);
int stc = srt_connect(sock, (sockaddr*)&rsa, sizeof rsa);
HandleConnection(sock);
or simpler
sockaddr_in lsa = { ... }; // set local listening IP/port
sockaddr_in rsa = { ... }; // set remote IP/port
int stc = srt_rendezvous(sock, (sockaddr*)&lsa, sizeof lsa,
(sockaddr*)&rsa, sizeof rsa);
HandleConnection(sock);
Sending and Receiving
=====================
The SRT API for sending and receiving is split into three categories: *simple*,
*rich*, and *for files only*.
The **simple API** includes: `srt_send` and `srt_recv` functions. They need only
the socket and the buffer to send from or receive to, just like system `read`
and `write` functions.
The **rich API** includes the `srt_sendmsg` and `srt_recvmsg` functions. Actually
`srt_recvmsg` is provided for convenience and backward compatibility, as it is
identical to `srt_recv`. The `srt_sendmsg` receives more parameters, specifically
for messages. The `srt_sendmsg2` and `srt_recvmsg2` functions receive the socket,
buffer, and the `SRT_MSGCTRL` object, which is an input-output object specifying
extra data for the operation.
Functions with the `msg2` suffix use the `SRT_MSGCTRL` object, and have the
following interpretation (except `flags` and `boundary` which are reserved for
future use and should be 0):
* `srt_sendmsg2`:
* `msgttl`: [IN] maximum time (in ms) to wait for successful delivery (-1: indefinitely)
* `inorder`: [IN] if false, the later sent message is allowed to be delivered earlier
* `srctime`: [IN] timestamp to be used for sending (0 if current time)
* `pktseq`: unused
* `msgno`: [OUT] message number assigned to the currently sent message
* `srt_recvmsg2`
* `msgttl`: unused
* `inorder`: unused
* `srctime`: [OUT] timestamp set for this dataset when sending
* `pktseq`: [OUT] packet sequence number (first packet from the message, if it spans multiple UDP packets)
* `msgno`: [OUT] message number assigned to the currently received message
Please note that the `msgttl` and `inorder` arguments and fields in `SRT_MSGCTRL`
are meaningful only when you use the message API in file mode (this will be explained
later). In live mode, which is the SRT default, packets are always delivered when
the time comes (always in order), where you don't want a packet to be dropped
before sending (so -1 should be passed here).
The `srctime` parameter is an SRT addition for applications (i.e. gateways)
forwarding SRT streams. It permits pulling and pushing of the sender's original
time stamp, converted to local time and drift adjusted. The `srctime` parameter
is the number of usec (since epoch) in local SRT clock time. If the connection
is not between SRT peers or if **Timestamp-Based Packet Delivery mode (TSBPDMODE)**
is not enabled (see [APISocketOptions.md](https://github.com/Haivision/srt/blob/master/docs/APISocketOptions.md)),
the extracted `srctime` will be 0. Passing `srctime = 0` in `sendmsg` is like using
the API without `srctime` and the local send time will be used (if TSBPDMODE is
enabled and receiver supports it).
Synopsis
--------
int srt_send(SRTSOCKET s, const char* buf, int len);
int srt_sendmsg(SRTSOCKET s, const char* buf, int len, int msgttl, bool inorder, uint64_t srctime);
int srt_sendmsg2(SRTSOCKET s, const char* buf, int len, SRT_MSGCTRL* msgctrl);
int srt_recv(SRTSOCKET s, char* buf, int len);
int srt_recvmsg(SRTSOCKET s, char* buf, int len);
int srt_recvmsg2(SRTSOCKET s, char* buf, int len, SRT_MSGCTRL* msgctrl);
Usage
-----
Sending a payload:
nb = srt_sendmsg(u, buf, nb, -1, true);
nb = srt_send(u, buf, nb);
SRT_MSGCTRL mc = srt_msgctrl_default;
nb = srt_sendmsg2(u, buf, nb, &mc);
Receiving a payload:
nb = srt_recvmsg(u, buf, nb);
nb = srt_recv(u, buf, nb);
SRT_MSGCTRL mc = srt_msgctrl_default;
nb = srt_recvmsg2(u, buf, nb, &mc);
Transmission types available in SRT
-----------------------------------
Mode settings determine how the sender and receiver functions work. The main
[socket options](APISocketOptions.md)
that control it are:
* `SRTO_TRANSTYPE`. Sets several parameters in accordance with the selected
mode:
* `SRTT_LIVE` (default) the Live mode (for live stream transmissions)
* `SRTT_FILE` the File mode (for "no time controlled" fastest data transmission)
* `SRTO_MESSAGEAPI`
* true: (default in Live mode): use Message API
* false: (default in File mode): use Buffer API
See [Transmission types](#transmission-types) below.
Blocking and Non-blocking Mode
==============================
SRT functions can also work in blocking and non-blocking mode, for which
there are two separate options for sending and receiving: `SRTO_SNDSYN` and
`SRTO_RCVSYN`. When blocking mode is used, a function will not exit until
the availability condition is satisfied. In non-blocking mode the function
always exits immediately, and in case of lack of resource availability, it
returns an error with an appropriate code. The use of non-blocking mode usually
requires using some polling mechanism, which in SRT is **EPoll**.
Note also that the blocking and non-blocking modes apply not only for sending
and receiving. For example, `SNDSYN` defines blocking for `srt_connect` and
`RCVSYN` defines blocking for `srt_accept`. The `SNDSYN` also makes `srt_close`
exit only after the sending buffer is completely empty.
EPoll (Non-blocking Mode Events)
================================
EPoll is a mechanism to track the events happening on the sockets, both "system
sockets" (see `SYSSOCKET` type) and SRT Sockets. Note that `SYSSOCKET` is also
an alias for `int`, used only for clarity.
Synopsis
--------
int srt_epoll_update_usock(int eid, SRTSOCKET u, const int* events = NULL);
int srt_epoll_update_ssock(int eid, SYSSOCKET s, const int* events = NULL);
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);
int srt_epoll_uwait(int eid, SRT_EPOLL_EVENT* fdsSet, int fdsSize, int64_t msTimeOut);
int srt_epoll_clear_usocks(int eid);
SRT Usage
---------
SRT socket being a user level concept, the system epoll (or other select)
cannot be used to handle SRT non-blocking mode events. Instead, SRT provides a
user-level epoll that supports both SRT and system sockets.
The `srt_epoll_update_{u|s}sock()` API functions described here are SRT additions
to the UDT-derived `srt_epoll_add_{u|s}sock()` and `epoll_remove_{u|s}sock()`
functions to atomically change the events of interest. For example, to remove
`SRT_EPOLL_OUT` but keep `SRT_EPOLL_IN` for a given socket with the existing
API, the socket must be removed from epoll and re-added. This cannot be done
atomically, the thread protection (against the epoll thread) being applied
within each function but unprotected between the two calls. It is then possible
to lose an `SRT_EPOLL_IN` event if it fires while the socket is not in the
epoll list.
Event flags are of various categories: `IN`, `OUT` and `ERR` are events,
which are level-triggered by default and become edge-triggered if combined
with `SRT_EPOLL_ET` flag. The latter is only an edge-triggered flag, not
an event. There's also an `SRT_EPOLL_UPDATE` flag, which is an edge-triggered
only event, and it reports an event on the listener socket that handles socket
group new connections for an already connected group - this is for internal use
only, and it's used in the internal code for socket groups.
Once the subscriptions are made, you can call an SRT polling function
(`srt_epoll_wait` or `srt_epoll_uwait`) that will block until an event
is raised on any of the subscribed sockets. This function will exit as
soon as at least one event is detected or a timeout occurs. The timeout is
specified in `[ms]`, with two special values:
- 0: check and report immediately (don't wait)
- -1: wait indefinitely (not interruptible, even by a system signal)
There are some differences in the synopsis between these two:
1. `srt_epoll_wait`: Both system and SRT sockets can be subscribed. This
function reports events on both socket types according to subscriptions, in
these arrays:
- `readfds` and `lrfds`: subscribed for `IN` and `ERR`
- `writefds` and `lwfds`: subscribed for `OUT` and `ERR`
where:
- `readfds` and `writefds` report SRT sockets ("user" socket)
- `lrfds` and `lwfds` report system sockets
**NOTE**: this function provides no straightforward possibility to report
sockets with an error. If you want to distinguish a report of readiness
for operation from an error report, the only way is to subscribe the
socket in only one direction (either `SRT_EPOLL_IN` or `SRT_EPOLL_OUT`,
but not both) and `SRT_EPOLL_ERR`, and then check the socket's presence
in the array in the direction for which the socket wasn't subscribed. For
example, when an SRT socket is subscribed for `SRT_EPOLL_OUT | SRT_EPOLL_ERR`,
its presence in `readfds` means that an error is reported for it.
This need not be a big problem, because when an error is reported on
a socket, making it appear as if it were ready for an operation, then when that
operation occurs it will simply result in an error. You can use this as an
alternative error check method.
This function also reports an error of type `SRT_ETIMEOUT` when no socket is
ready as the timeout elapses (including 0). This behavior is different in
`srt_epoll_uwait`.
Note that in this function there's a loop that checks for socket readiness
every 10ms. Thus, the minimum poll timeout the function can reliably support,
when system sockets are involved, is also 10ms. The return time from a poll
function can only be quicker when there is an event raised on one of the active
SRT sockets.
2. `srt_epoll_uwait`: In this function only the SRT sockets can be subscribed
(it reports error if you pass an epoll id that is subscribed to system sockets).
This function waits for the first event on subscribed SRT sockets and reports all
events collected at that moment in an array with the following structure:
```
typedef struct SRT_EPOLL_EVENT_
{
SRTSOCKET fd;
int events;
} SRT_EPOLL_EVENT;
```
Every item reports a single socket with all events as flags.
When the timeout is not -1, and no sockets are ready until the timeout time
passes, this function returns 0. This behavior is different in `srt_epoll_wait`.
The extra `srt_epoll_clear_usocks` function removes all subscriptions from
the epoll container.
The SRT EPoll system does not supports all features of Linux epoll. For
example, it only supports level-triggered events for system sockets.
Transmission types
------------------
SRT was originally intended to be used for Live Streaming and therefore its main
and default transmission type is "live". However, SRT supports the modes that
the original UDT library supported, that is, *file* and *message* transmission.
There are two general modes: **Live** and **File** transmission. Inside File
transmission mode, there are also two possibilities: **Buffer API** and
**Message API**. The Live mode uses Message API. However it doesn't exactly match
the description of the Message API because it uses a maximum single sending buffer
up to the size that fits in one UDP packet.
There are two options to set a particular type:
* `SRTO_TRANSTYPE`: uses the enum value with `SRTT_LIVE` for live mode
and `SRTT_FILE` for file mode. This option actually changes several parameters
to their default values for that mode. After this is done, additional parameters,
including those that are set here, can be further changed.
* `SRTO_MESSAGEAPI`: This sets the Message API (true) or Buffer API (false)
This makes possible a total of three data transmission methods:
* [Live](#transmission-method-live)
* [Buffer](#transmission-method-buffer)
* [Message](#transmission-method-message)
### Terminology
The following terms are used in the description of transmission types:
**HANGUP / RESUME**: These terms have different meanings depending on the blocking
state. They describe how a particular function behaves when performing an operation
requires a specific readiness condition to be satisfied.
In blocking mode HANGUP means that the function blocks until a condition is
satisfied. RESUME means that the condition is satisfied and the function performs
the required operation.
In non-blocking mode the only difference is that HANGUP, instead of blocking, makes
the function exit immediately with an appropriate error code (such as SRT_EASYNC*,
SRT_ETIMEOUT or SRT_ECONGEST) explaining why the function is not ready to perform
the operation. Refer to the error descriptions in [API-funtions.md](API-funtions.md)
for details.
The following types of operations are involved:
1. Reading data: `srt_recv`, `srt_recvmsg`, `srt_recvmsg2`, `srt_recvfile`.
The function HANGS UP if there are no available data to read, and RESUMES when
readable data become available (`SRT_EPOLL_IN` flag set in epoll). Use `SRTO_RCVSYN`
to control blocking mode here.
2. Writing data: `srt_send`, `srt_sendmsg`, `srt_sendmsg2`, `srt_sendfile`.
The function HANGS UP if the sender buffer becomes full and unable to store
any additional data, and RESUMES if the data scheduled for sending have been
removed from the sender buffer (after being sent and acknowledged) and there
is enough free space in the sender buffer to store data (`SRT_EPOLL_OUT` flag
set in epoll). Use `SRTO_SNDSYN` to control blocking mode here.
3. Accepting an incoming connection: `srt_accept`
The function HANGS UP if there are no new connections reporting in, and
RESUMES when a new connection has been processed and a new socket or group
has been created to handle it. Note that this function requires the listener
socket to get the connection (the flag `SRTO_RCVSYN` set on
the listener socket controls the blocking mode for this operation). Note also
that the blocking mode for a similar `srt_accept_bond` function is controlled
exclusively by its timeout parameter because it can work with multiple listener
sockets, potentially with different settings.
4. Connecting: `srt_connect` and its derivatives
The function HANGS UP in the beginning, and RESUMES when the socket used for
connecting is either ready to perform transmission operations or has failed to
connect. It behaves a little differently in non-blocking mode -- the function
should be called only once, and it simply returns a success result as a "HANGUP".
Calling it again with the same socket would be an error. Calling it with a group
would start a completely new connection. It is only possible to determine whether
an operation has finished ("has RESUMED") from epoll flags. The socket, when
successfully connected, would have `SRT_EPOLL_OUT` set, that is, becomes ready
to send data, and `SRT_EPOLL_ERR` when it failed to connect.
**BLIND / FAST / LATE REXMIT**: BLIND REXMIT is a situation where packets that
were sent are still not acknowledged, either in the expected time frame, or when
another ACK has come for the same number, but no packets have been reported as
lost, or at least not for all still unacknowledged packets. The congestion control
class is responsible for the algorithm for taking care of this situation, which is
either `FASTREXMIT` or `LATEREXMIT`. This will be explained below.
Transmission method: Live
-------------------------
Setting `SRTO_TRANSTYPE` to `SRTT_LIVE` sets the following [parameters](APISocketOptions.md):
* `SRTO_TSBPDMODE` = true
* `SRTO_RCVLATENCY` = 120
* `SRTO_PEERLATENCY` = 0
* `SRTO_TLPKTDROP` = true
* `SRTO_MESSAGEAPI` = true
* `SRTO_NAKREPORT` = true
* `SRTO_PAYLOADSIZE` = 1316
* `SRTO_CONGESTION` = "live"
In this mode, every call to a sending function is allowed to send only
so much data, as declared by `SRTO_PAYLOADSIZE`, whose value is still
limited to a maximum of 1456 bytes. The application that does the sending
is by itself responsible for calling the sending function in appropriate
time intervals between subsequent calls. By default, this implies that
the receiver uses 120 ms of latency, which is the declared time interval
between the moment when the packet is scheduled for sending at the
sender side, and when it is received by the receiver application (that
is, the data are kept in the buffer and declared as not received, until
the time comes for the packet to "play").
This mode uses the `LiveCC` congestion control class, which puts only a slight
limitation on the bandwidth, if needed (i.e. by adding extra time if the interval
between two consecutive packets would otherwise be too short for the defined speed
limit). Note that it is not intended to work with "virtually infinite" ingest
speeds (such as, for example, reading directly from a file). Therefore the
application is not allowed to stream data with maximum speed -- it must take care
that the speed of data being sent is in rhythm with timestamps in the live stream.
Otherwise the behavior is undefined and might be surprisingly disappointing.
The reading function will always return only a payload that was
sent, and it will HANGUP until the time to play has come for this
packet (if TSBPD mode is on) or when it is available without gaps of
lost packets (if TSBPD mode is off - see [`SRTO_TSBPDMODE`](APISocketOptions.md#SRTO_TSBPDMODE)).
You may wish to tweak some of the parameters below:
* `SRTO_TSBPDMODE`: You can turn off controlled latency if your application uses
its own method of latency control.
* `SRTO_RCVLATENCY`: You can increase the latency time, if this is
too short. Setting a shorter latency than the default is strongly
discouraged, although in some very specific and dedicated networks
this may still be reasonable. Note that `SRTO_PEERLATENCY` is an option
for the sending party, which is the minimum possible value for a receiver.
* `SRTO_TLPKTDROP`: When true (default), this will drop the packets
that haven't been retransmitted on time, that is, before the next packet
that is already received becomes ready to play. You can turn this off to always
ensure a clean delivery. However, a lost packet can simply pause a
delivery for some longer, potentially undefined time, and cause even
worse tearing for the player. Setting higher latency will help much more in
the case when TLPKTDROP causes packet drops too often.
* `SRTO_NAKREPORT`: Turns on repeated sending of loss reports, when the lost
packet was not recovered quickly enough, which raises suspicions that the
loss report itself was lost. Without it, the loss report will be always reported
just once and never repeated again, and then the lost payload packet will
be probably dropped by the TLPKTDROP mechanism.
* `SRTO_PAYLOADSIZE`: Default value is for MPEG TS. If you are going
to use SRT to send any different kind of payload, such as, for example,
wrapping a live stream in very small frames, then you can use a bigger
maximum frame size, though not greater than 1456 bytes.
Parameters from the modified for transmission type list, not mentioned in the
list above, are crucial for Live mode and shall not be changed.
The BLIND REXMIT situation is resolved using the FASTREXMIT algorithm by LiveCC:
sending non-acknowledged packets blindly on the premise that the receiver lingers
too long before acknowledging them. This mechanism isn't used (i.e. the BLIND REXMIT
situation isn't handled at all) when `SRTO_NAKREPORT` is set by the peer -- the
NAKREPORT method is considered so effective that FASTREXMIT isn't necessary.
Transmission method: Buffer
---------------------------
Setting `SRTO_TRANSTYPE` to `SRTT_FILE` sets the following [parameters](APISocketOptions.md):
* `SRTO_TSBPDMODE` = false
* `SRTO_RCVLATENCY` = 0
* `SRTO_PEERLATENCY` = 0
* `SRTO_TLPKTDROP` = false
* `SRTO_MESSAGEAPI` = false
* `SRTO_NAKREPORT` = false
* `SRTO_PAYLOADSIZE` = 0
* `SRTO_CONGESTION` = "file"
In this mode, calling a sending function is allowed to potentially send
virtually any size of data. The sending function will HANGUP only if the
sending buffer is completely filled, and RESUME if the sending buffers are
available for at least one smallest portion of data passed for sending. The
sending function need not send everything in this call, and the caller must
be aware that the sending function might return sent data of smaller size
than was actually requested.
From the receiving function there will be retrieved as many data as the minimum
of the passed buffer size and available data; data still available and not
retrieved by this call will be available for retrieval in the next call.
There is also a dedicated pair of functions that can only be used in this mode:
`srt_sendfile` and `srt_recvfile`. These functions can be used to transmit the
whole file, or a fragment of it, based on the offset and size.
This mode uses the `FileCC` congestion control class, which is a direct copy of
UDT's `CUDTCC` congestion control class, adjusted to the needs of SRT's
congestion control framework. This class generally sends the data with maximum
speed in the beginning, until the flight window is full, and then keeps the
speed at the edge of the flight window, only slowing down in the case where
packet loss was detected. The bandwidth usage can be directly limited by the
`SRTO_MAXBW` option.
The BLIND REXMIT situation is resolved in FileCC using the LATEREXMIT
algorithm: when the repeated ACK was received for the same packet, or when the
loss list is empty and the flight window is full, all packets since the last
ACK are sent again (that's more or less the TCP behavior, but in contrast to
TCP, this is done as a very low probability fallback).
Most of the parameters described above have `false` or `0` values as they usually
designate features used in Live mode. None are used with File mode. The only option
that makes sense to modify after the `SRTT_FILE` type was set is `SRTO_MESSAGEAPI`,
which is described below.
Transmission method: Message
----------------------------
Setting `SRTO_TRANSTYPE` to `SRTT_FILE` and then setting `SRTO_MESSAGEAPI` to
`true` implies usage of the Message transmission method. Parameters are set as
described above for the Buffer method, with the exception of `SRTO_MESSAGEAPI`.
The "file" congestion controller is also used in this mode. It differs from the
Buffer method, however, in terms of the rules concerning sending and receiving.
**HISTORICAL INFO**: The library on which SRT was based (UDT) somewhat misleadingly
used the terms `STREAM` and `DGRAM`, and used the system symbols `SOCK_STREAM` and
`SOCK_DGRAM` in the socket creation function. A "datagram" in the UDT terminology
has nothing to do with the "datagram" term in networking terminology, where its
size is limited to as much it can fit in one MTU. In UDT it is actually a message,
which may span multiple UDP packets and has clearly defined boundaries. It's rather
similar to the **SCTP** protocol. Also, in UDP the API functions were strictly bound
to `DGRAM` or `STREAM` mode: `UDT::send/UDT::recv` were only for `STREAM` and
`UDT::sendmsg/UDT::recvmsg` only for `DGRAM`. In SRT this is changed: all functions
can be used in all modes, except `srt_sendfile/srt_recvfile`, and how the functions
actually work is controlled by the `SRTO_MESSAGEAPI` flag.
In message mode, every sending function sends **exactly** as much data as it is
passed in a single sending function call. The receiver also receives not less than
**exactly** the number of bytes that was sent (although every message may have a
different size). Every message may also have extra parameters:
- **TTL** defines how much time (in ms) the message should wait in the sending
buffer for the opportunity to be picked up by the sender thread and sent over
the network; otherwise it is dropped. Note that this TTL only applies to packets that
have been lost and should be retransmitted.
- **INORDER**, when true, means the messages must be read by the receiver in
exactly the same order in which they were sent. In the situation where a message
suffers a packet loss, this prevents any subsequent messages from achieving
completion status prior to recovery of the preceding message.
The sending function will HANGUP when the free space in the sending buffer does
not exactly fit the whole message, and it will only RESUME if the free space in
the sending buffer grows up to this size. The call to the sending function also
returns with an error when the size of the message exceeds the total size of the
buffer (this can be modified by the `SRTO_SNDBUF` option). In other words, it is
not designed to send just a part of the message -- either the whole message is
sent, or nothing at all.
The receiving function will HANGUP until the whole message is available for reading;
if the message spans multiple UDP packets, then the function RESUMES only when
every single packet from the message has been received, including recovered packets,
if any. When the INORDER flag is set to false and parts of multiple messages are
currently available, the first message that is complete (possibly recovered) is
returned. Otherwise the function does a HANGUP until the next message is complete.
The call to the receiving function is rejected if the buffer size is too small
for a single message to fit in it.
Note that you can use any of the sending and receiving functions for sending and
receiving messages, except `sendfile/recvfile`, which are dedicated exclusively
for Buffer API.
For more information, see [APISocketOptions.md](APISocketOptions.md)
[Return to top](#srt-api)