Green-Sky/tomato
1
0
Fork 1
Code Issues Pull Requests 1 Actions Packages Projects Releases 1 Wiki Activity

Merge commit 'aae086cc650e42eec1eea8db28cd01fa868d7f90'

Browse Source
This commit is contained in:
Green Sky
2024-03-07 23:12:55 +01:00
parent 2d31b57097 aae086cc65
commit 6ec6fe96e4
358 changed files with 8093 additions and 5229 deletions
Download Patch File Download Diff File Expand all files Collapse all files

33
external/toxcore/c-toxcore/docs/Doxyfile vendored
View File

@ -1295,15 +1295,6 @@ HTML_COLORSTYLE_SAT = 100
HTML_COLORSTYLE_GAMMA = 80
# If the HTML_TIMESTAMP tag is set to YES then the footer of each generated HTML
# page will contain the date and time when the page was generated. Setting this
# to YES can help to show when doxygen was last run and thus if the
# documentation is up to date.
# The default value is: NO.
# This tag requires that the tag GENERATE_HTML is set to YES.
HTML_TIMESTAMP = NO
# If the HTML_DYNAMIC_MENUS tag is set to YES then the generated HTML
# documentation will contain a main index with vertical navigation menus that
# are dynamically created via JavaScript. If disabled, the navigation index will
@ -1950,14 +1941,6 @@ LATEX_HIDE_INDICES = NO
LATEX_BIB_STYLE = plain
# If the LATEX_TIMESTAMP tag is set to YES then the footer of each generated
# page will contain the date and time when the page was generated. Setting this
# to NO can help when comparing the output of multiple runs.
# The default value is: NO.
# This tag requires that the tag GENERATE_LATEX is set to YES.
LATEX_TIMESTAMP = NO
# The LATEX_EMOJI_DIRECTORY tag is used to specify the (relative or absolute)
# path from which the emoji images will be read. If a relative path is entered,
# it will be relative to the LATEX_OUTPUT directory. If left blank the
@ -2587,3 +2570,19 @@ GENERATE_LEGEND = YES
# The default value is: YES.
DOT_CLEANUP = YES
# If the CLANG_ASSISTED_PARSING tag is set to YES then doxygen will use the
# clang parser for more accurate parsing at the cost of reduced performance.
# This can be particularly helpful with template rich C++ code for which
# doxygen's built-in parser lacks the necessary type information.
CLANG_ASSISTED_PARSING = NO
# If clang assisted parsing is enabled you can provide the clang parser with
# the path to the directory containing a file called compile_commands.json.
# This file is the compilation database containing the options used when the
# source files were built. This is equivalent to specifying the -p option to a
# clang tool, such as clang-check. These options will then be passed to the
# parser. Any options specified with CLANG_OPTIONS will be added as well.
CLANG_DATABASE_PATH = _build

109
external/toxcore/c-toxcore/docs/Group-Chats.md vendored
View File

@ -2,77 +2,122 @@ Group chats.
Note: we assume everyone in the chat trusts each other.
These group chats work by temporarily adding the 4 "closest" people defined by a distance function
in group.c in order to form a circle of connected peers. These peers then relay messages to each other.
A friend invites another friend to a group chat by sending them an invite packet. The friend either ignores
the invite or responds with a response packet if he wants to join the chat. The friend invite contains the type
of groupchat (text only, A/V) the friend is being invited to.
These group chats work by temporarily adding the 4 "closest" people defined by a
distance function in group.c in order to form a circle of connected peers. These
peers then relay messages to each other.
A friend invites another friend to a group chat by sending them an invite
packet. The friend either ignores the invite or responds with a response packet
if he wants to join the chat. The friend invite contains the type of groupchat
(text only, A/V) the friend is being invited to.
TODO(irungentoo): write more of this.
## Protocol
Invite packets:
Invite packet:
### Invite packet:
```
[uint8_t id 96][uint8_t id 0][uint16_t group chat number][33 bytes group chat identifier[1 byte type][32 bytes id]]
```
Response packet
### Response packet
```
[uint8_t id 96][uint8_t id 1][uint16_t group chat number(local)][uint16_t group chat number to join][33 bytes group chat identifier[1 byte type][32 bytes id]]
```
### Peer online packet:
Peer online packet:
```
[uint8_t id 97][uint16_t group chat number (local)][33 bytes group chat identifier[1 byte type][32 bytes id]]
```
Peer leave packet:
### Peer leave packet:
```
[uint8_t id 98][uint16_t group chat number][uint8_t id 1]
```
Peer query packet:
### Peer query packet:
```
[uint8_t id 98][uint16_t group chat number][uint8_t id 8]
```
Peer response packet:
[uint8_t id 98][uint16_t group chat number][uint8_t id 9][Repeated times number of peers: [uint16_t peer num][uint8_t 32bytes real public key][uint8_t 32bytes temp DHT public key][uint8_t name length][name]]
### Peer response packet:
Title response packet:
```
[uint8_t id 98][uint16_t group chat number][uint8_t id 9][Repeated times number of peers: [uint16_t peer num][uint8_t 32bytes real public key][uint8_t 32bytes temp DHT public key][uint8_t name length][name]]
```
### Title response packet:
```
[uint8_t id 98][uint16_t group chat number][uint8_t id 10][title]
```
Message packets:
### Message packets:
```
[uint8_t id 99][uint16_t group chat number][uint16_t peer number][uint32_t message number][uint8_t with a value representing id of message][data]
```
Lossy Message packets:
### Lossy Message packets:
```
[uint8_t id 199][uint16_t group chat number][uint16_t peer number][uint16_t message number][uint8_t with a value representing id of message][data]
```
Group chat types:
0: text
1: AV
## Group chat types:
- 0: text
- 1: AV
Note: the message number is increased by 1 for each sent message.
message ids:
0 - ping
sent every ~60 seconds by every peer.
No data.
## message ids:
### 0 - ping
sent every ~60 seconds by every peer. No data.
### 16 - new_peer
16 - new_peer
Tell everyone about a new peer in the chat.
```
[uint16_t peer_num][uint8_t 32bytes real public key][uint8_t 32bytes temp DHT public key]
```
17 - kill_peer
### 17 - kill_peer
```
[uint16_t peer_num]
```
48 - name change
### 48 - name change
```
[uint8_t name[namelen]]
```
49 - groupchat title change
### 49 - groupchat title change
```
[uint8_t title[titlelen]]
```
64 - chat message
### 64 - chat message
```
[uint8_t message[messagelen]]
```
65 - action (/me)
### 65 - action (/me)
```
[uint8_t message[messagelen]]
```

51
external/toxcore/c-toxcore/docs/apidsl.md vendored
View File

@ -1,51 +0,0 @@
This folder contains the input file (``tox.in.h``) that has to be used to generate the ``tox.h`` api with: https://github.com/TokTok/apidsl
# Minimal requirements
There are some minimal requirements to contribute to ``tox.h``:
* unix environment
* ``astyle`` ``>=2.03``
* [``apidsl``](https://github.com/TokTok/apidsl) (you can use provided service with curl instead)
## Quick way
If you want to do it quickly and you don't have time for anything other than copypasting commands, you should have ``curl`` installed.
1. Make sure that you have ``curl`` and ``>=astyle-2.03`` installed
2. Modify [``tox.api.h``](/toxcore/tox.api.h)
3. Run command below ↓
Command to run from ``toxcore`` directory (quick way, involves using curl):
```bash
# For tox.h:
curl -X POST --data-binary @- https://apidsl.herokuapp.com/apidsl \
< toxcore/tox.api.h \
| astyle --options=other/astyle/astylerc \
> toxcore/tox.h
# For toxav.h:
curl -X POST --data-binary @- https://apidsl.herokuapp.com/apidsl \
< toxav/toxav.api.h \
| astyle --options=other/astyle/astylerc \
> toxav/toxav.h
```
You may want to make sure with ``git diff`` that changes made in ``tox.h`` reflect changes in ``tox.in.h``.
And you're done.
## Manually
If you prefer to have more control over what is happening, there are steps below:
1. Install [``apidsl``](https://github.com/TokTok/apidsl)
2. Install ``astyle``, version 2.03 or later.
3. Modify [``tox.api.h``](/toxcore/tox.api.h)
4. Use ``apidsl`` ``??``
5. Parse generated ``tox.h`` with astyle, minimal command for it would be:
```bash
astyle --options=other/astyle/astylerc toxcore/tox.h
```
**Always pass output from ``apidsl`` through astyle.**

129
external/toxcore/c-toxcore/docs/av_api.md vendored
View File

@ -8,38 +8,36 @@
phone_t* initPhone(uint16_t _listen_port, uint16_t _send_port);
```
function initializes sample phone. _listen_port and _send_port are variables only meant
for local testing. You will not have to do anything regarding to that since
everything will be started within a messenger.
function initializes sample phone. `_listen_port` and `_send_port` are variables
only meant for local testing. You will not have to do anything regarding to that
since everything will be started within a messenger.
Phone requires one msi session and two rtp sessions ( one for audio and one for
video ).
Phone requires one msi session and two rtp sessions (one for audio and one for
video).
```
msi_session_t* msi_init_session( void* _core_handler, const uint8_t* _user_agent );
```
initializes msi session.
Params:
initializes msi session. Params:
```
void* _core_handler - pointer to an object handling networking,
const uint8_t* _user_agent - string describing phone client version.
```
Return value:
msi_session_t* - pointer to a newly created msi session handler.
Return value: `msi_session_t*` - pointer to a newly created msi session handler.
### msi_session_t reference:
### `msi_session_t` reference:
How to handle msi session:
Controlling is done via callbacks and action handlers.
First register callbacks for every state/action received and make sure
NOT TO PLACE SOMETHING LIKE LOOPS THAT TAKES A LOT OF TIME TO EXECUTE; every callback is being called
directly from event loop. You can find examples in phone.c.
How to handle msi session: Controlling is done via callbacks and action
handlers. First register callbacks for every state/action received and make sure
NOT TO PLACE SOMETHING LIKE LOOPS THAT TAKES A LOT OF TIME TO EXECUTE; every
callback is being called directly from event loop. You can find examples in
phone.c.
Register callbacks:
Register callbacks:
```
void msi_register_callback_call_started ( MCALLBACK );
void msi_register_callback_call_canceled ( MCALLBACK );
@ -55,10 +53,9 @@ void msi_register_callback_recv_error ( MCALLBACK );
void msi_register_callback_requ_timeout ( MCALLBACK );
```
MCALLBACK is defined as: void (*callback) (void* _arg)
msi_session_t* handler is being thrown as \_arg so you can use that and \_agent_handler to get to your own phone handler
directly from callback.
MCALLBACK is defined as: `void (*callback) (void* _arg)` `msi_session_t*`
handler is being thrown as `_arg` so you can use that and `_agent_handler` to
get to your own phone handler directly from callback.
Actions:
@ -66,80 +63,93 @@ Actions:
int msi_invite ( msi_session_t* _session, call_type _call_type, uint32_t _timeoutms );
```
Sends call invite. Before calling/sending invite msi_session_t::_friend_id is needed to be set or else
it will not work. _call_type is type of the call ( Audio/Video ) and _timeoutms is how long
will poll wait until request is terminated.
Sends call invite. Before calling/sending invite `msi_session_t::_friend_id` is
needed to be set or else it will not work. `_call_type` is type of the call (
Audio/Video ) and `_timeoutms` is how long will poll wait until request is
terminated.
```
int msi_hangup ( msi_session_t* _session );
```
Hangs up active call
```
int msi_answer ( msi_session_t* _session, call_type _call_type );
```
Answer incoming call. _call_type set's callee call type.
Answer incoming call. `_call_type` set's callee call type.
```
int msi_cancel ( msi_session_t* _session );
```
Cancel current request.
```
int msi_reject ( msi_session_t* _session );
```
Reject incoming call.
Reject incoming call.
### Now for rtp:
You will need 2 sessions; one for audio one for video.
You start them with:
You will need 2 sessions; one for audio one for video. You start them with:
```
rtp_session_t* rtp_init_session ( int _max_users, int _multi_session );
```
Params:
```
int _max_users - max users. -1 if undefined
int _multi_session - any positive number means uses multi session; -1 if not.
```
Return value:
```
rtp_session_t* - pointer to a newly created rtp session handler.
```
### How to handle rtp session:
Take a look at
```
void* phone_handle_media_transport_poll ( void* _hmtc_args_p ) in phone.c
```
on example. Basically what you do is just receive a message via:
```
struct rtp_msg_s* rtp_recv_msg ( rtp_session_t* _session );
```
and then you use payload within the rtp_msg_s struct. Don't forget to deallocate it with:
void rtp_free_msg ( rtp_session_t* _session, struct rtp_msg_s* _msg );
and then you use payload within the `rtp_msg_s` struct. Don't forget to
deallocate it with:
`void rtp_free_msg ( rtp_session_t* _session, struct rtp_msg_s* _msg );`
Receiving should be thread safe so don't worry about that.
When you capture and encode a payload you want to send it ( obviously ).
first create a new message with:
```
struct rtp_msg_s* rtp_msg_new ( rtp_session_t* _session, const uint8_t* _data, uint32_t _length );
```
and then send it with:
```
int rtp_send_msg ( rtp_session_t* _session, struct rtp_msg_s* _msg, void* _core_handler );
```
_core_handler is the same network handler as in msi_session_s struct.
`_core_handler` is the same network handler as in `msi_session_s` struct.
## A/V initialization:
```
int init_receive_audio(codec_state *cs);
int init_receive_video(codec_state *cs);
@ -156,39 +166,62 @@ In the future, VP8 should be used directly and ffmpeg should be dropped from the
The variable bps is the required bitrate in bits per second.
```
### A/V encoding/decoding:
```
void *encode_video_thread(void *arg);
```
Spawns the video encoding thread. The argument should hold a pointer to a codec_state.
This function should only be called if video encoding is supported (when init_send_video returns 1).
Each video frame gets encoded into a packet, which is sent via RTP. Every 60 frames a new bidirectional interframe is encoded.
Spawns the video encoding thread. The argument should hold a pointer to a
`codec_state`. This function should only be called if video encoding is
supported (when `init_send_video` returns 1). Each video frame gets encoded into
a packet, which is sent via RTP. Every 60 frames a new bidirectional interframe
is encoded.
```
void *encode_audio_thread(void *arg);
```
Spawns the audio encoding thread. The argument should hold a pointer to a codec_state.
This function should only be called if audio encoding is supported (when init_send_audio returns 1).
Audio frames are read from the selected audio capture device during initialisation. This audio capturing can be rerouted to a different device on the fly.
Each audio frame is encoded into a packet, and sent via RTP. All audio frames have the same amount of samples, which is defined in AV_codec.h.
Spawns the audio encoding thread. The argument should hold a pointer to a
`codec_state`. This function should only be called if audio encoding is
supported (when `init_send_audio` returns 1). Audio frames are read from the
selected audio capture device during initialisation. This audio capturing can be
rerouted to a different device on the fly. Each audio frame is encoded into a
packet, and sent via RTP. All audio frames have the same amount of samples,
which is defined in `AV_codec.h`.
```
int video_decoder_refresh(codec_state *cs, int width, int height);
```
Sets the SDL window dimensions and creates a pixel buffer with the requested size. It also creates a scaling context, which will be used to convert the input image format to YUV420P.
Sets the SDL window dimensions and creates a pixel buffer with the requested
size. It also creates a scaling context, which will be used to convert the input
image format to YUV420P.
```
void *decode_video_thread(void *arg);
```
Spawns a video decoding thread. The argument should hold a pointer to a codec_state. The codec_state is assumed to contain a successfully initialised video decoder.
This function reads video packets and feeds them to the video decoder. If the video frame's resolution has changed, video_decoder_refresh() is called. Afterwards, the frame is displayed on the SDL window.
Spawns a video decoding thread. The argument should hold a pointer to a
`codec_state`. The `codec_state` is assumed to contain a successfully
initialised video decoder. This function reads video packets and feeds them to
the video decoder. If the video frame's resolution has changed,
`video_decoder_refresh()` is called. Afterwards, the frame is displayed on the
SDL window.
```
void *decode_audio_thread(void *arg);
```
Spawns an audio decoding thread. The argument should hold a pointer to a codec_state. The codec_state is assumed to contain a successfully initialised audio decoder.
All received audio packets are pushed into a jitter buffer and are reordered. If there is a missing packet, or a packet has arrived too late, it is treated as a lost packet and the audio decoder is informed of the packet loss. The audio decoder will then try to reconstruct the lost packet, based on information from previous packets.
Audio is played on the default OpenAL output device.
Spawns an audio decoding thread. The argument should hold a pointer to a
`codec_state`. The `codec_state` is assumed to contain a successfully
initialised audio decoder. All received audio packets are pushed into a jitter
buffer and are reordered. If there is a missing packet, or a packet has arrived
too late, it is treated as a lost packet and the audio decoder is informed of
the packet loss. The audio decoder will then try to reconstruct the lost packet,
based on information from previous packets. Audio is played on the default
OpenAL output device.
If you have any more qustions/bug reports/feature request contact the following users on the irc channel #tox-dev on irc.freenode.net:
For RTP and MSI: mannol
If you have any more qustions/bug reports/feature request contact the following
users on the irc channel #tox-dev on irc.freenode.net: For RTP and MSI: mannol
For audio and video: Martijnvdc

111
external/toxcore/c-toxcore/docs/minpgc.md vendored
View File

@ -3,29 +3,29 @@
This document describes the "minpgc" simple persistent conferences
implementation of PR #1069.
Many of the ideas derive from isotoxin's persistent conferences
implementation, PR #826.
Many of the ideas derive from isotoxin's persistent conferences implementation,
PR #826.
## Specification of changes from pre-existing conference specification
We add one new packet type:
Rejoin Conference packet
| Length | Contents |
|:-------|:--------------------------------|
| `1` | `uint8_t` (0x64) |
| `33` | Group chat identifier |
| Length | Contents |
| :----- | :-------------------- |
| `1` | `uint8_t` (0x64) |
| `33` | Group chat identifier |
A peer times out from a group if it has been inactive for 60s. When a peer times
out, we flag it as _frozen_. Frozen peers are disregarded for all purposes
except those discussed below - in particular no packets are sent to them except
as described below, they are omitted from the peer lists sent to the client or
in a Peer Response packet, and they are not considered when determining closest
peers for establishing direct connections.
A peer times out from a group if it has been inactive for 60s. When a peer
times out, we flag it as _frozen_. Frozen peers are disregarded for all
purposes except those discussed below - in particular no packets are sent to
them except as described below, they are omitted from the peer lists sent to
the client or in a Peer Response packet, and they are not considered when
determining closest peers for establishing direct connections.
A peer is considered to be active if we receive a group message or Rejoin
packet from it, or a New Peer message for it.
A peer is considered to be active if we receive a group message or Rejoin packet
from it, or a New Peer message for it.
If a frozen peer is seen to be active, we remove its 'frozen' flag and send a
Name group message. (We can hold off on sending this message until the next
@ -40,77 +40,83 @@ message. (This is current behaviour; it's mentioned here because it's important
and not currently mentioned in the spec.)
If we receive a Rejoin packet from a peer we update its DHT pubkey, add a
temporary groupchat connection for the peer, and, once the connection is
online, send out a New Peer message announcing the peer, and a Name message.
temporary groupchat connection for the peer, and, once the connection is online,
send out a New Peer message announcing the peer, and a Name message.
Whenever we make a new friend connection, we check if the public key is that
of any frozen peer. If so, we send it a Rejoin packet, add a temporary
groupchat connection for it, and, once the connection is online, send the
peer a Peer Query packet.
Whenever we make a new friend connection, we check if the public key is that of
any frozen peer. If so, we send it a Rejoin packet, add a temporary groupchat
connection for it, and, once the connection is online, send the peer a Peer
Query packet.
We do the same with a peer when we are setting it as frozen if we have a
friend connection to it.
We do the same with a peer when we are setting it as frozen if we have a friend
connection to it.
The temporary groupchat connections established in sending and handling Rejoin
packets are not immediately operational (because group numbers are not known);
rather, an Online packet is sent when we handle a Rejoin packet.
When a connection is set as online as a result of an Online packet, we ping
the group.
When a connection is set as online as a result of an Online packet, we ping the
group.
When processing the reply to a Peer Query, we update the DHT pubkey of an
existing peer if and only if it is frozen or has not had its DHT pubkey
updated since it last stopped being frozen.
existing peer if and only if it is frozen or has not had its DHT pubkey updated
since it last stopped being frozen.
When we receive a Title Response packet, we set the title if it has never been
set or if at some point since it was last set, there were no unfrozen peers
(except us).
## Discussion
### Overview
The intention is to recover seamlessly from splits in the group, the most
common form of which is a single peer temporarily losing all connectivity.
To see how this works, first note that groups (even before the changes
discussed here) have the property that for a group to be connected in the
sense that any peer will receive the messages of any other peer and have them
in their peerlist, it is necessary and sufficient that there is a path of
direct group connections between any two peers.
### Overview
The intention is to recover seamlessly from splits in the group, the most common
form of which is a single peer temporarily losing all connectivity.
To see how this works, first note that groups (even before the changes discussed
here) have the property that for a group to be connected in the sense that any
peer will receive the messages of any other peer and have them in their
peerlist, it is necessary and sufficient that there is a path of direct group
connections between any two peers.
Now suppose the group is split into two connected components, with each member
of one component frozen according to the members of the other. Suppose there
are two peers, one in each component, which are using the above protocol, and
of one component frozen according to the members of the other. Suppose there are
two peers, one in each component, which are using the above protocol, and
suppose they establish a friend connection. Then each will rejoin the other,
forming a direct group connection. Hence the whole group will become connected
(even if all other peers are using the unmodified protocol).
The Peer Query packet sent on rejoining hastens this process.
Peers who leave the group during a split will not be deleted by all peers
after the merge - but they will be set as frozen due to ping timeouts, which
is sufficient.
Peers who leave the group during a split will not be deleted by all peers after
the merge - but they will be set as frozen due to ping timeouts, which is
sufficient.
### Titles
If we have a split into components each containing multiple peers, and the
title is changed in one component, then peers will continue to disagree on the
title after the split. Short of a complicated voting system, this seems the
only reasonable behaviour.
If we have a split into components each containing multiple peers, and the title
is changed in one component, then peers will continue to disagree on the title
after the split. Short of a complicated voting system, this seems the only
reasonable behaviour.
### Implementation notes
Although I've described the logic in terms of an 'frozen' flag, it might
actually make more sense in the implementation to have a separate list for
Although I've described the logic in terms of an 'frozen' flag, it might
actually make more sense in the implementation to have a separate list for
frozen peers.
## Saving
Saving is implemented by simply saving all live groups with their group numbers
and full peer info for all peers. On reload, all peers are set as frozen.
Clients needs to support this by understanding that groups may exist on
start-up. Clients should call `tox_conference_get_chatlist` to obtain them. A
group which is deleted (with `tox_conference_delete`) is removed permanently
and will not be saved.
group which is deleted (with `tox_conference_delete`) is removed permanently and
will not be saved.
## Limitations
If a peer disconnects from the group for a period short enough that group
timeouts do not occur, and a name change occurs during this period, then the
name change will never be propagated.
@ -120,9 +126,8 @@ requesting missed group messages. But this is considered out of scope of this
PR.
If a peer changes its DHT pubkey, the change might not be properly propagated
under various circumstances - in particular, if connections do not go down
long enough for the peer to become frozen.
under various circumstances - in particular, if connections do not go down long
enough for the peer to become frozen.
One way to deal with this would be to add a group message announcing the
sending peer's current DHT pubkey, and treat it analogously to the Name
message.
One way to deal with this would be to add a group message announcing the sending
peer's current DHT pubkey, and treat it analogously to the Name message.