[BUG] Fixed the use of the right error constant

[ethouris]

Fixes #2505

This changes the use of the error constants SRT_ERROR and SRT_INVALID_SOCK. Besides, there are some others (maybe some better fix could be introduced sometimes, but note that some parts apply to the C API):

1. Introduced a new type, SRTSTATUS. This is obviously an alias for int, but the use of it suggests that there are only two possible values expected in return: SRT_ERROR or SRT_STATUS_OK (newly introduced in this PR - could be SRT_SUCCESS, but this symbol is already used for a 0 error code, so it's from a kinda different domain).
2. Introduced additionally SRTRUNSTATUS, which contains values for usual OK and ERROR, but also ALREADY, which means that no actual action was undertaken as it was started already. This is currently in use for srt_startup(), as it was hard to find any better solution (an integer value could be used, but this value is still symbolic, not anyhow numeric with trap), but made universal enough if any need for similar type of status appears.
3. Might be that the returned value has some "meaningful" value when it is non-negative, and other value is only -1, for which SRT_ERROR should be used. This is used explicitly now, although the return type is int, not SRTSTATUS.
4. Sometimes the returned value is a socket, but it still might return an error, with the same value -1. For this case the error value is used as SRT_INVALID_SOCK as per the SRTSOCKET return type. As this is also an alias to int (int32_t more preciesly), then there's nothing wrong with comparing it to SRT_ERROR, but the internal code is consequently using SRT_INVALID_SOCK wherever SRTSOCKET type is used.
5. Important: all functions that do "connect", including srt_connect, return SRTSOCKET even though the usual use of srt_connect is connecting a single socket and the returned value should be treated as a status. Therefore the pair of SRT_ERROR and SRT_STATUS_OK should be treated as equivalent to SRT_INVALID_SOCK and SRT_SOCKID_CONNREQ respectively. The latter is a value of the socket that is used only internally, it's not a valid value of a socket, but also not erroneous (as erroneous is only SRT_INVALID_SOCK).

Might be then that it deserves a description, which should mention something like this:

1. The SRTSTATUS type contains only two possible values: SRT_ERROR and SRT_STATUS_OK. When this is the return type in an API function, all values except these are illegal.
2. Usually - but not always - the returned int type is an extended version of SRTSTATUS with added positive meaningful values. In this case you are allowed to use SRT_ERROR and non-negative values in comparison, others are illegal.
3. The SRTSOCKET is also an extended version of SRTSTATUS, in which SRT_INVALID_SOCK and SRT_SOCKID_CONNREQ map to SRT_ERROR and SRT_STATUS_OK respectively. This way, SRT_SOCKID_CONNREQ should be treated as a possible return for a function, which in particular runtime circumstances is not expected to return a valid socket ID. This is the case of srt_connect, when it is called for a single socket.

TODO:

• Update the documentation, with regards to srt_accept and srt_connect and similar.

[codecov-commenter]

Codecov Report

Attention: 185 lines in your changes are missing coverage. Please review.

Comparison is base (ea8ea9f) 64.26% compared to head (be302ca) 64.40%.

Files	Patch %	Lines
srtcore/api.cpp	48.97%	124 Missing ⚠️
srtcore/srt_c_api.cpp	46.93%	26 Missing ⚠️
srtcore/core.cpp	41.37%	17 Missing ⚠️
srtcore/group.cpp	15.38%	11 Missing ⚠️
srtcore/epoll.cpp	42.85%	4 Missing ⚠️
srtcore/crypto.cpp	0.00%	1 Missing ⚠️
srtcore/group.h	0.00%	1 Missing ⚠️
test/test_file_transmission.cpp	75.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #2595      +/-   ##
==========================================
+ Coverage   64.26%   64.40%   +0.13%     
==========================================
  Files         101      101              
  Lines       17480    17512      +32     
==========================================
+ Hits        11233    11278      +45     
+ Misses       6247     6234      -13     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[maxsharabayko]

This is more for 1.6.0 due to changes to the API.

[maxsharabayko]

Copyright header is missing.

[ethouris]

RIght. Even though this file is normally unused.

[maxsharabayko]

What's the difference with utilities.h?

[ethouris]

This file contains things that are in any temporary use for development. This is only provided for convenience for the use during development, but the normal code goes with this file ousted, with provided just plain definitions for the specific types as alias to integer.

Directly this file is provided so that by a temporary change in srt.h you can run the compile command and then by the errors you get you can find out where the rules for the right usage of the status types has been violated.

[maxsharabayko]

C++ API (inline function) mixed with C API.

[ethouris]

I think it can be moved. I wanted to make it available for the users. We can just as well add this to the internals and later move it to the API.

[maxsharabayko]

I would prefer not to change the srt.h in the 1.5.4 patch release.