/work/toxcore/tox_private.h

Source (jump to first uncovered line)
/* SPDX-License-Identifier: GPL-3.0-or-later
 * Copyright © 2016-2020 The TokTok team.
 * Copyright © 2013 Tox project.
 */

#ifndef C_TOXCORE_TOXCORE_TOX_PRIVATE_H
#define C_TOXCORE_TOXCORE_TOX_PRIVATE_H

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>

#include "tox.h"

#ifdef __cplusplus
extern "C" {
#endif

typedef uint64_t tox_mono_time_cb(void *user_data);

struct Tox_System {
    tox_mono_time_cb *mono_time_callback;
    void *mono_time_user_data;
    const struct Random *rng;
    const struct Network *ns;
    const struct Memory *mem;
};

Tox_System tox_default_system(void);

void tox_lock(const Tox *tox);
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.
 *
 * allowed packet ID range:
 * 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.
 *
 * allowed packet ID range:
 * 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);

void tox_set_av_object(Tox *tox, void *object);
void *tox_get_av_object(const Tox *tox);


/*******************************************************************************
 *
 * :: DHT network queries.
 *
 ******************************************************************************/

/**
 * The minimum size of an IP string buffer in bytes.
 */
#define TOX_DHT_NODE_IP_STRING_SIZE      96

uint32_t tox_dht_node_ip_string_size(void);

/**
 * The size of a DHT node public key in bytes.
 */
#define TOX_DHT_NODE_PUBLIC_KEY_SIZE     32

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 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,
        void *user_data);


/**
 * Set the callback for the `dht_get_nodes_response` event. Pass NULL to unset.
 *
 * This event is triggered when a getnodes response is received from a DHT peer.
 */
void tox_callback_dht_get_nodes_response(Tox *tox, tox_dht_get_nodes_response_cb *callback);


typedef enum Tox_Err_Dht_Get_Nodes {
    /**
     * The function returned successfully.
     */
    TOX_ERR_DHT_GET_NODES_OK,

    /**
     * UDP is disabled in tox options; the DHT can only be queried when UDP is enabled.
     */
    TOX_ERR_DHT_GET_NODES_UDP_DISABLED,

    /**
     * One of the arguments to the function was NULL when it was not expected.
     */
    TOX_ERR_DHT_GET_NODES_NULL,

    /**
     * The supplied port is invalid.
     */
    TOX_ERR_DHT_GET_NODES_BAD_PORT,

    /**
     * The supplied IP address is invalid.
     */
    TOX_ERR_DHT_GET_NODES_BAD_IP,

    /**
     * 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.
 *
 * @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 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.
 *
 * @return true on success.
 */
bool tox_dht_get_nodes(const Tox *tox, const uint8_t *public_key, const char *ip, uint16_t port,
                       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.
 *
 * @return number
 */
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).
 *
 * @return number
 */
uint16_t tox_dht_get_num_closelist_announce_capable(const Tox *tox);


/*******************************************************************************
 *
 * :: DHT groupchat queries.
 *
 ******************************************************************************/

/**
 * Maximum size of a peer IP address string.
 */
#define TOX_GROUP_PEER_IP_STRING_MAX_LENGTH 96

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.
 *
 * @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.
 */
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.
 *
 * 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.
 *
 * 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.
 *
 * @return true on success.
 */
bool tox_group_peer_get_ip_address(const Tox *tox, uint32_t group_number, uint32_t peer_id, uint8_t *ip_addr,
                                   Tox_Err_Group_Peer_Query *error);

#ifdef __cplusplus
} /* extern "C" */
#endif

#endif /* C_TOXCORE_TOXCORE_TOX_PRIVATE_H */

Coverage Report

Created: 2024-01-26 01:52

Line	Count	Source (jump to first uncovered line)
1		/* SPDX-License-Identifier: GPL-3.0-or-later
2		* Copyright © 2016-2020 The TokTok team.
3		* Copyright © 2013 Tox project.
4		*/
5
6		#ifndef C_TOXCORE_TOXCORE_TOX_PRIVATE_H
7		#define C_TOXCORE_TOXCORE_TOX_PRIVATE_H
8
9		#include <stdbool.h>
10		#include <stddef.h>
11		#include <stdint.h>
12
13		#include "tox.h"
14
15		#ifdef __cplusplus
16		extern "C" {
17		#endif
18
19		typedef uint64_t tox_mono_time_cb(void *user_data);
20
21		struct Tox_System {
22		tox_mono_time_cb *mono_time_callback;
23		void *mono_time_user_data;
24		const struct Random *rng;
25		const struct Network *ns;
26		const struct Memory *mem;
27		};
28
29		Tox_System tox_default_system(void);
30
31		void tox_lock(const Tox *tox);
32		void tox_unlock(const Tox *tox);
33
34		const Tox_System tox_get_system(Tox tox);
35
36		/**
37		* Set the callback for the `friend_lossy_packet` event for a specific packet ID.
38		* Pass NULL to unset.
39		*
40		* allowed packet ID range:
41		* from `PACKET_ID_RANGE_LOSSY_START` to `PACKET_ID_RANGE_LOSSY_END` (both inclusive)
42		*/
43		void tox_callback_friend_lossy_packet_per_pktid(Tox tox, tox_friend_lossy_packet_cb callback, uint8_t pktid);
44
45		/**
46		* Set the callback for the `friend_lossless_packet` event for a specific packet ID.
47		* Pass NULL to unset.
48		*
49		* allowed packet ID range:
50		* from `PACKET_ID_RANGE_LOSSLESS_CUSTOM_START` to `PACKET_ID_RANGE_LOSSLESS_CUSTOM_END` (both inclusive)
51		* and
52		* `PACKET_ID_MSI`
53		*/
54		void tox_callback_friend_lossless_packet_per_pktid(Tox tox, tox_friend_lossless_packet_cb callback, uint8_t pktid);
55
56		void tox_set_av_object(Tox tox, void object);
57		void tox_get_av_object(const Tox tox);
58
59
60		/*******************************************************************************
61		*
62		* :: DHT network queries.
63		*
64		******************************************************************************/
65
66		/**
67		* The minimum size of an IP string buffer in bytes.
68		*/
69	1	#define TOX_DHT_NODE_IP_STRING_SIZE 96
70
71		uint32_t tox_dht_node_ip_string_size(void);
72
73		/**
74		* The size of a DHT node public key in bytes.
75		*/
76	653k	#define TOX_DHT_NODE_PUBLIC_KEY_SIZE 32
77
78		uint32_t tox_dht_node_public_key_size(void);
79
80		/**
81		* @param public_key The node's public key.
82		* @param ip The node's IP address, represented as a null terminated string.
83		* @param port The node's port.
84		*/
85		typedef void tox_dht_get_nodes_response_cb(Tox tox, const uint8_t public_key, const char *ip, uint16_t port,
86		void *user_data);
87
88
89		/**
90		* Set the callback for the `dht_get_nodes_response` event. Pass NULL to unset.
91		*
92		* This event is triggered when a getnodes response is received from a DHT peer.
93		*/
94		void tox_callback_dht_get_nodes_response(Tox tox, tox_dht_get_nodes_response_cb callback);
95
96
97		typedef enum Tox_Err_Dht_Get_Nodes {
98		/**
99		* The function returned successfully.
100		*/
101		TOX_ERR_DHT_GET_NODES_OK,
102
103		/**
104		* UDP is disabled in tox options; the DHT can only be queried when UDP is enabled.
105		*/
106		TOX_ERR_DHT_GET_NODES_UDP_DISABLED,
107
108		/**
109		* One of the arguments to the function was NULL when it was not expected.
110		*/
111		TOX_ERR_DHT_GET_NODES_NULL,
112
113		/**
114		* The supplied port is invalid.
115		*/
116		TOX_ERR_DHT_GET_NODES_BAD_PORT,
117
118		/**
119		* The supplied IP address is invalid.
120		*/
121		TOX_ERR_DHT_GET_NODES_BAD_IP,
122
123		/**
124		* The getnodes request failed. This usually means the packet failed to send.
125		*/
126		TOX_ERR_DHT_GET_NODES_FAIL,
127		} Tox_Err_Dht_Get_Nodes;
128
129		/**
130		* This function sends a getnodes request to a DHT node for its peers that
131		* are "close" to the passed target public key according to the distance metric used
132		* by the DHT implementation.
133		*
134		* @param public_key The public key of the node that we wish to query. This key must be
135		* at least `TOX_DHT_NODE_PUBLIC_KEY_SIZE` bytes in length.
136		* @param ip A NULL terminated string representing the IP address of the node we wish to query.
137		* @param port The port of the node we wish to query.
138		* @param target_public_key The public key for which we want to find close nodes.
139		*
140		* @return true on success.
141		*/
142		bool tox_dht_get_nodes(const Tox tox, const uint8_t public_key, const char *ip, uint16_t port,
143		const uint8_t target_public_key, Tox_Err_Dht_Get_Nodes error);
144
145		/**
146		* This function returns the ratio of close dht nodes that are known to support announce/store.
147		* This function returns the number of DHT nodes in the closelist.
148		*
149		* @return number
150		*/
151		uint16_t tox_dht_get_num_closelist(const Tox *tox);
152
153		/**
154		* This function returns the number of DHT nodes in the closelist,
155		* that are capable to store annouce data (introduced in version 0.2.18).
156		*
157		* @return number
158		*/
159		uint16_t tox_dht_get_num_closelist_announce_capable(const Tox *tox);
160
161
162		/*******************************************************************************
163		*
164		* :: DHT groupchat queries.
165		*
166		******************************************************************************/
167
168		/**
169		* Maximum size of a peer IP address string.
170		*/
171	0	#define TOX_GROUP_PEER_IP_STRING_MAX_LENGTH 96
172
173		uint32_t tox_group_peer_ip_string_max_length(void);
174
175		/**
176		* Return the length of the peer's IP address in string form. If the group number or ID
177		* is invalid, the return value is unspecified.
178		*
179		* @param group_number The group number of the group we wish to query.
180		* @param peer_id The ID of the peer whose IP address length we want to retrieve.
181		*/
182		size_t tox_group_peer_get_ip_address_size(const Tox *tox, uint32_t group_number, uint32_t peer_id,
183		Tox_Err_Group_Peer_Query *error);
184		/**
185		* Write the IP address associated with the designated peer_id for the designated group number
186		* to ip_addr.
187		*
188		* If the peer is forcing TCP connections a placeholder value will be written instead,
189		* indicating that their real IP address is unknown to us.
190		*
191		* If `peer_id` designates ourself, it will write either our own IP address or a placeholder value,
192		* depending on whether or not we're forcing TCP connections.
193		*
194		* Call tox_group_peer_get_ip_address_size to determine the allocation size for the `ip_addr` parameter.
195		*
196		* @param group_number The group number of the group we wish to query.
197		* @param peer_id The ID of the peer whose public key we wish to retrieve.
198		* @param ip_addr A valid memory region large enough to store the IP address string.
199		* If this parameter is NULL, this function call has no effect.
200		*
201		* @return true on success.
202		*/
203		bool tox_group_peer_get_ip_address(const Tox tox, uint32_t group_number, uint32_t peer_id, uint8_t ip_addr,
204		Tox_Err_Group_Peer_Query *error);
205
206		#ifdef __cplusplus
207		} /* extern "C" */
208		#endif
209
210		#endif /* C_TOXCORE_TOXCORE_TOX_PRIVATE_H */