docs: Public headers, Core/toxcore -> Tox/the Tox library

Toxcore public header documentation suffers from an identity crisis. It calls
itself three different things: Tox, toxcore and Core, depending on the
time period the comment was written in, the author of the comment,
whether the comment refers to the Tox instance or the Tox[core] library
(it doesn't seem like anything refers to the Tox protocol?), and maybe
some other nuances.

No one really calls it Core though, so this commit replaces the use of
Core with Tox/toxcore, and edits other instances of the documentation
referring to the library where I thought rewording was in order, though
in the end it's more of a subjective personal preference.

toxav/toxav.h

@@ -1,5 +1,5 @@
 /* SPDX-License-Identifier: GPL-3.0-or-later
- * Copyright © 2016-2018 The TokTok team.
+ * Copyright © 2016-2024 The TokTok team.
  * Copyright © 2013-2015 Tox project.
  */
 
@@ -7,39 +7,40 @@
  * @brief Public audio/video API for Tox clients.
  *
  * This API can handle multiple calls. Each call has its state, in very rare
- * occasions the library can change the state of the call without apps knowledge.
+ * occasions the library can change the state of the call without apps
+ * knowledge.
  *
  * @section av_events Events and callbacks
  *
- * As in Core API, events are handled by callbacks. One callback can be
+ * As in the toxcore API, events are handled by callbacks. One callback can be
  * registered per event. All events have a callback function type named
- * `toxav_{event}_cb` and a function to register it named `toxav_callback_{event}`.
- * Passing a NULL callback will result in no callback being registered for that
- * event. Only one callback per event can be registered, so if a client needs
- * multiple event listeners, it needs to implement the dispatch functionality
- * itself. Unlike Core API, lack of some event handlers will cause the the
- * library to drop calls before they are started. Hanging up call from a
- * callback causes undefined behaviour.
+ * `toxav_{event}_cb` and a function to register it named
+ * `toxav_callback_{event}`. Passing a NULL callback will result in no callback
+ * being registered for that event. Only one callback per event can be
+ * registered, so if a client needs multiple event listeners, it needs to
+ * implement the dispatch functionality itself. Unlike the toxcore API, lack of
+ * some event handlers will cause the the library to drop calls before they are
+ * started. Hanging up call from a callback causes undefined behaviour.
  *
  * @section av_threading Threading implications
  *
  * Only toxav_iterate is thread-safe, all other functions must run from the
- * tox thread.
+ * Tox thread.
  *
  * Important exceptions are the `*_iterate` and `*_iterate_interval`
  * functions. You have to choose either the single thread or the multi thread
  * functions and read their documentation.
  *
  * A common way to run ToxAV (multiple or single instance) is to have a thread,
- * separate from tox instance thread, running a simple toxav_iterate loop,
+ * separate from Tox instance thread, running a simple toxav_iterate loop,
  * sleeping for `toxav_iteration_interval * milliseconds` on each iteration.
  *
- * An important thing to note is that events are triggered from both tox and
- * toxav thread (see above). Audio and video receive frame events are triggered
- * from toxav thread while all the other events are triggered from tox thread.
+ * An important thing to note is that events are triggered from both Tox and
+ * ToxAV thread (see above). Audio and video receive frame events are triggered
+ * from ToxAV thread while all the other events are triggered from Tox thread.
  *
- * Tox thread has priority with mutex mechanisms. Any api function can
- * fail if mutexes are held by tox thread in which case they will set SYNC
+ * Tox thread has priority with mutex mechanisms. Any API function can
+ * fail if mutexes are held by Tox thread in which case they will set SYNC
  * error code.
  *
  * @subsection av_multi_threading Separate audio and video threads
@@ -77,9 +78,9 @@ typedef struct Tox Tox;
  *
  * Each ToxAV instance can be bound to only one Tox instance, and Tox instance
  * can have only one ToxAV instance. One must make sure to close ToxAV instance
- * prior closing Tox instance otherwise undefined behaviour occurs. Upon
- * closing of ToxAV instance, all active calls will be forcibly terminated
- * without notifying peers.
+ * prior closing Tox instance otherwise undefined behaviour occurs. Upon closing
+ * of ToxAV instance, all active calls will be forcibly terminated without
+ * notifying peers.
  */
 typedef struct ToxAV ToxAV;
 
@@ -100,8 +101,8 @@ typedef enum Toxav_Err_New {
     TOXAV_ERR_NEW_NULL,
 
     /**
-     * Memory allocation failure while trying to allocate structures required for
-     * the A/V session.
+     * Memory allocation failure while trying to allocate structures required
+     * for the A/V session.
      */
     TOXAV_ERR_NEW_MALLOC,
 
@@ -203,8 +204,8 @@ typedef enum Toxav_Err_Call {
     TOXAV_ERR_CALL_OK,
 
     /**
-     * A resource allocation error occurred while trying to create the structures
-     * required for the call.
+     * A resource allocation error occurred while trying to create the
+     * structures required for the call.
      */
     TOXAV_ERR_CALL_MALLOC,
 
@@ -246,9 +247,9 @@ typedef enum Toxav_Err_Call {
  *
  * @param friend_number The friend number of the friend that should be called.
  * @param audio_bit_rate Audio bit rate in Kb/sec. Set this to 0 to disable
- * audio sending.
+ *   audio sending.
  * @param video_bit_rate Video bit rate in Kb/sec. Set this to 0 to disable
- * video sending.
+ *   video sending.
  */
 bool toxav_call(ToxAV *av, uint32_t friend_number, uint32_t audio_bit_rate, uint32_t video_bit_rate,
                 Toxav_Err_Call *error);
@@ -293,8 +294,9 @@ typedef enum Toxav_Err_Answer {
     TOXAV_ERR_ANSWER_FRIEND_NOT_FOUND,
 
     /**
-     * The friend was valid, but they are not currently trying to initiate a call.
-     * This is also returned if this client is already in a call with the friend.
+     * The friend was valid, but they are not currently trying to initiate a
+     * call. This is also returned if this client is already in a call with the
+     * friend.
      */
     TOXAV_ERR_ANSWER_FRIEND_NOT_CALLING,
 
@@ -314,9 +316,9 @@ typedef enum Toxav_Err_Answer {
  *
  * @param friend_number The friend number of the friend that is calling.
  * @param audio_bit_rate Audio bit rate in Kb/sec. Set this to 0 to disable
- * audio sending.
+ *   audio sending.
  * @param video_bit_rate Video bit rate in Kb/sec. Set this to 0 to disable
- * video sending.
+ *   video sending.
  */
 bool toxav_answer(ToxAV *av, uint32_t friend_number, uint32_t audio_bit_rate, uint32_t video_bit_rate,
                   Toxav_Err_Answer *error);
@@ -337,8 +339,8 @@ enum Toxav_Friend_Call_State {
     /**
      * Set by the AV core if an error occurred on the remote end or if friend
      * timed out. This is the final state after which no more state
-     * transitions can occur for the call. This call state will never be triggered
-     * in combination with other call states.
+     * transitions can occur for the call. This call state will never be
+     * triggered in combination with other call states.
      */
     TOXAV_FRIEND_CALL_STATE_ERROR = 1,
 
@@ -376,9 +378,9 @@ enum Toxav_Friend_Call_State {
  *
  * @param friend_number The friend number for which the call state changed.
  * @param state The bitmask of the new call state which is guaranteed to be
- * different than the previous state. The state is set to 0 when the call is
- * paused. The bitmask represents all the activities currently performed by the
- * friend.
+ *   different than the previous state. The state is set to 0 when the call is
+ *   paused. The bitmask represents all the activities currently performed by
+ *   the friend.
  */
 typedef void toxav_call_state_cb(ToxAV *av, uint32_t friend_number, uint32_t state, void *user_data);
 
@@ -397,8 +399,9 @@ void toxav_callback_call_state(ToxAV *av, toxav_call_state_cb *callback, void *u
 typedef enum Toxav_Call_Control {
 
     /**
-     * Resume a previously paused call. Only valid if the pause was caused by this
-     * client, if not, this control is ignored. Not valid before the call is accepted.
+     * Resume a previously paused call. Only valid if the pause was caused by
+     * this client, if not, this control is ignored. Not valid before the call
+     * is accepted.
      */
     TOXAV_CALL_CONTROL_RESUME,
 
@@ -457,8 +460,8 @@ typedef enum Toxav_Err_Call_Control {
     TOXAV_ERR_CALL_CONTROL_FRIEND_NOT_FOUND,
 
     /**
-     * This client is currently not in a call with the friend. Before the call is
-     * answered, only CANCEL is a valid control.
+     * This client is currently not in a call with the friend. Before the call
+     * is answered, only CANCEL is a valid control.
      */
     TOXAV_ERR_CALL_CONTROL_FRIEND_NOT_IN_CALL,
 
@@ -474,7 +477,7 @@ typedef enum Toxav_Err_Call_Control {
  * Sends a call control command to a friend.
  *
  * @param friend_number The friend number of the friend this client is in a call
- * with.
+ *   with.
  * @param control The control command to send.
  *
  * @return true on success.
@@ -530,8 +533,8 @@ typedef enum Toxav_Err_Send_Frame {
     TOXAV_ERR_SEND_FRAME_OK,
 
     /**
-     * In case of video, one of Y, U, or V was NULL. In case of audio, the samples
-     * data pointer was NULL.
+     * In case of video, one of Y, U, or V was NULL. In case of audio, the
+     * samples data pointer was NULL.
      */
     TOXAV_ERR_SEND_FRAME_NULL,
 
@@ -557,13 +560,13 @@ typedef enum Toxav_Err_Send_Frame {
     TOXAV_ERR_SEND_FRAME_INVALID,
 
     /**
-     * Either friend turned off audio or video receiving or we turned off sending
-     * for the said payload.
+     * Either friend turned off audio or video receiving or we turned off
+     * sending for the said payload.
      */
     TOXAV_ERR_SEND_FRAME_PAYLOAD_TYPE_DISABLED,
 
     /**
-     * Failed to push frame through rtp interface.
+     * Failed to push frame through RTP interface.
      */
     TOXAV_ERR_SEND_FRAME_RTP_FAILED,
 
@@ -572,7 +575,8 @@ typedef enum Toxav_Err_Send_Frame {
 /**
  * Send an audio frame to a friend.
  *
- * The expected format of the PCM data is: `[s1c1][s1c2][...][s2c1][s2c2][...]...`
+ * The expected format of the PCM data is:
+ * `[s1c1][s1c2][...][s2c1][s2c2][...]...`
  * Meaning: sample 1 for channel 1, sample 1 for channel 2, ...
  * For mono audio, this has no meaning, every sample is subsequent. For stereo,
  * this means the expected format is LRLRLR... with samples for left and right
@@ -584,10 +588,10 @@ typedef enum Toxav_Err_Send_Frame {
  *   `sample_count * channels`.
  * @param sample_count Number of samples in this frame. Valid numbers here are
  *   `((sample rate) * (audio length) / 1000)`, where audio length can be
- *   2.5, 5, 10, 20, 40 or 60 millseconds.
+ *   2.5, 5, 10, 20, 40 or 60 milliseconds.
  * @param channels Number of audio channels. Supported values are 1 and 2.
  * @param sampling_rate Audio sampling rate used in this frame. Valid sampling
- * rates are 8000, 12000, 16000, 24000, or 48000.
+ *   rates are 8000, 12000, 16000, 24000, or 48000.
  */
 bool toxav_audio_send_frame(ToxAV *av, uint32_t friend_number, const int16_t pcm[], size_t sample_count,
                             uint8_t channels, uint32_t sampling_rate, Toxav_Err_Send_Frame *error);
@@ -596,7 +600,7 @@ bool toxav_audio_send_frame(ToxAV *av, uint32_t friend_number, const int16_t pcm
  * Set the bit rate to be used in subsequent video frames.
  *
  * @param friend_number The friend number of the friend for which to set the
- * bit rate.
+ *   bit rate.
  * @param bit_rate The new audio bit rate in Kb/sec. Set to 0 to disable.
  *
  * @return true on success.
@@ -605,11 +609,11 @@ bool toxav_audio_set_bit_rate(ToxAV *av, uint32_t friend_number, uint32_t bit_ra
 
 /**
  * The function type for the audio_bit_rate callback. The event is triggered
- * when the network becomes too saturated for current bit rates at which
- * point core suggests new bit rates.
+ * when the network becomes too saturated for current bit rates at which point
+ * ToxAV suggests new bit rates.
  *
  * @param friend_number The friend number of the friend for which to set the
- * bit rate.
+ *   bit rate.
  * @param audio_bit_rate Suggested maximum audio bit rate in Kb/sec.
  */
 typedef void toxav_audio_bit_rate_cb(ToxAV *av, uint32_t friend_number, uint32_t audio_bit_rate, void *user_data);
@@ -628,7 +632,7 @@ void toxav_callback_audio_bit_rate(ToxAV *av, toxav_audio_bit_rate_cb *callback,
  * V - plane should be of size: `(height/2) * (width/2)`
  *
  * @param friend_number The friend number of the friend to which to send a video
- * frame.
+ *   frame.
  * @param width Width of the frame in pixels.
  * @param height Height of the frame in pixels.
  * @param y Y (Luminance) plane data.
@@ -646,7 +650,7 @@ bool toxav_video_send_frame(
  * Set the bit rate to be used in subsequent video frames.
  *
  * @param friend_number The friend number of the friend for which to set the
- * bit rate.
+ *   bit rate.
  * @param bit_rate The new video bit rate in Kb/sec. Set to 0 to disable.
  *
  * @return true on success.
@@ -655,11 +659,11 @@ bool toxav_video_set_bit_rate(ToxAV *av, uint32_t friend_number, uint32_t bit_ra
 
 /**
  * The function type for the video_bit_rate callback. The event is triggered
- * when the network becomes too saturated for current bit rates at which
- * point core suggests new bit rates.
+ * when the network becomes too saturated for current bit rates at which point
+ * ToxAV suggests new bit rates.
  *
  * @param friend_number The friend number of the friend for which to set the
- * bit rate.
+ *   bit rate.
  * @param video_bit_rate Suggested maximum video bit rate in Kb/sec.
  */
 typedef void toxav_video_bit_rate_cb(ToxAV *av, uint32_t friend_number, uint32_t video_bit_rate, void *user_data);
@@ -714,7 +718,6 @@ void toxav_callback_audio_receive_frame(ToxAV *av, toxav_audio_receive_frame_cb
  * @param y Luminosity plane. `Size = MAX(width, abs(ystride)) * height`.
  * @param u U chroma plane. `Size = MAX(width/2, abs(ustride)) * (height/2)`.
  * @param v V chroma plane. `Size = MAX(width/2, abs(vstride)) * (height/2)`.
- *
  * @param ystride Luminosity plane stride.
  * @param ustride U chroma plane stride.
  * @param vstride V chroma plane stride.
@@ -737,26 +740,28 @@ void toxav_callback_video_receive_frame(ToxAV *av, toxav_video_receive_frame_cb
 #ifndef APIGEN_IGNORE
 
 /***
- * NOTE Compatibility with old toxav group calls. TODO(iphydf): remove
+ * NOTE Compatibility with old ToxAV group calls. TODO(iphydf): remove
  *
  * TODO(iphydf): Use proper new API guidelines for these. E.g. don't use inline
  * function types, don't have per-callback userdata, especially don't have one
  * userdata per group.
  */
 
-// TODO(iphydf): Use this better typed one instead of the void-pointer one below.
+// TODO(iphydf): Use this better typed one instead of the void-pointer one
+// below.
 typedef void toxav_group_audio_cb(Tox *tox, uint32_t groupnumber, uint32_t peernumber, const int16_t pcm[],
                                   uint32_t samples, uint8_t channels, uint32_t sample_rate, void *user_data);
 
 typedef void toxav_audio_data_cb(void *tox, uint32_t groupnumber, uint32_t peernumber, const int16_t pcm[],
                                  uint32_t samples, uint8_t channels, uint32_t sample_rate, void *userdata);
 
-/** @brief Create a new toxav group.
+/** @brief Create a new ToxAV group.
  *
  * @return group number on success.
  * @retval -1 on failure.
  *
- * Note that total size of pcm in bytes is equal to `samples * channels * sizeof(int16_t)`.
+ * Note that total size of pcm in bytes is equal to
+ * `samples * channels * sizeof(int16_t)`.
  */
 int32_t toxav_add_av_groupchat(Tox *tox, toxav_audio_data_cb *audio_callback, void *userdata);
 
@@ -765,7 +770,8 @@ int32_t toxav_add_av_groupchat(Tox *tox, toxav_audio_data_cb *audio_callback, vo
  * @return group number on success.
  * @retval -1 on failure.
  *
- * Note that total size of pcm in bytes is equal to `samples * channels * sizeof(int16_t)`.
+ * Note that total size of pcm in bytes is equal to
+ * `samples * channels * sizeof(int16_t)`.
  */
 int32_t toxav_join_av_groupchat(
     Tox *tox, uint32_t friendnumber, const uint8_t data[], uint16_t length,
@@ -776,7 +782,8 @@ int32_t toxav_join_av_groupchat(
  * @retval 0 on success.
  * @retval -1 on failure.
  *
- * Note that total size of pcm in bytes is equal to `samples * channels * sizeof(int16_t)`.
+ * Note that total size of pcm in bytes is equal to
+ * `samples * channels * sizeof(int16_t)`.
  *
  * Valid number of samples are `(sample rate) * (audio length) / 1000`
  *   (Valid values for audio length are: 2.5, 5, 10, 20, 40 or 60 ms)
@@ -794,15 +801,16 @@ int32_t toxav_group_send_audio(
  * A/V must be enabled on a groupchat for audio to be sent to it and for
  * received audio to be handled.
  *
- * An A/V group created with `toxav_add_av_groupchat` or `toxav_join_av_groupchat`
- * will start with A/V enabled.
+ * An A/V group created with `toxav_add_av_groupchat` or
+ * `toxav_join_av_groupchat` will start with A/V enabled.
  *
  * An A/V group loaded from a savefile will start with A/V disabled.
  *
  * @retval 0 on success.
  * @retval -1 on failure.
  *
- * Note that total size of pcm in bytes is equal to `samples * channels * sizeof(int16_t)`.
+ * Note that total size of pcm in bytes is equal to
+ * `samples * channels * sizeof(int16_t)`.
  */
 int32_t toxav_groupchat_enable_av(
     Tox *tox, uint32_t groupnumber,

toxcore/tox_private.h

@@ -1,5 +1,5 @@
 /* SPDX-License-Identifier: GPL-3.0-or-later
- * Copyright © 2016-2020 The TokTok team.
+ * Copyright © 2016-2024 The TokTok team.
  * Copyright © 2013 Tox project.
  */
 
@@ -34,22 +34,22 @@ void tox_unlock(const Tox *tox);
 const Tox_System *tox_get_system(Tox *tox);
 
 /**
- * Set the callback for the `friend_lossy_packet` event for a specific packet ID.
- * Pass NULL to unset.
+ * Set the callback for the `friend_lossy_packet` event for a specific packet
+ * ID. Pass NULL to unset.
  *
  * allowed packet ID range:
- * from `PACKET_ID_RANGE_LOSSY_START` to `PACKET_ID_RANGE_LOSSY_END` (both inclusive)
+ * from `PACKET_ID_RANGE_LOSSY_START` to `PACKET_ID_RANGE_LOSSY_END` (both
+ * inclusive)
  */
 void tox_callback_friend_lossy_packet_per_pktid(Tox *tox, tox_friend_lossy_packet_cb *callback, uint8_t pktid);
 
 /**
- * Set the callback for the `friend_lossless_packet` event for a specific packet ID.
- * Pass NULL to unset.
+ * Set the callback for the `friend_lossless_packet` event for a specific packet
+ * ID. Pass NULL to unset.
  *
  * allowed packet ID range:
- * from `PACKET_ID_RANGE_LOSSLESS_CUSTOM_START` to `PACKET_ID_RANGE_LOSSLESS_CUSTOM_END` (both inclusive)
- * and
- * `PACKET_ID_MSI`
+ * from `PACKET_ID_RANGE_LOSSLESS_CUSTOM_START` to
+ * `PACKET_ID_RANGE_LOSSLESS_CUSTOM_END` (both inclusive) and `PACKET_ID_MSI`
  */
 void tox_callback_friend_lossless_packet_per_pktid(Tox *tox, tox_friend_lossless_packet_cb *callback, uint8_t pktid);
 
@@ -78,7 +78,7 @@ uint32_t tox_dht_node_public_key_size(void);
 
 /**
  * @param public_key The node's public key.
- * @param ip The node's IP address, represented as a null terminated string.
+ * @param ip The node's IP address, represented as a NUL-terminated C string.
  * @param port The node's port.
  */
 typedef void tox_dht_get_nodes_response_cb(Tox *tox, const uint8_t *public_key, const char *ip, uint16_t port,
@@ -98,7 +98,8 @@ typedef enum Tox_Err_Dht_Get_Nodes {
     TOX_ERR_DHT_GET_NODES_OK,
 
     /**
-     * UDP is disabled in tox options; the DHT can only be queried when UDP is enabled.
+     * UDP is disabled in Tox options; the DHT can only be queried when UDP is
+     * enabled.
      */
     TOX_ERR_DHT_GET_NODES_UDP_DISABLED,
 
@@ -118,21 +119,24 @@ typedef enum Tox_Err_Dht_Get_Nodes {
     TOX_ERR_DHT_GET_NODES_BAD_IP,
 
     /**
-     * The getnodes request failed. This usually means the packet failed to send.
+     * The getnodes request failed. This usually means the packet failed to
+     * send.
      */
     TOX_ERR_DHT_GET_NODES_FAIL,
 } Tox_Err_Dht_Get_Nodes;
 
 /**
  * This function sends a getnodes request to a DHT node for its peers that
- * are "close" to the passed target public key according to the distance metric used
- * by the DHT implementation.
+ * are "close" to the passed target public key according to the distance metric
+ * used by the DHT implementation.
  *
- * @param public_key The public key of the node that we wish to query. This key must be
- *   at least `TOX_DHT_NODE_PUBLIC_KEY_SIZE` bytes in length.
- * @param ip A NULL terminated string representing the IP address of the node we wish to query.
+ * @param public_key The public key of the node that we wish to query. This key
+ *   must be at least `TOX_DHT_NODE_PUBLIC_KEY_SIZE` bytes in length.
+ * @param ip A NUL-terminated C string representing the IP address of the node
+ *   we wish to query.
  * @param port The port of the node we wish to query.
- * @param target_public_key The public key for which we want to find close nodes.
+ * @param target_public_key The public key for which we want to find close
+ *   nodes.
  *
  * @return true on success.
  */
@@ -140,8 +144,9 @@ bool tox_dht_get_nodes(const Tox *tox, const uint8_t *public_key, const char *ip
                        const uint8_t *target_public_key, Tox_Err_Dht_Get_Nodes *error);
 
 /**
- * This function returns the ratio of close dht nodes that are known to support announce/store.
- * This function returns the number of DHT nodes in the closelist.
+ * This function returns the ratio of close dht nodes that are known to support
+ * announce/store. This function returns the number of DHT nodes in the
+ * closelist.
  *
  * @return number
  */
@@ -149,7 +154,7 @@ uint16_t tox_dht_get_num_closelist(const Tox *tox);
 
 /**
  * This function returns the number of DHT nodes in the closelist,
- * that are capable to store annouce data (introduced in version 0.2.18).
+ * that are capable to store announce data (introduced in version 0.2.18).
  *
  * @return number
  */
@@ -169,30 +174,32 @@ uint16_t tox_dht_get_num_closelist_announce_capable(const Tox *tox);
 uint32_t tox_group_peer_ip_string_max_length(void);
 
 /**
- * Return the length of the peer's IP address in string form. If the group number or ID
- * is invalid, the return value is unspecified.
+ * Return the length of the peer's IP address in string form. If the group
+ * number or ID is invalid, the return value is unspecified.
  *
  * @param group_number The group number of the group we wish to query.
- * @param peer_id The ID of the peer whose IP address length we want to retrieve.
+ * @param peer_id The ID of the peer whose IP address length we want to
+ *   retrieve.
  */
 size_t tox_group_peer_get_ip_address_size(const Tox *tox, uint32_t group_number, uint32_t peer_id,
         Tox_Err_Group_Peer_Query *error);
 /**
- * Write the IP address associated with the designated peer_id for the designated group number
- * to ip_addr.
+ * Write the IP address associated with the designated peer_id for the
+ * designated group number to ip_addr.
  *
- * If the peer is forcing TCP connections a placeholder value will be written instead,
- * indicating that their real IP address is unknown to us.
+ * If the peer is forcing TCP connections a placeholder value will be written
+ * instead, indicating that their real IP address is unknown to us.
  *
- * If `peer_id` designates ourself, it will write either our own IP address or a placeholder value,
- * depending on whether or not we're forcing TCP connections.
+ * If `peer_id` designates ourself, it will write either our own IP address or a
+ * placeholder value, depending on whether or not we're forcing TCP connections.
  *
- * Call tox_group_peer_get_ip_address_size to determine the allocation size for the `ip_addr` parameter.
+ * Call tox_group_peer_get_ip_address_size to determine the allocation size for
+ * the `ip_addr` parameter.
  *
  * @param group_number The group number of the group we wish to query.
  * @param peer_id The ID of the peer whose public key we wish to retrieve.
- * @param ip_addr A valid memory region large enough to store the IP address string.
- *   If this parameter is NULL, this function call has no effect.
+ * @param ip_addr A valid memory region large enough to store the IP address
+ *   string. If this parameter is NULL, this function call has no effect.
  *
  * @return true on success.
  */

toxencryptsave/toxencryptsave.c

@@ -67,7 +67,8 @@ void tox_pass_key_free(Tox_Pass_Key *key)
  * produce the same key as was previously used. Any data encrypted with this
  * module can be used as input.
  *
- * The cipher text must be at least TOX_PASS_ENCRYPTION_EXTRA_LENGTH bytes in length.
+ * The cipher text must be at least TOX_PASS_ENCRYPTION_EXTRA_LENGTH bytes in
+ * length.
  * The salt must be TOX_PASS_SALT_LENGTH bytes in length.
  * If the passed byte arrays are smaller than required, the behaviour is
  * undefined.
@@ -182,10 +183,11 @@ Tox_Pass_Key *tox_pass_key_derive_with_salt(
 }
 
 /**
- * Encrypt a plain text with a key produced by tox_pass_key_derive or tox_pass_key_derive_with_salt.
+ * Encrypt a plain text with a key produced by tox_pass_key_derive or
+ * tox_pass_key_derive_with_salt.
  *
- * The output array must be at least `plaintext_len + TOX_PASS_ENCRYPTION_EXTRA_LENGTH`
- * bytes long.
+ * The output array must be at least
+ * `plaintext_len + TOX_PASS_ENCRYPTION_EXTRA_LENGTH` bytes long.
  *
  * @param plaintext A byte array of length `plaintext_len`.
  * @param plaintext_len The length of the plain text array. Bigger than 0.
@@ -242,9 +244,9 @@ bool tox_pass_key_encrypt(const Tox_Pass_Key *key, const uint8_t plaintext[], si
 /**
  * Encrypts the given data with the given passphrase.
  *
- * The output array must be at least `plaintext_len + TOX_PASS_ENCRYPTION_EXTRA_LENGTH`
- * bytes long. This delegates to tox_pass_key_derive and
- * tox_pass_key_encrypt.
+ * The output array must be at least
+ * `plaintext_len + TOX_PASS_ENCRYPTION_EXTRA_LENGTH` bytes long. This delegates
+ * to tox_pass_key_derive and tox_pass_key_encrypt.
  *
  * @param plaintext A byte array of length `plaintext_len`.
  * @param plaintext_len The length of the plain text array. Bigger than 0.
@@ -280,7 +282,8 @@ bool tox_pass_encrypt(const uint8_t plaintext[], size_t plaintext_len, const uin
  * tox_pass_key_derive or tox_pass_key_derive_with_salt.
  *
  * @param ciphertext A byte array of length `ciphertext_len`.
- * @param ciphertext_len The length of the cipher text array. At least TOX_PASS_ENCRYPTION_EXTRA_LENGTH.
+ * @param ciphertext_len The length of the cipher text array. At least
+ *   TOX_PASS_ENCRYPTION_EXTRA_LENGTH.
  * @param plaintext The plain text array to write the decrypted data to.
  *
  * @return true on success.
@@ -326,11 +329,13 @@ bool tox_pass_key_decrypt(const Tox_Pass_Key *key, const uint8_t ciphertext[], s
 /**
  * Decrypts the given data with the given passphrase.
  *
- * The output array must be at least `ciphertext_len - TOX_PASS_ENCRYPTION_EXTRA_LENGTH`
- * bytes long. This delegates to tox_pass_key_decrypt.
+ * The output array must be at least
+ * `ciphertext_len - TOX_PASS_ENCRYPTION_EXTRA_LENGTH` bytes long. This
+ * delegates to tox_pass_key_decrypt.
  *
  * @param ciphertext A byte array of length `ciphertext_len`.
- * @param ciphertext_len The length of the cipher text array. At least TOX_PASS_ENCRYPTION_EXTRA_LENGTH.
+ * @param ciphertext_len The length of the cipher text array. At least
+ *   TOX_PASS_ENCRYPTION_EXTRA_LENGTH.
  * @param passphrase The user-provided password. Can be empty.
  * @param passphrase_len The length of the password.
  * @param plaintext The plain text array to write the decrypted data to.

toxencryptsave/toxencryptsave.h

@@ -1,5 +1,5 @@
 /* SPDX-License-Identifier: GPL-3.0-or-later
- * Copyright © 2016-2018 The TokTok team.
+ * Copyright © 2016-2024 The TokTok team.
  * Copyright © 2013-2016 Tox Developers.
  */
 
@@ -165,9 +165,9 @@ typedef enum Tox_Err_Decryption {
 /**
  * Encrypts the given data with the given passphrase.
  *
- * The output array must be at least `plaintext_len + TOX_PASS_ENCRYPTION_EXTRA_LENGTH`
- * bytes long. This delegates to tox_pass_key_derive and
- * tox_pass_key_encrypt.
+ * The output array must be at least
+ * `plaintext_len + TOX_PASS_ENCRYPTION_EXTRA_LENGTH` bytes long. This delegates
+ * to tox_pass_key_derive and tox_pass_key_encrypt.
  *
  * @param plaintext A byte array of length `plaintext_len`.
  * @param plaintext_len The length of the plain text array. Bigger than 0.
@@ -183,11 +183,13 @@ bool tox_pass_encrypt(const uint8_t plaintext[], size_t plaintext_len, const uin
 /**
  * Decrypts the given data with the given passphrase.
  *
- * The output array must be at least `ciphertext_len - TOX_PASS_ENCRYPTION_EXTRA_LENGTH`
- * bytes long. This delegates to tox_pass_key_decrypt.
+ * The output array must be at least
+ * `ciphertext_len - TOX_PASS_ENCRYPTION_EXTRA_LENGTH` bytes long. This
+ * delegates to tox_pass_key_decrypt.
  *
  * @param ciphertext A byte array of length `ciphertext_len`.
- * @param ciphertext_len The length of the cipher text array. At least TOX_PASS_ENCRYPTION_EXTRA_LENGTH.
+ * @param ciphertext_len The length of the cipher text array. At least
+ *   TOX_PASS_ENCRYPTION_EXTRA_LENGTH.
  * @param passphrase The user-provided password. Can be empty.
  * @param passphrase_len The length of the password.
  * @param plaintext The plain text array to write the decrypted data to.
@@ -215,7 +217,8 @@ bool tox_pass_decrypt(const uint8_t ciphertext[], size_t ciphertext_len, const u
  * user-provided password.
  *
  * The Tox_Pass_Key structure is hidden in the implementation. It can be created
- * using tox_pass_key_derive or tox_pass_key_derive_with_salt and must be deallocated using tox_pass_key_free.
+ * using tox_pass_key_derive or tox_pass_key_derive_with_salt and must be
+ * deallocated using tox_pass_key_free.
  */
 #ifndef TOX_PASS_KEY_DEFINED
 #define TOX_PASS_KEY_DEFINED
@@ -261,10 +264,11 @@ Tox_Pass_Key *tox_pass_key_derive_with_salt(
     const uint8_t salt[TOX_PASS_SALT_LENGTH], Tox_Err_Key_Derivation *error);
 
 /**
- * Encrypt a plain text with a key produced by tox_pass_key_derive or tox_pass_key_derive_with_salt.
+ * Encrypt a plain text with a key produced by tox_pass_key_derive or
+ * tox_pass_key_derive_with_salt.
  *
- * The output array must be at least `plaintext_len + TOX_PASS_ENCRYPTION_EXTRA_LENGTH`
- * bytes long.
+ * The output array must be at least
+ * `plaintext_len + TOX_PASS_ENCRYPTION_EXTRA_LENGTH` bytes long.
  *
  * @param plaintext A byte array of length `plaintext_len`.
  * @param plaintext_len The length of the plain text array. Bigger than 0.
@@ -280,7 +284,8 @@ bool tox_pass_key_encrypt(const Tox_Pass_Key *key, const uint8_t plaintext[], si
  * tox_pass_key_derive or tox_pass_key_derive_with_salt.
  *
  * @param ciphertext A byte array of length `ciphertext_len`.
- * @param ciphertext_len The length of the cipher text array. At least TOX_PASS_ENCRYPTION_EXTRA_LENGTH.
+ * @param ciphertext_len The length of the cipher text array. At least
+ *   TOX_PASS_ENCRYPTION_EXTRA_LENGTH.
  * @param plaintext The plain text array to write the decrypted data to.
  *
  * @return true on success.
@@ -315,7 +320,8 @@ typedef enum Tox_Err_Get_Salt {
  * produce the same key as was previously used. Any data encrypted with this
  * module can be used as input.
  *
- * The cipher text must be at least TOX_PASS_ENCRYPTION_EXTRA_LENGTH bytes in length.
+ * The cipher text must be at least TOX_PASS_ENCRYPTION_EXTRA_LENGTH bytes in
+ * length.
  * The salt must be TOX_PASS_SALT_LENGTH bytes in length.
  * If the passed byte arrays are smaller than required, the behaviour is
  * undefined.