/work/toxcore/tox_private.h

Source (jump to first uncovered line)
/* SPDX-License-Identifier: GPL-3.0-or-later
 * Copyright © 2016-2026 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"
#include "tox_attributes.h"
#include "tox_options.h"

#ifdef __cplusplus
extern "C" {
#endif

typedef uint64_t tox_mono_time_cb(void *_Nullable user_data);

typedef struct Random Random;
typedef struct Network Network;
typedef struct Memory Memory;

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

Tox_System tox_default_system(void);

const Tox_System *_Nonnull tox_get_system(const Tox *_Nonnull tox);

typedef struct Tox_Options_Testing {
    const struct Tox_System *_Nullable operating_system;
} Tox_Options_Testing;

typedef enum Tox_Err_New_Testing {
    TOX_ERR_NEW_TESTING_OK,
    TOX_ERR_NEW_TESTING_NULL,
} Tox_Err_New_Testing;

Tox *_Nullable tox_new_testing(const Tox_Options *_Nonnull options, Tox_Err_New *_Nullable error, const Tox_Options_Testing *_Nonnull testing, Tox_Err_New_Testing *_Nullable testing_error);

typedef enum Tox_Err_Iterate_Options_New {
    TOX_ERR_ITERATE_OPTIONS_NEW_OK,
    TOX_ERR_ITERATE_OPTIONS_NEW_MALLOC,
} Tox_Err_Iterate_Options_New;

typedef struct Tox_Iterate_Options Tox_Iterate_Options;

/**
 * Allocates a new Tox_Iterate_Options object and initializes it with
 * default values.
 *
 * Default values:
 * - fail_hard: false
 *
 * @param error An error code. Will be set to OK on success.
 * @return A new options object or NULL on failure.
 */
Tox_Iterate_Options *_Nullable tox_iterate_options_new(Tox_Err_Iterate_Options_New *_Nullable error);

/**
 * Frees the options object.
 */
void tox_iterate_options_free(Tox_Iterate_Options *_Nullable options);

/**
 * Set whether to drop all events when any allocation fails.
 *
 * This only applies when using tox_events_iterate.
 */
void tox_iterate_options_set_fail_hard(Tox_Iterate_Options *_Nonnull options, bool fail_hard);

/**
 * Get whether to drop all events when any allocation fails.
 */
bool tox_iterate_options_get_fail_hard(const Tox_Iterate_Options *_Nullable options);

/**
 * Run a single tox_iterate iteration with custom options.
 */
void tox_iterate_with_options(
    Tox *_Nonnull tox,
    const Tox_Iterate_Options *_Nullable options,
    void *_Nullable user_data);

void tox_lock(const Tox *_Nonnull tox);
void tox_unlock(const Tox *_Nonnull 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 *_Nonnull tox, tox_friend_lossy_packet_cb *_Nullable 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 *_Nonnull tox, tox_friend_lossless_packet_cb *_Nullable callback, uint8_t pktid);

void tox_set_av_object(Tox *_Nonnull tox, void *_Nullable object);
void *_Nullable tox_get_av_object(const Tox *_Nonnull 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 NUL-terminated C string.
 * @param port The node's port.
 */
typedef void tox_dht_nodes_response_cb(
    Tox *_Nonnull tox, const uint8_t *_Nonnull public_key, const char *_Nonnull ip, uint32_t ip_length,
    uint16_t port, void *_Nullable user_data);

/**
 * Set the callback for the `dht_nodes_response` event. Pass NULL to unset.
 *
 * This event is triggered when a nodes response is received from a DHT peer.
 */
void tox_callback_dht_nodes_response(Tox *_Nonnull tox, tox_dht_nodes_response_cb *_Nullable callback);

typedef enum Tox_Err_Dht_Send_Nodes_Request {
    /**
     * The function returned successfully.
     */
    TOX_ERR_DHT_SEND_NODES_REQUEST_OK,

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

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

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

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

    /**
     * The nodes request failed. This usually means the packet failed to
     * send.
     */
    TOX_ERR_DHT_SEND_NODES_REQUEST_FAIL,
} Tox_Err_Dht_Send_Nodes_Request;

/**
 * This function sends a nodes 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 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.
 *
 * @return true on success.
 */
bool tox_dht_send_nodes_request(const Tox *_Nonnull tox, const uint8_t *_Nonnull public_key, const char *_Nonnull ip, uint16_t port,
                                const uint8_t *_Nonnull target_public_key, Tox_Err_Dht_Send_Nodes_Request *_Nullable error);

/**
 * This function returns the number of DHT nodes in the closelist.
 *
 * @return number
 */
uint16_t tox_dht_get_num_closelist(const Tox *_Nonnull tox);

/**
 * This function returns the number of DHT nodes in the closelist
 * that are capable of storing announce data (introduced in version 0.2.18).
 *
 * @return number
 */
uint16_t tox_dht_get_num_closelist_announce_capable(const Tox *_Nonnull tox);

/*******************************************************************************
 *
 * :: Network profiler
 *
 ******************************************************************************/


/**
 * Represents all of the network packet identifiers that Toxcore uses.
 *
 * Notes:
 * - Some packet ID's have different purposes depending on the
 * packet type. These ID's are given numeral names.
 *
 * - Queries for invalid packet ID's return undefined results. For example,
 *   querying a TCP-exclusive packet ID for UDP, or querying an ID that
 *   doesn't exist in this enum.
 */
typedef enum Tox_Netprof_Packet_Id {
    /**
     * Ping request packet (UDP).
     * Routing request (TCP).
     */
    TOX_NETPROF_PACKET_ID_ZERO                 = 0x00,

    /**
     * Ping response packet (UDP).
     * Routing response (TCP).
     */
    TOX_NETPROF_PACKET_ID_ONE                  = 0x01,

    /**
     * Nodes request packet (UDP).
     * Connection notification (TCP).
     */
    TOX_NETPROF_PACKET_ID_TWO                  = 0x02,

    /**
     * TCP disconnect notification.
     */
    TOX_NETPROF_PACKET_ID_TCP_DISCONNECT       = 0x03,

    /**
     * Nodes response packet (UDP).
     * Ping packet (TCP).
     */
    TOX_NETPROF_PACKET_ID_FOUR                 = 0x04,

    /**
     * TCP pong packet.
     */
    TOX_NETPROF_PACKET_ID_TCP_PONG             = 0x05,

    /**
     * TCP out-of-band send packet.
     */
    TOX_NETPROF_PACKET_ID_TCP_OOB_SEND         = 0x06,

    /**
     * TCP out-of-band receive packet.
     */
    TOX_NETPROF_PACKET_ID_TCP_OOB_RECV         = 0x07,

    /**
     * TCP onion request packet.
     */
    TOX_NETPROF_PACKET_ID_TCP_ONION_REQUEST    = 0x08,

    /**
     * TCP onion response packet.
     */
    TOX_NETPROF_PACKET_ID_TCP_ONION_RESPONSE   = 0x09,

    /**
     * TCP data packet.
     */
    TOX_NETPROF_PACKET_ID_TCP_DATA             = 0x10,

    /**
     * Cookie request packet.
     */
    TOX_NETPROF_PACKET_ID_COOKIE_REQUEST       = 0x18,

    /**
     * Cookie response packet.
     */
    TOX_NETPROF_PACKET_ID_COOKIE_RESPONSE      = 0x19,

    /**
     * Crypto handshake packet.
     */
    TOX_NETPROF_PACKET_ID_CRYPTO_HS            = 0x1a,

    /**
     * Crypto data packet.
     */
    TOX_NETPROF_PACKET_ID_CRYPTO_DATA          = 0x1b,

    /**
     * Encrypted data packet.
     */
    TOX_NETPROF_PACKET_ID_CRYPTO               = 0x20,

    /**
     * LAN discovery packet.
     */
    TOX_NETPROF_PACKET_ID_LAN_DISCOVERY        = 0x21,

    /**
     * DHT groupchat packets.
     */
    TOX_NETPROF_PACKET_ID_GC_HANDSHAKE         = 0x5a,
    TOX_NETPROF_PACKET_ID_GC_LOSSLESS          = 0x5b,
    TOX_NETPROF_PACKET_ID_GC_LOSSY             = 0x5c,

    /**
     * Onion send packets.
     */
    TOX_NETPROF_PACKET_ID_ONION_SEND_INITIAL   = 0x80,
    TOX_NETPROF_PACKET_ID_ONION_SEND_1         = 0x81,
    TOX_NETPROF_PACKET_ID_ONION_SEND_2         = 0x82,

    /**
     * DHT announce request packet (deprecated).
     */
    TOX_NETPROF_PACKET_ID_ANNOUNCE_REQUEST_OLD = 0x83,

    /**
     * DHT announce response packet (deprecated).
     */
    TOX_NETPROF_PACKET_ID_ANNOUNCE_RESPONSE_OLD = 0x84,

    /**
     * Onion data request packet.
     */
    TOX_NETPROF_PACKET_ID_ONION_DATA_REQUEST   = 0x85,

    /**
     * Onion data response packet.
     */
    TOX_NETPROF_PACKET_ID_ONION_DATA_RESPONSE  = 0x86,

    /**
     * DHT announce request packet.
     */
    TOX_NETPROF_PACKET_ID_ANNOUNCE_REQUEST     = 0x87,

    /**
     * DHT announce response packet.
     */
    TOX_NETPROF_PACKET_ID_ANNOUNCE_RESPONSE    = 0x88,

    /**
     * Onion receive packets.
     */
    TOX_NETPROF_PACKET_ID_ONION_RECV_3         = 0x8c,
    TOX_NETPROF_PACKET_ID_ONION_RECV_2         = 0x8d,
    TOX_NETPROF_PACKET_ID_ONION_RECV_1         = 0x8e,

    TOX_NETPROF_PACKET_ID_FORWARD_REQUEST      = 0x90,
    TOX_NETPROF_PACKET_ID_FORWARDING           = 0x91,
    TOX_NETPROF_PACKET_ID_FORWARD_REPLY        = 0x92,

    TOX_NETPROF_PACKET_ID_DATA_SEARCH_REQUEST     = 0x93,
    TOX_NETPROF_PACKET_ID_DATA_SEARCH_RESPONSE    = 0x94,
    TOX_NETPROF_PACKET_ID_DATA_RETRIEVE_REQUEST   = 0x95,
    TOX_NETPROF_PACKET_ID_DATA_RETRIEVE_RESPONSE  = 0x96,
    TOX_NETPROF_PACKET_ID_STORE_ANNOUNCE_REQUEST  = 0x97,
    TOX_NETPROF_PACKET_ID_STORE_ANNOUNCE_RESPONSE = 0x98,

    /**
     * Bootstrap info packet.
     */
    TOX_NETPROF_PACKET_ID_BOOTSTRAP_INFO       = 0xf0,
} Tox_Netprof_Packet_Id;

const char *_Nonnull tox_netprof_packet_id_to_string(Tox_Netprof_Packet_Id value);

/**
 * Specifies the packet type for a given query.
 */
typedef enum Tox_Netprof_Packet_Type {
    /**
     * TCP client packets.
     */
    TOX_NETPROF_PACKET_TYPE_TCP_CLIENT,

    /**
     * TCP server packets.
     */
    TOX_NETPROF_PACKET_TYPE_TCP_SERVER,

    /**
     * Combined TCP server and TCP client packets.
     */
    TOX_NETPROF_PACKET_TYPE_TCP,

    /**
     * UDP packets.
     */
    TOX_NETPROF_PACKET_TYPE_UDP,
} Tox_Netprof_Packet_Type;

const char *_Nonnull tox_netprof_packet_type_to_string(Tox_Netprof_Packet_Type value);

/**
 * Specifies the packet direction for a given query.
 */
typedef enum Tox_Netprof_Direction {
    /**
     * Outbound packets.
     */
    TOX_NETPROF_DIRECTION_SENT,

    /**
     * Inbound packets.
     */
    TOX_NETPROF_DIRECTION_RECV,
} Tox_Netprof_Direction;

const char *_Nonnull tox_netprof_direction_to_string(Tox_Netprof_Direction value);

/**
 * Return the number of packets sent or received for a specific packet ID.
 *
 * @param type The types of packets being queried.
 * @param id The packet ID being queried.
 * @param direction The packet direction.
 */
uint64_t tox_netprof_get_packet_id_count(const Tox *_Nonnull tox, Tox_Netprof_Packet_Type type, uint8_t id,
        Tox_Netprof_Direction direction);

/**
 * Return the total number of packets sent or received.
 *
 * @param type The types of packets being queried.
 * @param direction The packet direction.
 */
uint64_t tox_netprof_get_packet_total_count(const Tox *_Nonnull tox, Tox_Netprof_Packet_Type type,
        Tox_Netprof_Direction direction);

/**
 * Return the number of bytes sent or received for a specific packet ID.
 *
 * @param type The types of packets being queried.
 * @param id The packet ID being queried.
 * @param direction The packet direction.
 */
uint64_t tox_netprof_get_packet_id_bytes(const Tox *_Nonnull tox, Tox_Netprof_Packet_Type type, uint8_t id,
        Tox_Netprof_Direction direction);

/**
 * Return the total number of bytes sent or received.
 *
 * @param type The types of packets being queried.
 * @param direction The packet direction.
 */
uint64_t tox_netprof_get_packet_total_bytes(const Tox *_Nonnull tox, Tox_Netprof_Packet_Type type,
        Tox_Netprof_Direction direction);


/*******************************************************************************
 *
 * :: 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 *_Nonnull tox, uint32_t group_number, uint32_t peer_id,
        Tox_Err_Group_Peer_Query *_Nullable 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 *_Nonnull tox, uint32_t group_number, uint32_t peer_id, uint8_t *_Nonnull ip_addr,
                                   Tox_Err_Group_Peer_Query *_Nullable error);

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

#endif /* C_TOXCORE_TOXCORE_TOX_PRIVATE_H */

Coverage Report

Created: 2026-10-24 08:16

Line	Count	Source (jump to first uncovered line)
1		/* SPDX-License-Identifier: GPL-3.0-or-later
2		* Copyright © 2016-2026 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		#include "tox_attributes.h"
15		#include "tox_options.h"
16
17		#ifdef __cplusplus
18		extern "C" {
19		#endif
20
21		typedef uint64_t tox_mono_time_cb(void *_Nullable user_data);
22
23		typedef struct Random Random;
24		typedef struct Network Network;
25		typedef struct Memory Memory;
26
27		typedef struct Tox_System {
28		tox_mono_time_cb *_Nullable mono_time_callback;
29		void *_Nullable mono_time_user_data;
30		const Random *_Nullable rng;
31		const Network *_Nullable ns;
32		const Memory *_Nullable mem;
33		} Tox_System;
34
35		Tox_System tox_default_system(void);
36
37		const Tox_System _Nonnull tox_get_system(const Tox _Nonnull tox);
38
39		typedef struct Tox_Options_Testing {
40		const struct Tox_System *_Nullable operating_system;
41		} Tox_Options_Testing;
42
43		typedef enum Tox_Err_New_Testing {
44		TOX_ERR_NEW_TESTING_OK,
45		TOX_ERR_NEW_TESTING_NULL,
46		} Tox_Err_New_Testing;
47
48		Tox _Nullable tox_new_testing(const Tox_Options _Nonnull options, Tox_Err_New _Nullable error, const Tox_Options_Testing _Nonnull testing, Tox_Err_New_Testing *_Nullable testing_error);
49
50		typedef enum Tox_Err_Iterate_Options_New {
51		TOX_ERR_ITERATE_OPTIONS_NEW_OK,
52		TOX_ERR_ITERATE_OPTIONS_NEW_MALLOC,
53		} Tox_Err_Iterate_Options_New;
54
55		typedef struct Tox_Iterate_Options Tox_Iterate_Options;
56
57		/**
58		* Allocates a new Tox_Iterate_Options object and initializes it with
59		* default values.
60		*
61		* Default values:
62		* - fail_hard: false
63		*
64		* @param error An error code. Will be set to OK on success.
65		* @return A new options object or NULL on failure.
66		*/
67		Tox_Iterate_Options _Nullable tox_iterate_options_new(Tox_Err_Iterate_Options_New _Nullable error);
68
69		/**
70		* Frees the options object.
71		*/
72		void tox_iterate_options_free(Tox_Iterate_Options *_Nullable options);
73
74		/**
75		* Set whether to drop all events when any allocation fails.
76		*
77		* This only applies when using tox_events_iterate.
78		*/
79		void tox_iterate_options_set_fail_hard(Tox_Iterate_Options *_Nonnull options, bool fail_hard);
80
81		/**
82		* Get whether to drop all events when any allocation fails.
83		*/
84		bool tox_iterate_options_get_fail_hard(const Tox_Iterate_Options *_Nullable options);
85
86		/**
87		* Run a single tox_iterate iteration with custom options.
88		*/
89		void tox_iterate_with_options(
90		Tox *_Nonnull tox,
91		const Tox_Iterate_Options *_Nullable options,
92		void *_Nullable user_data);
93
94		void tox_lock(const Tox *_Nonnull tox);
95		void tox_unlock(const Tox *_Nonnull tox);
96
97		/**
98		* Set the callback for the `friend_lossy_packet` event for a specific packet
99		* ID. Pass NULL to unset.
100		*
101		* allowed packet ID range:
102		* from `PACKET_ID_RANGE_LOSSY_START` to `PACKET_ID_RANGE_LOSSY_END` (both
103		* inclusive)
104		*/
105		void tox_callback_friend_lossy_packet_per_pktid(Tox _Nonnull tox, tox_friend_lossy_packet_cb _Nullable callback, uint8_t pktid);
106
107		/**
108		* Set the callback for the `friend_lossless_packet` event for a specific packet
109		* ID. Pass NULL to unset.
110		*
111		* allowed packet ID range:
112		* from `PACKET_ID_RANGE_LOSSLESS_CUSTOM_START` to
113		* `PACKET_ID_RANGE_LOSSLESS_CUSTOM_END` (both inclusive) and `PACKET_ID_MSI`
114		*/
115		void tox_callback_friend_lossless_packet_per_pktid(Tox _Nonnull tox, tox_friend_lossless_packet_cb _Nullable callback, uint8_t pktid);
116
117		void tox_set_av_object(Tox _Nonnull tox, void _Nullable object);
118		void _Nullable tox_get_av_object(const Tox _Nonnull tox);
119
120		/*******************************************************************************
121		*
122		* :: DHT network queries.
123		*
124		******************************************************************************/
125
126		/**
127		* The minimum size of an IP string buffer in bytes.
128		*/
129	1	#define TOX_DHT_NODE_IP_STRING_SIZE 96
130
131		uint32_t tox_dht_node_ip_string_size(void);
132
133		/**
134		* The size of a DHT node public key in bytes.
135		*/
136	1.39M	#define TOX_DHT_NODE_PUBLIC_KEY_SIZE 32
137
138		uint32_t tox_dht_node_public_key_size(void);
139
140		/**
141		* @param public_key The node's public key.
142		* @param ip The node's IP address, represented as a NUL-terminated C string.
143		* @param port The node's port.
144		*/
145		typedef void tox_dht_nodes_response_cb(
146		Tox _Nonnull tox, const uint8_t _Nonnull public_key, const char *_Nonnull ip, uint32_t ip_length,
147		uint16_t port, void *_Nullable user_data);
148
149		/**
150		* Set the callback for the `dht_nodes_response` event. Pass NULL to unset.
151		*
152		* This event is triggered when a nodes response is received from a DHT peer.
153		*/
154		void tox_callback_dht_nodes_response(Tox _Nonnull tox, tox_dht_nodes_response_cb _Nullable callback);
155
156		typedef enum Tox_Err_Dht_Send_Nodes_Request {
157		/**
158		* The function returned successfully.
159		*/
160		TOX_ERR_DHT_SEND_NODES_REQUEST_OK,
161
162		/**
163		* UDP is disabled in Tox options; the DHT can only be queried when UDP is
164		* enabled.
165		*/
166		TOX_ERR_DHT_SEND_NODES_REQUEST_UDP_DISABLED,
167
168		/**
169		* One of the arguments to the function was NULL when it was not expected.
170		*/
171		TOX_ERR_DHT_SEND_NODES_REQUEST_NULL,
172
173		/**
174		* The supplied port is invalid.
175		*/
176		TOX_ERR_DHT_SEND_NODES_REQUEST_BAD_PORT,
177
178		/**
179		* The supplied IP address is invalid.
180		*/
181		TOX_ERR_DHT_SEND_NODES_REQUEST_BAD_IP,
182
183		/**
184		* The nodes request failed. This usually means the packet failed to
185		* send.
186		*/
187		TOX_ERR_DHT_SEND_NODES_REQUEST_FAIL,
188		} Tox_Err_Dht_Send_Nodes_Request;
189
190		/**
191		* This function sends a nodes request to a DHT node for its peers that
192		* are "close" to the passed target public key according to the distance metric
193		* used by the DHT implementation.
194		*
195		* @param public_key The public key of the node that we wish to query. This key
196		* must be at least `TOX_DHT_NODE_PUBLIC_KEY_SIZE` bytes in length.
197		* @param ip A NUL-terminated C string representing the IP address of the node
198		* we wish to query.
199		* @param port The port of the node we wish to query.
200		* @param target_public_key The public key for which we want to find close
201		* nodes.
202		*
203		* @return true on success.
204		*/
205		bool tox_dht_send_nodes_request(const Tox _Nonnull tox, const uint8_t _Nonnull public_key, const char *_Nonnull ip, uint16_t port,
206		const uint8_t _Nonnull target_public_key, Tox_Err_Dht_Send_Nodes_Request _Nullable error);
207
208		/**
209		* This function returns the number of DHT nodes in the closelist.
210		*
211		* @return number
212		*/
213		uint16_t tox_dht_get_num_closelist(const Tox *_Nonnull tox);
214
215		/**
216		* This function returns the number of DHT nodes in the closelist
217		* that are capable of storing announce data (introduced in version 0.2.18).
218		*
219		* @return number
220		*/
221		uint16_t tox_dht_get_num_closelist_announce_capable(const Tox *_Nonnull tox);
222
223		/*******************************************************************************
224		*
225		* :: Network profiler
226		*
227		******************************************************************************/
228
229
230		/**
231		* Represents all of the network packet identifiers that Toxcore uses.
232		*
233		* Notes:
234		* - Some packet ID's have different purposes depending on the
235		* packet type. These ID's are given numeral names.
236		*
237		* - Queries for invalid packet ID's return undefined results. For example,
238		* querying a TCP-exclusive packet ID for UDP, or querying an ID that
239		* doesn't exist in this enum.
240		*/
241		typedef enum Tox_Netprof_Packet_Id {
242		/**
243		* Ping request packet (UDP).
244		* Routing request (TCP).
245		*/
246		TOX_NETPROF_PACKET_ID_ZERO = 0x00,
247
248		/**
249		* Ping response packet (UDP).
250		* Routing response (TCP).
251		*/
252		TOX_NETPROF_PACKET_ID_ONE = 0x01,
253
254		/**
255		* Nodes request packet (UDP).
256		* Connection notification (TCP).
257		*/
258		TOX_NETPROF_PACKET_ID_TWO = 0x02,
259
260		/**
261		* TCP disconnect notification.
262		*/
263		TOX_NETPROF_PACKET_ID_TCP_DISCONNECT = 0x03,
264
265		/**
266		* Nodes response packet (UDP).
267		* Ping packet (TCP).
268		*/
269		TOX_NETPROF_PACKET_ID_FOUR = 0x04,
270
271		/**
272		* TCP pong packet.
273		*/
274		TOX_NETPROF_PACKET_ID_TCP_PONG = 0x05,
275
276		/**
277		* TCP out-of-band send packet.
278		*/
279		TOX_NETPROF_PACKET_ID_TCP_OOB_SEND = 0x06,
280
281		/**
282		* TCP out-of-band receive packet.
283		*/
284		TOX_NETPROF_PACKET_ID_TCP_OOB_RECV = 0x07,
285
286		/**
287		* TCP onion request packet.
288		*/
289		TOX_NETPROF_PACKET_ID_TCP_ONION_REQUEST = 0x08,
290
291		/**
292		* TCP onion response packet.
293		*/
294		TOX_NETPROF_PACKET_ID_TCP_ONION_RESPONSE = 0x09,
295
296		/**
297		* TCP data packet.
298		*/
299		TOX_NETPROF_PACKET_ID_TCP_DATA = 0x10,
300
301		/**
302		* Cookie request packet.
303		*/
304		TOX_NETPROF_PACKET_ID_COOKIE_REQUEST = 0x18,
305
306		/**
307		* Cookie response packet.
308		*/
309		TOX_NETPROF_PACKET_ID_COOKIE_RESPONSE = 0x19,
310
311		/**
312		* Crypto handshake packet.
313		*/
314		TOX_NETPROF_PACKET_ID_CRYPTO_HS = 0x1a,
315
316		/**
317		* Crypto data packet.
318		*/
319		TOX_NETPROF_PACKET_ID_CRYPTO_DATA = 0x1b,
320
321		/**
322		* Encrypted data packet.
323		*/
324		TOX_NETPROF_PACKET_ID_CRYPTO = 0x20,
325
326		/**
327		* LAN discovery packet.
328		*/
329		TOX_NETPROF_PACKET_ID_LAN_DISCOVERY = 0x21,
330
331		/**
332		* DHT groupchat packets.
333		*/
334		TOX_NETPROF_PACKET_ID_GC_HANDSHAKE = 0x5a,
335		TOX_NETPROF_PACKET_ID_GC_LOSSLESS = 0x5b,
336		TOX_NETPROF_PACKET_ID_GC_LOSSY = 0x5c,
337
338		/**
339		* Onion send packets.
340		*/
341		TOX_NETPROF_PACKET_ID_ONION_SEND_INITIAL = 0x80,
342		TOX_NETPROF_PACKET_ID_ONION_SEND_1 = 0x81,
343		TOX_NETPROF_PACKET_ID_ONION_SEND_2 = 0x82,
344
345		/**
346		* DHT announce request packet (deprecated).
347		*/
348		TOX_NETPROF_PACKET_ID_ANNOUNCE_REQUEST_OLD = 0x83,
349
350		/**
351		* DHT announce response packet (deprecated).
352		*/
353		TOX_NETPROF_PACKET_ID_ANNOUNCE_RESPONSE_OLD = 0x84,
354
355		/**
356		* Onion data request packet.
357		*/
358		TOX_NETPROF_PACKET_ID_ONION_DATA_REQUEST = 0x85,
359
360		/**
361		* Onion data response packet.
362		*/
363		TOX_NETPROF_PACKET_ID_ONION_DATA_RESPONSE = 0x86,
364
365		/**
366		* DHT announce request packet.
367		*/
368		TOX_NETPROF_PACKET_ID_ANNOUNCE_REQUEST = 0x87,
369
370		/**
371		* DHT announce response packet.
372		*/
373		TOX_NETPROF_PACKET_ID_ANNOUNCE_RESPONSE = 0x88,
374
375		/**
376		* Onion receive packets.
377		*/
378		TOX_NETPROF_PACKET_ID_ONION_RECV_3 = 0x8c,
379		TOX_NETPROF_PACKET_ID_ONION_RECV_2 = 0x8d,
380		TOX_NETPROF_PACKET_ID_ONION_RECV_1 = 0x8e,
381
382		TOX_NETPROF_PACKET_ID_FORWARD_REQUEST = 0x90,
383		TOX_NETPROF_PACKET_ID_FORWARDING = 0x91,
384		TOX_NETPROF_PACKET_ID_FORWARD_REPLY = 0x92,
385
386		TOX_NETPROF_PACKET_ID_DATA_SEARCH_REQUEST = 0x93,
387		TOX_NETPROF_PACKET_ID_DATA_SEARCH_RESPONSE = 0x94,
388		TOX_NETPROF_PACKET_ID_DATA_RETRIEVE_REQUEST = 0x95,
389		TOX_NETPROF_PACKET_ID_DATA_RETRIEVE_RESPONSE = 0x96,
390		TOX_NETPROF_PACKET_ID_STORE_ANNOUNCE_REQUEST = 0x97,
391		TOX_NETPROF_PACKET_ID_STORE_ANNOUNCE_RESPONSE = 0x98,
392
393		/**
394		* Bootstrap info packet.
395		*/
396		TOX_NETPROF_PACKET_ID_BOOTSTRAP_INFO = 0xf0,
397		} Tox_Netprof_Packet_Id;
398
399		const char *_Nonnull tox_netprof_packet_id_to_string(Tox_Netprof_Packet_Id value);
400
401		/**
402		* Specifies the packet type for a given query.
403		*/
404		typedef enum Tox_Netprof_Packet_Type {
405		/**
406		* TCP client packets.
407		*/
408		TOX_NETPROF_PACKET_TYPE_TCP_CLIENT,
409
410		/**
411		* TCP server packets.
412		*/
413		TOX_NETPROF_PACKET_TYPE_TCP_SERVER,
414
415		/**
416		* Combined TCP server and TCP client packets.
417		*/
418		TOX_NETPROF_PACKET_TYPE_TCP,
419
420		/**
421		* UDP packets.
422		*/
423		TOX_NETPROF_PACKET_TYPE_UDP,
424		} Tox_Netprof_Packet_Type;
425
426		const char *_Nonnull tox_netprof_packet_type_to_string(Tox_Netprof_Packet_Type value);
427
428		/**
429		* Specifies the packet direction for a given query.
430		*/
431		typedef enum Tox_Netprof_Direction {
432		/**
433		* Outbound packets.
434		*/
435		TOX_NETPROF_DIRECTION_SENT,
436
437		/**
438		* Inbound packets.
439		*/
440		TOX_NETPROF_DIRECTION_RECV,
441		} Tox_Netprof_Direction;
442
443		const char *_Nonnull tox_netprof_direction_to_string(Tox_Netprof_Direction value);
444
445		/**
446		* Return the number of packets sent or received for a specific packet ID.
447		*
448		* @param type The types of packets being queried.
449		* @param id The packet ID being queried.
450		* @param direction The packet direction.
451		*/
452		uint64_t tox_netprof_get_packet_id_count(const Tox *_Nonnull tox, Tox_Netprof_Packet_Type type, uint8_t id,
453		Tox_Netprof_Direction direction);
454
455		/**
456		* Return the total number of packets sent or received.
457		*
458		* @param type The types of packets being queried.
459		* @param direction The packet direction.
460		*/
461		uint64_t tox_netprof_get_packet_total_count(const Tox *_Nonnull tox, Tox_Netprof_Packet_Type type,
462		Tox_Netprof_Direction direction);
463
464		/**
465		* Return the number of bytes sent or received for a specific packet ID.
466		*
467		* @param type The types of packets being queried.
468		* @param id The packet ID being queried.
469		* @param direction The packet direction.
470		*/
471		uint64_t tox_netprof_get_packet_id_bytes(const Tox *_Nonnull tox, Tox_Netprof_Packet_Type type, uint8_t id,
472		Tox_Netprof_Direction direction);
473
474		/**
475		* Return the total number of bytes sent or received.
476		*
477		* @param type The types of packets being queried.
478		* @param direction The packet direction.
479		*/
480		uint64_t tox_netprof_get_packet_total_bytes(const Tox *_Nonnull tox, Tox_Netprof_Packet_Type type,
481		Tox_Netprof_Direction direction);
482
483
484		/*******************************************************************************
485		*
486		* :: DHT groupchat queries.
487		*
488		******************************************************************************/
489
490		/**
491		* Maximum size of a peer IP address string.
492		*/
493	0	#define TOX_GROUP_PEER_IP_STRING_MAX_LENGTH 96
494
495		uint32_t tox_group_peer_ip_string_max_length(void);
496
497		/**
498		* Return the length of the peer's IP address in string form. If the group
499		* number or ID is invalid, the return value is unspecified.
500		*
501		* @param group_number The group number of the group we wish to query.
502		* @param peer_id The ID of the peer whose IP address length we want to
503		* retrieve.
504		*/
505		size_t tox_group_peer_get_ip_address_size(const Tox *_Nonnull tox, uint32_t group_number, uint32_t peer_id,
506		Tox_Err_Group_Peer_Query *_Nullable error);
507		/**
508		* Write the IP address associated with the designated peer_id for the
509		* designated group number to ip_addr.
510		*
511		* If the peer is forcing TCP connections a placeholder value will be written
512		* instead, indicating that their real IP address is unknown to us.
513		*
514		* If `peer_id` designates ourself, it will write either our own IP address or a
515		* placeholder value, depending on whether or not we're forcing TCP connections.
516		*
517		* Call tox_group_peer_get_ip_address_size to determine the allocation size for
518		* the `ip_addr` parameter.
519		*
520		* @param group_number The group number of the group we wish to query.
521		* @param peer_id The ID of the peer whose public key we wish to retrieve.
522		* @param ip_addr A valid memory region large enough to store the IP address
523		* string. If this parameter is NULL, this function call has no effect.
524		*
525		* @return true on success.
526		*/
527		bool tox_group_peer_get_ip_address(const Tox _Nonnull tox, uint32_t group_number, uint32_t peer_id, uint8_t _Nonnull ip_addr,
528		Tox_Err_Group_Peer_Query *_Nullable error);
529
530		#ifdef __cplusplus
531		} /* extern "C" */
532		#endif
533
534		#endif /* C_TOXCORE_TOXCORE_TOX_PRIVATE_H */