Added connection callback, called when the async connection succeeded or failed

[ethouris]

Fixes #1464

This adds the connection callback, which is called in case when the connection that is to be completed in the background is finished, that is, succeeded or failed.

The statement as to whether this could be called in synchronous mode should be left undefined. The only cases when it is intended to be used is:

1. When you use non-blocking mode for a single socket (SRTO_RCVSYN=false) - as an alternative for epoll.
2. When you use group connections, in which case single socket connections are done always in the background. In this case it's the only way how you can get error information for every single socket and associate it with the link in your application's link table.

By registerring a callback by srt_connect_callback, you install a function that will be called at the moment, when the connection process about the single socket is done. The callback gets:

• the socket in question
• the error code (including SRT_SUCCESS if the connection succeeded)
• the target address by sockaddr*

The additional reject reason can be obtained by srt_getrejectreason on the socket.

[maxsharabayko]

• Update API.md. Note: might be good to merge Added modified API.md and new APISocketOptions.md #1510 first.

[maxsharabayko]

• Fix API.md for listener callback (listeneing - > listening)

This call installs a callback hook, which will be executed on a socket that is automatically created to handle the incoming connection on the listeneing socket

[maxsharabayko]

We have listener callback, that is called on every incoming connection request (conclusion stage) before accepting it.

Now we are going to have connection callback that is called only if the connection has failed, and not called when the connection succeeds.
Maybe it should rather be named "connection failure callback". 🤔

[jeandube]

Connection callback upon success at the link level is of less interest than failure. connection success is of interest to start sending and this is more for the group socket than the individual links. Connection failure/timeout is of interest at the link level to reissue a link reconnect.

[ethouris]

Yes, but it should be there for consistency. You still can distinguish these situations by checking the error code. Also it's not exactly for knowing if to "start sending" - that you know from the group readiness. When the group is connected, it doesn't report any new links connected - you still you the group for sending, no matter how many links it is currently utilizing.

[maxsharabayko]

In the case of listener callback, there is a possibility to reject the connection.
The connection callback, as I understand, does not provide this possibility, right?
Maybe it should be rather a "connection failure callback"? Especially given that it is intended only for group connections.

Note. Don't forget to update the docs with the new function.

[ethouris]

It is intended mainly for the failed group member connections, but:

1. If someone already uses it, they can simplify the application architecture by relying on the callback report in every case.
2. The error status check is enough to know if the callback was called in case of a failure.
3. The success callback is also an opportunity to update quickly the application's connection array, or use it as an alternative to epoll-write check in case of a single-socket connections. I've seen already that users generally don't like it and check the socket status periodically instead, which has a disadvantage of having no wait-trigger ability.

[stevomatthews]

Minor edits.