Skip to content

Commit

Permalink
[docs] remove trailing spaces
Browse files Browse the repository at this point in the history
Signed-off-by: Sirio Balmelli <[email protected]>
  • Loading branch information
siriobalmelli committed Oct 3, 2023
1 parent 0d90826 commit d72eb00
Show file tree
Hide file tree
Showing 19 changed files with 1,344 additions and 1,344 deletions.
1,004 changes: 502 additions & 502 deletions docs/API/API-functions.md

Large diffs are not rendered by default.

74 changes: 37 additions & 37 deletions docs/API/API-socket-options.md
Original file line number Diff line number Diff line change
Expand Up @@ -60,10 +60,10 @@ Exchange for the initial key is done in the handshake.
encrypted and will be decrypted by the receiver. This state is only possible on
both sides in both directions simultaneously.

- `SRT_KM_S_NOSECRET` (`3`): If this state is in the sending direction (`SRTO_SNDKMSTATE`),
then it means that the sending party has set a passphrase, but the peer did not.
In this case the sending party can receive unencrypted packets from the peer, but
packets it sends to the peer will be encrypted and the peer will not be able to
- `SRT_KM_S_NOSECRET` (`3`): If this state is in the sending direction (`SRTO_SNDKMSTATE`),
then it means that the sending party has set a passphrase, but the peer did not.
In this case the sending party can receive unencrypted packets from the peer, but
packets it sends to the peer will be encrypted and the peer will not be able to
decrypt them. This state is only possible in HSv5.

- `SRT_KM_S_BADSECRET` (`4`): The password is wrong (set differently on each party);
Expand Down Expand Up @@ -97,8 +97,8 @@ New version:
int srt_getsockflag(SRTSOCKET socket, SRT_SOCKOPT optName, void* optval, int& optlen);
int srt_setsockflag(SRTSOCKET socket, SRT_SOCKOPT optName, const void* optval, int optlen);

In the legacy version, there's an additional unused `level` parameter. It was
there in the original UDT API just to mimic the system `setsockopt` function,
In the legacy version, there's an additional unused `level` parameter. It was
there in the original UDT API just to mimic the system `setsockopt` function,
but it's ignored.

Some options require a value of type `bool` while others require type `integer`,
Expand All @@ -117,7 +117,7 @@ legacy/C++ API file. Note the translation rules:
* `UDP_` prefix from UDT options was changed to the prefix `SRTO_UDP_`
* `SRT_` prefix in older SRT versions was changed to `SRTO_`

The [table below](#list-of-options) provides a complete list of SRT options and
The [table below](#list-of-options) provides a complete list of SRT options and
their characteristics according to the following legend:

1. **Since**: Defines the SRT version when this option was first introduced. If this field
Expand All @@ -137,7 +137,7 @@ or `SRTS_CONNECTED` state. If an option was set on a listener socket, it will be
by a socket returned by `srt_accept()` (except for `SRTO_STREAMID`).

- `post`: The option is unrestricted and can be altered at any time, including when the
socket is connected, as well as on an accepted socket. The setting of this flag on a listening
socket is connected, as well as on an accepted socket. The setting of this flag on a listening
socket is usually derived by the accepted socket, but this isn't a rule for all options.
Note though that there are some unrestricted options that have an important meaning when
set prior to connecting (different one than for a connected socket).
Expand Down Expand Up @@ -179,7 +179,7 @@ restrictions on the value apply, as explained in the [description](#option-descr

8. **Entity**: This describes whether the option can be set on the socket or the group.
The G and S options may appear together, in which case both possibilities apply.
The D and I options, mutually exclusive, appear always with G.
The D and I options, mutually exclusive, appear always with G.
The + marker can only coexist with GS. Possible specifications are:

- S: This option can be set on a single socket (exclusively, if not GS)
Expand Down Expand Up @@ -348,7 +348,7 @@ Once a connection is established, reading `SRTO_CRYPTOMODE` shows the negotiated
AES-CTR (1) or AES-GCM (2).

When [Listener callback](./API-functions.md##srt_listen_callback) is used, the value of
`SRTO_CRYPTOMODE` read on the new SRT socket to be accepted is not yet the
`SRTO_CRYPTOMODE` read on the new SRT socket to be accepted is not yet the
negotiated one. It is the value to be negotiated, and is inherited from the listener SRT socket.
If a specific behavior for each individual connection request is desired based on
[the user ID or anything else](../features/access-control.md),
Expand Down Expand Up @@ -473,16 +473,16 @@ The default flow control window size is 25600 packets. It is approximately:
- 270 Mbits of payload in the default live streaming configuration with an SRT payload size of 1316 bytes;
- 300 Mbits of payload with an SRT payload size of 1456 bytes.

The minimum number of packets in flight should be (assuming max payload size):
`FCmin = bps / 8 × RTTsec / (MSS - 44)`,
The minimum number of packets in flight should be (assuming max payload size):
`FCmin = bps / 8 × RTTsec / (MSS - 44)`,
where
- `bps` - is the payload bitrate of the stream in bits per second;
- `RTTsec` - RTT of the network connection in seconds;
- `MSS` - Maximum segment size (aka MTU), see [SRTO_MSS](#SRTO_MSS);
- 44 - size of headers (20 bytes IPv4 + 8 bytes of UDP + 16 bytes of SRT packet header).

To avoid blocking the sending of further packets in case of packet loss, the recommended flow control window is
`FC = bps / 8 × (RTTsec + latency_sec) / (MSS - 44)`,
To avoid blocking the sending of further packets in case of packet loss, the recommended flow control window is
`FC = bps / 8 × (RTTsec + latency_sec) / (MSS - 44)`,
where `latency_sec` is the receiver buffering delay ([SRTO_RCVLATENCY](#SRTO_RCVLATENCY)) **in seconds**.

[Return to list](#list-of-options)
Expand Down Expand Up @@ -655,9 +655,9 @@ possibilities:
* IPv6 only: bind to an IPv6 wildcard address and set this option to 1
* IPv4 and IPv6: bind to an IPv6 wildcard address and set this option to 0

This option's default value is -1 because it is not possible to determine the default
value on the current platform, and if you bind to an IPv6 wildcard address, this value
is required prior to binding. When you bind implicitly by calling `srt_connect` on the
This option's default value is -1 because it is not possible to determine the default
value on the current platform, and if you bind to an IPv6 wildcard address, this value
is required prior to binding. When you bind implicitly by calling `srt_connect` on the
socket, this isn't a problem -- binding will be done using the system-default value and then
extracted afterwards. But if you want to bind explicitly using `srt_bind`, this
option must be set explicitly to 0 or 1 because this information is vital for
Expand Down Expand Up @@ -881,7 +881,7 @@ functions that operate directly on a file. The internal facility will take care
of any speed and congestion control. When receiving, you can also receive as
many data as desired. The data not extracted will be waiting for the next call.
There is no boundary between data portions in Stream mode.

- **Message API**: In this mode your single sending instruction passes exactly
one piece of data that has boundaries (a message). Contrary to Live mode,
this message may span multiple UDP packets, and the only size limitation
Expand All @@ -893,7 +893,7 @@ copied to the application's buffer. Messages that are sent later, but were
earlier reassembled by the receiver, will be delivered once ready, if the
`inorder` flag was set to false.
See [`srt_sendmsg`](API.md#sending-and-receiving).

As a comparison to the standard system protocols, the Stream API does
transmission similar to TCP, whereas the Message API functions like the
SCTP protocol.
Expand Down Expand Up @@ -1025,21 +1025,21 @@ negotiated config need not have parameters in the given order.

Cases when negotiation succeeds:

| Peer A | Peer B | Negotiated Config
| Peer A | Peer B | Negotiated Config
|----------------------|---------------------|------------------------------------------------------
| (no filter) | (no filter) |
| fec,cols:10 | fec | fec,cols:10,rows:1,arq:onreq,layout:even
| fec,cols:10 | fec,cols:10,rows:20 | fec,cols:10,rows:20,arq:onreq,layout:even
| fec,layout:staircase | fec,cols:10 | fec,cols:10,rows:1,arq:onreq,layout:staircase
| (no filter) | (no filter) |
| fec,cols:10 | fec | fec,cols:10,rows:1,arq:onreq,layout:even
| fec,cols:10 | fec,cols:10,rows:20 | fec,cols:10,rows:20,arq:onreq,layout:even
| fec,layout:staircase | fec,cols:10 | fec,cols:10,rows:1,arq:onreq,layout:staircase

In these cases the configuration is rejected with SRT_REJ_FILTER code:

| Peer A | Peer B | Error reason
|-----------------------|---------------------|--------------------------
| fec | (no filter) | missing `cols` parameter
| fec,rows:20,arq:never | fec,layout:even | missing `cols` parameter
| fec,cols:20 | fec,cols:10 | `cols` parameter value conflict
| fec,cols:20,rows:20 | fec,cols:20,rows:10 | `rows` parameter value conflict
| fec | (no filter) | missing `cols` parameter
| fec,rows:20,arq:never | fec,layout:even | missing `cols` parameter
| fec,cols:20 | fec,cols:10 | `cols` parameter value conflict
| fec,cols:20,rows:20 | fec,cols:20,rows:10 | `rows` parameter value conflict

In general it is recommended that one party defines the full configuration,
while the other keeps this value empty.
Expand Down Expand Up @@ -1133,7 +1133,7 @@ party remains at the default 0, it will accept the peer's value. The situation
where both parties set a value should be treated carefully. Actually there are
three intended methods of defining it, and all other uses are considered
undefined behavior:

- **Unidirectional**: the sender shall set `PBKEYLEN` and the receiver shall
not alter the default value 0. The effective `PBKEYLEN` will be the one set
on the sender. The receiver need not know the sender's `PBKEYLEN`, just the
Expand All @@ -1145,8 +1145,8 @@ undefined behavior:
(the service allows all clients to freely decide about encryption, or the
server uses more elaborate rules for encryption).

- **Bidirectional in Rendezvous mode**: In Rendezvous mode it is assumed that the settings (including `PBKEYLEN`) are known at both ends.
as it is with Listener mode, so both parties should set the same passphrase and the same key length,
- **Bidirectional in Rendezvous mode**: In Rendezvous mode it is assumed that the settings (including `PBKEYLEN`) are known at both ends.
as it is with Listener mode, so both parties should set the same passphrase and the same key length,
or both should leave the `SRTO_PBKEYLEN` option unchanged (which results in default 16).

- **Unwanted behavior cases**: if both parties set `PBKEYLEN` and the value
Expand Down Expand Up @@ -1588,19 +1588,19 @@ Returns the current socket state, same as `srt_getsockstate`.
| -------------------- | ----- | -------- | ---------- | ------- | --------- | ------ | --- | ------ |
| `SRTO_STREAMID` | 1.3.0 | pre | `string` | | "" | [512] | RW | GSD |

- A string that can be set on the socket prior to connecting. The listener side
will be able to retrieve this stream ID from the socket that is returned from
`srt_accept` (for a connected socket with that stream ID). You usually use SET
on the socket used for `srt_connect`, and GET on the socket retrieved from
`srt_accept`. This string can be used completely free-form. However, it's highly
- A string that can be set on the socket prior to connecting. The listener side
will be able to retrieve this stream ID from the socket that is returned from
`srt_accept` (for a connected socket with that stream ID). You usually use SET
on the socket used for `srt_connect`, and GET on the socket retrieved from
`srt_accept`. This string can be used completely free-form. However, it's highly
recommended to follow the [SRT Access Control (Stream ID) Guidlines](../features/access-control.md).

- As this uses internally the `std::string` type, there are additional functions
for it in the legacy/C++ API (udt.h): `srt::setstreamid` and `srt::getstreamid`.

- This option is not useful for a Rendezvous connection, since one side would
override the value from the other side resulting in an arbitrary winner. Also
in this connection both peers are known to one another and both have equivalent
in this connection both peers are known to one another and both have equivalent
roles in the connection.

- **IMPORTANT**: This option is not derived by the accepted socket from the listener
Expand Down
6 changes: 3 additions & 3 deletions docs/API/API.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ 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
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.

Expand Down Expand Up @@ -205,8 +205,8 @@ 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
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
Expand Down
8 changes: 4 additions & 4 deletions docs/API/configuration-guidelines.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ The default flow control window size is 25600 packets. It is approximately:
- **270 Mbits** of payload in the default live streaming configuration with an SRT payload size of **1316 bytes**;
- **300 Mbits** of payload in the default file transfer configuration with an SRT payload size of **1456 bytes**.

The default receiver buffer size is 8192 packets. It is approximately:
The default receiver buffer size is 8192 packets. It is approximately:
- **86 Mbits** of payload with the effective SRT payload size of **1316 bytes**.

### Setting Receiver Buffer Size
Expand Down Expand Up @@ -63,7 +63,7 @@ where
- `bytePayloadSize` is the expected size of the payload of the SRT data packet.
If the whole remainder of the MTU is expected to be used, payload size is calculated as follows:
If the whole remainder of the MTU is expected to be used, payload size is calculated as follows:
`bytePayloadSize = MSS - UDP_IPv4_HDR - SRT_HDR`
Expand All @@ -79,9 +79,9 @@ To determine the value to pass in `srt_setsockopt(..)` with `SRTO_RCVBUF`
the size in packets `pktsRBufSize` must be converted to the size in bytes
assuming the internal conversion of the `srt_setsockopt(..)` function.
The target size of the payload stored by the receiver buffer would be:
The target size of the payload stored by the receiver buffer would be:
`SRTO_RCVBUF = pktsRBufSize × (SRTO_MSS - UDPHDR_SIZE)`
`SRTO_RCVBUF = pktsRBufSize × (SRTO_MSS - UDPHDR_SIZE)`
where
Expand Down
Loading

0 comments on commit d72eb00

Please sign in to comment.