From 08d82dc75a406f4338548cdd8d16c2cf6ffdfb00 Mon Sep 17 00:00:00 2001 From: iphydf Date: Tue, 21 Dec 2021 19:37:13 +0000 Subject: [PATCH] cleanup: Sync comments in all `toxcore/*.[ch]`. --- toxcore/DHT.c | 16 ++++++--- toxcore/DHT.h | 13 ++++--- toxcore/TCP_client.c | 48 +++++++++++++------------- toxcore/TCP_client.h | 18 +++++----- toxcore/TCP_connection.c | 68 +++++++++++++++++++------------------ toxcore/TCP_connection.h | 36 ++++++++++---------- toxcore/TCP_server.c | 48 +++++++++++++------------- toxcore/TCP_server.h | 12 +++---- toxcore/crypto_core.c | 26 +++++++++----- toxcore/friend_connection.h | 2 +- toxcore/friend_requests.c | 9 +++-- toxcore/group.c | 4 +-- toxcore/group.h | 13 ++++--- toxcore/mono_time.c | 5 ++- toxcore/network.c | 7 ++-- toxcore/network.h | 19 +++++++---- toxcore/onion.h | 2 +- toxcore/onion_announce.c | 2 ++ toxcore/onion_client.c | 3 +- toxcore/onion_client.h | 8 ++--- toxcore/ping.h | 2 +- 21 files changed, 200 insertions(+), 161 deletions(-) diff --git a/toxcore/DHT.c b/toxcore/DHT.c index 30b0f162294..20f545622e6 100644 --- a/toxcore/DHT.c +++ b/toxcore/DHT.c @@ -395,6 +395,8 @@ int packed_node_size(Family ip_family) /** Packs an IP_Port structure into data of max size length. + * + * Packed_length is the offset of data currently packed. * * Returns size of packed IP_Port data on success * Return -1 on failure. @@ -473,6 +475,8 @@ static int dht_create_packet(const uint8_t public_key[CRYPTO_PUBLIC_KEY_SIZE], } /** Unpack IP_Port structure from data of max size length into ip_port. + * + * len_processed is the offset of data currently unpacked. * * Return size of unpacked ip_port on success. * Return -1 on failure. @@ -1464,7 +1468,7 @@ static bool sent_getnode_to_node(DHT *dht, const uint8_t *public_key, IP_Port no return true; } -/** Function is needed in following functions. */ +/* Function is needed in following functions. */ static int send_hardening_getnode_res(const DHT *dht, const Node_format *sendto, const uint8_t *queried_client_id, const uint8_t *nodes_data, uint16_t nodes_data_length); @@ -1873,7 +1877,7 @@ int dht_bootstrap_from_address(DHT *dht, const char *address, uint8_t ipv6enable return 0; } -/** Send the given packet to node with public_key +/** Send the given packet to node with public_key. * * return -1 if failure. */ @@ -2904,10 +2908,14 @@ void dht_save(const DHT *dht, uint8_t *data) free(clients); } -/* Bootstrap from this number of nodes every time dht_connect_after_load() is called */ +/** Bootstrap from this number of nodes every time dht_connect_after_load() is called */ #define SAVE_BOOTSTAP_FREQUENCY 8 -/** Start sending packets after DHT loaded_friends_list and loaded_clients_list are set */ +/** Start sending packets after DHT loaded_friends_list and loaded_clients_list are set. + * + * returns 0 if successful + * returns -1 otherwise + */ int dht_connect_after_load(DHT *dht) { if (dht == nullptr) { diff --git a/toxcore/DHT.h b/toxcore/DHT.h index 9bdf2b1314e..c92dc7c4d45 100644 --- a/toxcore/DHT.h +++ b/toxcore/DHT.h @@ -72,10 +72,12 @@ extern "C" { int create_request(const uint8_t *send_public_key, const uint8_t *send_secret_key, uint8_t *packet, const uint8_t *recv_public_key, const uint8_t *data, uint32_t length, uint8_t request_id); -/** puts the senders public key in the request in public_key, the data from the request +/** Puts the senders public key in the request in public_key, the data from the request * in data if a friend or ping request was sent to us and returns the length of the data. - * packet is the request packet and length is its length - * return -1 if not valid request. */ + * packet is the request packet and length is its length. + * + * return -1 if not valid request. + */ int handle_request(const uint8_t *self_public_key, const uint8_t *self_secret_key, uint8_t *public_key, uint8_t *data, uint8_t *request_id, const uint8_t *packet, uint16_t length); @@ -294,7 +296,7 @@ int dht_getfriendip(const DHT *dht, const uint8_t *public_key, IP_Port *ip_port) */ int id_closest(const uint8_t *pk, const uint8_t *pk1, const uint8_t *pk2); -/** +/*** * Add node to the node list making sure only the nodes closest to cmp_pk are in the list. * * @return true iff the node was added to the list. @@ -373,7 +375,8 @@ int route_packet(const DHT *dht, const uint8_t *public_key, const uint8_t *packe /** Send the following packet to everyone who tells us they are connected to friend_id. * - * return number of nodes it sent the packet to. + * return ip for friend. + * return number of nodes the packet was sent to. (Only works if more than (MAX_FRIEND_CLIENTS / 4). */ int route_tofriend(const DHT *dht, const uint8_t *friend_id, const uint8_t *packet, uint16_t length); diff --git a/toxcore/TCP_client.c b/toxcore/TCP_client.c index f95c59ebc8b..9899a93958b 100644 --- a/toxcore/TCP_client.c +++ b/toxcore/TCP_client.c @@ -100,7 +100,7 @@ void tcp_con_set_custom_uint(TCP_Client_Connection *con, uint32_t value) con->custom_uint = value; } -/* return 1 on success +/** return 1 on success * return 0 on failure */ static int connect_sock_to(Socket sock, IP_Port ip_port, const TCP_Proxy_Info *proxy_info) @@ -115,7 +115,7 @@ static int connect_sock_to(Socket sock, IP_Port ip_port, const TCP_Proxy_Info *p return 1; } -/* return 1 on success. +/** return 1 on success. * return 0 on failure. */ static int proxy_http_generate_connection_request(TCP_Client_Connection *tcp_conn) @@ -144,7 +144,7 @@ static int proxy_http_generate_connection_request(TCP_Client_Connection *tcp_con return 1; } -/* return 1 on success. +/** return 1 on success. * return 0 if no data received. * return -1 on failure (connection refused). */ @@ -186,7 +186,7 @@ static void proxy_socks5_generate_handshake(TCP_Client_Connection *tcp_conn) tcp_conn->last_packet_sent = 0; } -/* return 1 on success. +/** return 1 on success. * return 0 if no data received. * return -1 on failure (connection refused). */ @@ -232,7 +232,7 @@ static void proxy_socks5_generate_connection_request(TCP_Client_Connection *tcp_ tcp_conn->last_packet_sent = 0; } -/* return 1 on success. +/** return 1 on success. * return 0 if no data received. * return -1 on failure (connection refused). */ @@ -265,7 +265,7 @@ static int proxy_socks5_read_connection_response(const Logger *logger, TCP_Clien return -1; } -/* return 0 on success. +/** return 0 on success. * return -1 on failure. */ static int generate_handshake(TCP_Client_Connection *tcp_conn) @@ -288,7 +288,7 @@ static int generate_handshake(TCP_Client_Connection *tcp_conn) return 0; } -/* data must be of length TCP_SERVER_HANDSHAKE_SIZE +/** data must be of length TCP_SERVER_HANDSHAKE_SIZE * * return 0 on success. * return -1 on failure. @@ -309,7 +309,7 @@ static int handle_handshake(TCP_Client_Connection *tcp_conn, const uint8_t *data return 0; } -/* return 0 if pending data was sent completely +/** return 0 if pending data was sent completely * return -1 if it wasn't */ static int client_send_pending_data_nonpriority(TCP_Client_Connection *con) @@ -335,7 +335,7 @@ static int client_send_pending_data_nonpriority(TCP_Client_Connection *con) return -1; } -/* return 0 if pending data was sent completely +/** return 0 if pending data was sent completely * return -1 if it wasn't */ static int client_send_pending_data(TCP_Client_Connection *con) @@ -374,7 +374,7 @@ static int client_send_pending_data(TCP_Client_Connection *con) return -1; } -/* return 0 on failure (only if malloc fails) +/** return 0 on failure (only if malloc fails) * return 1 on success */ static bool client_add_priority(TCP_Client_Connection *con, const uint8_t *packet, uint16_t size, uint16_t sent) @@ -401,7 +401,7 @@ static bool client_add_priority(TCP_Client_Connection *con, const uint8_t *packe return 1; } -/* return 1 on success. +/** return 1 on success. * return 0 if could not send packet. * return -1 on failure (connection must be killed). */ @@ -466,7 +466,7 @@ static int write_packet_TCP_client_secure_connection(TCP_Client_Connection *con, return 1; } -/* return 1 on success. +/** return 1 on success. * return 0 if could not send packet. * return -1 on failure (connection must be killed). */ @@ -493,7 +493,7 @@ void routing_status_handler(TCP_Client_Connection *con, tcp_routing_status_cb *s static int tcp_send_ping_response(TCP_Client_Connection *con); static int tcp_send_ping_request(TCP_Client_Connection *con); -/* return 1 on success. +/** return 1 on success. * return 0 if could not send packet. * return -1 on failure. */ @@ -517,7 +517,7 @@ int send_data(TCP_Client_Connection *con, uint8_t con_id, const uint8_t *data, u return write_packet_TCP_client_secure_connection(con, packet, SIZEOF_VLA(packet), 0); } -/* return 1 on success. +/** return 1 on success. * return 0 if could not send packet. * return -1 on failure. */ @@ -535,7 +535,7 @@ int send_oob_packet(TCP_Client_Connection *con, const uint8_t *public_key, const } -/* Set the number that will be used as an argument in the callbacks related to con_id. +/** Set the number that will be used as an argument in the callbacks related to con_id. * * When not set by this function, the number is -1. * @@ -568,7 +568,7 @@ void oob_data_handler(TCP_Client_Connection *con, tcp_oob_data_cb *oob_data_call con->oob_data_callback_object = object; } -/* return 1 on success. +/** return 1 on success. * return 0 if could not send packet. * return -1 on failure (connection must be killed). */ @@ -580,7 +580,7 @@ static int client_send_disconnect_notification(TCP_Client_Connection *con, uint8 return write_packet_TCP_client_secure_connection(con, packet, sizeof(packet), 1); } -/* return 1 on success. +/** return 1 on success. * return 0 if could not send packet. * return -1 on failure (connection must be killed). */ @@ -602,7 +602,7 @@ static int tcp_send_ping_request(TCP_Client_Connection *con) return ret; } -/* return 1 on success. +/** return 1 on success. * return 0 if could not send packet. * return -1 on failure (connection must be killed). */ @@ -624,7 +624,7 @@ static int tcp_send_ping_response(TCP_Client_Connection *con) return ret; } -/* return 1 on success. +/** return 1 on success. * return 0 if could not send packet. * return -1 on failure (connection must be killed). */ @@ -639,7 +639,7 @@ int send_disconnect_request(TCP_Client_Connection *con, uint8_t con_id) return client_send_disconnect_notification(con, con_id + NUM_RESERVED_PORTS); } -/* return 1 on success. +/** return 1 on success. * return 0 if could not send packet. * return -1 on failure (connection must be killed). */ @@ -657,7 +657,7 @@ void onion_response_handler(TCP_Client_Connection *con, tcp_onion_response_cb *o con->onion_callback_object = object; } -/* Create new TCP connection to ip_port/public_key +/** Create new TCP connection to ip_port/public_key */ TCP_Client_Connection *new_TCP_connection(const Mono_Time *mono_time, IP_Port ip_port, const uint8_t *public_key, const uint8_t *self_public_key, const uint8_t *self_secret_key, const TCP_Proxy_Info *proxy_info) @@ -743,7 +743,7 @@ TCP_Client_Connection *new_TCP_connection(const Mono_Time *mono_time, IP_Port ip return temp; } -/* return 0 on success +/** return 0 on success * return -1 on failure */ static int handle_TCP_client_packet(TCP_Client_Connection *conn, const uint8_t *data, uint16_t length, void *userdata) @@ -955,7 +955,7 @@ static int do_confirmed_TCP(const Logger *logger, TCP_Client_Connection *conn, c return 0; } -/* Run the TCP connection +/** Run the TCP connection */ void do_TCP_connection(const Logger *logger, Mono_Time *mono_time, TCP_Client_Connection *tcp_connection, void *userdata) @@ -1042,7 +1042,7 @@ void do_TCP_connection(const Logger *logger, Mono_Time *mono_time, TCP_Client_Co } } -/* Kill the TCP connection +/** Kill the TCP connection */ void kill_TCP_connection(TCP_Client_Connection *tcp_connection) { diff --git a/toxcore/TCP_client.h b/toxcore/TCP_client.h index 82eb211a517..fed8b637380 100644 --- a/toxcore/TCP_client.h +++ b/toxcore/TCP_client.h @@ -47,23 +47,23 @@ uint32_t tcp_con_custom_uint(const TCP_Client_Connection *con); void tcp_con_set_custom_object(TCP_Client_Connection *con, void *object); void tcp_con_set_custom_uint(TCP_Client_Connection *con, uint32_t value); -/* Create new TCP connection to ip_port/public_key +/** Create new TCP connection to ip_port/public_key */ TCP_Client_Connection *new_TCP_connection(const Mono_Time *mono_time, IP_Port ip_port, const uint8_t *public_key, const uint8_t *self_public_key, const uint8_t *self_secret_key, const TCP_Proxy_Info *proxy_info); -/* Run the TCP connection +/** Run the TCP connection */ void do_TCP_connection(const Logger *logger, Mono_Time *mono_time, TCP_Client_Connection *tcp_connection, void *userdata); -/* Kill the TCP connection +/** Kill the TCP connection */ void kill_TCP_connection(TCP_Client_Connection *tcp_connection); typedef int tcp_onion_response_cb(void *object, const uint8_t *data, uint16_t length, void *userdata); -/* return 1 on success. +/** return 1 on success. * return 0 if could not send packet. * return -1 on failure (connection must be killed). */ @@ -73,7 +73,7 @@ void onion_response_handler(TCP_Client_Connection *con, tcp_onion_response_cb *o typedef int tcp_routing_response_cb(void *object, uint8_t connection_id, const uint8_t *public_key); typedef int tcp_routing_status_cb(void *object, uint32_t number, uint8_t connection_id, uint8_t status); -/* return 1 on success. +/** return 1 on success. * return 0 if could not send packet. * return -1 on failure (connection must be killed). */ @@ -81,13 +81,13 @@ int send_routing_request(TCP_Client_Connection *con, uint8_t *public_key); void routing_response_handler(TCP_Client_Connection *con, tcp_routing_response_cb *response_callback, void *object); void routing_status_handler(TCP_Client_Connection *con, tcp_routing_status_cb *status_callback, void *object); -/* return 1 on success. +/** return 1 on success. * return 0 if could not send packet. * return -1 on failure (connection must be killed). */ int send_disconnect_request(TCP_Client_Connection *con, uint8_t con_id); -/* Set the number that will be used as an argument in the callbacks related to con_id. +/** Set the number that will be used as an argument in the callbacks related to con_id. * * When not set by this function, the number is -1. * @@ -99,7 +99,7 @@ int set_tcp_connection_number(TCP_Client_Connection *con, uint8_t con_id, uint32 typedef int tcp_routing_data_cb(void *object, uint32_t number, uint8_t connection_id, const uint8_t *data, uint16_t length, void *userdata); -/* return 1 on success. +/** return 1 on success. * return 0 if could not send packet. * return -1 on failure. */ @@ -109,7 +109,7 @@ void routing_data_handler(TCP_Client_Connection *con, tcp_routing_data_cb *data_ typedef int tcp_oob_data_cb(void *object, const uint8_t *public_key, const uint8_t *data, uint16_t length, void *userdata); -/* return 1 on success. +/** return 1 on success. * return 0 if could not send packet. * return -1 on failure. */ diff --git a/toxcore/TCP_connection.c b/toxcore/TCP_connection.c index d2a70bf7a57..e128ca0fbf0 100644 --- a/toxcore/TCP_connection.c +++ b/toxcore/TCP_connection.c @@ -56,7 +56,7 @@ uint32_t tcp_connections_count(const TCP_Connections *tcp_c) return tcp_c->tcp_connections_length; } -/* Set the size of the array to num. +/** Set the size of the array to num. * * return -1 if realloc fails. * return 0 if it succeeds. @@ -141,7 +141,7 @@ static bool tcp_connections_number_is_valid(const TCP_Connections *tcp_c, int tc return true; } -/* Create a new empty connection. +/** Create a new empty connection. * * return -1 on failure. * return connections_number on success. @@ -165,7 +165,7 @@ static int create_connection(TCP_Connections *tcp_c) return id; } -/* Create a new empty tcp connection. +/** Create a new empty tcp connection. * * return -1 on failure. * return tcp_connections_number on success. @@ -189,7 +189,7 @@ static int create_tcp_connection(TCP_Connections *tcp_c) return id; } -/* Wipe a connection. +/** Wipe a connection. * * return -1 on failure. * return 0 on success. @@ -217,7 +217,7 @@ static int wipe_connection(TCP_Connections *tcp_c, int connections_number) return 0; } -/* Wipe a connection. +/** Wipe a connection. * * return -1 on failure. * return 0 on success. @@ -264,7 +264,7 @@ static TCP_con *get_tcp_connection(const TCP_Connections *tcp_c, int tcp_connect return &tcp_c->tcp_connections[tcp_connections_number]; } -/* Returns the number of connected TCP relays */ +/** Returns the number of connected TCP relays */ uint32_t tcp_connected_relays_count(const TCP_Connections *tcp_c) { uint32_t count = 0; @@ -284,7 +284,7 @@ uint32_t tcp_connected_relays_count(const TCP_Connections *tcp_c) return count; } -/* Send a packet to the TCP connection. +/** Send a packet to the TCP connection. * * return -1 on failure. * return 0 on success. @@ -365,7 +365,7 @@ int send_packet_tcp_connection(TCP_Connections *tcp_c, int connections_number, c return -1; } -/* Return a random TCP connection number for use in send_tcp_onion_request. +/** Return a random TCP connection number for use in send_tcp_onion_request. * * TODO(irungentoo): This number is just the index of an array that the elements * can change without warning. @@ -388,7 +388,7 @@ int get_random_tcp_onion_conn_number(TCP_Connections *tcp_c) return -1; } -/* Send an onion packet via the TCP relay corresponding to tcp_connections_number. +/** Send an onion packet via the TCP relay corresponding to tcp_connections_number. * * return 0 on success. * return -1 on failure. @@ -411,7 +411,7 @@ int tcp_send_onion_request(TCP_Connections *tcp_c, uint32_t tcp_connections_numb return -1; } -/* Send an oob packet via the TCP relay corresponding to tcp_connections_number. +/** Send an oob packet via the TCP relay corresponding to tcp_connections_number. * * return 0 on success. * return -1 on failure. @@ -440,7 +440,7 @@ int tcp_send_oob_packet(TCP_Connections *tcp_c, unsigned int tcp_connections_num static int find_tcp_connection_relay(TCP_Connections *tcp_c, const uint8_t *relay_pk); -/* Send an oob packet via the TCP relay corresponding to relay_pk. +/** Send an oob packet via the TCP relay corresponding to relay_pk. * * return 0 on success. * return -1 on failure. @@ -457,7 +457,7 @@ int tcp_send_oob_packet_using_relay(TCP_Connections *tcp_c, const uint8_t *relay return tcp_send_oob_packet(tcp_c, tcp_con_number, public_key, packet, length); } -/* Set the callback for TCP data packets. +/** Set the callback for TCP data packets. */ void set_packet_tcp_connection_callback(TCP_Connections *tcp_c, tcp_data_cb *tcp_data_callback, void *object) { @@ -465,7 +465,7 @@ void set_packet_tcp_connection_callback(TCP_Connections *tcp_c, tcp_data_cb *tcp tcp_c->tcp_data_callback_object = object; } -/* Set the callback for TCP onion packets. +/** Set the callback for TCP oob data packets. */ void set_oob_packet_tcp_connection_callback(TCP_Connections *tcp_c, tcp_oob_cb *tcp_oob_callback, void *object) { @@ -473,7 +473,7 @@ void set_oob_packet_tcp_connection_callback(TCP_Connections *tcp_c, tcp_oob_cb * tcp_c->tcp_oob_callback_object = object; } -/* Set the callback for TCP oob data packets. +/** Set the callback for TCP onion packets. */ void set_onion_packet_tcp_connection_callback(TCP_Connections *tcp_c, tcp_onion_cb *tcp_onion_callback, void *object) { @@ -481,7 +481,7 @@ void set_onion_packet_tcp_connection_callback(TCP_Connections *tcp_c, tcp_onion_ tcp_c->tcp_onion_callback_object = object; } -/* Find the TCP connection with public_key. +/** Find the TCP connection with public_key. * * return connections_number on success. * return -1 on failure. @@ -503,7 +503,7 @@ static int find_tcp_connection_to(TCP_Connections *tcp_c, const uint8_t *public_ return -1; } -/* Find the TCP connection to a relay with relay_pk. +/** Find the TCP connection to a relay with relay_pk. * * return connections_number on success. * return -1 on failure. @@ -529,7 +529,7 @@ static int find_tcp_connection_relay(TCP_Connections *tcp_c, const uint8_t *rela return -1; } -/* Create a new TCP connection to public_key. +/** Create a new TCP connection to public_key. * * public_key must be the counterpart to the secret key that the other peer used with new_tcp_connections(). * @@ -559,7 +559,7 @@ int new_tcp_connection_to(TCP_Connections *tcp_c, const uint8_t *public_key, int return connections_number; } -/* return 0 on success. +/** return 0 on success. * return -1 on failure. */ int kill_tcp_connection_to(TCP_Connections *tcp_c, int connections_number) @@ -598,7 +598,7 @@ int kill_tcp_connection_to(TCP_Connections *tcp_c, int connections_number) return wipe_connection(tcp_c, connections_number); } -/* Set connection status. +/** Set connection status. * * status of 1 means we are using the connection. * status of 0 means we are not using it. @@ -682,7 +682,7 @@ static bool tcp_connection_in_conn(TCP_Connection_to *con_to, unsigned int tcp_c return 0; } -/* return index on success. +/** return index on success. * return -1 on failure. */ static int add_tcp_connection_to_conn(TCP_Connection_to *con_to, unsigned int tcp_connections_number) @@ -705,7 +705,7 @@ static int add_tcp_connection_to_conn(TCP_Connection_to *con_to, unsigned int tc return -1; } -/* return index on success. +/** return index on success. * return -1 on failure. */ static int rm_tcp_connection_from_conn(TCP_Connection_to *con_to, unsigned int tcp_connections_number) @@ -724,7 +724,7 @@ static int rm_tcp_connection_from_conn(TCP_Connection_to *con_to, unsigned int t return -1; } -/* return number of online connections on success. +/** return number of online connections on success. * return -1 on failure. */ static unsigned int online_tcp_connection_from_conn(TCP_Connection_to *con_to) @@ -742,7 +742,7 @@ static unsigned int online_tcp_connection_from_conn(TCP_Connection_to *con_to) return count; } -/* return index on success. +/** return index on success. * return -1 on failure. */ static int set_tcp_connection_status(TCP_Connection_to *con_to, unsigned int tcp_connections_number, @@ -765,7 +765,7 @@ static int set_tcp_connection_status(TCP_Connection_to *con_to, unsigned int tcp return -1; } -/* Kill a TCP relay connection. +/** Kill a TCP relay connection. * * return 0 on success. * return -1 on failure. @@ -919,7 +919,7 @@ static int unsleep_tcp_relay_connection(TCP_Connections *tcp_c, int tcp_connecti return 0; } -/* Send a TCP routing request. +/** Send a TCP routing request. * * return 0 on success. * return -1 on failure. @@ -1088,7 +1088,7 @@ static int tcp_onion_callback(void *object, const uint8_t *data, uint16_t length return 0; } -/* Set callbacks for the TCP relay connection. +/** Set callbacks for the TCP relay connection. * * return 0 on success. * return -1 on failure. @@ -1186,7 +1186,7 @@ static int add_tcp_relay_instance(TCP_Connections *tcp_c, IP_Port ip_port, const return tcp_connections_number; } -/* Add a TCP relay to the TCP_Connections instance. +/** Add a TCP relay to the TCP_Connections instance. * * return 0 on success. * return -1 on failure. @@ -1206,7 +1206,9 @@ int add_tcp_relay_global(TCP_Connections *tcp_c, IP_Port ip_port, const uint8_t return 0; } -/* Add a TCP relay tied to a connection. +/** Add a TCP relay tied to a connection. + * + * NOTE: This can only be used during the tcp_oob_callback. * * return 0 on success. * return -1 on failure. @@ -1242,7 +1244,7 @@ int add_tcp_number_relay_connection(TCP_Connections *tcp_c, int connections_numb return 0; } -/* Add a TCP relay tied to a connection. +/** Add a TCP relay tied to a connection. * * This should be called with the same relay by two peers who want to create a TCP connection with each other. * @@ -1282,7 +1284,7 @@ int add_tcp_relay_connection(TCP_Connections *tcp_c, int connections_number, IP_ return 0; } -/* return number of online tcp relays tied to the connection on success. +/** return number of online tcp relays tied to the connection on success. * return 0 on failure. */ unsigned int tcp_connection_to_online_tcp_relays(TCP_Connections *tcp_c, int connections_number) @@ -1296,7 +1298,7 @@ unsigned int tcp_connection_to_online_tcp_relays(TCP_Connections *tcp_c, int con return online_tcp_connection_from_conn(con_to); } -/* Copy a maximum of max_num TCP relays we are connected to to tcp_relays. +/** Copy a maximum of max_num TCP relays we are connected to to tcp_relays. * NOTE that the family of the copied ip ports will be set to TCP_INET or TCP_INET6. * * return number of relays copied to tcp_relays on success. @@ -1333,7 +1335,7 @@ uint32_t tcp_copy_connected_relays(TCP_Connections *tcp_c, Node_format *tcp_rela return copied; } -/* Set if we want TCP_connection to allocate some connection for onion use. +/** Set if we want TCP_connection to allocate some connection for onion use. * * If status is 1, allocate some connections. if status is 0, don't. * @@ -1399,7 +1401,7 @@ int set_tcp_onion_status(TCP_Connections *tcp_c, bool status) return 0; } -/* Returns a new TCP_Connections object associated with the secret_key. +/** Returns a new TCP_Connections object associated with the secret_key. * * In order for others to connect to this instance new_tcp_connection_to() must be called with the * public_key associated with secret_key. diff --git a/toxcore/TCP_connection.h b/toxcore/TCP_connection.h index 7451d920142..d27b3e941db 100644 --- a/toxcore/TCP_connection.h +++ b/toxcore/TCP_connection.h @@ -72,17 +72,17 @@ const uint8_t *tcp_connections_public_key(const TCP_Connections *tcp_c); uint32_t tcp_connections_count(const TCP_Connections *tcp_c); -/* Returns the number of connected TCP relays */ +/** Returns the number of connected TCP relays */ uint32_t tcp_connected_relays_count(const TCP_Connections *tcp_c); -/* Send a packet to the TCP connection. +/** Send a packet to the TCP connection. * * return -1 on failure. * return 0 on success. */ int send_packet_tcp_connection(TCP_Connections *tcp_c, int connections_number, const uint8_t *packet, uint16_t length); -/* Return a random TCP connection number for use in send_tcp_onion_request. +/** Return a random TCP connection number for use in send_tcp_onion_request. * * TODO(irungentoo): This number is just the index of an array that the elements * can change without warning. @@ -92,7 +92,7 @@ int send_packet_tcp_connection(TCP_Connections *tcp_c, int connections_number, c */ int get_random_tcp_onion_conn_number(TCP_Connections *tcp_c); -/* Send an onion packet via the TCP relay corresponding to tcp_connections_number. +/** Send an onion packet via the TCP relay corresponding to tcp_connections_number. * * return 0 on success. * return -1 on failure. @@ -100,7 +100,7 @@ int get_random_tcp_onion_conn_number(TCP_Connections *tcp_c); int tcp_send_onion_request(TCP_Connections *tcp_c, unsigned int tcp_connections_number, const uint8_t *data, uint16_t length); -/* Set if we want TCP_connection to allocate some connection for onion use. +/** Set if we want TCP_connection to allocate some connection for onion use. * * If status is 1, allocate some connections. if status is 0, don't. * @@ -109,7 +109,7 @@ int tcp_send_onion_request(TCP_Connections *tcp_c, unsigned int tcp_connections_ */ int set_tcp_onion_status(TCP_Connections *tcp_c, bool status); -/* Send an oob packet via the TCP relay corresponding to tcp_connections_number. +/** Send an oob packet via the TCP relay corresponding to tcp_connections_number. * * return 0 on success. * return -1 on failure. @@ -122,24 +122,24 @@ typedef int tcp_data_cb(void *object, int id, const uint8_t *data, uint16_t leng int tcp_send_oob_packet_using_relay(TCP_Connections *tcp_c, const uint8_t *relay_pk, const uint8_t *public_key, const uint8_t *packet, uint16_t length); -/* Set the callback for TCP data packets. +/** Set the callback for TCP data packets. */ void set_packet_tcp_connection_callback(TCP_Connections *tcp_c, tcp_data_cb *tcp_data_callback, void *object); typedef int tcp_onion_cb(void *object, const uint8_t *data, uint16_t length, void *userdata); -/* Set the callback for TCP onion packets. +/** Set the callback for TCP onion packets. */ void set_onion_packet_tcp_connection_callback(TCP_Connections *tcp_c, tcp_onion_cb *tcp_onion_callback, void *object); typedef int tcp_oob_cb(void *object, const uint8_t *public_key, unsigned int tcp_connections_number, const uint8_t *data, uint16_t length, void *userdata); -/* Set the callback for TCP oob data packets. +/** Set the callback for TCP oob data packets. */ void set_oob_packet_tcp_connection_callback(TCP_Connections *tcp_c, tcp_oob_cb *tcp_oob_callback, void *object); -/* Create a new TCP connection to public_key. +/** Create a new TCP connection to public_key. * * public_key must be the counterpart to the secret key that the other peer used with new_tcp_connections(). * @@ -150,12 +150,12 @@ void set_oob_packet_tcp_connection_callback(TCP_Connections *tcp_c, tcp_oob_cb * */ int new_tcp_connection_to(TCP_Connections *tcp_c, const uint8_t *public_key, int id); -/* return 0 on success. +/** return 0 on success. * return -1 on failure. */ int kill_tcp_connection_to(TCP_Connections *tcp_c, int connections_number); -/* Set connection status. +/** Set connection status. * * status of 1 means we are using the connection. * status of 0 means we are not using it. @@ -167,12 +167,12 @@ int kill_tcp_connection_to(TCP_Connections *tcp_c, int connections_number); */ int set_tcp_connection_to_status(TCP_Connections *tcp_c, int connections_number, bool status); -/* return number of online tcp relays tied to the connection on success. +/** return number of online tcp relays tied to the connection on success. * return 0 on failure. */ unsigned int tcp_connection_to_online_tcp_relays(TCP_Connections *tcp_c, int connections_number); -/* Add a TCP relay tied to a connection. +/** Add a TCP relay tied to a connection. * * NOTE: This can only be used during the tcp_oob_callback. * @@ -182,7 +182,7 @@ unsigned int tcp_connection_to_online_tcp_relays(TCP_Connections *tcp_c, int con int add_tcp_number_relay_connection(TCP_Connections *tcp_c, int connections_number, unsigned int tcp_connections_number); -/* Add a TCP relay tied to a connection. +/** Add a TCP relay tied to a connection. * * This should be called with the same relay by two peers who want to create a TCP connection with each other. * @@ -192,14 +192,14 @@ int add_tcp_number_relay_connection(TCP_Connections *tcp_c, int connections_numb int add_tcp_relay_connection(TCP_Connections *tcp_c, int connections_number, IP_Port ip_port, const uint8_t *relay_pk); -/* Add a TCP relay to the instance. +/** Add a TCP relay to the TCP_Connections instance. * * return 0 on success. * return -1 on failure. */ int add_tcp_relay_global(TCP_Connections *tcp_c, IP_Port ip_port, const uint8_t *relay_pk); -/* Copy a maximum of max_num TCP relays we are connected to to tcp_relays. +/** Copy a maximum of max_num TCP relays we are connected to to tcp_relays. * NOTE that the family of the copied ip ports will be set to TCP_INET or TCP_INET6. * * return number of relays copied to tcp_relays on success. @@ -207,7 +207,7 @@ int add_tcp_relay_global(TCP_Connections *tcp_c, IP_Port ip_port, const uint8_t */ uint32_t tcp_copy_connected_relays(TCP_Connections *tcp_c, Node_format *tcp_relays, uint16_t max_num); -/* Returns a new TCP_Connections object associated with the secret_key. +/** Returns a new TCP_Connections object associated with the secret_key. * * In order for others to connect to this instance new_tcp_connection_to() must be called with the * public_key associated with secret_key. diff --git a/toxcore/TCP_server.c b/toxcore/TCP_server.c index c7b0db8e834..e978cdc6cd6 100644 --- a/toxcore/TCP_server.c +++ b/toxcore/TCP_server.c @@ -97,7 +97,7 @@ size_t tcp_server_listen_count(const TCP_Server *tcp_server) return tcp_server->num_listening_socks; } -/* This is needed to compile on Android below API 21 +/** This is needed to compile on Android below API 21 */ #ifdef TCP_SERVER_USE_EPOLL #ifndef EPOLLRDHUP @@ -105,7 +105,7 @@ size_t tcp_server_listen_count(const TCP_Server *tcp_server) #endif #endif -/* Increase the size of the connection list +/** Increase the size of the connection list * * return -1 on failure * return 0 on success. @@ -173,7 +173,7 @@ static void free_accepted_connection_array(TCP_Server *tcp_server) tcp_server->size_accepted_connections = 0; } -/* return index corresponding to connection with peer on success +/** return index corresponding to connection with peer on success * return -1 on failure. */ static int get_TCP_connection_index(const TCP_Server *tcp_server, const uint8_t *public_key) @@ -184,7 +184,7 @@ static int get_TCP_connection_index(const TCP_Server *tcp_server, const uint8_t static int kill_accepted(TCP_Server *tcp_server, int index); -/* Add accepted TCP connection to the list. +/** Add accepted TCP connection to the list. * * return index on success * return -1 on failure @@ -235,7 +235,7 @@ static int add_accepted(TCP_Server *tcp_server, const Mono_Time *mono_time, TCP_ return index; } -/* Delete accepted connection from list. +/** Delete accepted connection from list. * * return 0 on success * return -1 on failure @@ -264,7 +264,7 @@ static int del_accepted(TCP_Server *tcp_server, int index) return 0; } -/* Read the next two bytes in TCP stream then convert them to +/** Read the next two bytes in TCP stream then convert them to * length (host byte order). * * return length on success @@ -296,7 +296,7 @@ uint16_t read_TCP_length(const Logger *logger, Socket sock) return 0; } -/* Read length bytes from socket. +/** Read length bytes from socket. * * return length on success * return -1 on failure/no data in buffer. @@ -319,7 +319,7 @@ int read_TCP_packet(const Logger *logger, Socket sock, uint8_t *data, uint16_t l return -1; } -/* return length of received packet on success. +/** return length of received packet on success. * return 0 if could not read any packet. * return -1 on failure (connection must be killed). */ @@ -364,7 +364,7 @@ int read_packet_TCP_secure_connection(const Logger *logger, Socket sock, uint16_ return len; } -/* return 0 if pending data was sent completely +/** return 0 if pending data was sent completely * return -1 if it wasn't */ static int send_pending_data_nonpriority(TCP_Secure_Connection *con) @@ -390,7 +390,7 @@ static int send_pending_data_nonpriority(TCP_Secure_Connection *con) return -1; } -/* return 0 if pending data was sent completely +/** return 0 if pending data was sent completely * return -1 if it wasn't */ static int send_pending_data(TCP_Secure_Connection *con) @@ -429,7 +429,7 @@ static int send_pending_data(TCP_Secure_Connection *con) return -1; } -/* return 0 on failure (only if malloc fails) +/** return 0 on failure (only if malloc fails) * return 1 on success */ static bool add_priority(TCP_Secure_Connection *con, const uint8_t *packet, uint16_t size, uint16_t sent) @@ -456,7 +456,7 @@ static bool add_priority(TCP_Secure_Connection *con, const uint8_t *packet, uint return 1; } -/* return 1 on success. +/** return 1 on success. * return 0 if could not send packet. * return -1 on failure (connection must be killed). */ @@ -521,7 +521,7 @@ static int write_packet_TCP_secure_connection(TCP_Secure_Connection *con, const return 1; } -/* Kill a TCP_Secure_Connection +/** Kill a TCP_Secure_Connection */ static void kill_TCP_secure_connection(TCP_Secure_Connection *con) { @@ -531,7 +531,7 @@ static void kill_TCP_secure_connection(TCP_Secure_Connection *con) static int rm_connection_index(TCP_Server *tcp_server, TCP_Secure_Connection *con, uint8_t con_number); -/* Kill an accepted TCP_Secure_Connection +/** Kill an accepted TCP_Secure_Connection * * return -1 on failure. * return 0 on success. @@ -558,7 +558,7 @@ static int kill_accepted(TCP_Server *tcp_server, int index) return 0; } -/* return 1 if everything went well. +/** return 1 if everything went well. * return -1 if the connection must be killed. */ static int handle_TCP_handshake(TCP_Secure_Connection *con, const uint8_t *data, uint16_t length, @@ -615,7 +615,7 @@ static int handle_TCP_handshake(TCP_Secure_Connection *con, const uint8_t *data, return 1; } -/* return 1 if connection handshake was handled correctly. +/** return 1 if connection handshake was handled correctly. * return 0 if we didn't get it yet. * return -1 if the connection must be killed. */ @@ -631,7 +631,7 @@ static int read_connection_handshake(const Logger *logger, TCP_Secure_Connection return 0; } -/* return 1 on success. +/** return 1 on success. * return 0 if could not send packet. * return -1 on failure (connection must be killed). */ @@ -645,7 +645,7 @@ static int send_routing_response(TCP_Secure_Connection *con, uint8_t rpid, const return write_packet_TCP_secure_connection(con, data, sizeof(data), 1); } -/* return 1 on success. +/** return 1 on success. * return 0 if could not send packet. * return -1 on failure (connection must be killed). */ @@ -655,7 +655,7 @@ static int send_connect_notification(TCP_Secure_Connection *con, uint8_t id) return write_packet_TCP_secure_connection(con, data, sizeof(data), 1); } -/* return 1 on success. +/** return 1 on success. * return 0 if could not send packet. * return -1 on failure (connection must be killed). */ @@ -665,7 +665,7 @@ static int send_disconnect_notification(TCP_Secure_Connection *con, uint8_t id) return write_packet_TCP_secure_connection(con, data, sizeof(data), 1); } -/* return 0 on success. +/** return 0 on success. * return -1 on failure (connection must be killed). */ static int handle_TCP_routing_req(TCP_Server *tcp_server, uint32_t con_id, const uint8_t *public_key) @@ -747,7 +747,7 @@ static int handle_TCP_routing_req(TCP_Server *tcp_server, uint32_t con_id, const return 0; } -/* return 0 on success. +/** return 0 on success. * return -1 on failure (connection must be killed). */ static int handle_TCP_oob_send(TCP_Server *tcp_server, uint32_t con_id, const uint8_t *public_key, const uint8_t *data, @@ -773,7 +773,7 @@ static int handle_TCP_oob_send(TCP_Server *tcp_server, uint32_t con_id, const ui return 0; } -/* Remove connection with con_number from the connections array of con. +/** Remove connection with con_number from the connections array of con. * * return -1 on failure. * return 0 on success. @@ -836,7 +836,7 @@ static int handle_onion_recv_1(void *object, IP_Port dest, const uint8_t *data, return 0; } -/* return 0 on success +/** return 0 on success * return -1 on failure */ static int handle_TCP_packet(TCP_Server *tcp_server, uint32_t con_id, const uint8_t *data, uint16_t length) @@ -994,7 +994,7 @@ static int confirm_TCP_connection(TCP_Server *tcp_server, const Mono_Time *mono_ return index; } -/* return index on success +/** return index on success * return -1 on failure */ static int accept_connection(TCP_Server *tcp_server, Socket sock) diff --git a/toxcore/TCP_server.h b/toxcore/TCP_server.h index 46dd03304f1..b9e4a671aac 100644 --- a/toxcore/TCP_server.h +++ b/toxcore/TCP_server.h @@ -67,20 +67,20 @@ typedef struct TCP_Server TCP_Server; const uint8_t *tcp_server_public_key(const TCP_Server *tcp_server); size_t tcp_server_listen_count(const TCP_Server *tcp_server); -/* Create new TCP server instance. +/** Create new TCP server instance. */ TCP_Server *new_TCP_server(const Logger *logger, uint8_t ipv6_enabled, uint16_t num_sockets, const uint16_t *ports, const uint8_t *secret_key, Onion *onion); -/* Run the TCP_server +/** Run the TCP_server */ void do_TCP_server(TCP_Server *tcp_server, Mono_Time *mono_time); -/* Kill the TCP server +/** Kill the TCP server */ void kill_TCP_server(TCP_Server *tcp_server); -/* Read the next two bytes in TCP stream then convert them to +/** Read the next two bytes in TCP stream then convert them to * length (host byte order). * * return length on success @@ -89,14 +89,14 @@ void kill_TCP_server(TCP_Server *tcp_server); */ uint16_t read_TCP_length(const Logger *logger, Socket sock); -/* Read length bytes from socket. +/** Read length bytes from socket. * * return length on success * return -1 on failure/no data in buffer. */ int read_TCP_packet(const Logger *logger, Socket sock, uint8_t *data, uint16_t length); -/* return length of received packet on success. +/** return length of received packet on success. * return 0 if could not read any packet. * return -1 on failure (connection must be killed). */ diff --git a/toxcore/crypto_core.c b/toxcore/crypto_core.c index 620d363ce14..ba7301ecc12 100644 --- a/toxcore/crypto_core.c +++ b/toxcore/crypto_core.c @@ -113,10 +113,10 @@ bool public_key_valid(const uint8_t *public_key) return 1; } -/** Precomputes the shared key from their public_key and our secret_key. - * This way we can avoid an expensive elliptic curve scalar multiply for each - * encrypt/decrypt operation. - * shared_key has to be crypto_box_BEFORENMBYTES bytes long. +/** + * Fast encrypt/decrypt operations. Use if this is not a one-time communication. + * encrypt_precompute does the shared-key generation once so it does not have + * to be performed on every encrypt/decrypt. */ int32_t encrypt_precompute(const uint8_t *public_key, const uint8_t *secret_key, uint8_t *shared_key) @@ -228,7 +228,10 @@ int32_t decrypt_data(const uint8_t *public_key, const uint8_t *secret_key, const return ret; } -/** Increment the given nonce by 1. */ +/** + * Increment the given nonce by 1 in big endian (rightmost byte incremented + * first). + */ void increment_nonce(uint8_t *nonce) { /* TODO(irungentoo): use `increment_nonce_number(nonce, 1)` or @@ -248,7 +251,10 @@ void increment_nonce(uint8_t *nonce) } } -/** increment the given nonce by num */ +/** + * Increment the given nonce by a given number. The number should be in host + * byte order. + */ void increment_nonce_number(uint8_t *nonce, uint32_t increment) { /* NOTE don't use breaks inside this loop @@ -271,13 +277,17 @@ void increment_nonce_number(uint8_t *nonce, uint32_t increment) } } -/** Fill the given nonce with random bytes. */ +/** + * Fill the given nonce with random bytes. + */ void random_nonce(uint8_t *nonce) { random_bytes(nonce, crypto_box_NONCEBYTES); } -/** Fill a key CRYPTO_SYMMETRIC_KEY_SIZE big with random bytes */ +/** + * Fill a key CRYPTO_SYMMETRIC_KEY_SIZE big with random bytes. + */ void new_symmetric_key(uint8_t *key) { random_bytes(key, CRYPTO_SYMMETRIC_KEY_SIZE); diff --git a/toxcore/friend_connection.h b/toxcore/friend_connection.h index 23ccc116d13..49340edb468 100644 --- a/toxcore/friend_connection.h +++ b/toxcore/friend_connection.h @@ -143,7 +143,7 @@ typedef int fr_request_cb(void *object, const uint8_t *source_pubkey, const uint /** Set friend request callback. * - * This function will be called every time a friend request is received. + * This function will be called every time a friend request packet is received. */ void set_friend_request_callback(Friend_Connections *fr_c, fr_request_cb *fr_request_callback, void *object); diff --git a/toxcore/friend_requests.c b/toxcore/friend_requests.c index 40c16f26646..37dd8202fe4 100644 --- a/toxcore/friend_requests.c +++ b/toxcore/friend_requests.c @@ -47,7 +47,8 @@ uint32_t get_nospam(const Friend_Requests *fr) } -/** Set the function that will be executed when a friend request is received. */ +/** Set the function that will be executed when a friend request for us is received. + */ void callback_friendrequest(Friend_Requests *fr, fr_friend_request_cb *function, void *object) { fr->handle_friendrequest = function; @@ -55,7 +56,9 @@ void callback_friendrequest(Friend_Requests *fr, fr_friend_request_cb *function, fr->handle_friendrequest_object = object; } -/** Set the function used to check if a friend request should be displayed to the user or not. */ +/** Set the function used to check if a friend request should be displayed to the user or not. + * It must return 0 if the request is ok (anything else if it is bad.) + */ void set_filter_function(Friend_Requests *fr, filter_function_cb *function, void *userdata) { fr->filter_function = function; @@ -89,7 +92,7 @@ static bool request_received(const Friend_Requests *fr, const uint8_t *real_pk) return false; } -/** Remove real pk from received.requests list. +/** Remove real_pk from received_requests list. * * return 0 if it removed it successfully. * return -1 if it didn't find it. diff --git a/toxcore/group.c b/toxcore/group.c index d482a72e093..0f887ffeaba 100644 --- a/toxcore/group.c +++ b/toxcore/group.c @@ -1263,12 +1263,12 @@ int group_peername(const Group_Chats *g_c, uint32_t groupnumber, uint32_t peernu return peer->nick_len; } -/** Copy last active timestamp of frozennumber who is in groupnumber to +/** Copy last active timestamp of frozen peernumber who is in groupnumber to * last_active. * * return 0 on success. * return -1 if groupnumber is invalid. - * return -2 if frozennumber is invalid. + * return -2 if peernumber is invalid. */ int group_frozen_last_active(const Group_Chats *g_c, uint32_t groupnumber, uint32_t peernumber, uint64_t *last_active) diff --git a/toxcore/group.h b/toxcore/group.h index 7c1bd9d0464..89b084f9573 100644 --- a/toxcore/group.h +++ b/toxcore/group.h @@ -237,8 +237,7 @@ int add_groupchat(Group_Chats *g_c, uint8_t type); int del_groupchat(Group_Chats *g_c, uint32_t groupnumber, bool leave_permanently); /** Copy the public key of (frozen, if frozen is true) peernumber who is in - * groupnumber to pk. - * pk must be CRYPTO_PUBLIC_KEY_SIZE long. + * groupnumber to pk. pk must be CRYPTO_PUBLIC_KEY_SIZE long. * * return 0 on success * return -1 if groupnumber is invalid. @@ -255,8 +254,7 @@ int group_peer_pubkey(const Group_Chats *g_c, uint32_t groupnumber, uint32_t pee int group_peername_size(const Group_Chats *g_c, uint32_t groupnumber, uint32_t peernumber, bool frozen); /** Copy the name of (frozen, if frozen is true) peernumber who is in - * groupnumber to name. - * name must be at least MAX_NAME_LENGTH long. + * groupnumber to name. name must be at least MAX_NAME_LENGTH long. * * return length of name if success * return -1 if groupnumber is invalid. @@ -281,15 +279,16 @@ int group_frozen_last_active(const Group_Chats *g_c, uint32_t groupnumber, uint3 */ int group_set_max_frozen(const Group_Chats *g_c, uint32_t groupnumber, uint32_t maxfrozen); -/** invite friendnumber to groupnumber +/** invite friendnumber to groupnumber. * * return 0 on success. * return -1 if groupnumber is invalid. * return -2 if invite packet failed to send. + * return -3 if we are not connected to the group chat. */ int invite_friend(Group_Chats *g_c, uint32_t friendnumber, uint32_t groupnumber); -/** Join a group (you need to have been invited first.) +/** Join a group (we need to have been invited first.) * * expected_type is the groupchat type we expect the chat we are joining to * have. @@ -385,7 +384,7 @@ uint32_t copy_chatlist(const Group_Chats *g_c, uint32_t *out_list, uint32_t list */ int group_get_type(const Group_Chats *g_c, uint32_t groupnumber); -/** Copies the unique id of `group_chat[groupnumber]` into id. +/** Copies the unique id of `group_chat[groupnumber]` into `id`. * * return false on failure. * return true on success. diff --git a/toxcore/mono_time.c b/toxcore/mono_time.c index d50e3b7beaf..f6ee15ec230 100644 --- a/toxcore/mono_time.c +++ b/toxcore/mono_time.c @@ -198,7 +198,10 @@ void mono_time_set_current_time_callback(Mono_Time *mono_time, } } -/** return current monotonic time in milliseconds (ms). */ +/** + * Return current monotonic time in milliseconds (ms). The starting point is + * unspecified. + */ uint64_t current_time_monotonic(Mono_Time *mono_time) { /* For WIN32 we don't want to change overflow state of mono_time here */ diff --git a/toxcore/network.c b/toxcore/network.c index 9035d47f8b0..00be27476df 100644 --- a/toxcore/network.c +++ b/toxcore/network.c @@ -502,7 +502,10 @@ uint16_t net_port(const Networking_Core *net) return net->port; } -/** Basic network functions: +/* Basic network functions: + */ + +/** * Function to send packet(data) of length length to ip_port. */ int sendpacket(Networking_Core *net, IP_Port ip_port, const uint8_t *data, uint16_t length) @@ -988,7 +991,7 @@ Networking_Core *new_networking_no_udp(const Logger *log) return net; } -/** Function to cleanup networking stuff. */ +/** Function to cleanup networking stuff (doesn't do much right now). */ void kill_networking(Networking_Core *net) { if (!net) { diff --git a/toxcore/network.h b/toxcore/network.h index 727c590eae9..b3b8da246e1 100644 --- a/toxcore/network.h +++ b/toxcore/network.h @@ -272,9 +272,9 @@ void ip_init(IP *ip, bool ipv6enabled); bool ip_isset(const IP *ip); /** checks if ip is valid */ bool ipport_isset(const IP_Port *ipport); -/** copies an ip structure */ +/** copies an ip structure (careful about direction!) */ void ip_copy(IP *target, const IP *source); -/** copies an ip_port structure */ +/** copies an ip_port structure (careful about direction!) */ void ipport_copy(IP_Port *target, const IP_Port *source); /** @@ -364,7 +364,9 @@ bool set_socket_dualstack(Socket sock); /* Basic network functions: */ -/** Function to send packet(data) of length length to ip_port. */ +/** + * Function to send packet(data) of length length to ip_port. + */ int sendpacket(Networking_Core *net, IP_Port ip_port, const uint8_t *data, uint16_t length); /** Function to call when packet beginning with byte is received. */ @@ -431,16 +433,19 @@ const char *net_new_strerror(int error); void net_kill_strerror(const char *strerror); /** Initialize networking. - * bind to ip and port. + * Added for reverse compatibility with old new_networking calls. + */ +Networking_Core *new_networking(const Logger *log, IP ip, uint16_t port); +/** Initialize networking. + * Bind to ip and port. * ip must be in network order EX: 127.0.0.1 = (7F000001). * port is in host byte order (this means don't worry about it). * - * return Networking_Core object if no problems - * return NULL if there are problems. + * return Networking_Core object if no problems + * return NULL if there are problems. * * If error is non NULL it is set to 0 if no issues, 1 if socket related error, 2 if other. */ -Networking_Core *new_networking(const Logger *log, IP ip, uint16_t port); Networking_Core *new_networking_ex(const Logger *log, IP ip, uint16_t port_from, uint16_t port_to, unsigned int *error); Networking_Core *new_networking_no_udp(const Logger *log); diff --git a/toxcore/onion.h b/toxcore/onion.h index b09e2a0cdd0..2e15ea23ce0 100644 --- a/toxcore/onion.h +++ b/toxcore/onion.h @@ -79,7 +79,7 @@ typedef struct Onion_Path { */ int create_onion_path(const DHT *dht, Onion_Path *new_path, const Node_format *nodes); -/** Dump nodes in onion path to nodes of length num_nodes; +/** Dump nodes in onion path to nodes of length num_nodes. * * return -1 on failure. * return 0 on success. diff --git a/toxcore/onion_announce.c b/toxcore/onion_announce.c index dfcafcc08e5..5f4cd46aea9 100644 --- a/toxcore/onion_announce.c +++ b/toxcore/onion_announce.c @@ -197,6 +197,8 @@ int send_announce_request(Networking_Core *net, const Onion_Path *path, Node_for * * nonce is the nonce to encrypt this packet with * + * The maximum length of data is MAX_DATA_REQUEST_SIZE. + * * return -1 on failure. * return 0 on success. */ diff --git a/toxcore/onion_client.c b/toxcore/onion_client.c index e21dbdf3ead..c9f1dd3e5ea 100644 --- a/toxcore/onion_client.c +++ b/toxcore/onion_client.c @@ -1023,7 +1023,8 @@ static int handle_tcp_onion(void *object, const uint8_t *data, uint16_t length, } /** Send data of length length to friendnum. - * This data will be received by the friend using the onion_data_handlers callbacks. + * Maximum length of data is ONION_CLIENT_MAX_DATA_SIZE. + * This data will be received by the friend using the Onion_Data_Handlers callbacks. * * Even if this function succeeds, the friend might not receive any data. * diff --git a/toxcore/onion_client.h b/toxcore/onion_client.h index a0b8263566b..5ebf4c5b8c2 100644 --- a/toxcore/onion_client.h +++ b/toxcore/onion_client.h @@ -68,17 +68,17 @@ int onion_add_bs_path_node(Onion_Client *onion_c, IP_Port ip_port, const uint8_t */ uint16_t onion_backup_nodes(const Onion_Client *onion_c, Node_format *nodes, uint16_t max_num); -/** Add a friend who we want to connect to. +/** Get the friend_num of a friend. * * return -1 on failure. - * return the friend number on success or if the friend was already added. + * return friend number on success. */ int onion_friend_num(const Onion_Client *onion_c, const uint8_t *public_key); /** Add a friend who we want to connect to. * * return -1 on failure. - * return the friend number on success. + * return the friend number on success or if the friend was already added. */ int onion_addfriend(Onion_Client *onion_c, const uint8_t *public_key); @@ -135,7 +135,7 @@ typedef void onion_dht_pk_cb(void *data, int32_t number, const uint8_t *dht_publ int onion_dht_pk_callback(Onion_Client *onion_c, int friend_num, onion_dht_pk_cb *function, void *object, uint32_t number); -/** Set a friends DHT public key. +/** Set a friend's DHT public key. * * return -1 on failure. * return 0 on success. diff --git a/toxcore/ping.h b/toxcore/ping.h index c088c5a1dae..f117db8f280 100644 --- a/toxcore/ping.h +++ b/toxcore/ping.h @@ -22,7 +22,7 @@ Ping *ping_new(const struct Mono_Time *mono_time, DHT *dht); void ping_kill(Ping *ping); /** Add nodes to the to_ping list. - * All nodes in this list are pinged every TIME_TOPING seconds + * All nodes in this list are pinged every TIME_TO_PING seconds * and are then removed from the list. * If the list is full the nodes farthest from our public_key are replaced. * The purpose of this list is to enable quick integration of new nodes into the