From aebbfabe2601dea91a459dcc7efb30d68e6e156a Mon Sep 17 00:00:00 2001 From: Green Sky Date: Fri, 8 Mar 2024 11:08:22 +0100 Subject: [PATCH 01/13] cleanup: event length naming inconsistencies --- other/event_tooling/generate_event_c.cpp | 22 ++++++------- toxcore/events/group_custom_packet.c | 4 +-- toxcore/events/group_custom_private_packet.c | 4 +-- toxcore/events/group_invite.c | 4 +-- toxcore/events/group_message.c | 4 +-- toxcore/events/group_password.c | 4 +-- toxcore/events/group_peer_name.c | 4 +-- toxcore/events/group_private_message.c | 4 +-- toxcore/events/group_topic.c | 4 +-- toxcore/tox.h | 33 ++++++++++---------- 10 files changed, 44 insertions(+), 43 deletions(-) diff --git a/other/event_tooling/generate_event_c.cpp b/other/event_tooling/generate_event_c.cpp index de5e52ac8e..e5c0fd2a16 100644 --- a/other/event_tooling/generate_event_c.cpp +++ b/other/event_tooling/generate_event_c.cpp @@ -686,7 +686,7 @@ int main(int argc, char** argv) { { EventTypeTrivial{"uint32_t", "group_number"}, EventTypeTrivial{"uint32_t", "peer_id"}, - EventTypeByteRange{"name", "name_length", "length"}, // the latter two are ideally the same + EventTypeByteRange{"name", "name_length", "name_length"}, } }, { @@ -702,7 +702,7 @@ int main(int argc, char** argv) { { EventTypeTrivial{"uint32_t", "group_number"}, EventTypeTrivial{"uint32_t", "peer_id"}, - EventTypeByteRange{"topic", "topic_length", "length"}, // the latter two are ideally the same + EventTypeByteRange{"topic", "topic_length", "topic_length"}, } }, { @@ -737,7 +737,7 @@ int main(int argc, char** argv) { "Group_Password", { EventTypeTrivial{"uint32_t", "group_number"}, - EventTypeByteRange{"password", "password_length", "length"}, // the latter two are ideally the same + EventTypeByteRange{"password", "password_length", "password_length"}, } }, { @@ -746,7 +746,7 @@ int main(int argc, char** argv) { EventTypeTrivial{"uint32_t", "group_number"}, EventTypeTrivial{"uint32_t", "peer_id"}, EventTypeTrivial{"Tox_Message_Type", "type"}, - EventTypeByteRange{"message", "message_length", "length"}, // the latter two are ideally the same + EventTypeByteRange{"message", "message_length", "message_length"}, EventTypeTrivial{"uint32_t", "message_id"}, } }, @@ -756,7 +756,7 @@ int main(int argc, char** argv) { EventTypeTrivial{"uint32_t", "group_number"}, EventTypeTrivial{"uint32_t", "peer_id"}, EventTypeTrivial{"Tox_Message_Type", "type"}, - EventTypeByteRange{"message", "message_length", "length"}, // the latter two are ideally the same + EventTypeByteRange{"message", "message_length", "message_length"}, EventTypeTrivial{"uint32_t", "message_id"}, } }, @@ -765,7 +765,7 @@ int main(int argc, char** argv) { { EventTypeTrivial{"uint32_t", "group_number"}, EventTypeTrivial{"uint32_t", "peer_id"}, - EventTypeByteRange{"data", "data_length", "length"}, // the latter two are ideally the same + EventTypeByteRange{"data", "data_length", "data_length"}, } }, { @@ -773,15 +773,15 @@ int main(int argc, char** argv) { { EventTypeTrivial{"uint32_t", "group_number"}, EventTypeTrivial{"uint32_t", "peer_id"}, - EventTypeByteRange{"data", "data_length", "length"}, // the latter two are ideally the same + EventTypeByteRange{"data", "data_length", "data_length"}, } }, { "Group_Invite", { EventTypeTrivial{"uint32_t", "friend_number"}, - EventTypeByteRange{"invite_data", "invite_data_length", "length"}, // the latter two are ideally the same - EventTypeByteRange{"group_name", "group_name_length", "group_name_length"}, // they are :) + EventTypeByteRange{"invite_data", "invite_data_length", "invite_data_length"}, + EventTypeByteRange{"group_name", "group_name_length", "group_name_length"}, } }, { @@ -797,8 +797,8 @@ int main(int argc, char** argv) { EventTypeTrivial{"uint32_t", "group_number"}, EventTypeTrivial{"uint32_t", "peer_id"}, EventTypeTrivial{"Tox_Group_Exit_Type", "exit_type"}, - EventTypeByteRange{"name", "name_length", "name_length"}, // they are :) - EventTypeByteRange{"part_message", "part_message_length", "part_message_length"}, // they are :) + EventTypeByteRange{"name", "name_length", "name_length"}, + EventTypeByteRange{"part_message", "part_message_length", "part_message_length"}, } }, { diff --git a/toxcore/events/group_custom_packet.c b/toxcore/events/group_custom_packet.c index a82e2c3a6c..f7a879aa92 100644 --- a/toxcore/events/group_custom_packet.c +++ b/toxcore/events/group_custom_packet.c @@ -220,7 +220,7 @@ static Tox_Event_Group_Custom_Packet *tox_event_group_custom_packet_alloc(void * *****************************************************/ void tox_events_handle_group_custom_packet( - Tox *tox, uint32_t group_number, uint32_t peer_id, const uint8_t *data, size_t length, + Tox *tox, uint32_t group_number, uint32_t peer_id, const uint8_t *data, size_t data_length, void *user_data) { Tox_Event_Group_Custom_Packet *group_custom_packet = tox_event_group_custom_packet_alloc(user_data); @@ -231,5 +231,5 @@ void tox_events_handle_group_custom_packet( tox_event_group_custom_packet_set_group_number(group_custom_packet, group_number); tox_event_group_custom_packet_set_peer_id(group_custom_packet, peer_id); - tox_event_group_custom_packet_set_data(group_custom_packet, data, length); + tox_event_group_custom_packet_set_data(group_custom_packet, data, data_length); } diff --git a/toxcore/events/group_custom_private_packet.c b/toxcore/events/group_custom_private_packet.c index 56282f0fb8..751724c8ee 100644 --- a/toxcore/events/group_custom_private_packet.c +++ b/toxcore/events/group_custom_private_packet.c @@ -220,7 +220,7 @@ static Tox_Event_Group_Custom_Private_Packet *tox_event_group_custom_private_pac *****************************************************/ void tox_events_handle_group_custom_private_packet( - Tox *tox, uint32_t group_number, uint32_t peer_id, const uint8_t *data, size_t length, + Tox *tox, uint32_t group_number, uint32_t peer_id, const uint8_t *data, size_t data_length, void *user_data) { Tox_Event_Group_Custom_Private_Packet *group_custom_private_packet = tox_event_group_custom_private_packet_alloc(user_data); @@ -231,5 +231,5 @@ void tox_events_handle_group_custom_private_packet( tox_event_group_custom_private_packet_set_group_number(group_custom_private_packet, group_number); tox_event_group_custom_private_packet_set_peer_id(group_custom_private_packet, peer_id); - tox_event_group_custom_private_packet_set_data(group_custom_private_packet, data, length); + tox_event_group_custom_private_packet_set_data(group_custom_private_packet, data, data_length); } diff --git a/toxcore/events/group_invite.c b/toxcore/events/group_invite.c index 0691dcd1fe..c2035c18d1 100644 --- a/toxcore/events/group_invite.c +++ b/toxcore/events/group_invite.c @@ -248,7 +248,7 @@ static Tox_Event_Group_Invite *tox_event_group_invite_alloc(void *user_data) *****************************************************/ void tox_events_handle_group_invite( - Tox *tox, uint32_t friend_number, const uint8_t *invite_data, size_t length, const uint8_t *group_name, size_t group_name_length, + Tox *tox, uint32_t friend_number, const uint8_t *invite_data, size_t invite_data_length, const uint8_t *group_name, size_t group_name_length, void *user_data) { Tox_Event_Group_Invite *group_invite = tox_event_group_invite_alloc(user_data); @@ -258,6 +258,6 @@ void tox_events_handle_group_invite( } tox_event_group_invite_set_friend_number(group_invite, friend_number); - tox_event_group_invite_set_invite_data(group_invite, invite_data, length); + tox_event_group_invite_set_invite_data(group_invite, invite_data, invite_data_length); tox_event_group_invite_set_group_name(group_invite, group_name, group_name_length); } diff --git a/toxcore/events/group_message.c b/toxcore/events/group_message.c index a200f84566..d6b09eb29a 100644 --- a/toxcore/events/group_message.c +++ b/toxcore/events/group_message.c @@ -254,7 +254,7 @@ static Tox_Event_Group_Message *tox_event_group_message_alloc(void *user_data) *****************************************************/ void tox_events_handle_group_message( - Tox *tox, uint32_t group_number, uint32_t peer_id, Tox_Message_Type type, const uint8_t *message, size_t length, uint32_t message_id, + Tox *tox, uint32_t group_number, uint32_t peer_id, Tox_Message_Type type, const uint8_t *message, size_t message_length, uint32_t message_id, void *user_data) { Tox_Event_Group_Message *group_message = tox_event_group_message_alloc(user_data); @@ -266,6 +266,6 @@ void tox_events_handle_group_message( tox_event_group_message_set_group_number(group_message, group_number); tox_event_group_message_set_peer_id(group_message, peer_id); tox_event_group_message_set_type(group_message, type); - tox_event_group_message_set_message(group_message, message, length); + tox_event_group_message_set_message(group_message, message, message_length); tox_event_group_message_set_message_id(group_message, message_id); } diff --git a/toxcore/events/group_password.c b/toxcore/events/group_password.c index ad6e86b9d3..2e937e9a22 100644 --- a/toxcore/events/group_password.c +++ b/toxcore/events/group_password.c @@ -204,7 +204,7 @@ static Tox_Event_Group_Password *tox_event_group_password_alloc(void *user_data) *****************************************************/ void tox_events_handle_group_password( - Tox *tox, uint32_t group_number, const uint8_t *password, size_t length, + Tox *tox, uint32_t group_number, const uint8_t *password, size_t password_length, void *user_data) { Tox_Event_Group_Password *group_password = tox_event_group_password_alloc(user_data); @@ -214,5 +214,5 @@ void tox_events_handle_group_password( } tox_event_group_password_set_group_number(group_password, group_number); - tox_event_group_password_set_password(group_password, password, length); + tox_event_group_password_set_password(group_password, password, password_length); } diff --git a/toxcore/events/group_peer_name.c b/toxcore/events/group_peer_name.c index f8273e94b4..3d3722d73a 100644 --- a/toxcore/events/group_peer_name.c +++ b/toxcore/events/group_peer_name.c @@ -220,7 +220,7 @@ static Tox_Event_Group_Peer_Name *tox_event_group_peer_name_alloc(void *user_dat *****************************************************/ void tox_events_handle_group_peer_name( - Tox *tox, uint32_t group_number, uint32_t peer_id, const uint8_t *name, size_t length, + Tox *tox, uint32_t group_number, uint32_t peer_id, const uint8_t *name, size_t name_length, void *user_data) { Tox_Event_Group_Peer_Name *group_peer_name = tox_event_group_peer_name_alloc(user_data); @@ -231,5 +231,5 @@ void tox_events_handle_group_peer_name( tox_event_group_peer_name_set_group_number(group_peer_name, group_number); tox_event_group_peer_name_set_peer_id(group_peer_name, peer_id); - tox_event_group_peer_name_set_name(group_peer_name, name, length); + tox_event_group_peer_name_set_name(group_peer_name, name, name_length); } diff --git a/toxcore/events/group_private_message.c b/toxcore/events/group_private_message.c index a9efdd526c..807b2885e3 100644 --- a/toxcore/events/group_private_message.c +++ b/toxcore/events/group_private_message.c @@ -254,7 +254,7 @@ static Tox_Event_Group_Private_Message *tox_event_group_private_message_alloc(vo *****************************************************/ void tox_events_handle_group_private_message( - Tox *tox, uint32_t group_number, uint32_t peer_id, Tox_Message_Type type, const uint8_t *message, size_t length, uint32_t message_id, + Tox *tox, uint32_t group_number, uint32_t peer_id, Tox_Message_Type type, const uint8_t *message, size_t message_length, uint32_t message_id, void *user_data) { Tox_Event_Group_Private_Message *group_private_message = tox_event_group_private_message_alloc(user_data); @@ -266,6 +266,6 @@ void tox_events_handle_group_private_message( tox_event_group_private_message_set_group_number(group_private_message, group_number); tox_event_group_private_message_set_peer_id(group_private_message, peer_id); tox_event_group_private_message_set_type(group_private_message, type); - tox_event_group_private_message_set_message(group_private_message, message, length); + tox_event_group_private_message_set_message(group_private_message, message, message_length); tox_event_group_private_message_set_message_id(group_private_message, message_id); } diff --git a/toxcore/events/group_topic.c b/toxcore/events/group_topic.c index 23cdd5d354..9c95d01ae0 100644 --- a/toxcore/events/group_topic.c +++ b/toxcore/events/group_topic.c @@ -220,7 +220,7 @@ static Tox_Event_Group_Topic *tox_event_group_topic_alloc(void *user_data) *****************************************************/ void tox_events_handle_group_topic( - Tox *tox, uint32_t group_number, uint32_t peer_id, const uint8_t *topic, size_t length, + Tox *tox, uint32_t group_number, uint32_t peer_id, const uint8_t *topic, size_t topic_length, void *user_data) { Tox_Event_Group_Topic *group_topic = tox_event_group_topic_alloc(user_data); @@ -231,5 +231,5 @@ void tox_events_handle_group_topic( tox_event_group_topic_set_group_number(group_topic, group_number); tox_event_group_topic_set_peer_id(group_topic, peer_id); - tox_event_group_topic_set_topic(group_topic, topic, length); + tox_event_group_topic_set_topic(group_topic, topic, topic_length); } diff --git a/toxcore/tox.h b/toxcore/tox.h index af0bab858a..ae32401a6c 100644 --- a/toxcore/tox.h +++ b/toxcore/tox.h @@ -4094,11 +4094,11 @@ bool tox_group_peer_get_public_key( * @param group_number The group number of the group the name change is intended for. * @param peer_id The ID of the peer who has changed their name. * @param name The name data. - * @param length The length of the name. + * @param name_length The length of the name. */ typedef void tox_group_peer_name_cb( Tox *tox, Tox_Group_Number group_number, Tox_Group_Peer_Number peer_id, - const uint8_t name[], size_t length, void *user_data); + const uint8_t name[], size_t name_length, void *user_data); /** * Set the callback for the `group_peer_name` event. Pass NULL to unset. @@ -4235,11 +4235,11 @@ bool tox_group_get_topic( * @param peer_id The ID of the peer who changed the topic. If the peer who set the topic * is not present in our peer list this value will be set to 0. * @param topic The topic data. - * @param length The topic length. + * @param topic_length The topic length. */ typedef void tox_group_topic_cb( Tox *tox, Tox_Group_Number group_number, Tox_Group_Peer_Number peer_id, - const uint8_t topic[], size_t length, + const uint8_t topic[], size_t topic_length, void *user_data); /** @@ -4416,11 +4416,11 @@ bool tox_group_get_password( /** * @param group_number The group number of the group for which the password has changed. * @param password The new group password. - * @param length The length of the password. + * @param password_length The length of the password. */ typedef void tox_group_password_cb( Tox *tox, Tox_Group_Number group_number, - const uint8_t password[], size_t length, + const uint8_t password[], size_t password_length, void *user_data); /** @@ -4731,12 +4731,12 @@ bool tox_group_send_custom_private_packet(const Tox *tox, Tox_Group_Number group * @param peer_id The ID of the peer who sent the message. * @param type The type of message (normal, action, ...). * @param message The message data. + * @param message_length The length of the message. * @param message_id A pseudo message id that clients can use to uniquely identify this group message. - * @param length The length of the message. */ typedef void tox_group_message_cb( Tox *tox, Tox_Group_Number group_number, Tox_Group_Peer_Number peer_id, Tox_Message_Type type, - const uint8_t message[], size_t length, Tox_Group_Message_Id message_id, void *user_data); + const uint8_t message[], size_t message_length, Tox_Group_Message_Id message_id, void *user_data); /** * Set the callback for the `group_message` event. Pass NULL to unset. @@ -4749,11 +4749,12 @@ void tox_callback_group_message(Tox *tox, tox_group_message_cb *callback); * @param group_number The group number of the group the private message is intended for. * @param peer_id The ID of the peer who sent the private message. * @param message The message data. - * @param length The length of the message. + * @param message_length The length of the message. + * @param message_id A pseudo message id that clients can use to uniquely identify this group message. */ typedef void tox_group_private_message_cb( Tox *tox, Tox_Group_Number group_number, Tox_Group_Peer_Number peer_id, Tox_Message_Type type, - const uint8_t message[], size_t length, Tox_Group_Message_Id message_id, void *user_data); + const uint8_t message[], size_t message_length, Tox_Group_Message_Id message_id, void *user_data); /** * Set the callback for the `group_private_message` event. Pass NULL to unset. @@ -4766,11 +4767,11 @@ void tox_callback_group_private_message(Tox *tox, tox_group_private_message_cb * * @param group_number The group number of the group the packet is intended for. * @param peer_id The ID of the peer who sent the packet. * @param data The packet data. - * @param length The length of the data. + * @param data_length The length of the data. */ typedef void tox_group_custom_packet_cb( Tox *tox, Tox_Group_Number group_number, Tox_Group_Peer_Number peer_id, - const uint8_t data[], size_t length, void *user_data); + const uint8_t data[], size_t data_length, void *user_data); /** * Set the callback for the `group_custom_packet` event. Pass NULL to unset. @@ -4783,11 +4784,11 @@ void tox_callback_group_custom_packet(Tox *tox, tox_group_custom_packet_cb *call * @param group_number The group number of the group the packet is intended for. * @param peer_id The ID of the peer who sent the packet. * @param data The packet data. - * @param length The length of the data. + * @param data_length The length of the data. */ typedef void tox_group_custom_private_packet_cb( Tox *tox, Tox_Group_Number group_number, Tox_Group_Peer_Number peer_id, - const uint8_t data[], size_t length, void *user_data); + const uint8_t data[], size_t data_length, void *user_data); /** * Set the callback for the `group_custom_private_packet` event. Pass NULL to unset. @@ -4923,11 +4924,11 @@ Tox_Group_Number tox_group_invite_accept( /** * @param friend_number The friend number of the contact who sent the invite. * @param invite_data The invite data. - * @param length The length of invite_data. + * @param invite_data_length The length of invite_data. */ typedef void tox_group_invite_cb( Tox *tox, Tox_Friend_Number friend_number, - const uint8_t invite_data[], size_t length, + const uint8_t invite_data[], size_t invite_data_length, const uint8_t group_name[], size_t group_name_length, void *user_data); From 0199c0f17fd13b7f13ae6154a4f0629a47d4998e Mon Sep 17 00:00:00 2001 From: Green Sky Date: Fri, 8 Mar 2024 17:47:35 +0100 Subject: [PATCH 02/13] cleanup: apply the same scheme to types --- auto_tests/group_message_test.c | 2 +- other/event_tooling/generate_event_c.cpp | 4 ++-- toxcore/events/group_message.c | 20 ++++++++++---------- toxcore/events/group_private_message.c | 20 ++++++++++---------- toxcore/tox.c | 8 ++++---- toxcore/tox.h | 14 ++++++++------ toxcore/tox_events.h | 4 ++-- 7 files changed, 37 insertions(+), 35 deletions(-) diff --git a/auto_tests/group_message_test.c b/auto_tests/group_message_test.c index 608cebf844..380a994b56 100644 --- a/auto_tests/group_message_test.c +++ b/auto_tests/group_message_test.c @@ -284,7 +284,7 @@ static void group_private_message_handler(const Tox_Event_Group_Private_Message const uint32_t groupnumber = tox_event_group_private_message_get_group_number(event); const uint32_t peer_id = tox_event_group_private_message_get_peer_id(event); - const Tox_Message_Type type = tox_event_group_private_message_get_type(event); + const Tox_Message_Type type = tox_event_group_private_message_get_message_type(event); const uint8_t *message = tox_event_group_private_message_get_message(event); const size_t length = tox_event_group_private_message_get_message_length(event); const Tox_Group_Message_Id pseudo_msg_id = tox_event_group_private_message_get_message_id(event); diff --git a/other/event_tooling/generate_event_c.cpp b/other/event_tooling/generate_event_c.cpp index e5c0fd2a16..2ef1e056fa 100644 --- a/other/event_tooling/generate_event_c.cpp +++ b/other/event_tooling/generate_event_c.cpp @@ -745,7 +745,7 @@ int main(int argc, char** argv) { { EventTypeTrivial{"uint32_t", "group_number"}, EventTypeTrivial{"uint32_t", "peer_id"}, - EventTypeTrivial{"Tox_Message_Type", "type"}, + EventTypeTrivial{"Tox_Message_Type", "message_type"}, EventTypeByteRange{"message", "message_length", "message_length"}, EventTypeTrivial{"uint32_t", "message_id"}, } @@ -755,7 +755,7 @@ int main(int argc, char** argv) { { EventTypeTrivial{"uint32_t", "group_number"}, EventTypeTrivial{"uint32_t", "peer_id"}, - EventTypeTrivial{"Tox_Message_Type", "type"}, + EventTypeTrivial{"Tox_Message_Type", "message_type"}, EventTypeByteRange{"message", "message_length", "message_length"}, EventTypeTrivial{"uint32_t", "message_id"}, } diff --git a/toxcore/events/group_message.c b/toxcore/events/group_message.c index d6b09eb29a..96b6bce64c 100644 --- a/toxcore/events/group_message.c +++ b/toxcore/events/group_message.c @@ -27,7 +27,7 @@ struct Tox_Event_Group_Message { uint32_t group_number; uint32_t peer_id; - Tox_Message_Type type; + Tox_Message_Type message_type; uint8_t *message; uint32_t message_length; uint32_t message_id; @@ -60,16 +60,16 @@ uint32_t tox_event_group_message_get_peer_id(const Tox_Event_Group_Message *grou } non_null() -static void tox_event_group_message_set_type(Tox_Event_Group_Message *group_message, - Tox_Message_Type type) +static void tox_event_group_message_set_message_type(Tox_Event_Group_Message *group_message, + Tox_Message_Type message_type) { assert(group_message != nullptr); - group_message->type = type; + group_message->message_type = message_type; } -Tox_Message_Type tox_event_group_message_get_type(const Tox_Event_Group_Message *group_message) +Tox_Message_Type tox_event_group_message_get_message_type(const Tox_Event_Group_Message *group_message) { assert(group_message != nullptr); - return group_message->type; + return group_message->message_type; } non_null(1) nullable(2) @@ -143,7 +143,7 @@ bool tox_event_group_message_pack( return bin_pack_array(bp, 5) && bin_pack_u32(bp, event->group_number) && bin_pack_u32(bp, event->peer_id) - && tox_message_type_pack(event->type, bp) + && tox_message_type_pack(event->message_type, bp) && bin_pack_bin(bp, event->message, event->message_length) && bin_pack_u32(bp, event->message_id); } @@ -159,7 +159,7 @@ static bool tox_event_group_message_unpack_into( return bin_unpack_u32(bu, &event->group_number) && bin_unpack_u32(bu, &event->peer_id) - && tox_message_type_unpack(&event->type, bu) + && tox_message_type_unpack(&event->message_type, bu) && bin_unpack_bin(bu, &event->message, &event->message_length) && bin_unpack_u32(bu, &event->message_id); } @@ -254,7 +254,7 @@ static Tox_Event_Group_Message *tox_event_group_message_alloc(void *user_data) *****************************************************/ void tox_events_handle_group_message( - Tox *tox, uint32_t group_number, uint32_t peer_id, Tox_Message_Type type, const uint8_t *message, size_t message_length, uint32_t message_id, + Tox *tox, uint32_t group_number, uint32_t peer_id, Tox_Message_Type message_type, const uint8_t *message, size_t message_length, uint32_t message_id, void *user_data) { Tox_Event_Group_Message *group_message = tox_event_group_message_alloc(user_data); @@ -265,7 +265,7 @@ void tox_events_handle_group_message( tox_event_group_message_set_group_number(group_message, group_number); tox_event_group_message_set_peer_id(group_message, peer_id); - tox_event_group_message_set_type(group_message, type); + tox_event_group_message_set_message_type(group_message, message_type); tox_event_group_message_set_message(group_message, message, message_length); tox_event_group_message_set_message_id(group_message, message_id); } diff --git a/toxcore/events/group_private_message.c b/toxcore/events/group_private_message.c index 807b2885e3..ec40b2c18c 100644 --- a/toxcore/events/group_private_message.c +++ b/toxcore/events/group_private_message.c @@ -27,7 +27,7 @@ struct Tox_Event_Group_Private_Message { uint32_t group_number; uint32_t peer_id; - Tox_Message_Type type; + Tox_Message_Type message_type; uint8_t *message; uint32_t message_length; uint32_t message_id; @@ -60,16 +60,16 @@ uint32_t tox_event_group_private_message_get_peer_id(const Tox_Event_Group_Priva } non_null() -static void tox_event_group_private_message_set_type(Tox_Event_Group_Private_Message *group_private_message, - Tox_Message_Type type) +static void tox_event_group_private_message_set_message_type(Tox_Event_Group_Private_Message *group_private_message, + Tox_Message_Type message_type) { assert(group_private_message != nullptr); - group_private_message->type = type; + group_private_message->message_type = message_type; } -Tox_Message_Type tox_event_group_private_message_get_type(const Tox_Event_Group_Private_Message *group_private_message) +Tox_Message_Type tox_event_group_private_message_get_message_type(const Tox_Event_Group_Private_Message *group_private_message) { assert(group_private_message != nullptr); - return group_private_message->type; + return group_private_message->message_type; } non_null(1) nullable(2) @@ -143,7 +143,7 @@ bool tox_event_group_private_message_pack( return bin_pack_array(bp, 5) && bin_pack_u32(bp, event->group_number) && bin_pack_u32(bp, event->peer_id) - && tox_message_type_pack(event->type, bp) + && tox_message_type_pack(event->message_type, bp) && bin_pack_bin(bp, event->message, event->message_length) && bin_pack_u32(bp, event->message_id); } @@ -159,7 +159,7 @@ static bool tox_event_group_private_message_unpack_into( return bin_unpack_u32(bu, &event->group_number) && bin_unpack_u32(bu, &event->peer_id) - && tox_message_type_unpack(&event->type, bu) + && tox_message_type_unpack(&event->message_type, bu) && bin_unpack_bin(bu, &event->message, &event->message_length) && bin_unpack_u32(bu, &event->message_id); } @@ -254,7 +254,7 @@ static Tox_Event_Group_Private_Message *tox_event_group_private_message_alloc(vo *****************************************************/ void tox_events_handle_group_private_message( - Tox *tox, uint32_t group_number, uint32_t peer_id, Tox_Message_Type type, const uint8_t *message, size_t message_length, uint32_t message_id, + Tox *tox, uint32_t group_number, uint32_t peer_id, Tox_Message_Type message_type, const uint8_t *message, size_t message_length, uint32_t message_id, void *user_data) { Tox_Event_Group_Private_Message *group_private_message = tox_event_group_private_message_alloc(user_data); @@ -265,7 +265,7 @@ void tox_events_handle_group_private_message( tox_event_group_private_message_set_group_number(group_private_message, group_number); tox_event_group_private_message_set_peer_id(group_private_message, peer_id); - tox_event_group_private_message_set_type(group_private_message, type); + tox_event_group_private_message_set_message_type(group_private_message, message_type); tox_event_group_private_message_set_message(group_private_message, message, message_length); tox_event_group_private_message_set_message_id(group_private_message, message_id); } diff --git a/toxcore/tox.c b/toxcore/tox.c index 7943167a71..ebcb53bb41 100644 --- a/toxcore/tox.c +++ b/toxcore/tox.c @@ -3932,7 +3932,7 @@ bool tox_group_get_password(const Tox *tox, uint32_t group_number, uint8_t *pass } Tox_Group_Message_Id tox_group_send_message( - const Tox *tox, uint32_t group_number, Tox_Message_Type type, const uint8_t *message, + const Tox *tox, uint32_t group_number, Tox_Message_Type message_type, const uint8_t *message, size_t length, Tox_Err_Group_Send_Message *error) { assert(tox != nullptr); @@ -3953,7 +3953,7 @@ Tox_Group_Message_Id tox_group_send_message( } uint32_t message_id = 0; - const int ret = gc_send_message(chat, message, length, type, &message_id); + const int ret = gc_send_message(chat, message, length, message_type, &message_id); tox_unlock(tox); switch (ret) { @@ -3995,7 +3995,7 @@ Tox_Group_Message_Id tox_group_send_message( } Tox_Group_Message_Id tox_group_send_private_message(const Tox *tox, uint32_t group_number, uint32_t peer_id, - Tox_Message_Type type, const uint8_t *message, size_t length, Tox_Err_Group_Send_Private_Message *error) + Tox_Message_Type message_type, const uint8_t *message, size_t length, Tox_Err_Group_Send_Private_Message *error) { assert(tox != nullptr); @@ -4015,7 +4015,7 @@ Tox_Group_Message_Id tox_group_send_private_message(const Tox *tox, uint32_t gro } uint32_t message_id = 0; - const int ret = gc_send_private_message(chat, gc_peer_id_from_int(peer_id), type, message, length, &message_id); + const int ret = gc_send_private_message(chat, gc_peer_id_from_int(peer_id), message_type, message, length, &message_id); tox_unlock(tox); switch (ret) { diff --git a/toxcore/tox.h b/toxcore/tox.h index ae32401a6c..7aca21eab5 100644 --- a/toxcore/tox.h +++ b/toxcore/tox.h @@ -4493,7 +4493,7 @@ const char *tox_err_group_send_message_to_string(Tox_Err_Group_Send_Message valu * then reassemble the fragments. Messages may not be empty. * * @param group_number The group number of the group the message is intended for. - * @param type Message type (normal, action, ...). + * @param message_type Message type (normal, action, ...). * @param message A non-NULL pointer to the first element of a byte array * containing the message text. * @param length Length of the message to be sent. @@ -4502,7 +4502,7 @@ const char *tox_err_group_send_message_to_string(Tox_Err_Group_Send_Message valu * returned message ID value will be undefined. */ Tox_Group_Message_Id tox_group_send_message( - const Tox *tox, Tox_Group_Number group_number, Tox_Message_Type type, + const Tox *tox, Tox_Group_Number group_number, Tox_Message_Type message_type, const uint8_t message[], size_t length, Tox_Err_Group_Send_Message *error); @@ -4569,6 +4569,7 @@ const char *tox_err_group_send_private_message_to_string(Tox_Err_Group_Send_Priv * * @param group_number The group number of the group the message is intended for. * @param peer_id The ID of the peer the message is intended for. + * @param message_type The type of message (normal, action, ...). * @param message A non-NULL pointer to the first element of a byte array * containing the message text. * @param length Length of the message to be sent. @@ -4576,7 +4577,7 @@ const char *tox_err_group_send_private_message_to_string(Tox_Err_Group_Send_Priv * @return true on success. */ Tox_Group_Message_Id tox_group_send_private_message( - const Tox *tox, Tox_Group_Number group_number, Tox_Group_Peer_Number peer_id, Tox_Message_Type type, + const Tox *tox, Tox_Group_Number group_number, Tox_Group_Peer_Number peer_id, Tox_Message_Type message_type, const uint8_t message[], size_t length, Tox_Err_Group_Send_Private_Message *error); @@ -4729,13 +4730,13 @@ bool tox_group_send_custom_private_packet(const Tox *tox, Tox_Group_Number group /** * @param group_number The group number of the group the message is intended for. * @param peer_id The ID of the peer who sent the message. - * @param type The type of message (normal, action, ...). + * @param message_type The type of message (normal, action, ...). * @param message The message data. * @param message_length The length of the message. * @param message_id A pseudo message id that clients can use to uniquely identify this group message. */ typedef void tox_group_message_cb( - Tox *tox, Tox_Group_Number group_number, Tox_Group_Peer_Number peer_id, Tox_Message_Type type, + Tox *tox, Tox_Group_Number group_number, Tox_Group_Peer_Number peer_id, Tox_Message_Type message_type, const uint8_t message[], size_t message_length, Tox_Group_Message_Id message_id, void *user_data); /** @@ -4748,12 +4749,13 @@ void tox_callback_group_message(Tox *tox, tox_group_message_cb *callback); /** * @param group_number The group number of the group the private message is intended for. * @param peer_id The ID of the peer who sent the private message. + * @param message_type The type of message (normal, action, ...). * @param message The message data. * @param message_length The length of the message. * @param message_id A pseudo message id that clients can use to uniquely identify this group message. */ typedef void tox_group_private_message_cb( - Tox *tox, Tox_Group_Number group_number, Tox_Group_Peer_Number peer_id, Tox_Message_Type type, + Tox *tox, Tox_Group_Number group_number, Tox_Group_Peer_Number peer_id, Tox_Message_Type message_type, const uint8_t message[], size_t message_length, Tox_Group_Message_Id message_id, void *user_data); /** diff --git a/toxcore/tox_events.h b/toxcore/tox_events.h index 73068829e0..b69683e9c0 100644 --- a/toxcore/tox_events.h +++ b/toxcore/tox_events.h @@ -248,7 +248,7 @@ uint32_t tox_event_group_message_get_group_number( const Tox_Event_Group_Message *group_message); uint32_t tox_event_group_message_get_peer_id( const Tox_Event_Group_Message *group_message); -Tox_Message_Type tox_event_group_message_get_type( +Tox_Message_Type tox_event_group_message_get_message_type( const Tox_Event_Group_Message *group_message); const uint8_t *tox_event_group_message_get_message( const Tox_Event_Group_Message *group_message); @@ -262,7 +262,7 @@ uint32_t tox_event_group_private_message_get_group_number( const Tox_Event_Group_Private_Message *group_private_message); uint32_t tox_event_group_private_message_get_peer_id( const Tox_Event_Group_Private_Message *group_private_message); -Tox_Message_Type tox_event_group_private_message_get_type( +Tox_Message_Type tox_event_group_private_message_get_message_type( const Tox_Event_Group_Private_Message *group_private_message); const uint8_t *tox_event_group_private_message_get_message( const Tox_Event_Group_Private_Message *group_private_message); From 3e05824b80eb9bee33e8254cba0780d84c522182 Mon Sep 17 00:00:00 2001 From: iphydf Date: Wed, 6 Mar 2024 16:10:34 +0000 Subject: [PATCH 03/13] refactor: Rename `out` parameters to `out_$something`. In preparation for supporting `out` as a type qualifier in parameters. --- testing/BUILD.bazel | 1 + toxcore/Messenger.c | 12 ++--- toxcore/group_pack.c | 18 +++---- toxcore/group_pack.h | 4 +- toxcore/tox_event.c | 86 ++++++++++++++++----------------- toxcore/tox_unpack.c | 110 +++++++++++++++++++++---------------------- 6 files changed, 116 insertions(+), 115 deletions(-) diff --git a/testing/BUILD.bazel b/testing/BUILD.bazel index 41ba8338e6..4427347f16 100644 --- a/testing/BUILD.bazel +++ b/testing/BUILD.bazel @@ -14,6 +14,7 @@ sh_test( args = ["$(locations %s)" % f for f in CIMPLE_FILES] + [ "-Wno-boolean-return", "-Wno-callback-names", + "-Wno-enum-from-int", "+RTS", "-N4", "-RTS", diff --git a/toxcore/Messenger.c b/toxcore/Messenger.c index 947edef7e1..d20d740577 100644 --- a/toxcore/Messenger.c +++ b/toxcore/Messenger.c @@ -775,31 +775,31 @@ int m_set_statusmessage(Messenger *m, const uint8_t *status, uint16_t length) } non_null() -static bool userstatus_from_int(uint8_t status, Userstatus *out) +static bool userstatus_from_int(uint8_t status, Userstatus *out_enum) { switch (status) { case USERSTATUS_NONE: { - *out = USERSTATUS_NONE; + *out_enum = USERSTATUS_NONE; return true; } case USERSTATUS_AWAY: { - *out = USERSTATUS_AWAY; + *out_enum = USERSTATUS_AWAY; return true; } case USERSTATUS_BUSY: { - *out = USERSTATUS_BUSY; + *out_enum = USERSTATUS_BUSY; return true; } case USERSTATUS_INVALID: { - *out = USERSTATUS_INVALID; + *out_enum = USERSTATUS_INVALID; return true; } default: { - *out = USERSTATUS_INVALID; + *out_enum = USERSTATUS_INVALID; return false; } } diff --git a/toxcore/group_pack.c b/toxcore/group_pack.c index e3af82c67a..c20d6a1213 100644 --- a/toxcore/group_pack.c +++ b/toxcore/group_pack.c @@ -26,46 +26,46 @@ #include "network.h" #include "util.h" -bool group_privacy_state_from_int(uint8_t value, Group_Privacy_State *out) +bool group_privacy_state_from_int(uint8_t value, Group_Privacy_State *out_enum) { switch (value) { case GI_PUBLIC: { - *out = GI_PUBLIC; + *out_enum = GI_PUBLIC; return true; } case GI_PRIVATE: { - *out = GI_PRIVATE; + *out_enum = GI_PRIVATE; return true; } default: { - *out = GI_PUBLIC; + *out_enum = GI_PUBLIC; return false; } } } -bool group_voice_state_from_int(uint8_t value, Group_Voice_State *out) +bool group_voice_state_from_int(uint8_t value, Group_Voice_State *out_enum) { switch (value) { case GV_ALL: { - *out = GV_ALL; + *out_enum = GV_ALL; return true; } case GV_MODS: { - *out = GV_MODS; + *out_enum = GV_MODS; return true; } case GV_FOUNDER: { - *out = GV_FOUNDER; + *out_enum = GV_FOUNDER; return true; } default: { - *out = GV_ALL; + *out_enum = GV_ALL; return false; } } diff --git a/toxcore/group_pack.h b/toxcore/group_pack.h index 03252fb86d..4c999132db 100644 --- a/toxcore/group_pack.h +++ b/toxcore/group_pack.h @@ -34,8 +34,8 @@ non_null() bool gc_load_unpack_group(GC_Chat *chat, Bin_Unpack *bu); non_null() -bool group_privacy_state_from_int(uint8_t value, Group_Privacy_State *out); +bool group_privacy_state_from_int(uint8_t value, Group_Privacy_State *out_enum); non_null() -bool group_voice_state_from_int(uint8_t value, Group_Voice_State *out); +bool group_voice_state_from_int(uint8_t value, Group_Voice_State *out_enum); #endif /* C_TOXCORE_TOXCORE_GROUP_PACK_H */ diff --git a/toxcore/tox_event.c b/toxcore/tox_event.c index b0a65503cd..f702d629fc 100644 --- a/toxcore/tox_event.c +++ b/toxcore/tox_event.c @@ -725,216 +725,216 @@ bool tox_event_pack(const Tox_Event *event, Bin_Pack *bp) } non_null() -static bool tox_event_type_from_int(uint32_t value, Tox_Event_Type *out) +static bool tox_event_type_from_int(uint32_t value, Tox_Event_Type *out_enum) { switch (value) { case TOX_EVENT_SELF_CONNECTION_STATUS: { - *out = TOX_EVENT_SELF_CONNECTION_STATUS; + *out_enum = TOX_EVENT_SELF_CONNECTION_STATUS; return true; } case TOX_EVENT_FRIEND_REQUEST: { - *out = TOX_EVENT_FRIEND_REQUEST; + *out_enum = TOX_EVENT_FRIEND_REQUEST; return true; } case TOX_EVENT_FRIEND_CONNECTION_STATUS: { - *out = TOX_EVENT_FRIEND_CONNECTION_STATUS; + *out_enum = TOX_EVENT_FRIEND_CONNECTION_STATUS; return true; } case TOX_EVENT_FRIEND_LOSSY_PACKET: { - *out = TOX_EVENT_FRIEND_LOSSY_PACKET; + *out_enum = TOX_EVENT_FRIEND_LOSSY_PACKET; return true; } case TOX_EVENT_FRIEND_LOSSLESS_PACKET: { - *out = TOX_EVENT_FRIEND_LOSSLESS_PACKET; + *out_enum = TOX_EVENT_FRIEND_LOSSLESS_PACKET; return true; } case TOX_EVENT_FRIEND_NAME: { - *out = TOX_EVENT_FRIEND_NAME; + *out_enum = TOX_EVENT_FRIEND_NAME; return true; } case TOX_EVENT_FRIEND_STATUS: { - *out = TOX_EVENT_FRIEND_STATUS; + *out_enum = TOX_EVENT_FRIEND_STATUS; return true; } case TOX_EVENT_FRIEND_STATUS_MESSAGE: { - *out = TOX_EVENT_FRIEND_STATUS_MESSAGE; + *out_enum = TOX_EVENT_FRIEND_STATUS_MESSAGE; return true; } case TOX_EVENT_FRIEND_MESSAGE: { - *out = TOX_EVENT_FRIEND_MESSAGE; + *out_enum = TOX_EVENT_FRIEND_MESSAGE; return true; } case TOX_EVENT_FRIEND_READ_RECEIPT: { - *out = TOX_EVENT_FRIEND_READ_RECEIPT; + *out_enum = TOX_EVENT_FRIEND_READ_RECEIPT; return true; } case TOX_EVENT_FRIEND_TYPING: { - *out = TOX_EVENT_FRIEND_TYPING; + *out_enum = TOX_EVENT_FRIEND_TYPING; return true; } case TOX_EVENT_FILE_CHUNK_REQUEST: { - *out = TOX_EVENT_FILE_CHUNK_REQUEST; + *out_enum = TOX_EVENT_FILE_CHUNK_REQUEST; return true; } case TOX_EVENT_FILE_RECV: { - *out = TOX_EVENT_FILE_RECV; + *out_enum = TOX_EVENT_FILE_RECV; return true; } case TOX_EVENT_FILE_RECV_CHUNK: { - *out = TOX_EVENT_FILE_RECV_CHUNK; + *out_enum = TOX_EVENT_FILE_RECV_CHUNK; return true; } case TOX_EVENT_FILE_RECV_CONTROL: { - *out = TOX_EVENT_FILE_RECV_CONTROL; + *out_enum = TOX_EVENT_FILE_RECV_CONTROL; return true; } case TOX_EVENT_CONFERENCE_INVITE: { - *out = TOX_EVENT_CONFERENCE_INVITE; + *out_enum = TOX_EVENT_CONFERENCE_INVITE; return true; } case TOX_EVENT_CONFERENCE_CONNECTED: { - *out = TOX_EVENT_CONFERENCE_CONNECTED; + *out_enum = TOX_EVENT_CONFERENCE_CONNECTED; return true; } case TOX_EVENT_CONFERENCE_PEER_LIST_CHANGED: { - *out = TOX_EVENT_CONFERENCE_PEER_LIST_CHANGED; + *out_enum = TOX_EVENT_CONFERENCE_PEER_LIST_CHANGED; return true; } case TOX_EVENT_CONFERENCE_PEER_NAME: { - *out = TOX_EVENT_CONFERENCE_PEER_NAME; + *out_enum = TOX_EVENT_CONFERENCE_PEER_NAME; return true; } case TOX_EVENT_CONFERENCE_TITLE: { - *out = TOX_EVENT_CONFERENCE_TITLE; + *out_enum = TOX_EVENT_CONFERENCE_TITLE; return true; } case TOX_EVENT_CONFERENCE_MESSAGE: { - *out = TOX_EVENT_CONFERENCE_MESSAGE; + *out_enum = TOX_EVENT_CONFERENCE_MESSAGE; return true; } case TOX_EVENT_GROUP_PEER_NAME: { - *out = TOX_EVENT_GROUP_PEER_NAME; + *out_enum = TOX_EVENT_GROUP_PEER_NAME; return true; } case TOX_EVENT_GROUP_PEER_STATUS: { - *out = TOX_EVENT_GROUP_PEER_STATUS; + *out_enum = TOX_EVENT_GROUP_PEER_STATUS; return true; } case TOX_EVENT_GROUP_TOPIC: { - *out = TOX_EVENT_GROUP_TOPIC; + *out_enum = TOX_EVENT_GROUP_TOPIC; return true; } case TOX_EVENT_GROUP_PRIVACY_STATE: { - *out = TOX_EVENT_GROUP_PRIVACY_STATE; + *out_enum = TOX_EVENT_GROUP_PRIVACY_STATE; return true; } case TOX_EVENT_GROUP_VOICE_STATE: { - *out = TOX_EVENT_GROUP_VOICE_STATE; + *out_enum = TOX_EVENT_GROUP_VOICE_STATE; return true; } case TOX_EVENT_GROUP_TOPIC_LOCK: { - *out = TOX_EVENT_GROUP_TOPIC_LOCK; + *out_enum = TOX_EVENT_GROUP_TOPIC_LOCK; return true; } case TOX_EVENT_GROUP_PEER_LIMIT: { - *out = TOX_EVENT_GROUP_PEER_LIMIT; + *out_enum = TOX_EVENT_GROUP_PEER_LIMIT; return true; } case TOX_EVENT_GROUP_PASSWORD: { - *out = TOX_EVENT_GROUP_PASSWORD; + *out_enum = TOX_EVENT_GROUP_PASSWORD; return true; } case TOX_EVENT_GROUP_MESSAGE: { - *out = TOX_EVENT_GROUP_MESSAGE; + *out_enum = TOX_EVENT_GROUP_MESSAGE; return true; } case TOX_EVENT_GROUP_PRIVATE_MESSAGE: { - *out = TOX_EVENT_GROUP_PRIVATE_MESSAGE; + *out_enum = TOX_EVENT_GROUP_PRIVATE_MESSAGE; return true; } case TOX_EVENT_GROUP_CUSTOM_PACKET: { - *out = TOX_EVENT_GROUP_CUSTOM_PACKET; + *out_enum = TOX_EVENT_GROUP_CUSTOM_PACKET; return true; } case TOX_EVENT_GROUP_CUSTOM_PRIVATE_PACKET: { - *out = TOX_EVENT_GROUP_CUSTOM_PRIVATE_PACKET; + *out_enum = TOX_EVENT_GROUP_CUSTOM_PRIVATE_PACKET; return true; } case TOX_EVENT_GROUP_INVITE: { - *out = TOX_EVENT_GROUP_INVITE; + *out_enum = TOX_EVENT_GROUP_INVITE; return true; } case TOX_EVENT_GROUP_PEER_JOIN: { - *out = TOX_EVENT_GROUP_PEER_JOIN; + *out_enum = TOX_EVENT_GROUP_PEER_JOIN; return true; } case TOX_EVENT_GROUP_PEER_EXIT: { - *out = TOX_EVENT_GROUP_PEER_EXIT; + *out_enum = TOX_EVENT_GROUP_PEER_EXIT; return true; } case TOX_EVENT_GROUP_SELF_JOIN: { - *out = TOX_EVENT_GROUP_SELF_JOIN; + *out_enum = TOX_EVENT_GROUP_SELF_JOIN; return true; } case TOX_EVENT_GROUP_JOIN_FAIL: { - *out = TOX_EVENT_GROUP_JOIN_FAIL; + *out_enum = TOX_EVENT_GROUP_JOIN_FAIL; return true; } case TOX_EVENT_GROUP_MODERATION: { - *out = TOX_EVENT_GROUP_MODERATION; + *out_enum = TOX_EVENT_GROUP_MODERATION; return true; } case TOX_EVENT_DHT_GET_NODES_RESPONSE: { - *out = TOX_EVENT_DHT_GET_NODES_RESPONSE; + *out_enum = TOX_EVENT_DHT_GET_NODES_RESPONSE; return true; } case TOX_EVENT_INVALID: { - *out = TOX_EVENT_INVALID; + *out_enum = TOX_EVENT_INVALID; return true; } default: { - *out = TOX_EVENT_INVALID; + *out_enum = TOX_EVENT_INVALID; return false; } } diff --git a/toxcore/tox_unpack.c b/toxcore/tox_unpack.c index b5e05da872..5caef02c07 100644 --- a/toxcore/tox_unpack.c +++ b/toxcore/tox_unpack.c @@ -11,21 +11,21 @@ #include "tox.h" non_null() -static bool tox_conference_type_from_int(uint32_t value, Tox_Conference_Type *out) +static bool tox_conference_type_from_int(uint32_t value, Tox_Conference_Type *out_enum) { switch (value) { case TOX_CONFERENCE_TYPE_TEXT: { - *out = TOX_CONFERENCE_TYPE_TEXT; + *out_enum = TOX_CONFERENCE_TYPE_TEXT; return true; } case TOX_CONFERENCE_TYPE_AV: { - *out = TOX_CONFERENCE_TYPE_AV; + *out_enum = TOX_CONFERENCE_TYPE_AV; return true; } default: { - *out = TOX_CONFERENCE_TYPE_TEXT; + *out_enum = TOX_CONFERENCE_TYPE_TEXT; return false; } } @@ -38,26 +38,26 @@ bool tox_conference_type_unpack(Tox_Conference_Type *val, Bin_Unpack *bu) } non_null() -static bool tox_connection_from_int(uint32_t value, Tox_Connection *out) +static bool tox_connection_from_int(uint32_t value, Tox_Connection *out_enum) { switch (value) { case TOX_CONNECTION_NONE: { - *out = TOX_CONNECTION_NONE; + *out_enum = TOX_CONNECTION_NONE; return true; } case TOX_CONNECTION_TCP: { - *out = TOX_CONNECTION_TCP; + *out_enum = TOX_CONNECTION_TCP; return true; } case TOX_CONNECTION_UDP: { - *out = TOX_CONNECTION_UDP; + *out_enum = TOX_CONNECTION_UDP; return true; } default: { - *out = TOX_CONNECTION_NONE; + *out_enum = TOX_CONNECTION_NONE; return false; } } @@ -71,26 +71,26 @@ bool tox_connection_unpack(Tox_Connection *val, Bin_Unpack *bu) } non_null() -static bool tox_file_control_from_int(uint32_t value, Tox_File_Control *out) +static bool tox_file_control_from_int(uint32_t value, Tox_File_Control *out_enum) { switch (value) { case TOX_FILE_CONTROL_RESUME: { - *out = TOX_FILE_CONTROL_RESUME; + *out_enum = TOX_FILE_CONTROL_RESUME; return true; } case TOX_FILE_CONTROL_PAUSE: { - *out = TOX_FILE_CONTROL_PAUSE; + *out_enum = TOX_FILE_CONTROL_PAUSE; return true; } case TOX_FILE_CONTROL_CANCEL: { - *out = TOX_FILE_CONTROL_CANCEL; + *out_enum = TOX_FILE_CONTROL_CANCEL; return true; } default: { - *out = TOX_FILE_CONTROL_RESUME; + *out_enum = TOX_FILE_CONTROL_RESUME; return false; } } @@ -104,21 +104,21 @@ bool tox_file_control_unpack(Tox_File_Control *val, Bin_Unpack *bu) } non_null() -static bool tox_message_type_from_int(uint32_t value, Tox_Message_Type *out) +static bool tox_message_type_from_int(uint32_t value, Tox_Message_Type *out_enum) { switch (value) { case TOX_MESSAGE_TYPE_NORMAL: { - *out = TOX_MESSAGE_TYPE_NORMAL; + *out_enum = TOX_MESSAGE_TYPE_NORMAL; return true; } case TOX_MESSAGE_TYPE_ACTION: { - *out = TOX_MESSAGE_TYPE_ACTION; + *out_enum = TOX_MESSAGE_TYPE_ACTION; return true; } default: { - *out = TOX_MESSAGE_TYPE_NORMAL; + *out_enum = TOX_MESSAGE_TYPE_NORMAL; return false; } } @@ -132,26 +132,26 @@ bool tox_message_type_unpack(Tox_Message_Type *val, Bin_Unpack *bu) } non_null() -static bool tox_user_status_from_int(uint32_t value, Tox_User_Status *out) +static bool tox_user_status_from_int(uint32_t value, Tox_User_Status *out_enum) { switch (value) { case TOX_USER_STATUS_NONE: { - *out = TOX_USER_STATUS_NONE; + *out_enum = TOX_USER_STATUS_NONE; return true; } case TOX_USER_STATUS_AWAY: { - *out = TOX_USER_STATUS_AWAY; + *out_enum = TOX_USER_STATUS_AWAY; return true; } case TOX_USER_STATUS_BUSY: { - *out = TOX_USER_STATUS_BUSY; + *out_enum = TOX_USER_STATUS_BUSY; return true; } default: { - *out = TOX_USER_STATUS_NONE; + *out_enum = TOX_USER_STATUS_NONE; return false; } } @@ -165,19 +165,19 @@ bool tox_user_status_unpack(Tox_User_Status *val, Bin_Unpack *bu) } non_null() -static bool tox_group_privacy_state_from_int(uint32_t value, Tox_Group_Privacy_State *out) +static bool tox_group_privacy_state_from_int(uint32_t value, Tox_Group_Privacy_State *out_enum) { switch (value) { case TOX_GROUP_PRIVACY_STATE_PUBLIC: { - *out = TOX_GROUP_PRIVACY_STATE_PUBLIC; + *out_enum = TOX_GROUP_PRIVACY_STATE_PUBLIC; return true; } case TOX_GROUP_PRIVACY_STATE_PRIVATE: { - *out = TOX_GROUP_PRIVACY_STATE_PRIVATE; + *out_enum = TOX_GROUP_PRIVACY_STATE_PRIVATE; return true; } default: { - *out = TOX_GROUP_PRIVACY_STATE_PUBLIC; + *out_enum = TOX_GROUP_PRIVACY_STATE_PUBLIC; return false; } } @@ -189,23 +189,23 @@ bool tox_group_privacy_state_unpack(Tox_Group_Privacy_State *val, Bin_Unpack *bu && tox_group_privacy_state_from_int(u32, val); } non_null() -static bool tox_group_voice_state_from_int(uint32_t value, Tox_Group_Voice_State *out) +static bool tox_group_voice_state_from_int(uint32_t value, Tox_Group_Voice_State *out_enum) { switch (value) { case TOX_GROUP_VOICE_STATE_ALL: { - *out = TOX_GROUP_VOICE_STATE_ALL; + *out_enum = TOX_GROUP_VOICE_STATE_ALL; return true; } case TOX_GROUP_VOICE_STATE_MODERATOR: { - *out = TOX_GROUP_VOICE_STATE_MODERATOR; + *out_enum = TOX_GROUP_VOICE_STATE_MODERATOR; return true; } case TOX_GROUP_VOICE_STATE_FOUNDER: { - *out = TOX_GROUP_VOICE_STATE_FOUNDER; + *out_enum = TOX_GROUP_VOICE_STATE_FOUNDER; return true; } default: { - *out = TOX_GROUP_VOICE_STATE_ALL; + *out_enum = TOX_GROUP_VOICE_STATE_ALL; return false; } } @@ -218,19 +218,19 @@ bool tox_group_voice_state_unpack(Tox_Group_Voice_State *val, Bin_Unpack *bu) } non_null() -static bool tox_group_topic_lock_from_int(uint32_t value, Tox_Group_Topic_Lock *out) +static bool tox_group_topic_lock_from_int(uint32_t value, Tox_Group_Topic_Lock *out_enum) { switch (value) { case TOX_GROUP_TOPIC_LOCK_ENABLED: { - *out = TOX_GROUP_TOPIC_LOCK_ENABLED; + *out_enum = TOX_GROUP_TOPIC_LOCK_ENABLED; return true; } case TOX_GROUP_TOPIC_LOCK_DISABLED: { - *out = TOX_GROUP_TOPIC_LOCK_DISABLED; + *out_enum = TOX_GROUP_TOPIC_LOCK_DISABLED; return true; } default: { - *out = TOX_GROUP_TOPIC_LOCK_ENABLED; + *out_enum = TOX_GROUP_TOPIC_LOCK_ENABLED; return false; } } @@ -243,23 +243,23 @@ bool tox_group_topic_lock_unpack(Tox_Group_Topic_Lock *val, Bin_Unpack *bu) } non_null() -static bool tox_group_join_fail_from_int(uint32_t value, Tox_Group_Join_Fail *out) +static bool tox_group_join_fail_from_int(uint32_t value, Tox_Group_Join_Fail *out_enum) { switch (value) { case TOX_GROUP_JOIN_FAIL_PEER_LIMIT: { - *out = TOX_GROUP_JOIN_FAIL_PEER_LIMIT; + *out_enum = TOX_GROUP_JOIN_FAIL_PEER_LIMIT; return true; } case TOX_GROUP_JOIN_FAIL_INVALID_PASSWORD: { - *out = TOX_GROUP_JOIN_FAIL_INVALID_PASSWORD; + *out_enum = TOX_GROUP_JOIN_FAIL_INVALID_PASSWORD; return true; } case TOX_GROUP_JOIN_FAIL_UNKNOWN: { - *out = TOX_GROUP_JOIN_FAIL_UNKNOWN; + *out_enum = TOX_GROUP_JOIN_FAIL_UNKNOWN; return true; } default: { - *out = TOX_GROUP_JOIN_FAIL_PEER_LIMIT; + *out_enum = TOX_GROUP_JOIN_FAIL_PEER_LIMIT; return false; } } @@ -272,27 +272,27 @@ bool tox_group_join_fail_unpack(Tox_Group_Join_Fail *val, Bin_Unpack *bu) } non_null() -static bool tox_group_mod_event_from_int(uint32_t value, Tox_Group_Mod_Event *out) +static bool tox_group_mod_event_from_int(uint32_t value, Tox_Group_Mod_Event *out_enum) { switch (value) { case TOX_GROUP_MOD_EVENT_KICK: { - *out = TOX_GROUP_MOD_EVENT_KICK; + *out_enum = TOX_GROUP_MOD_EVENT_KICK; return true; } case TOX_GROUP_MOD_EVENT_OBSERVER: { - *out = TOX_GROUP_MOD_EVENT_OBSERVER; + *out_enum = TOX_GROUP_MOD_EVENT_OBSERVER; return true; } case TOX_GROUP_MOD_EVENT_USER: { - *out = TOX_GROUP_MOD_EVENT_USER; + *out_enum = TOX_GROUP_MOD_EVENT_USER; return true; } case TOX_GROUP_MOD_EVENT_MODERATOR: { - *out = TOX_GROUP_MOD_EVENT_MODERATOR; + *out_enum = TOX_GROUP_MOD_EVENT_MODERATOR; return true; } default: { - *out = TOX_GROUP_MOD_EVENT_KICK; + *out_enum = TOX_GROUP_MOD_EVENT_KICK; return false; } } @@ -305,35 +305,35 @@ bool tox_group_mod_event_unpack(Tox_Group_Mod_Event *val, Bin_Unpack *bu) } non_null() -static bool tox_group_exit_type_from_int(uint32_t value, Tox_Group_Exit_Type *out) +static bool tox_group_exit_type_from_int(uint32_t value, Tox_Group_Exit_Type *out_enum) { switch (value) { case TOX_GROUP_EXIT_TYPE_QUIT: { - *out = TOX_GROUP_EXIT_TYPE_QUIT; + *out_enum = TOX_GROUP_EXIT_TYPE_QUIT; return true; } case TOX_GROUP_EXIT_TYPE_TIMEOUT: { - *out = TOX_GROUP_EXIT_TYPE_TIMEOUT; + *out_enum = TOX_GROUP_EXIT_TYPE_TIMEOUT; return true; } case TOX_GROUP_EXIT_TYPE_DISCONNECTED: { - *out = TOX_GROUP_EXIT_TYPE_DISCONNECTED; + *out_enum = TOX_GROUP_EXIT_TYPE_DISCONNECTED; return true; } case TOX_GROUP_EXIT_TYPE_SELF_DISCONNECTED: { - *out = TOX_GROUP_EXIT_TYPE_SELF_DISCONNECTED; + *out_enum = TOX_GROUP_EXIT_TYPE_SELF_DISCONNECTED; return true; } case TOX_GROUP_EXIT_TYPE_KICK: { - *out = TOX_GROUP_EXIT_TYPE_KICK; + *out_enum = TOX_GROUP_EXIT_TYPE_KICK; return true; } case TOX_GROUP_EXIT_TYPE_SYNC_ERROR: { - *out = TOX_GROUP_EXIT_TYPE_SYNC_ERROR; + *out_enum = TOX_GROUP_EXIT_TYPE_SYNC_ERROR; return true; } default: { - *out = TOX_GROUP_EXIT_TYPE_QUIT; + *out_enum = TOX_GROUP_EXIT_TYPE_QUIT; return false; } } From ad4921dbaa2d8c98d9c3b89a113da244064f4d11 Mon Sep 17 00:00:00 2001 From: jfreegman Date: Mon, 11 Mar 2024 09:19:16 -0400 Subject: [PATCH 04/13] cleanup: A more descriptive error for group invite accept function --- toxcore/tox.c | 2 +- toxcore/tox.h | 4 ++-- toxcore/tox_api.c | 4 ++-- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/toxcore/tox.c b/toxcore/tox.c index ebcb53bb41..679f1d89fd 100644 --- a/toxcore/tox.c +++ b/toxcore/tox.c @@ -4269,7 +4269,7 @@ uint32_t tox_group_invite_accept(Tox *tox, uint32_t friend_number, const uint8_t } case -6: { - SET_ERROR_PARAMETER(error, TOX_ERR_GROUP_INVITE_ACCEPT_CORE); + SET_ERROR_PARAMETER(error, TOX_ERR_GROUP_INVITE_ACCEPT_FRIEND_NOT_FOUND); return UINT32_MAX; } diff --git a/toxcore/tox.h b/toxcore/tox.h index 7aca21eab5..d953bb6694 100644 --- a/toxcore/tox.h +++ b/toxcore/tox.h @@ -4888,9 +4888,9 @@ typedef enum Tox_Err_Group_Invite_Accept { TOX_ERR_GROUP_INVITE_ACCEPT_PASSWORD, /** - * There was a core error when initiating the group. + * The friend number passed did not designate a valid friend. */ - TOX_ERR_GROUP_INVITE_ACCEPT_CORE, + TOX_ERR_GROUP_INVITE_ACCEPT_FRIEND_NOT_FOUND, /** * Packet failed to send. diff --git a/toxcore/tox_api.c b/toxcore/tox_api.c index d2ac0f5953..26da9b2490 100644 --- a/toxcore/tox_api.c +++ b/toxcore/tox_api.c @@ -1451,8 +1451,8 @@ const char *tox_err_group_invite_accept_to_string(Tox_Err_Group_Invite_Accept va case TOX_ERR_GROUP_INVITE_ACCEPT_PASSWORD: return "TOX_ERR_GROUP_INVITE_ACCEPT_PASSWORD"; - case TOX_ERR_GROUP_INVITE_ACCEPT_CORE: - return "TOX_ERR_GROUP_INVITE_ACCEPT_CORE"; + case TOX_ERR_GROUP_INVITE_ACCEPT_FRIEND_NOT_FOUND: + return "TOX_ERR_GROUP_INVITE_ACCEPT_FRIEND_NOT_FOUND"; case TOX_ERR_GROUP_INVITE_ACCEPT_FAIL_SEND: return "TOX_ERR_GROUP_INVITE_ACCEPT_FAIL_SEND"; From 5c8aa65e41ef32ecc69763b75e24aa176dc2cada Mon Sep 17 00:00:00 2001 From: Maxim Biro Date: Sun, 10 Mar 2024 08:57:21 -0400 Subject: [PATCH 05/13] docs: Update user data API explanation There is no APIDSL so it shouldn't be mentioned, nor are there old style callbacks that take user data when registering them. --- toxcore/tox.h | 22 ++++++++-------------- 1 file changed, 8 insertions(+), 14 deletions(-) diff --git a/toxcore/tox.h b/toxcore/tox.h index d953bb6694..b5a3a98ed1 100644 --- a/toxcore/tox.h +++ b/toxcore/tox.h @@ -1,5 +1,5 @@ /* SPDX-License-Identifier: GPL-3.0-or-later - * Copyright © 2016-2018 The TokTok team. + * Copyright © 2016-2024 The TokTok team. * Copyright © 2013 Tox project. */ @@ -52,17 +52,9 @@ * event listeners, it needs to implement the dispatch functionality itself. * * The last argument to a callback is the user data pointer. It is passed from - * tox_iterate to each callback in sequence. - * - * The user data pointer is never stored or dereferenced by any library code, so - * can be any pointer, including NULL. Callbacks must all operate on the same - * object type. In the apidsl code (tox.in.h), this is denoted with `any`. The - * `any` in tox_iterate must be the same `any` as in all callbacks. In C, - * lacking parametric polymorphism, this is a pointer to void. - * - * Old style callbacks that are registered together with a user data pointer - * receive that pointer as argument when they are called. They can each have - * their own user data pointer of their own type. + * tox_iterate to each callback in sequence. The user data pointer is never + * stored or dereferenced by any library code, so can be any pointer, including + * NULL. * * @section threading Threading implications * @@ -1071,8 +1063,10 @@ void tox_callback_self_connection_status(Tox *tox, tox_self_connection_status_cb uint32_t tox_iteration_interval(const Tox *tox); /** - * @brief The main loop that needs to be run in intervals of `tox_iteration_interval()` - * milliseconds. + * @brief The main loop that needs to be run in intervals of + * `tox_iteration_interval()` milliseconds. + * @param user_data Any pointer a client wishes the Tox instance to pass into + * the event callbacks, including NULL. */ void tox_iterate(Tox *tox, void *user_data); From 419d783d95bfdb5e0fb1961817a9a2600581e261 Mon Sep 17 00:00:00 2001 From: Maxim Biro Date: Sun, 10 Mar 2024 09:09:40 -0400 Subject: [PATCH 06/13] docs: Public headers, tox -> Tox --- toxav/toxav.h | 18 +++++++++--------- toxcore/tox.h | 13 +++++++------ toxcore/tox_private.h | 4 ++-- 3 files changed, 18 insertions(+), 17 deletions(-) diff --git a/toxav/toxav.h b/toxav/toxav.h index 07d8d0eef7..cbbe611824 100644 --- a/toxav/toxav.h +++ b/toxav/toxav.h @@ -1,5 +1,5 @@ /* SPDX-License-Identifier: GPL-3.0-or-later - * Copyright © 2016-2018 The TokTok team. + * Copyright © 2016-2024 The TokTok team. * Copyright © 2013-2015 Tox project. */ @@ -24,22 +24,22 @@ * @section av_threading Threading implications * * Only toxav_iterate is thread-safe, all other functions must run from the - * tox thread. + * Tox thread. * * Important exceptions are the `*_iterate` and `*_iterate_interval` * functions. You have to choose either the single thread or the multi thread * functions and read their documentation. * * A common way to run ToxAV (multiple or single instance) is to have a thread, - * separate from tox instance thread, running a simple toxav_iterate loop, + * separate from Tox instance thread, running a simple toxav_iterate loop, * sleeping for `toxav_iteration_interval * milliseconds` on each iteration. * - * An important thing to note is that events are triggered from both tox and - * toxav thread (see above). Audio and video receive frame events are triggered - * from toxav thread while all the other events are triggered from tox thread. + * An important thing to note is that events are triggered from both Tox and + * ToxAV thread (see above). Audio and video receive frame events are triggered + * from ToxAV thread while all the other events are triggered from Tox thread. * * Tox thread has priority with mutex mechanisms. Any api function can - * fail if mutexes are held by tox thread in which case they will set SYNC + * fail if mutexes are held by Tox thread in which case they will set SYNC * error code. * * @subsection av_multi_threading Separate audio and video threads @@ -737,7 +737,7 @@ void toxav_callback_video_receive_frame(ToxAV *av, toxav_video_receive_frame_cb #ifndef APIGEN_IGNORE /*** - * NOTE Compatibility with old toxav group calls. TODO(iphydf): remove + * NOTE Compatibility with old ToxAV group calls. TODO(iphydf): remove * * TODO(iphydf): Use proper new API guidelines for these. E.g. don't use inline * function types, don't have per-callback userdata, especially don't have one @@ -751,7 +751,7 @@ typedef void toxav_group_audio_cb(Tox *tox, uint32_t groupnumber, uint32_t peern typedef void toxav_audio_data_cb(void *tox, uint32_t groupnumber, uint32_t peernumber, const int16_t pcm[], uint32_t samples, uint8_t channels, uint32_t sample_rate, void *userdata); -/** @brief Create a new toxav group. +/** @brief Create a new ToxAV group. * * @return group number on success. * @retval -1 on failure. diff --git a/toxcore/tox.h b/toxcore/tox.h index b5a3a98ed1..137f5cd6fb 100644 --- a/toxcore/tox.h +++ b/toxcore/tox.h @@ -642,7 +642,7 @@ struct Tox_Options { size_t savedata_length; /** - * Logging callback for the new tox instance. + * Logging callback for the new Tox instance. */ tox_log_cb *log_callback; @@ -905,7 +905,7 @@ Tox *tox_new(const Tox_Options *options, Tox_Err_New *error); void tox_kill(Tox *tox); /** - * @brief Calculates the number of bytes required to store the tox instance with + * @brief Calculates the number of bytes required to store the Tox instance with * tox_get_savedata. * * This function cannot fail. The result is always greater than 0. @@ -915,11 +915,12 @@ void tox_kill(Tox *tox); size_t tox_get_savedata_size(const Tox *tox); /** - * @brief Store all information associated with the tox instance to a byte array. + * @brief Store all information associated with the Tox instance to a byte + * array. * - * @param savedata A memory region large enough to store the tox instance - * data. Call tox_get_savedata_size to find the number of bytes required. If this parameter - * is NULL, this function has no effect. + * @param savedata A memory region large enough to store the Tox instance + * data. Call tox_get_savedata_size to find the number of bytes required. If + * this parameter is NULL, this function has no effect. */ void tox_get_savedata(const Tox *tox, uint8_t savedata[]); diff --git a/toxcore/tox_private.h b/toxcore/tox_private.h index d36ab026c3..604bd796a4 100644 --- a/toxcore/tox_private.h +++ b/toxcore/tox_private.h @@ -1,5 +1,5 @@ /* SPDX-License-Identifier: GPL-3.0-or-later - * Copyright © 2016-2020 The TokTok team. + * Copyright © 2016-2024 The TokTok team. * Copyright © 2013 Tox project. */ @@ -98,7 +98,7 @@ typedef enum Tox_Err_Dht_Get_Nodes { TOX_ERR_DHT_GET_NODES_OK, /** - * UDP is disabled in tox options; the DHT can only be queried when UDP is enabled. + * UDP is disabled in Tox options; the DHT can only be queried when UDP is enabled. */ TOX_ERR_DHT_GET_NODES_UDP_DISABLED, From be8a82a8183ef6289b73fb751f51f7ac0a939567 Mon Sep 17 00:00:00 2001 From: Maxim Biro Date: Sun, 10 Mar 2024 09:14:31 -0400 Subject: [PATCH 07/13] docs: Public headers, null -> NULL --- toxcore/tox.h | 12 ++++++------ toxcore/tox_private.h | 2 +- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/toxcore/tox.h b/toxcore/tox.h index 137f5cd6fb..9e3b951038 100644 --- a/toxcore/tox.h +++ b/toxcore/tox.h @@ -4071,8 +4071,8 @@ Tox_Connection tox_group_peer_get_connection_status(const Tox *tox, Tox_Group_Nu * This key will be permanently tied to a particular peer until they explicitly leave the group and is * the only way to reliably identify the same peer across client restarts. * - * `public_key` should have room for at least TOX_GROUP_PEER_PUBLIC_KEY_SIZE bytes. If `public_key` is null - * this function has no effect. + * `public_key` should have room for at least TOX_GROUP_PEER_PUBLIC_KEY_SIZE + * bytes. If `public_key` is NULL this function has no effect. * * @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. @@ -4449,7 +4449,7 @@ typedef enum Tox_Err_Group_Send_Message { TOX_ERR_GROUP_SEND_MESSAGE_TOO_LONG, /** - * The message pointer is null or length is zero. + * The message pointer is NULL or length is zero. */ TOX_ERR_GROUP_SEND_MESSAGE_EMPTY, @@ -4524,7 +4524,7 @@ typedef enum Tox_Err_Group_Send_Private_Message { TOX_ERR_GROUP_SEND_PRIVATE_MESSAGE_TOO_LONG, /** - * The message pointer is null or length is zero. + * The message pointer is NULL or length is zero. */ TOX_ERR_GROUP_SEND_PRIVATE_MESSAGE_EMPTY, @@ -4596,7 +4596,7 @@ typedef enum Tox_Err_Group_Send_Custom_Packet { TOX_ERR_GROUP_SEND_CUSTOM_PACKET_TOO_LONG, /** - * The message pointer is null or length is zero. + * The message pointer is NULL or length is zero. */ TOX_ERR_GROUP_SEND_CUSTOM_PACKET_EMPTY, @@ -4664,7 +4664,7 @@ typedef enum Tox_Err_Group_Send_Custom_Private_Packet { TOX_ERR_GROUP_SEND_CUSTOM_PRIVATE_PACKET_TOO_LONG, /** - * The message pointer is null or length is zero. + * The message pointer is NULL or length is zero. */ TOX_ERR_GROUP_SEND_CUSTOM_PRIVATE_PACKET_EMPTY, diff --git a/toxcore/tox_private.h b/toxcore/tox_private.h index 604bd796a4..92f30d092d 100644 --- a/toxcore/tox_private.h +++ b/toxcore/tox_private.h @@ -78,7 +78,7 @@ uint32_t tox_dht_node_public_key_size(void); /** * @param public_key The node's public key. - * @param ip The node's IP address, represented as a null terminated string. + * @param ip The node's IP address, represented as a 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, From 4c902955f32a34f137b741121318e63130ef6c18 Mon Sep 17 00:00:00 2001 From: Maxim Biro Date: Sun, 10 Mar 2024 09:24:19 -0400 Subject: [PATCH 08/13] docs: Public headers, 80 column width comments --- toxav/toxav.h | 108 ++-- toxcore/tox.h | 841 +++++++++++++++++++------------- toxcore/tox_private.h | 67 +-- toxencryptsave/toxencryptsave.c | 27 +- toxencryptsave/toxencryptsave.h | 32 +- 5 files changed, 625 insertions(+), 450 deletions(-) diff --git a/toxav/toxav.h b/toxav/toxav.h index cbbe611824..57a7ccf741 100644 --- a/toxav/toxav.h +++ b/toxav/toxav.h @@ -7,19 +7,20 @@ * @brief Public audio/video API for Tox clients. * * This API can handle multiple calls. Each call has its state, in very rare - * occasions the library can change the state of the call without apps knowledge. + * occasions the library can change the state of the call without apps + * knowledge. * * @section av_events Events and callbacks * * As in Core API, events are handled by callbacks. One callback can be * registered per event. All events have a callback function type named - * `toxav_{event}_cb` and a function to register it named `toxav_callback_{event}`. - * Passing a NULL callback will result in no callback being registered for that - * event. Only one callback per event can be registered, so if a client needs - * multiple event listeners, it needs to implement the dispatch functionality - * itself. Unlike Core API, lack of some event handlers will cause the the - * library to drop calls before they are started. Hanging up call from a - * callback causes undefined behaviour. + * `toxav_{event}_cb` and a function to register it named + * `toxav_callback_{event}`. Passing a NULL callback will result in no callback + * being registered for that event. Only one callback per event can be + * registered, so if a client needs multiple event listeners, it needs to + * implement the dispatch functionality itself. Unlike Core API, lack of some + * event handlers will cause the the library to drop calls before they are + * started. Hanging up call from a callback causes undefined behaviour. * * @section av_threading Threading implications * @@ -77,9 +78,9 @@ typedef struct Tox Tox; * * Each ToxAV instance can be bound to only one Tox instance, and Tox instance * can have only one ToxAV instance. One must make sure to close ToxAV instance - * prior closing Tox instance otherwise undefined behaviour occurs. Upon - * closing of ToxAV instance, all active calls will be forcibly terminated - * without notifying peers. + * prior closing Tox instance otherwise undefined behaviour occurs. Upon closing + * of ToxAV instance, all active calls will be forcibly terminated without + * notifying peers. */ typedef struct ToxAV ToxAV; @@ -100,8 +101,8 @@ typedef enum Toxav_Err_New { TOXAV_ERR_NEW_NULL, /** - * Memory allocation failure while trying to allocate structures required for - * the A/V session. + * Memory allocation failure while trying to allocate structures required + * for the A/V session. */ TOXAV_ERR_NEW_MALLOC, @@ -203,8 +204,8 @@ typedef enum Toxav_Err_Call { TOXAV_ERR_CALL_OK, /** - * A resource allocation error occurred while trying to create the structures - * required for the call. + * A resource allocation error occurred while trying to create the + * structures required for the call. */ TOXAV_ERR_CALL_MALLOC, @@ -246,9 +247,9 @@ typedef enum Toxav_Err_Call { * * @param friend_number The friend number of the friend that should be called. * @param audio_bit_rate Audio bit rate in Kb/sec. Set this to 0 to disable - * audio sending. + * audio sending. * @param video_bit_rate Video bit rate in Kb/sec. Set this to 0 to disable - * video sending. + * video sending. */ bool toxav_call(ToxAV *av, uint32_t friend_number, uint32_t audio_bit_rate, uint32_t video_bit_rate, Toxav_Err_Call *error); @@ -293,8 +294,9 @@ typedef enum Toxav_Err_Answer { TOXAV_ERR_ANSWER_FRIEND_NOT_FOUND, /** - * The friend was valid, but they are not currently trying to initiate a call. - * This is also returned if this client is already in a call with the friend. + * The friend was valid, but they are not currently trying to initiate a + * call. This is also returned if this client is already in a call with the + * friend. */ TOXAV_ERR_ANSWER_FRIEND_NOT_CALLING, @@ -314,9 +316,9 @@ typedef enum Toxav_Err_Answer { * * @param friend_number The friend number of the friend that is calling. * @param audio_bit_rate Audio bit rate in Kb/sec. Set this to 0 to disable - * audio sending. + * audio sending. * @param video_bit_rate Video bit rate in Kb/sec. Set this to 0 to disable - * video sending. + * video sending. */ bool toxav_answer(ToxAV *av, uint32_t friend_number, uint32_t audio_bit_rate, uint32_t video_bit_rate, Toxav_Err_Answer *error); @@ -337,8 +339,8 @@ enum Toxav_Friend_Call_State { /** * Set by the AV core if an error occurred on the remote end or if friend * timed out. This is the final state after which no more state - * transitions can occur for the call. This call state will never be triggered - * in combination with other call states. + * transitions can occur for the call. This call state will never be + * triggered in combination with other call states. */ TOXAV_FRIEND_CALL_STATE_ERROR = 1, @@ -376,9 +378,9 @@ enum Toxav_Friend_Call_State { * * @param friend_number The friend number for which the call state changed. * @param state The bitmask of the new call state which is guaranteed to be - * different than the previous state. The state is set to 0 when the call is - * paused. The bitmask represents all the activities currently performed by the - * friend. + * different than the previous state. The state is set to 0 when the call is + * paused. The bitmask represents all the activities currently performed by + * the friend. */ typedef void toxav_call_state_cb(ToxAV *av, uint32_t friend_number, uint32_t state, void *user_data); @@ -397,8 +399,9 @@ void toxav_callback_call_state(ToxAV *av, toxav_call_state_cb *callback, void *u typedef enum Toxav_Call_Control { /** - * Resume a previously paused call. Only valid if the pause was caused by this - * client, if not, this control is ignored. Not valid before the call is accepted. + * Resume a previously paused call. Only valid if the pause was caused by + * this client, if not, this control is ignored. Not valid before the call + * is accepted. */ TOXAV_CALL_CONTROL_RESUME, @@ -457,8 +460,8 @@ typedef enum Toxav_Err_Call_Control { TOXAV_ERR_CALL_CONTROL_FRIEND_NOT_FOUND, /** - * This client is currently not in a call with the friend. Before the call is - * answered, only CANCEL is a valid control. + * This client is currently not in a call with the friend. Before the call + * is answered, only CANCEL is a valid control. */ TOXAV_ERR_CALL_CONTROL_FRIEND_NOT_IN_CALL, @@ -474,7 +477,7 @@ typedef enum Toxav_Err_Call_Control { * Sends a call control command to a friend. * * @param friend_number The friend number of the friend this client is in a call - * with. + * with. * @param control The control command to send. * * @return true on success. @@ -530,8 +533,8 @@ typedef enum Toxav_Err_Send_Frame { TOXAV_ERR_SEND_FRAME_OK, /** - * In case of video, one of Y, U, or V was NULL. In case of audio, the samples - * data pointer was NULL. + * In case of video, one of Y, U, or V was NULL. In case of audio, the + * samples data pointer was NULL. */ TOXAV_ERR_SEND_FRAME_NULL, @@ -557,8 +560,8 @@ typedef enum Toxav_Err_Send_Frame { TOXAV_ERR_SEND_FRAME_INVALID, /** - * Either friend turned off audio or video receiving or we turned off sending - * for the said payload. + * Either friend turned off audio or video receiving or we turned off + * sending for the said payload. */ TOXAV_ERR_SEND_FRAME_PAYLOAD_TYPE_DISABLED, @@ -572,7 +575,8 @@ typedef enum Toxav_Err_Send_Frame { /** * Send an audio frame to a friend. * - * The expected format of the PCM data is: `[s1c1][s1c2][...][s2c1][s2c2][...]...` + * The expected format of the PCM data is: + * `[s1c1][s1c2][...][s2c1][s2c2][...]...` * Meaning: sample 1 for channel 1, sample 1 for channel 2, ... * For mono audio, this has no meaning, every sample is subsequent. For stereo, * this means the expected format is LRLRLR... with samples for left and right @@ -587,7 +591,7 @@ typedef enum Toxav_Err_Send_Frame { * 2.5, 5, 10, 20, 40 or 60 millseconds. * @param channels Number of audio channels. Supported values are 1 and 2. * @param sampling_rate Audio sampling rate used in this frame. Valid sampling - * rates are 8000, 12000, 16000, 24000, or 48000. + * rates are 8000, 12000, 16000, 24000, or 48000. */ bool toxav_audio_send_frame(ToxAV *av, uint32_t friend_number, const int16_t pcm[], size_t sample_count, uint8_t channels, uint32_t sampling_rate, Toxav_Err_Send_Frame *error); @@ -596,7 +600,7 @@ bool toxav_audio_send_frame(ToxAV *av, uint32_t friend_number, const int16_t pcm * Set the bit rate to be used in subsequent video frames. * * @param friend_number The friend number of the friend for which to set the - * bit rate. + * bit rate. * @param bit_rate The new audio bit rate in Kb/sec. Set to 0 to disable. * * @return true on success. @@ -609,7 +613,7 @@ bool toxav_audio_set_bit_rate(ToxAV *av, uint32_t friend_number, uint32_t bit_ra * point core suggests new bit rates. * * @param friend_number The friend number of the friend for which to set the - * bit rate. + * bit rate. * @param audio_bit_rate Suggested maximum audio bit rate in Kb/sec. */ typedef void toxav_audio_bit_rate_cb(ToxAV *av, uint32_t friend_number, uint32_t audio_bit_rate, void *user_data); @@ -628,7 +632,7 @@ void toxav_callback_audio_bit_rate(ToxAV *av, toxav_audio_bit_rate_cb *callback, * V - plane should be of size: `(height/2) * (width/2)` * * @param friend_number The friend number of the friend to which to send a video - * frame. + * frame. * @param width Width of the frame in pixels. * @param height Height of the frame in pixels. * @param y Y (Luminance) plane data. @@ -646,7 +650,7 @@ bool toxav_video_send_frame( * Set the bit rate to be used in subsequent video frames. * * @param friend_number The friend number of the friend for which to set the - * bit rate. + * bit rate. * @param bit_rate The new video bit rate in Kb/sec. Set to 0 to disable. * * @return true on success. @@ -659,7 +663,7 @@ bool toxav_video_set_bit_rate(ToxAV *av, uint32_t friend_number, uint32_t bit_ra * point core suggests new bit rates. * * @param friend_number The friend number of the friend for which to set the - * bit rate. + * bit rate. * @param video_bit_rate Suggested maximum video bit rate in Kb/sec. */ typedef void toxav_video_bit_rate_cb(ToxAV *av, uint32_t friend_number, uint32_t video_bit_rate, void *user_data); @@ -714,7 +718,6 @@ void toxav_callback_audio_receive_frame(ToxAV *av, toxav_audio_receive_frame_cb * @param y Luminosity plane. `Size = MAX(width, abs(ystride)) * height`. * @param u U chroma plane. `Size = MAX(width/2, abs(ustride)) * (height/2)`. * @param v V chroma plane. `Size = MAX(width/2, abs(vstride)) * (height/2)`. - * * @param ystride Luminosity plane stride. * @param ustride U chroma plane stride. * @param vstride V chroma plane stride. @@ -744,7 +747,8 @@ void toxav_callback_video_receive_frame(ToxAV *av, toxav_video_receive_frame_cb * userdata per group. */ -// TODO(iphydf): Use this better typed one instead of the void-pointer one below. +// TODO(iphydf): Use this better typed one instead of the void-pointer one +// below. typedef void toxav_group_audio_cb(Tox *tox, uint32_t groupnumber, uint32_t peernumber, const int16_t pcm[], uint32_t samples, uint8_t channels, uint32_t sample_rate, void *user_data); @@ -756,7 +760,8 @@ typedef void toxav_audio_data_cb(void *tox, uint32_t groupnumber, uint32_t peern * @return group number on success. * @retval -1 on failure. * - * Note that total size of pcm in bytes is equal to `samples * channels * sizeof(int16_t)`. + * Note that total size of pcm in bytes is equal to + * `samples * channels * sizeof(int16_t)`. */ int32_t toxav_add_av_groupchat(Tox *tox, toxav_audio_data_cb *audio_callback, void *userdata); @@ -765,7 +770,8 @@ int32_t toxav_add_av_groupchat(Tox *tox, toxav_audio_data_cb *audio_callback, vo * @return group number on success. * @retval -1 on failure. * - * Note that total size of pcm in bytes is equal to `samples * channels * sizeof(int16_t)`. + * Note that total size of pcm in bytes is equal to + * `samples * channels * sizeof(int16_t)`. */ int32_t toxav_join_av_groupchat( Tox *tox, uint32_t friendnumber, const uint8_t data[], uint16_t length, @@ -776,7 +782,8 @@ int32_t toxav_join_av_groupchat( * @retval 0 on success. * @retval -1 on failure. * - * Note that total size of pcm in bytes is equal to `samples * channels * sizeof(int16_t)`. + * Note that total size of pcm in bytes is equal to + * `samples * channels * sizeof(int16_t)`. * * Valid number of samples are `(sample rate) * (audio length) / 1000` * (Valid values for audio length are: 2.5, 5, 10, 20, 40 or 60 ms) @@ -794,15 +801,16 @@ int32_t toxav_group_send_audio( * A/V must be enabled on a groupchat for audio to be sent to it and for * received audio to be handled. * - * An A/V group created with `toxav_add_av_groupchat` or `toxav_join_av_groupchat` - * will start with A/V enabled. + * An A/V group created with `toxav_add_av_groupchat` or + * `toxav_join_av_groupchat` will start with A/V enabled. * * An A/V group loaded from a savefile will start with A/V disabled. * * @retval 0 on success. * @retval -1 on failure. * - * Note that total size of pcm in bytes is equal to `samples * channels * sizeof(int16_t)`. + * Note that total size of pcm in bytes is equal to + * `samples * channels * sizeof(int16_t)`. */ int32_t toxav_groupchat_enable_av( Tox *tox, uint32_t groupnumber, diff --git a/toxcore/tox.h b/toxcore/tox.h index 9e3b951038..b74071a326 100644 --- a/toxcore/tox.h +++ b/toxcore/tox.h @@ -25,9 +25,8 @@ * could not perform any operation, because one of the required parameters was * NULL. Some functions operate correctly or are defined as effectless on NULL. * - * Some functions additionally return a value outside their - * return type domain, or a bool containing true on success and false on - * failure. + * Some functions additionally return a value outside their return type domain, + * or a bool containing true on success and false on failure. * * All functions that take a Tox instance pointer will cause undefined behaviour * when passed a NULL Tox pointer. @@ -465,7 +464,8 @@ typedef enum Tox_Log_Level { TOX_LOG_LEVEL_WARNING, /** - * Severe unexpected errors caused by external or events_alloc inconsistency. + * Severe unexpected errors caused by external or events_alloc + * inconsistency. */ TOX_LOG_LEVEL_ERROR, @@ -474,7 +474,8 @@ typedef enum Tox_Log_Level { const char *tox_log_level_to_string(Tox_Log_Level value); /** - * @brief This event is triggered when the toxcore library logs an events_alloc message. + * @brief This event is triggered when the toxcore library logs an events_alloc + * message. * * This is mostly useful for debugging. This callback can be called from any * function, not just tox_iterate. This means the user data lifetime must at @@ -538,7 +539,8 @@ struct Tox_Options { * Enable the use of UDP communication when available. * * Setting this to false will force Tox to use TCP only. Communications will - * need to be relayed through a TCP relay node, potentially slowing them down. + * need to be relayed through a TCP relay node, potentially slowing them + * down. * * If a proxy is enabled, UDP will be disabled if either toxcore or the * proxy don't support proxying UDP messages. @@ -568,10 +570,11 @@ struct Tox_Options { * The IP address or DNS name of the proxy to be used. * * If used, this must be non-NULL and be a valid DNS name. The name must not - * exceed TOX_MAX_HOSTNAME_LENGTH characters, and be in a NUL-terminated C string - * format (TOX_MAX_HOSTNAME_LENGTH includes the NUL byte). + * exceed TOX_MAX_HOSTNAME_LENGTH characters, and be in a NUL-terminated C + * string format (TOX_MAX_HOSTNAME_LENGTH includes the NUL byte). * - * This member is ignored (it can be NULL) if proxy_type is TOX_PROXY_TYPE_NONE. + * This member is ignored (it can be NULL) if proxy_type is + * TOX_PROXY_TYPE_NONE. * * The data pointed at by this member is owned by the user, so must * outlive the options object. @@ -595,8 +598,8 @@ struct Tox_Options { * If either start_port or end_port is 0 while the other is non-zero, the * non-zero port will be the only port in the range. * - * Having start_port > end_port will yield the same behavior as if start_port - * and end_port were swapped. + * Having start_port > end_port will yield the same behavior as if + * start_port and end_port were swapped. */ uint16_t start_port; @@ -671,8 +674,9 @@ struct Tox_Options { const Tox_System *operating_system; /** - * Enable saving DHT-based group chats to Tox save data (via `tox_get_savedata`). - * This format will change in the future, so don't rely on it. + * Enable saving DHT-based group chats to Tox save data (via + * `tox_get_savedata`). This format will change in the future, so don't rely + * on it. * * As an alternative, clients can save the group chat ID in client-owned * savedata. Then, when the client starts, it can use `tox_group_join` @@ -829,15 +833,16 @@ typedef enum Tox_Err_New { TOX_ERR_NEW_NULL, /** - * The function was unable to allocate enough memory to store the events_alloc - * structures for the Tox object. + * The function was unable to allocate enough memory to store the + * events_alloc structures for the Tox object. */ TOX_ERR_NEW_MALLOC, /** * The function was unable to bind to a port. This may mean that all ports * have already been bound, e.g. by other Tox instances, or it may mean - * a permission error. You may be able to gather more information from errno. + * a permission error. You may be able to gather more information from + * errno. */ TOX_ERR_NEW_PORT_ALLOC, @@ -1058,8 +1063,8 @@ typedef void tox_self_connection_status_cb(Tox *tox, Tox_Connection connection_s void tox_callback_self_connection_status(Tox *tox, tox_self_connection_status_cb *callback); /** - * @brief Return the time in milliseconds before `tox_iterate()` should be called again - * for optimal performance. + * @brief Return the time in milliseconds before `tox_iterate()` should be + * called again for optimal performance. */ uint32_t tox_iteration_interval(const Tox *tox); @@ -1167,7 +1172,8 @@ const char *tox_err_set_info_to_string(Tox_Err_Set_Info value); bool tox_self_set_name(Tox *tox, const uint8_t name[], size_t length, Tox_Err_Set_Info *error); /** - * @brief Return the length of the current nickname as passed to tox_self_set_name. + * @brief Return the length of the current nickname as passed to + * tox_self_set_name. * * If no nickname was set before calling this function, the name is empty, * and this function returns 0. @@ -1201,7 +1207,8 @@ bool tox_self_set_status_message( Tox *tox, const uint8_t status_message[], size_t length, Tox_Err_Set_Info *error); /** - * @brief Return the length of the current status message as passed to tox_self_set_status_message. + * @brief Return the length of the current status message as passed to + * tox_self_set_status_message. * * If no status message was set before calling this function, the status * is empty, and this function returns 0. @@ -1211,13 +1218,14 @@ bool tox_self_set_status_message( size_t tox_self_get_status_message_size(const Tox *tox); /** - * @brief Write the status message set by tox_self_set_status_message to a byte array. + * @brief Write the status message set by tox_self_set_status_message to a byte + * array. * * If no status message was set before calling this function, the status is * empty, and this function has no effect. * - * Call tox_self_get_status_message_size to find out how much memory to allocate for - * the result. + * Call tox_self_get_status_message_size to find out how much memory to allocate + * for the result. * * @param status_message A valid memory location large enough to hold the * status message. If this parameter is NULL, the function has no effect. @@ -1274,8 +1282,8 @@ typedef enum Tox_Err_Friend_Add { TOX_ERR_FRIEND_ADD_OWN_KEY, /** - * A friend request has already been sent, or the address belongs to a friend - * that is already on the friend list. + * A friend request has already been sent, or the address belongs to a + * friend that is already on the friend list. */ TOX_ERR_FRIEND_ADD_ALREADY_SENT, @@ -1355,7 +1363,8 @@ typedef enum Tox_Err_Friend_Delete { TOX_ERR_FRIEND_DELETE_OK, /** - * There was no friend with the given friend number. No friends were deleted. + * There was no friend with the given friend number. No friends were + * deleted. */ TOX_ERR_FRIEND_DELETE_FRIEND_NOT_FOUND, @@ -1406,14 +1415,15 @@ const char *tox_err_friend_by_public_key_to_string(Tox_Err_Friend_By_Public_Key /** * @brief Return the friend number associated with that Public Key. * - * @return the friend number on success, an unspecified value on failure. * @param public_key A byte array containing the Public Key. + * + * @return the friend number on success, an unspecified value on failure. */ Tox_Friend_Number tox_friend_by_public_key(const Tox *tox, const uint8_t public_key[TOX_PUBLIC_KEY_SIZE], Tox_Err_Friend_By_Public_Key *error); /** - * @brief Checks if a friend with the given friend number exists and returns true if - * it does. + * @brief Checks if a friend with the given friend number exists and returns + * true if it does. */ bool tox_friend_exists(const Tox *tox, Tox_Friend_Number friend_number); @@ -1428,7 +1438,8 @@ size_t tox_self_get_friend_list_size(const Tox *tox); /** * @brief Copy a list of valid friend numbers into an array. * - * Call tox_self_get_friend_list_size to determine the number of elements to allocate. + * Call tox_self_get_friend_list_size to determine the number of elements to + * allocate. * * @param friend_list A memory region with enough space to hold the friend * list. If this parameter is NULL, this function has no effect. @@ -1452,7 +1463,8 @@ typedef enum Tox_Err_Friend_Get_Public_Key { const char *tox_err_friend_get_public_key_to_string(Tox_Err_Friend_Get_Public_Key value); /** - * @brief Copies the Public Key associated with a given friend number to a byte array. + * @brief Copies the Public Key associated with a given friend number to a byte + * array. * * @param friend_number The friend number you want the Public Key of. * @param public_key A memory region of at least TOX_PUBLIC_KEY_SIZE bytes. If @@ -1481,8 +1493,8 @@ typedef enum Tox_Err_Friend_Get_Last_Online { const char *tox_err_friend_get_last_online_to_string(Tox_Err_Friend_Get_Last_Online value); /** - * @brief Return a unix-time timestamp of the last time the friend associated with a given - * friend number was seen online. + * @brief Return a unix-time timestamp of the last time the friend associated + * with a given friend number was seen online. * * This function will return UINT64_MAX on error. * @@ -1509,8 +1521,9 @@ typedef enum Tox_Err_Friend_Query { /** * The pointer parameter for storing the query result (name, message) was - * NULL. Unlike the `_self_` variants of these functions, which have no effect - * when a parameter is NULL, these functions return an error in that case. + * NULL. Unlike the `_self_` variants of these functions, which have no + * effect when a parameter is NULL, these functions return an error in that + * case. */ TOX_ERR_FRIEND_QUERY_NULL, @@ -1535,8 +1548,8 @@ size_t tox_friend_get_name_size( const Tox *tox, Tox_Friend_Number friend_number, Tox_Err_Friend_Query *error); /** - * @brief Write the name of the friend designated by the given friend number to a byte - * array. + * @brief Write the name of the friend designated by the given friend number to + * a byte array. * * Call tox_friend_get_name_size to determine the allocation size for the `name` * parameter. @@ -1580,16 +1593,17 @@ size_t tox_friend_get_status_message_size( const Tox *tox, Tox_Friend_Number friend_number, Tox_Err_Friend_Query *error); /** - * @brief Write the status message of the friend designated by the given friend number to a byte - * array. + * @brief Write the status message of the friend designated by the given friend + * number to a byte array. * - * Call tox_friend_get_status_message_size to determine the allocation size for the `status_message` - * parameter. + * Call tox_friend_get_status_message_size to determine the allocation size for + * the `status_message` parameter. * - * The data written to `status_message` is equal to the data received by the last - * `friend_status_message` callback. + * The data written to `status_message` is equal to the data received by the + * last `friend_status_message` callback. * - * @param status_message A valid memory region large enough to store the friend's status message. + * @param status_message A valid memory region large enough to store the + * friend's status message. */ bool tox_friend_get_status_message( const Tox *tox, Tox_Friend_Number friend_number, uint8_t status_message[], @@ -1599,7 +1613,8 @@ bool tox_friend_get_status_message( * @param friend_number The friend number of the friend whose status message * changed. * @param message A byte array containing the same data as - * tox_friend_get_status_message would write to its `status_message` parameter. + * tox_friend_get_status_message would write to its `status_message` + * parameter. * @param length A value equal to the return value of * tox_friend_get_status_message_size. */ @@ -1809,7 +1824,8 @@ typedef uint32_t Tox_Friend_Message_Id; * then reassemble the fragments. Messages may not be empty. * * The return value of this function is the message ID. If a read receipt is - * received, the triggered `friend_read_receipt` event will be passed this message ID. + * received, the triggered `friend_read_receipt` event will be passed this + * message ID. * * Message IDs are unique per friend. The first message ID is 0. Message IDs are * incremented by 1 each time a message is sent. If UINT32_MAX messages were @@ -1826,7 +1842,8 @@ Tox_Friend_Message_Id tox_friend_send_message( const uint8_t message[], size_t length, Tox_Err_Friend_Send_Message *error); /** - * @param friend_number The friend number of the friend who received the message. + * @param friend_number The friend number of the friend who received the + * message. * @param message_id The message ID as returned from tox_friend_send_message * corresponding to the message sent. */ @@ -1901,8 +1918,8 @@ typedef uint32_t Tox_File_Number; * primarily for validating cached avatars. This use is highly recommended to * avoid unnecessary avatar updates. * - * If hash is NULL or data is NULL while length is not 0 the function returns false, - * otherwise it returns true. + * If hash is NULL or data is NULL while length is not 0 the function returns + * false, otherwise it returns true. * * This function is a wrapper to events_alloc message-digest functions. * @@ -1927,8 +1944,8 @@ bool tox_hash(uint8_t hash[TOX_HASH_LENGTH], const uint8_t data[], size_t length enum Tox_File_Kind { /** - * Arbitrary file data. Clients can choose to handle it based on the file name - * or magic or any other way they choose. + * Arbitrary file data. Clients can choose to handle it based on the file + * name or magic or any other way they choose. */ TOX_FILE_KIND_DATA, @@ -1936,21 +1953,21 @@ enum Tox_File_Kind { * Avatar file_id. This consists of tox_hash(image). * Avatar data. This consists of the image data. * - * Avatars can be sent at any time the client wishes. Generally, a client will - * send the avatar to a friend when that friend comes online, and to all - * friends when the avatar changed. A client can save some traffic by - * remembering which friend received the updated avatar already and only send - * it if the friend has an out of date avatar. + * Avatars can be sent at any time the client wishes. Generally, a client + * will send the avatar to a friend when that friend comes online, and to + * all friends when the avatar changed. A client can save some traffic by + * remembering which friend received the updated avatar already and only + * send it if the friend has an out of date avatar. * * Clients who receive avatar send requests can reject it (by sending * TOX_FILE_CONTROL_CANCEL before any other controls), or accept it (by - * sending TOX_FILE_CONTROL_RESUME). The file_id of length TOX_HASH_LENGTH bytes - * (same length as TOX_FILE_ID_LENGTH) will contain the hash. A client can compare - * this hash with a saved hash and send TOX_FILE_CONTROL_CANCEL to terminate the avatar - * transfer if it matches. + * sending TOX_FILE_CONTROL_RESUME). The file_id of length TOX_HASH_LENGTH + * bytes (same length as TOX_FILE_ID_LENGTH) will contain the hash. A client + * can compare this hash with a saved hash and send TOX_FILE_CONTROL_CANCEL + * to terminate the avatar transfer if it matches. * - * When file_size is set to 0 in the transfer request it means that the client - * has no avatar. + * When file_size is set to 0 in the transfer request it means that the + * client has no avatar. */ TOX_FILE_KIND_AVATAR, @@ -1959,16 +1976,17 @@ enum Tox_File_Kind { typedef enum Tox_File_Control { /** - * Sent by the receiving side to accept a file send request. Also sent after a - * TOX_FILE_CONTROL_PAUSE command to continue sending or receiving. + * Sent by the receiving side to accept a file send request. Also sent after + * a TOX_FILE_CONTROL_PAUSE command to continue sending or receiving. */ TOX_FILE_CONTROL_RESUME, /** * Sent by clients to pause the file transfer. The initial state of a file - * transfer is always paused on the receiving side and running on the sending - * side. If both the sending and receiving side pause the transfer, then both - * need to send TOX_FILE_CONTROL_RESUME for the transfer to resume. + * transfer is always paused on the receiving side and running on the + * sending side. If both the sending and receiving side pause the transfer, + * then both need to send TOX_FILE_CONTROL_RESUME for the transfer to + * resume. */ TOX_FILE_CONTROL_PAUSE, @@ -2000,7 +2018,8 @@ typedef enum Tox_Err_File_Control { TOX_ERR_FILE_CONTROL_FRIEND_NOT_CONNECTED, /** - * No file transfer with the given file number was found for the given friend. + * No file transfer with the given file number was found for the given + * friend. */ TOX_ERR_FILE_CONTROL_NOT_FOUND, @@ -2084,7 +2103,8 @@ typedef enum Tox_Err_File_Seek { TOX_ERR_FILE_SEEK_FRIEND_NOT_CONNECTED, /** - * No file transfer with the given file number was found for the given friend. + * No file transfer with the given file number was found for the given + * friend. */ TOX_ERR_FILE_SEEK_NOT_FOUND, @@ -2108,7 +2128,8 @@ typedef enum Tox_Err_File_Seek { const char *tox_err_file_seek_to_string(Tox_Err_File_Seek value); /** - * @brief Sends a file seek control command to a friend for a given file transfer. + * @brief Sends a file seek control command to a friend for a given file + * transfer. * * This function can only be called to resume a file transfer right before * TOX_FILE_CONTROL_RESUME is sent. @@ -2139,7 +2160,8 @@ typedef enum Tox_Err_File_Get { TOX_ERR_FILE_GET_FRIEND_NOT_FOUND, /** - * No file transfer with the given file number was found for the given friend. + * No file transfer with the given file number was found for the given + * friend. */ TOX_ERR_FILE_GET_NOT_FOUND, @@ -2153,8 +2175,8 @@ const char *tox_err_file_get_to_string(Tox_Err_File_Get value); * @param friend_number The friend number of the friend the file is being * transferred to or received from. * @param file_number The friend-specific identifier for the file transfer. - * @param file_id A memory region of at least TOX_FILE_ID_LENGTH bytes. If - * this parameter is NULL, this function has no effect. + * @param file_id A memory region of at least TOX_FILE_ID_LENGTH bytes. If this + * parameter is NULL, this function has no effect. * * @return true on success. */ @@ -2197,8 +2219,8 @@ typedef enum Tox_Err_File_Send { TOX_ERR_FILE_SEND_NAME_TOO_LONG, /** - * Too many ongoing transfers. The maximum number of concurrent file transfers - * is 256 per friend per direction (sending and receiving). + * Too many ongoing transfers. The maximum number of concurrent file + * transfers is 256 per friend per direction (sending and receiving). */ TOX_ERR_FILE_SEND_TOO_MANY, @@ -2209,8 +2231,8 @@ const char *tox_err_file_send_to_string(Tox_Err_File_Send value); /** * @brief Send a file transmission request. * - * Maximum filename length is TOX_MAX_FILENAME_LENGTH bytes. The filename - * should generally just be a file name, not a path with directory names. + * Maximum filename length is TOX_MAX_FILENAME_LENGTH bytes. The filename should + * generally just be a file name, not a path with directory names. * * If a non-UINT64_MAX file size is provided, it can be used by both sides to * determine the sending progress. File size can be set to UINT64_MAX for @@ -2229,11 +2251,12 @@ const char *tox_err_file_send_to_string(Tox_Err_File_Send value); * - If the file size was increased * - and sending mode was streaming (file_size = UINT64_MAX), the behaviour * will be as expected. - * - and sending mode was file (file_size != UINT64_MAX), the file_chunk_request - * callback will receive length = 0 when Core thinks the file transfer has - * finished. If the client remembers the file size as it was when sending the - * request, it will terminate the transfer normally. If the client re-reads the - * size, it will think the friend cancelled the transfer. + * - and sending mode was file (file_size != UINT64_MAX), the + * file_chunk_request callback will receive length = 0 when Core thinks the + * file transfer has finished. If the client remembers the file size as it + * was when sending the request, it will terminate the transfer normally. If + * the client re-reads the size, it will think the friend cancelled the + * transfer. * - If the file size was decreased * - and sending mode was streaming, the behaviour is as expected. * - and sending mode was file, the callback will return 0 at the new @@ -2250,19 +2273,20 @@ const char *tox_err_file_send_to_string(Tox_Err_File_Send value); * @param friend_number The friend number of the friend the file send request * should be sent to. * @param kind The meaning of the file to be sent. - * @param file_size Size in bytes of the file the client wants to send, UINT64_MAX if - * unknown or streaming. - * @param file_id A file identifier of length TOX_FILE_ID_LENGTH that can be used to - * uniquely identify file transfers across core restarts. If NULL, a random one will - * be generated by core. It can then be obtained by using `tox_file_get_file_id()`. + * @param file_size Size in bytes of the file the client wants to send, + * UINT64_MAX if unknown or streaming. + * @param file_id A file identifier of length TOX_FILE_ID_LENGTH that can be + * used to uniquely identify file transfers across core restarts. If NULL, a + * random one will be generated by core. It can then be obtained by using + * `tox_file_get_file_id()`. * @param filename Name of the file. Does not need to be the actual name. This * name will be sent along with the file send request. * @param filename_length Size in bytes of the filename. * * @return A file number used as an identifier in subsequent callbacks. This * number is per friend. File numbers are reused after a transfer terminates. - * On failure, this function returns an unspecified value. Any pattern in file numbers - * should not be relied on. + * On failure, this function returns an unspecified value. Any pattern in file + * numbers should not be relied on. */ Tox_File_Number tox_file_send( Tox *tox, Tox_Friend_Number friend_number, uint32_t kind, uint64_t file_size, @@ -2292,20 +2316,23 @@ typedef enum Tox_Err_File_Send_Chunk { TOX_ERR_FILE_SEND_CHUNK_FRIEND_NOT_CONNECTED, /** - * No file transfer with the given file number was found for the given friend. + * No file transfer with the given file number was found for the given + * friend. */ TOX_ERR_FILE_SEND_CHUNK_NOT_FOUND, /** * File transfer was found but isn't in a transferring state: (paused, done, - * broken, etc...) (happens only when not called from the request chunk callback). + * broken, etc...) (happens only when not called from the request chunk + * callback). */ TOX_ERR_FILE_SEND_CHUNK_NOT_TRANSFERRING, /** - * Attempted to send more or less data than requested. The requested data size is - * adjusted according to maximum transmission unit and the expected end of - * the file. Trying to send less or more than requested will return this error. + * Attempted to send more or less data than requested. The requested data + * size is adjusted according to maximum transmission unit and the expected + * end of the file. Trying to send less or more than requested will return + * this error. */ TOX_ERR_FILE_SEND_CHUNK_INVALID_LENGTH, @@ -2332,7 +2359,8 @@ const char *tox_err_file_send_chunk_to_string(Tox_Err_File_Send_Chunk value); * Core will know that the transfer is complete after the last byte has been * received, so it is not necessary (though not harmful) to send a zero-length * chunk to terminate. For streams, core will know that the transfer is finished - * if a chunk with length less than the length requested in the callback is sent. + * if a chunk with length less than the length requested in the callback is + * sent. * * @param friend_number The friend number of the receiving friend for this file. * @param file_number The file transfer identifier returned by tox_file_send. @@ -2461,7 +2489,8 @@ typedef uint32_t Tox_Conference_Offline_Peer_Number; typedef enum Tox_Conference_Type { /** - * Text-only conferences that must be accepted with the tox_conference_join function. + * Text-only conferences that must be accepted with the tox_conference_join + * function. */ TOX_CONFERENCE_TYPE_TEXT, @@ -2498,7 +2527,8 @@ typedef void tox_conference_invite_cb( void tox_callback_conference_invite(Tox *tox, tox_conference_invite_cb *callback); /** - * @param conference_number The conference number of the conference to which we have connected. + * @param conference_number The conference number of the conference to which we + * have connected. */ typedef void tox_conference_connected_cb(Tox *tox, Tox_Conference_Number conference_number, void *user_data); @@ -2551,7 +2581,8 @@ typedef void tox_conference_title_cb( * * This event is triggered when a peer changes the conference title. * - * If peer_number == UINT32_MAX, then author is unknown (e.g. initial joining the conference). + * If peer_number == UINT32_MAX, then author is unknown (e.g. initial joining + * the conference). */ void tox_callback_conference_title(Tox *tox, tox_conference_title_cb *callback); @@ -2636,7 +2667,8 @@ const char *tox_err_conference_delete_to_string(Tox_Err_Conference_Delete value) /** * @brief This function deletes a conference. * - * @param conference_number The conference number of the conference to be deleted. + * @param conference_number The conference number of the conference to be + * deleted. * * @return true on success. */ @@ -2693,7 +2725,8 @@ size_t tox_conference_peer_get_name_size( /** * @brief Copy the name of peer_number who is in conference_number to name. * - * Call tox_conference_peer_get_name_size to determine the allocation size for the `name` parameter. + * Call tox_conference_peer_get_name_size to determine the allocation size for + * the `name` parameter. * * @param name A valid memory region large enough to store the peer's name. * @@ -2704,7 +2737,8 @@ bool tox_conference_peer_get_name( uint8_t name[], Tox_Err_Conference_Peer_Query *error); /** - * @brief Copy the public key of peer_number who is in conference_number to public_key. + * @brief Copy the public key of peer_number who is in conference_number to + * public_key. * * public_key must be TOX_PUBLIC_KEY_SIZE long. * @@ -2743,7 +2777,8 @@ size_t tox_conference_offline_peer_get_name_size( Tox_Conference_Offline_Peer_Number offline_peer_number, Tox_Err_Conference_Peer_Query *error); /** - * @brief Copy the name of offline_peer_number who is in conference_number to name. + * @brief Copy the name of offline_peer_number who is in conference_number to + * name. * * Call tox_conference_offline_peer_get_name_size to determine the allocation * size for the `name` parameter. @@ -2757,7 +2792,8 @@ bool tox_conference_offline_peer_get_name( uint8_t name[], Tox_Err_Conference_Peer_Query *error); /** - * @brief Copy the public key of offline_peer_number who is in conference_number to public_key. + * @brief Copy the public key of offline_peer_number who is in conference_number + * to public_key. * * public_key must be TOX_PUBLIC_KEY_SIZE long. * @@ -2768,7 +2804,8 @@ bool tox_conference_offline_peer_get_public_key( Tox_Conference_Offline_Peer_Number offline_peer_number, uint8_t public_key[TOX_PUBLIC_KEY_SIZE], Tox_Err_Conference_Peer_Query *error); /** - * @brief Return a unix-time timestamp of the last time offline_peer_number was seen to be active. + * @brief Return a unix-time timestamp of the last time offline_peer_number was + * seen to be active. */ uint64_t tox_conference_offline_peer_get_last_active( const Tox *tox, Tox_Conference_Number conference_number, @@ -2827,7 +2864,8 @@ const char *tox_err_conference_invite_to_string(Tox_Err_Conference_Invite value) * @brief Invites a friend to a conference. * * @param friend_number The friend number of the friend we want to invite. - * @param conference_number The conference number of the conference we want to invite the friend to. + * @param conference_number The conference number of the conference we want to + * invite the friend to. * * @return true on success. */ @@ -2848,7 +2886,8 @@ typedef enum Tox_Err_Conference_Join { TOX_ERR_CONFERENCE_JOIN_INVALID_LENGTH, /** - * The conference is not the expected type. This indicates an invalid cookie. + * The conference is not the expected type. This indicates an invalid + * cookie. */ TOX_ERR_CONFERENCE_JOIN_WRONG_TYPE, @@ -2991,9 +3030,11 @@ size_t tox_conference_get_title_size( const Tox *tox, Tox_Conference_Number conference_number, Tox_Err_Conference_Title *error); /** - * @brief Write the title designated by the given conference number to a byte array. + * @brief Write the title designated by the given conference number to a byte + * array. * - * Call tox_conference_get_title_size to determine the allocation size for the `title` parameter. + * Call tox_conference_get_title_size to determine the allocation size for the + * `title` parameter. * * The data written to `title` is equal to the data received by the last * `conference_title` callback. @@ -3009,7 +3050,8 @@ bool tox_conference_get_title( Tox_Err_Conference_Title *error); /** - * @brief Set the conference title and broadcast it to the rest of the conference. + * @brief Set the conference title and broadcast it to the rest of the + * conference. * * Title length cannot be longer than TOX_MAX_NAME_LENGTH. * @@ -3023,7 +3065,8 @@ bool tox_conference_set_title( /** * @brief Return the number of conferences in the Tox instance. * - * This should be used to determine how much memory to allocate for `tox_conference_get_chatlist`. + * This should be used to determine how much memory to allocate for + * `tox_conference_get_chatlist`. */ size_t tox_conference_get_chatlist_size(const Tox *tox); @@ -3044,7 +3087,8 @@ size_t tox_conference_get_chatlist_size(const Tox *tox); void tox_conference_get_chatlist(const Tox *tox, Tox_Conference_Number chatlist[]); /** - * @brief Returns the type of conference (Tox_Conference_Type) that conference_number is. + * @brief Returns the type of conference (Tox_Conference_Type) that + * conference_number is. * * Return value is unspecified on failure. */ @@ -3119,10 +3163,12 @@ Tox_Conference_Number tox_conference_by_id( * * If uid is NULL, this function has no effect. * - * @param uid A memory region large enough to store TOX_CONFERENCE_UID_SIZE bytes. + * @param uid A memory region large enough to store TOX_CONFERENCE_UID_SIZE + * bytes. * * @return true on success. - * @deprecated use tox_conference_get_id instead (exactly the same function, just renamed). + * @deprecated use tox_conference_get_id instead (exactly the same function, + * just renamed). */ bool tox_conference_get_uid( const Tox *tox, Tox_Conference_Number conference_number, uint8_t uid[TOX_CONFERENCE_UID_SIZE]); @@ -3151,10 +3197,12 @@ const char *tox_err_conference_by_uid_to_string(Tox_Err_Conference_By_Uid value) /** * @brief Return the conference number associated with the specified uid. * - * @param uid A byte array containing the conference id (TOX_CONFERENCE_UID_SIZE). + * @param uid A byte array containing the conference id + * (TOX_CONFERENCE_UID_SIZE). * * @return the conference number on success, an unspecified value on failure. - * @deprecated use tox_conference_by_id instead (exactly the same function, just renamed). + * @deprecated use tox_conference_by_id instead (exactly the same function, + * just renamed). */ Tox_Conference_Number tox_conference_by_uid( const Tox *tox, const uint8_t uid[TOX_CONFERENCE_UID_SIZE], Tox_Err_Conference_By_Uid *error); @@ -3188,8 +3236,9 @@ typedef enum Tox_Err_Friend_Custom_Packet { TOX_ERR_FRIEND_CUSTOM_PACKET_FRIEND_NOT_CONNECTED, /** - * The first byte of data was not in the specified range for the packet type. - * This range is 192-254 for lossy, and 69, 160-191 for lossless packets. + * The first byte of data was not in the specified range for the packet + * type. This range is 192-254 for lossy, and 69, 160-191 for lossless + * packets. */ TOX_ERR_FRIEND_CUSTOM_PACKET_INVALID, @@ -3318,7 +3367,8 @@ const char *tox_err_get_port_to_string(Tox_Err_Get_Port value); * @brief Writes the temporary DHT public key of this instance to a byte array. * * This can be used in combination with an externally accessible IP address and - * the bound port (from tox_self_get_udp_port) to run a temporary bootstrap node. + * the bound port (from tox_self_get_udp_port) to run a temporary bootstrap + * node. * * Be aware that every time a new instance is created, the DHT public key * changes, meaning this cannot be used to run a permanent bootstrap node. @@ -3431,22 +3481,24 @@ uint32_t tox_group_peer_public_key_size(void); typedef enum Tox_Group_Privacy_State { /** - * The group is considered to be public. Anyone may join the group using the Chat ID. + * The group is considered to be public. Anyone may join the group using + * the Chat ID. * - * If the group is in this state, even if the Chat ID is never explicitly shared - * with someone outside of the group, information including the Chat ID, IP addresses, - * and peer ID's (but not Tox ID's) is visible to anyone with access to a node - * storing a DHT entry for the given group. + * If the group is in this state, even if the Chat ID is never explicitly + * shared with someone outside of the group, information including the Chat + * ID, IP addresses, and peer ID's (but not Tox ID's) is visible to anyone + * with access to a node storing a DHT entry for the given group. */ TOX_GROUP_PRIVACY_STATE_PUBLIC, /** - * The group is considered to be private. The only way to join the group is by having - * someone in your contact list send you an invite. + * The group is considered to be private. The only way to join the group is + * by having someone in your contact list send you an invite. * - * If the group is in this state, no group information (mentioned above) is present in the DHT; - * the DHT is not used for any purpose at all. If a public group is set to private, - * all DHT information related to the group will expire shortly. + * If the group is in this state, no group information (mentioned above) is + * present in the DHT; the DHT is not used for any purpose at all. If a + * public group is set to private, all DHT information related to the group + * will expire shortly. */ TOX_GROUP_PRIVACY_STATE_PRIVATE, @@ -3460,12 +3512,14 @@ const char *tox_group_privacy_state_to_string(Tox_Group_Privacy_State value); typedef enum Tox_Group_Topic_Lock { /** - * The topic lock is enabled. Only peers with the founder and moderator roles may set the topic. + * The topic lock is enabled. Only peers with the founder and moderator + * roles may set the topic. */ TOX_GROUP_TOPIC_LOCK_ENABLED, /** - * The topic lock is disabled. All peers except those with the observer role may set the topic. + * The topic lock is disabled. All peers except those with the observer role + * may set the topic. */ TOX_GROUP_TOPIC_LOCK_DISABLED, @@ -3474,8 +3528,9 @@ typedef enum Tox_Group_Topic_Lock { const char *tox_group_topic_lock_to_string(Tox_Group_Topic_Lock value); /** - * Represents the group voice state, which determines which Group Roles have permission to speak - * in the group chat. The voice state does not have any effect private messages or topic setting. + * Represents the group voice state, which determines which Group Roles have + * permission to speak in the group chat. The voice state does not have any + * effect private messages or topic setting. */ typedef enum Tox_Group_Voice_State { /** @@ -3499,14 +3554,15 @@ const char *tox_group_voice_state_to_string(Tox_Group_Voice_State value); /** * Represents group roles. * - * Roles are hierarchical in that each role has a set of privileges plus all the privileges - * of the roles below it. + * Roles are hierarchical in that each role has a set of privileges plus all the + * privileges of the roles below it. */ typedef enum Tox_Group_Role { /** - * May kick all other peers as well as set their role to anything (except founder). - * Founders may also set the group password, toggle the privacy state, and set the peer limit. + * May kick all other peers as well as set their role to anything (except + * founder). Founders may also set the group password, toggle the privacy + * state, and set the peer limit. */ TOX_GROUP_ROLE_FOUNDER, @@ -3522,7 +3578,8 @@ typedef enum Tox_Group_Role { TOX_GROUP_ROLE_USER, /** - * May observe the group and ignore peers; may not communicate with other peers or with the group. + * May observe the group and ignore peers; may not communicate with other + * peers or with the group. */ TOX_GROUP_ROLE_OBSERVER, @@ -3544,7 +3601,8 @@ typedef enum Tox_Err_Group_New { TOX_ERR_GROUP_NEW_OK, /** - * name exceeds TOX_MAX_NAME_LENGTH or group_name exceeded TOX_GROUP_MAX_GROUP_NAME_LENGTH. + * name exceeds TOX_MAX_NAME_LENGTH or group_name exceeded + * TOX_GROUP_MAX_GROUP_NAME_LENGTH. */ TOX_ERR_GROUP_NEW_TOO_LONG, @@ -3559,13 +3617,14 @@ typedef enum Tox_Err_Group_New { TOX_ERR_GROUP_NEW_INIT, /** - * The group state failed to initialize. This usually indicates that something went wrong - * related to cryptographic signing. + * The group state failed to initialize. This usually indicates that + * something went wrong related to cryptographic signing. */ TOX_ERR_GROUP_NEW_STATE, /** - * The group failed to announce to the DHT. This indicates a network related error. + * The group failed to announce to the DHT. This indicates a network related + * error. */ TOX_ERR_GROUP_NEW_ANNOUNCE, @@ -3580,18 +3639,19 @@ const char *tox_err_group_new_to_string(Tox_Err_Group_New value); * * The caller of this function has Founder role privileges. * - * The client should initiate its peer list with self info after calling this function, as - * the peer_join callback will not be triggered. + * The client should initiate its peer list with self info after calling this + * function, as the peer_join callback will not be triggered. * - * @param privacy_state The privacy state of the group. If this is set to TOX_GROUP_PRIVACY_STATE_PUBLIC, - * the group will attempt to announce itself to the DHT and anyone with the Chat ID may join. - * Otherwise a friend invite will be required to join the group. + * @param privacy_state The privacy state of the group. If this is set to + * TOX_GROUP_PRIVACY_STATE_PUBLIC, the group will attempt to announce itself + * to the DHT and anyone with the Chat ID may join. Otherwise a friend invite + * will be required to join the group. * @param group_name The name of the group. The name must be non-NULL. - * @param group_name_length The length of the group name. This must be greater than zero and no larger than - * TOX_GROUP_MAX_GROUP_NAME_LENGTH. + * @param group_name_length The length of the group name. This must be greater + * than zero and no larger than TOX_GROUP_MAX_GROUP_NAME_LENGTH. * @param name The name of the peer creating the group. - * @param name_length The length of the peer's name. This must be greater than zero and no larger - * than TOX_MAX_NAME_LENGTH. + * @param name_length The length of the peer's name. This must be greater than + * zero and no larger than TOX_MAX_NAME_LENGTH. * * @return group_number on success, UINT32_MAX on failure. */ @@ -3613,8 +3673,9 @@ typedef enum Tox_Err_Group_Join { TOX_ERR_GROUP_JOIN_INIT, /** - * The chat_id pointer is set to NULL or a group with chat_id already exists. This usually - * happens if the client attempts to create multiple sessions for the same group. + * The chat_id pointer is set to NULL or a group with chat_id already + * exists. This usually happens if the client attempts to create multiple + * sessions for the same group. */ TOX_ERR_GROUP_JOIN_BAD_CHAT_ID, @@ -3629,7 +3690,8 @@ typedef enum Tox_Err_Group_Join { TOX_ERR_GROUP_JOIN_TOO_LONG, /** - * Failed to set password. This usually occurs if the password exceeds TOX_GROUP_MAX_PASSWORD_SIZE. + * Failed to set password. This usually occurs if the password exceeds + * TOX_GROUP_MAX_PASSWORD_SIZE. */ TOX_ERR_GROUP_JOIN_PASSWORD, @@ -3645,17 +3707,20 @@ const char *tox_err_group_join_to_string(Tox_Err_Group_Join value); /** * Joins a group chat with specified Chat ID. * - * This function creates a new group chat object, adds it to the chats array, and sends - * a DHT announcement to find peers in the group associated with chat_id. Once a peer has been - * found a join attempt will be initiated. - * - * @param chat_id The Chat ID of the group you wish to join. This must be TOX_GROUP_CHAT_ID_SIZE bytes. - * @param password The password required to join the group. Set to NULL if no password is required. - * @param password_length The length of the password. If length is equal to zero, - * the password parameter is ignored. length must be no larger than TOX_GROUP_MAX_PASSWORD_SIZE. + * This function creates a new group chat object, adds it to the chats array, + * and sends a DHT announcement to find peers in the group associated with + * chat_id. Once a peer has been found a join attempt will be initiated. + * + * @param chat_id The Chat ID of the group you wish to join. This must be + * TOX_GROUP_CHAT_ID_SIZE bytes. + * @param password The password required to join the group. Set to NULL if no + * password is required. + * @param password_length The length of the password. If length is equal to + * zero, the password parameter is ignored. length must be no larger than + * TOX_GROUP_MAX_PASSWORD_SIZE. * @param name The name of the peer joining the group. - * @param name_length The length of the peer's name. This must be greater than zero and no larger - * than TOX_MAX_NAME_LENGTH. + * @param name_length The length of the peer's name. This must be greater than + * zero and no larger than TOX_MAX_NAME_LENGTH. * * @return group_number on success, UINT32_MAX on failure. */ @@ -3682,8 +3747,8 @@ typedef enum Tox_Err_Group_Is_Connected { const char *tox_err_group_is_connected_to_string(Tox_Err_Group_Is_Connected value); /** - * Returns true if the group chat is currently connected or attempting to connect to other peers - * in the group. + * Returns true if the group chat is currently connected or attempting to + * connect to other peers in the group. * * @param group_number The group number of the designated group. */ @@ -3710,7 +3775,8 @@ typedef enum Tox_Err_Group_Disconnect { const char *tox_err_group_disconnect_to_string(Tox_Err_Group_Disconnect value); /** - * Disconnects from a group chat while retaining the group state and credentials. + * Disconnects from a group chat while retaining the group state and + * credentials. * * Returns true if we successfully disconnect from the group. * @@ -3742,8 +3808,9 @@ const char *tox_err_group_reconnect_to_string(Tox_Err_Group_Reconnect value); /** * Reconnects to a group. * - * This function disconnects from all peers in the group, then attempts to reconnect with the group. - * The caller's state is not changed (i.e. name, status, role, chat public key etc.). + * This function disconnects from all peers in the group, then attempts to + * reconnect with the group. The caller's state is not changed (i.e. name, + * status, role, chat public key etc.). * * @param group_number The group number of the group we wish to reconnect to. * @@ -3779,14 +3846,16 @@ const char *tox_err_group_leave_to_string(Tox_Err_Group_Leave value); /** * Leaves a group. * - * This function sends a parting packet containing a custom (non-obligatory) message to all - * peers in a group, and deletes the group from the chat array. All group state information is permanently - * lost, including keys and role credentials. + * This function sends a parting packet containing a custom (non-obligatory) + * message to all peers in a group, and deletes the group from the chat array. + * All group state information is permanently lost, including keys and role + * credentials. * * @param group_number The group number of the group we wish to leave. - * @param part_message The parting message to be sent to all the peers. Set to NULL if we do not wish to - * send a parting message. - * @param length The length of the parting message. Set to 0 if we do not wish to send a parting message. + * @param part_message The parting message to be sent to all the peers. Set to + * NULL if we do not wish to send a parting message. + * @param length The length of the parting message. Set to 0 if we do not wish + * to send a parting message. * * @return true if the group chat instance is successfully deleted. */ @@ -3855,10 +3924,11 @@ typedef enum Tox_Err_Group_Self_Name_Set { const char *tox_err_group_self_name_set_to_string(Tox_Err_Group_Self_Name_Set value); /** - * Set the client's nickname for the group instance designated by the given group number. + * Set the client's nickname for the group instance designated by the given + * group number. * - * Nickname length cannot exceed TOX_MAX_NAME_LENGTH. If length is equal to zero or name is a NULL - * pointer, the function call will fail. + * Nickname length cannot exceed TOX_MAX_NAME_LENGTH. If length is equal to + * zero or name is a NULL pointer, the function call will fail. * * @param name A byte array containing the new nickname. * @param length The size of the name byte array. @@ -3871,8 +3941,8 @@ bool tox_group_self_set_name( Tox_Err_Group_Self_Name_Set *error); /** - * Return the length of the client's current nickname for the group instance designated - * by group_number as passed to tox_group_self_set_name. + * Return the length of the client's current nickname for the group instance + * designated by group_number as passed to tox_group_self_set_name. * * If no nickname was set before calling this function, the name is empty, * and this function returns 0. @@ -3887,7 +3957,8 @@ size_t tox_group_self_get_name_size(const Tox *tox, Tox_Group_Number group_numbe * If no nickname was set before calling this function, the name is empty, * and this function has no effect. * - * Call tox_group_self_get_name_size to find out how much memory to allocate for the result. + * Call tox_group_self_get_name_size to find out how much memory to allocate for + * the result. * * @param name A valid memory location large enough to hold the nickname. * If this parameter is NULL, the function has no effect. @@ -3923,7 +3994,8 @@ typedef enum Tox_Err_Group_Self_Status_Set { const char *tox_err_group_self_status_set_to_string(Tox_Err_Group_Self_Status_Set value); /** - * Set the client's status for the group instance. Status must be a Tox_User_Status. + * Set the client's status for the group instance. Status must be a + * Tox_User_Status. * * @return true on success. */ @@ -3949,13 +4021,16 @@ Tox_Group_Role tox_group_self_get_role(const Tox *tox, Tox_Group_Number group_nu Tox_Group_Peer_Number tox_group_self_get_peer_id(const Tox *tox, Tox_Group_Number group_number, Tox_Err_Group_Self_Query *error); /** - * Write the client's group public key designated by the given group number to a byte array. + * Write the client's group public key designated by the given group number to + * a byte array. * - * This key will be permanently tied to the client's identity for this particular group until - * the client explicitly leaves the group. This key is the only way for other peers to reliably - * identify the client across client restarts. + * This key will be permanently tied to the client's identity for this + * particular group until the client explicitly leaves the group. This key is + * the only way for other peers to reliably identify the client across client + * restarts. * - * `public_key` should have room for at least TOX_GROUP_PEER_PUBLIC_KEY_SIZE bytes. + * `public_key` should have room for at least TOX_GROUP_PEER_PUBLIC_KEY_SIZE + * bytes. * * @param public_key A valid memory region large enough to store the public key. * If this parameter is NULL, this function call has no effect. @@ -3996,8 +4071,8 @@ typedef enum Tox_Err_Group_Peer_Query { const char *tox_err_group_peer_query_to_string(Tox_Err_Group_Peer_Query value); /** - * Return the length of the peer's name. If the group number or ID is invalid, the - * return value is unspecified. + * Return the length of the peer's name. 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 name length we want to retrieve. @@ -4012,7 +4087,8 @@ size_t tox_group_peer_get_name_size(const Tox *tox, Tox_Group_Number group_numbe * Write the name of the peer designated by the given ID to a byte * array. * - * Call tox_group_peer_get_name_size to determine the allocation size for the `name` parameter. + * Call tox_group_peer_get_name_size to determine the allocation size for the + * `name` parameter. * * The data written to `name` is equal to the data received by the last * `group_peer_name` callback. @@ -4041,8 +4117,8 @@ Tox_User_Status tox_group_peer_get_status(const Tox *tox, Tox_Group_Number group Tox_Err_Group_Peer_Query *error); /** - * Return the peer's role (user/moderator/founder...). If the ID or group number is - * invalid, the return value is unspecified. + * Return the peer's role (user/moderator/founder...). If the ID or group number + * 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 role we wish to query. @@ -4056,8 +4132,9 @@ Tox_Group_Role tox_group_peer_get_role(const Tox *tox, Tox_Group_Number group_nu /** * Return the type of connection we have established with a peer. * - * If `peer_id` designates ourself, the return value indicates whether we're capable - * of making UDP connections with other peers, or are limited to TCP connections. + * If `peer_id` designates ourself, the return value indicates whether we're + * capable of making UDP connections with other peers, or are limited to TCP + * connections. * * @param group_number The group number of the group we wish to query. * @param peer_id The ID of the peer whose connection status we wish to query. @@ -4066,10 +4143,12 @@ Tox_Connection tox_group_peer_get_connection_status(const Tox *tox, Tox_Group_Nu Tox_Err_Group_Peer_Query *error); /** - * Write the group public key with the designated peer_id for the designated group number to public_key. + * Write the group public key with the designated peer_id for the designated + * group number to public_key. * - * This key will be permanently tied to a particular peer until they explicitly leave the group and is - * the only way to reliably identify the same peer across client restarts. + * This key will be permanently tied to a particular peer until they explicitly + * leave the group and is the only way to reliably identify the same peer across + * client restarts. * * `public_key` should have room for at least TOX_GROUP_PEER_PUBLIC_KEY_SIZE * bytes. If `public_key` is NULL this function has no effect. @@ -4086,7 +4165,8 @@ bool tox_group_peer_get_public_key( uint8_t public_key[TOX_PUBLIC_KEY_SIZE], Tox_Err_Group_Peer_Query *error); /** - * @param group_number The group number of the group the name change is intended for. + * @param group_number The group number of the group the name change is intended + * for. * @param peer_id The ID of the peer who has changed their name. * @param name The name data. * @param name_length The length of the name. @@ -4103,7 +4183,8 @@ typedef void tox_group_peer_name_cb( void tox_callback_group_peer_name(Tox *tox, tox_group_peer_name_cb *callback); /** - * @param group_number The group number of the group the status change is intended for. + * @param group_number The group number of the group the status change is + * intended for. * @param peer_id The ID of the peer who has changed their status. * @param status The new status of the peer. */ @@ -4168,7 +4249,8 @@ typedef enum Tox_Err_Group_Topic_Set { TOX_ERR_GROUP_TOPIC_SET_PERMISSIONS, /** - * The packet could not be created. This error is usually related to cryptographic signing. + * The packet could not be created. This error is usually related to + * cryptographic signing. */ TOX_ERR_GROUP_TOPIC_SET_FAIL_CREATE, @@ -4189,8 +4271,8 @@ const char *tox_err_group_topic_set_to_string(Tox_Err_Group_Topic_Set value); /** * Set the group topic and broadcast it to the rest of the group. * - * topic length cannot be longer than TOX_GROUP_MAX_TOPIC_LENGTH. If length is equal to zero or - * topic is set to NULL, the topic will be unset. + * Topic length cannot be longer than TOX_GROUP_MAX_TOPIC_LENGTH. If the length + * is equal to zero or topic is set to NULL, the topic will be unset. * * @return true on success. */ @@ -4211,7 +4293,8 @@ size_t tox_group_get_topic_size(const Tox *tox, Tox_Group_Number group_number, T /** * Write the topic designated by the given group number to a byte array. * - * Call tox_group_get_topic_size to determine the allocation size for the `topic` parameter. + * Call tox_group_get_topic_size to determine the allocation size for the + * `topic` parameter. * * The data written to `topic` is equal to the data received by the last * `group_topic` callback. @@ -4226,9 +4309,10 @@ bool tox_group_get_topic( uint8_t topic[], Tox_Err_Group_State_Query *error); /** - * @param group_number The group number of the group the topic change is intended for. - * @param peer_id The ID of the peer who changed the topic. If the peer who set the topic - * is not present in our peer list this value will be set to 0. + * @param group_number The group number of the group the topic change is + * intended for. + * @param peer_id The ID of the peer who changed the topic. If the peer who set + * the topic is not present in our peer list this value will be set to 0. * @param topic The topic data. * @param topic_length The topic length. */ @@ -4251,9 +4335,11 @@ void tox_callback_group_topic(Tox *tox, tox_group_topic_cb *callback); size_t tox_group_get_name_size(const Tox *tox, Tox_Group_Number group_number, Tox_Err_Group_State_Query *error); /** - * Write the name of the group designated by the given group number to a byte array. + * Write the name of the group designated by the given group number to a byte + * array. * - * Call tox_group_get_name_size to determine the allocation size for the `name` parameter. + * Call tox_group_get_name_size to determine the allocation size for the `name` + * parameter. * * @param name A valid memory region large enough to store the group name. * If this parameter is NULL, this function call has no effect. @@ -4284,19 +4370,21 @@ bool tox_group_get_chat_id( uint32_t tox_group_get_number_groups(const Tox *tox); /** - * Return the privacy state of the group designated by the given group number. If group number - * is invalid, the return value is unspecified. + * Return the privacy state of the group designated by the given group number. + * If group number is invalid, the return value is unspecified. * * The value returned is equal to the data received by the last * `group_privacy_state` callback. * - * @see the `Group chat founder controls` section for the respective set function. + * @see the `Group chat founder controls` section for the respective set + * function. */ Tox_Group_Privacy_State tox_group_get_privacy_state(const Tox *tox, Tox_Group_Number group_number, Tox_Err_Group_State_Query *error); /** - * @param group_number The group number of the group the privacy state is intended for. + * @param group_number The group number of the group the privacy state is + * intended for. * @param privacy_state The new privacy state. */ typedef void tox_group_privacy_state_cb(Tox *tox, Tox_Group_Number group_number, Tox_Group_Privacy_State privacy_state, @@ -4310,18 +4398,21 @@ typedef void tox_group_privacy_state_cb(Tox *tox, Tox_Group_Number group_number, void tox_callback_group_privacy_state(Tox *tox, tox_group_privacy_state_cb *callback); /** - * Return the voice state of the group designated by the given group number. If group number - * is invalid, the return value is unspecified. + * Return the voice state of the group designated by the given group number. If + * group number is invalid, the return value is unspecified. * - * The value returned is equal to the data received by the last `group_voice_state` callback. + * The value returned is equal to the data received by the last + * `group_voice_state` callback. * - * @see the `Group chat founder controls` section for the respective set function. + * @see the `Group chat founder controls` section for the respective set + * function. */ Tox_Group_Voice_State tox_group_get_voice_state(const Tox *tox, Tox_Group_Number group_number, Tox_Err_Group_State_Query *error); /** - * @param group_number The group number of the group the voice state change is intended for. + * @param group_number The group number of the group the voice state change is + * intended for. * @param voice_state The new voice state. */ typedef void tox_group_voice_state_cb(Tox *tox, Tox_Group_Number group_number, Tox_Group_Voice_State voice_state, @@ -4335,19 +4426,22 @@ typedef void tox_group_voice_state_cb(Tox *tox, Tox_Group_Number group_number, T void tox_callback_group_voice_state(Tox *tox, tox_group_voice_state_cb *callback); /** - * Return the topic lock status of the group designated by the given group number. If group number + * Return the topic lock status of the group designated by the given group + * number. If group number * is invalid, the return value is unspecified. * * The value returned is equal to the data received by the last * `group_topic_lock` callback. * - * @see the `Group chat founder contols` section for the respective set function. + * @see the `Group chat founder contols` section for the respective set + * function. */ Tox_Group_Topic_Lock tox_group_get_topic_lock(const Tox *tox, Tox_Group_Number group_number, Tox_Err_Group_State_Query *error); /** - * @param group_number The group number of the group for which the topic lock has changed. + * @param group_number The group number of the group for which the topic lock + * has changed. * @param topic_lock The new topic lock state. */ typedef void tox_group_topic_lock_cb(Tox *tox, Tox_Group_Number group_number, Tox_Group_Topic_Lock topic_lock, void *user_data); @@ -4360,18 +4454,21 @@ typedef void tox_group_topic_lock_cb(Tox *tox, Tox_Group_Number group_number, To void tox_callback_group_topic_lock(Tox *tox, tox_group_topic_lock_cb *callback); /** - * Return the maximum number of peers allowed for the group designated by the given group number. - * If the group number is invalid, the return value is unspecified. + * Return the maximum number of peers allowed for the group designated by the + * given group number. If the group number is invalid, the return value is + * unspecified. * * The value returned is equal to the data received by the last * `group_peer_limit` callback. * - * @see the `Group chat founder controls` section for the respective set function. + * @see the `Group chat founder controls` section for the respective set + * function. */ uint16_t tox_group_get_peer_limit(const Tox *tox, Tox_Group_Number group_number, Tox_Err_Group_State_Query *error); /** - * @param group_number The group number of the group for which the peer limit has changed. + * @param group_number The group number of the group for which the peer limit + * has changed. * @param peer_limit The new peer limit for the group. */ typedef void tox_group_peer_limit_cb(Tox *tox, Tox_Group_Number group_number, uint32_t peer_limit, void *user_data); @@ -4379,7 +4476,8 @@ typedef void tox_group_peer_limit_cb(Tox *tox, Tox_Group_Number group_number, ui /** * Set the callback for the `group_peer_limit` event. Pass NULL to unset. * - * This event is triggered when the group founder changes the maximum peer limit. + * This event is triggered when the group founder changes the maximum peer + * limit. */ void tox_callback_group_peer_limit(Tox *tox, tox_group_peer_limit_cb *callback); @@ -4390,17 +4488,20 @@ void tox_callback_group_peer_limit(Tox *tox, tox_group_peer_limit_cb *callback); size_t tox_group_get_password_size(const Tox *tox, Tox_Group_Number group_number, Tox_Err_Group_State_Query *error); /** - * Write the password for the group designated by the given group number to a byte array. + * Write the password for the group designated by the given group number to a + * byte array. * - * Call tox_group_get_password_size to determine the allocation size for the `password` parameter. + * Call tox_group_get_password_size to determine the allocation size for the + * `password` parameter. * - * The data received is equal to the data received by the last - * `group_password` callback. + * The data received is equal to the data received by the last `group_password` + * callback. * - * @see the `Group chat Founder controls` section for the respective set function. + * @see the `Group chat Founder controls` section for the respective set + * function. * - * @param password A valid memory region large enough to store the group password. - * If this parameter is NULL, this function call has no effect. + * @param password A valid memory region large enough to store the group + * password. If this parameter is NULL, this function call has no effect. * * @return true on success. */ @@ -4409,7 +4510,8 @@ bool tox_group_get_password( Tox_Err_Group_State_Query *error); /** - * @param group_number The group number of the group for which the password has changed. + * @param group_number The group number of the group for which the password has + * changed. * @param password The new group password. * @param password_length The length of the password. */ @@ -4483,11 +4585,12 @@ const char *tox_err_group_send_message_to_string(Tox_Err_Group_Send_Message valu * This function creates a group message packet and pushes it into the send * queue. * - * The message length may not exceed TOX_GROUP_MAX_MESSAGE_LENGTH. Larger messages - * must be split by the client and sent as separate messages. Other clients can - * then reassemble the fragments. Messages may not be empty. + * The message length may not exceed TOX_GROUP_MAX_MESSAGE_LENGTH. Larger + * messages must be split by the client and sent as separate messages. Other + * clients can then reassemble the fragments. Messages may not be empty. * - * @param group_number The group number of the group the message is intended for. + * @param group_number The group number of the group the message is intended + * for. * @param message_type Message type (normal, action, ...). * @param message A non-NULL pointer to the first element of a byte array * containing the message text. @@ -4555,14 +4658,15 @@ const char *tox_err_group_send_private_message_to_string(Tox_Err_Group_Send_Priv /** * Send a text chat message to the specified peer in the specified group. * - * This function creates a group private message packet and pushes it into the send - * queue. + * This function creates a group private message packet and pushes it into the + * send queue. * - * The message length may not exceed TOX_GROUP_MAX_MESSAGE_LENGTH. Larger messages - * must be split by the client and sent as separate messages. Other clients can - * then reassemble the fragments. Messages may not be empty. + * The message length may not exceed TOX_GROUP_MAX_MESSAGE_LENGTH. Larger + * messages must be split by the client and sent as separate messages. Other + * clients can then reassemble the fragments. Messages may not be empty. * - * @param group_number The group number of the group the message is intended for. + * @param group_number The group number of the group the message is intended + * for. * @param peer_id The ID of the peer the message is intended for. * @param message_type The type of message (normal, action, ...). * @param message A non-NULL pointer to the first element of a byte array @@ -4618,15 +4722,17 @@ const char *tox_err_group_send_custom_packet_to_string(Tox_Err_Group_Send_Custom /** * Send a custom packet to the group. * - * If lossless is true the packet will be lossless. Lossless packet behaviour is comparable - * to TCP (reliability, arrive in order) but with packets instead of a stream. + * If lossless is true the packet will be lossless. Lossless packet behaviour is + * comparable to TCP (reliability, arrive in order) but with packets instead of + * a stream. * - * If lossless is false, the packet will be lossy. Lossy packets behave like UDP packets, - * meaning they might never reach the other side or might arrive more than once (if someone - * is messing with the connection) or might arrive in the wrong order. + * If lossless is false, the packet will be lossy. Lossy packets behave like UDP + * packets, meaning they might never reach the other side or might arrive more + * than once (if someone is messing with the connection) or might arrive in the + * wrong order. * - * Unless latency is an issue or message reliability is not important, it is recommended that you use - * lossless packets. + * Unless latency is an issue or message reliability is not important, it is + * recommended that you use lossless packets. * * The message length may not exceed TOX_MAX_CUSTOM_PACKET_SIZE. Larger packets * must be split by the client and sent as separate packets. Other clients can @@ -4690,15 +4796,17 @@ const char *tox_err_group_send_custom_private_packet_to_string(Tox_Err_Group_Sen /** * Send a custom private packet to a designated peer in the group. * - * If lossless is true the packet will be lossless. Lossless packet behaviour is comparable - * to TCP (reliability, arrive in order) but with packets instead of a stream. + * If lossless is true the packet will be lossless. Lossless packet behaviour is + * comparable to TCP (reliability, arrive in order) but with packets instead of + * a stream. * - * If lossless is false, the packet will be lossy. Lossy packets behave like UDP packets, - * meaning they might never reach the other side or might arrive more than once (if someone - * is messing with the connection) or might arrive in the wrong order. + * If lossless is false, the packet will be lossy. Lossy packets behave like UDP + * packets, meaning they might never reach the other side or might arrive more + * than once (if someone is messing with the connection) or might arrive in the + * wrong order. * - * Unless latency is an issue or message reliability is not important, it is recommended that you use - * lossless packets. + * Unless latency is an issue or message reliability is not important, it is + * recommended that you use lossless packets. * * The packet length may not exceed TOX_MAX_CUSTOM_PACKET_SIZE. Larger packets * must be split by the client and sent as separate packets. Other clients can @@ -4723,12 +4831,14 @@ bool tox_group_send_custom_private_packet(const Tox *tox, Tox_Group_Number group ******************************************************************************/ /** - * @param group_number The group number of the group the message is intended for. + * @param group_number The group number of the group the message is intended + * for. * @param peer_id The ID of the peer who sent the message. * @param message_type The type of message (normal, action, ...). * @param message The message data. * @param message_length The length of the message. - * @param message_id A pseudo message id that clients can use to uniquely identify this group message. + * @param message_id A pseudo message id that clients can use to uniquely + * identify this group message. */ typedef void tox_group_message_cb( Tox *tox, Tox_Group_Number group_number, Tox_Group_Peer_Number peer_id, Tox_Message_Type message_type, @@ -4742,12 +4852,14 @@ typedef void tox_group_message_cb( void tox_callback_group_message(Tox *tox, tox_group_message_cb *callback); /** - * @param group_number The group number of the group the private message is intended for. + * @param group_number The group number of the group the private message is + * intended for. * @param peer_id The ID of the peer who sent the private message. * @param message_type The type of message (normal, action, ...). * @param message The message data. * @param message_length The length of the message. - * @param message_id A pseudo message id that clients can use to uniquely identify this group message. + * @param message_id A pseudo message id that clients can use to uniquely + * identify this group message. */ typedef void tox_group_private_message_cb( Tox *tox, Tox_Group_Number group_number, Tox_Group_Peer_Number peer_id, Tox_Message_Type message_type, @@ -4788,7 +4900,8 @@ typedef void tox_group_custom_private_packet_cb( const uint8_t data[], size_t data_length, void *user_data); /** - * Set the callback for the `group_custom_private_packet` event. Pass NULL to unset. + * Set the callback for the `group_custom_private_packet` event. Pass NULL to + * unset. * * This event is triggered when the client receives a custom private packet. */ @@ -4818,7 +4931,8 @@ typedef enum Tox_Err_Group_Invite_Friend { TOX_ERR_GROUP_INVITE_FRIEND_FRIEND_NOT_FOUND, /** - * Creation of the invite packet failed. This indicates a network related error. + * Creation of the invite packet failed. This indicates a network related + * error. */ TOX_ERR_GROUP_INVITE_FRIEND_INVITE_FAIL, @@ -4839,10 +4953,13 @@ const char *tox_err_group_invite_friend_to_string(Tox_Err_Group_Invite_Friend va /** * Invite a friend to a group. * - * This function creates an invite request packet and pushes it to the send queue. + * This function creates an invite request packet and pushes it to the send + * queue. * - * @param group_number The group number of the group the message is intended for. - * @param friend_number The friend number of the friend the invite is intended for. + * @param group_number The group number of the group the message is intended + * for. + * @param friend_number The friend number of the friend the invite is intended + * for. * * @return true on success. */ @@ -4878,7 +4995,8 @@ typedef enum Tox_Err_Group_Invite_Accept { TOX_ERR_GROUP_INVITE_ACCEPT_EMPTY, /** - * Failed to set password. This usually occurs if the password exceeds TOX_GROUP_MAX_PASSWORD_SIZE. + * Failed to set password. This usually occurs if the password exceeds + * TOX_GROUP_MAX_PASSWORD_SIZE. */ TOX_ERR_GROUP_INVITE_ACCEPT_PASSWORD, @@ -4897,17 +5015,19 @@ typedef enum Tox_Err_Group_Invite_Accept { const char *tox_err_group_invite_accept_to_string(Tox_Err_Group_Invite_Accept value); /** - * Accept an invite to a group chat that the client previously received from a friend. The invite - * is only valid while the inviter is present in the group. + * Accept an invite to a group chat that the client previously received from a + * friend. The invite is only valid while the inviter is present in the group. * * @param invite_data The invite data received from the `group_invite` event. * @param length The length of the invite data. * @param name The name of the peer joining the group. - * @param name_length The length of the peer's name. This must be greater than zero and no larger - * than TOX_MAX_NAME_LENGTH. - * @param password The password required to join the group. Set to NULL if no password is required. - * @param password_length The length of the password. If password_length is equal to zero, the password - * parameter will be ignored. password_length must be no larger than TOX_GROUP_MAX_PASSWORD_SIZE. + * @param name_length The length of the peer's name. This must be greater than + * zero and no larger than TOX_MAX_NAME_LENGTH. + * @param password The password required to join the group. Set to NULL if no + * password is required. + * @param password_length The length of the password. If password_length is + * equal to zero, the password parameter will be ignored. password_length + * must be no larger than TOX_GROUP_MAX_PASSWORD_SIZE. * * @return the group_number on success, UINT32_MAX on failure. */ @@ -4932,15 +5052,17 @@ typedef void tox_group_invite_cb( /** * Set the callback for the `group_invite` event. Pass NULL to unset. * - * This event is triggered when the client receives a group invite from a friend. The client must store - * invite_data which is used to join the group via tox_group_invite_accept. + * This event is triggered when the client receives a group invite from a + * friend. The client must store invite_data which is used to join the group + * via tox_group_invite_accept. */ void tox_callback_group_invite(Tox *tox, tox_group_invite_cb *callback); /** - * @param group_number The group number of the group in which a new peer has joined. - * @param peer_id The permanent ID of the new peer. This id should not be relied on for - * client behaviour and should be treated as a random value. + * @param group_number The group number of the group in which a new peer has + * joined. + * @param peer_id The permanent ID of the new peer. This id should not be relied + * on for client behaviour and should be treated as a random value. */ typedef void tox_group_peer_join_cb(Tox *tox, Tox_Group_Number group_number, Tox_Group_Peer_Number peer_id, void *user_data); @@ -4952,7 +5074,8 @@ typedef void tox_group_peer_join_cb(Tox *tox, Tox_Group_Number group_number, Tox void tox_callback_group_peer_join(Tox *tox, tox_group_peer_join_cb *callback); /** - * Represents peer exit events. These should be used with the `group_peer_exit` event. + * Represents peer exit events. These should be used with the `group_peer_exit` + * event. */ typedef enum Tox_Group_Exit_Type { @@ -4972,8 +5095,9 @@ typedef enum Tox_Group_Exit_Type { TOX_GROUP_EXIT_TYPE_DISCONNECTED, /** - * Your connection with all peers has been severed. This will occur when you are kicked from - * a group, rejoin a group, or manually disconnect from a group. + * Your connection with all peers has been severed. This will occur when you + * are kicked from a group, rejoin a group, or manually disconnect from a + * group. */ TOX_GROUP_EXIT_TYPE_SELF_DISCONNECTED, @@ -4993,8 +5117,8 @@ const char *tox_group_exit_type_to_string(Tox_Group_Exit_Type value); /** * @param group_number The group number of the group in which a peer has left. - * @param peer_id The ID of the peer who left the group. This ID no longer designates a valid peer - * and cannot be used for API calls. + * @param peer_id The ID of the peer who left the group. This ID no longer + * designates a valid peer and cannot be used for API calls. * @param exit_type The type of exit event. One of Tox_Group_Exit_Type. * @param name The nickname of the peer who left the group. * @param name_length The length of the peer name. @@ -5021,14 +5145,14 @@ typedef void tox_group_self_join_cb(Tox *tox, Tox_Group_Number group_number, voi /** * Set the callback for the `group_self_join` event. Pass NULL to unset. * - * This event is triggered when the client has successfully joined a group. Use this to initialize - * any group information the client may need. + * This event is triggered when the client has successfully joined a group. Use + * this to initialize any group information the client may need. */ void tox_callback_group_self_join(Tox *tox, tox_group_self_join_cb *callback); /** - * Represents types of failed group join attempts. These are used in the tox_callback_group_rejected - * callback when a peer fails to join a group. + * Represents types of failed group join attempts. These are used in the + * tox_callback_group_rejected callback when a peer fails to join a group. */ typedef enum Tox_Group_Join_Fail { @@ -5043,8 +5167,8 @@ typedef enum Tox_Group_Join_Fail { TOX_GROUP_JOIN_FAIL_INVALID_PASSWORD, /** - * The join attempt failed due to an unspecified error. This often occurs when the group is - * not found in the DHT. + * The join attempt failed due to an unspecified error. This often occurs + * when the group is not found in the DHT. */ TOX_GROUP_JOIN_FAIL_UNKNOWN, @@ -5053,7 +5177,8 @@ typedef enum Tox_Group_Join_Fail { const char *tox_group_join_fail_to_string(Tox_Group_Join_Fail value); /** - * @param group_number The group number of the group for which the join has failed. + * @param group_number The group number of the group for which the join has + * failed. * @param fail_type The type of group rejection. */ typedef void tox_group_join_fail_cb(Tox *tox, Tox_Group_Number group_number, Tox_Group_Join_Fail fail_type, void *user_data); @@ -5115,12 +5240,16 @@ const char *tox_err_group_set_password_to_string(Tox_Err_Group_Set_Password valu /** * Set or unset the group password. * - * This function allows Founders to set or unset a group password. It will create a new - * group shared state including the change and distribute it to the rest of the group. + * This function allows Founders to set or unset a group password. It will + * create a new group shared state including the change and distribute it to the + * rest of the group. * - * @param group_number The group number of the group for which we wish to set the password. - * @param password The password we want to set. Set password to NULL to unset the password. - * @param length The length of the password. length must be no longer than TOX_GROUP_MAX_PASSWORD_SIZE. + * @param group_number The group number of the group for which we wish to set + * the password. + * @param password The password we want to set. Set password to NULL to unset + * the password. + * @param length The length of the password. length must be no longer than + * TOX_GROUP_MAX_PASSWORD_SIZE. * * @return true on success. */ @@ -5152,8 +5281,8 @@ typedef enum Tox_Err_Group_Set_Topic_Lock { TOX_ERR_GROUP_SET_TOPIC_LOCK_PERMISSIONS, /** - * The topic lock could not be set. This may occur due to an error related to - * cryptographic signing of the new shared state. + * The topic lock could not be set. This may occur due to an error related + * to cryptographic signing of the new shared state. */ TOX_ERR_GROUP_SET_TOPIC_LOCK_FAIL_SET, @@ -5174,13 +5303,16 @@ const char *tox_err_group_set_topic_lock_to_string(Tox_Err_Group_Set_Topic_Lock /** * Set the group topic lock state. * - * This function allows Founders to enable or disable the group's topic lock. It will create a - * new shared state including the change and distribute it to the rest of the group. + * This function allows Founders to enable or disable the group's topic lock. It + * will create a new shared state including the change and distribute it to the + * rest of the group. * - * When the topic lock is enabled, only the group founder and moderators may set the topic. - * When disabled, all peers except those with the observer role may set the topic. + * When the topic lock is enabled, only the group founder and moderators may set + * the topic. When disabled, all peers except those with the observer role may + * set the topic. * - * @param group_number The group number of the group for which we wish to change the topic lock state. + * @param group_number The group number of the group for which we wish to change + * the topic lock state. * @param topic_lock The state we wish to set the topic lock to. * * @return true on success. @@ -5201,13 +5333,14 @@ typedef enum Tox_Err_Group_Set_Voice_State { TOX_ERR_GROUP_SET_VOICE_STATE_GROUP_NOT_FOUND, /** - * The caller does not have the required permissions to set the privacy state. + * The caller does not have the required permissions to set the privacy + * state. */ TOX_ERR_GROUP_SET_VOICE_STATE_PERMISSIONS, /** - * The voice state could not be set. This may occur due to an error related to - * cryptographic signing of the new shared state. + * The voice state could not be set. This may occur due to an error related + * to cryptographic signing of the new shared state. */ TOX_ERR_GROUP_SET_VOICE_STATE_FAIL_SET, @@ -5228,13 +5361,16 @@ const char *tox_err_group_set_voice_state_to_string(Tox_Err_Group_Set_Voice_Stat /** * Set the group voice state. * - * This function allows Founders to set the group's voice state. It will create a new group - * shared state including the change and distribute it to the rest of the group. + * This function allows Founders to set the group's voice state. It will create + * a new group shared state including the change and distribute it to the rest + * of the group. * - * If an attempt is made to set the voice state to the same state that the group is already - * in, the function call will be successful and no action will be taken. + * If an attempt is made to set the voice state to the same state that the group + * is already in, the function call will be successful and no action will be + * taken. * - * @param group_number The group number of the group for which we wish to change the voice state. + * @param group_number The group number of the group for which we wish to change + * the voice state. * @param voice_state The voice state we wish to set the group to. * * @return true on success. @@ -5255,13 +5391,14 @@ typedef enum Tox_Err_Group_Set_Privacy_State { TOX_ERR_GROUP_SET_PRIVACY_STATE_GROUP_NOT_FOUND, /** - * The caller does not have the required permissions to set the privacy state. + * The caller does not have the required permissions to set the privacy + * state. */ TOX_ERR_GROUP_SET_PRIVACY_STATE_PERMISSIONS, /** - * The privacy state could not be set. This may occur due to an error related to - * cryptographic signing of the new shared state. + * The privacy state could not be set. This may occur due to an error + * related to cryptographic signing of the new shared state. */ TOX_ERR_GROUP_SET_PRIVACY_STATE_FAIL_SET, @@ -5282,13 +5419,16 @@ const char *tox_err_group_set_privacy_state_to_string(Tox_Err_Group_Set_Privacy_ /** * Set the group privacy state. * - * This function allows Founders to set the group's privacy state. It will create a new group - * shared state including the change and distribute it to the rest of the group. + * This function allows Founders to set the group's privacy state. It will + * create a new group shared state including the change and distribute it to the + * rest of the group. * - * If an attempt is made to set the privacy state to the same state that the group is already - * in, the function call will be successful and no action will be taken. + * If an attempt is made to set the privacy state to the same state that the + * group is already in, the function call will be successful and no action will + * be taken. * - * @param group_number The group number of the group for which we wish to change the privacy state. + * @param group_number The group number of the group for which we wish to change + * the privacy state. * @param privacy_state The privacy state we wish to set the group to. * * @return true on success. @@ -5314,8 +5454,8 @@ typedef enum Tox_Err_Group_Set_Peer_Limit { TOX_ERR_GROUP_SET_PEER_LIMIT_PERMISSIONS, /** - * The peer limit could not be set. This may occur due to an error related to - * cryptographic signing of the new shared state. + * The peer limit could not be set. This may occur due to an error related + * to cryptographic signing of the new shared state. */ TOX_ERR_GROUP_SET_PEER_LIMIT_FAIL_SET, @@ -5336,11 +5476,12 @@ const char *tox_err_group_set_peer_limit_to_string(Tox_Err_Group_Set_Peer_Limit /** * Set the group peer limit. * - * This function allows Founders to set a limit for the number of peers who may be in the - * group. It will create a new group shared state including the change and distribute it to the - * rest of the group. + * This function allows Founders to set a limit for the number of peers who may + * be in the group. It will create a new group shared state including the change + * and distribute it to the rest of the group. * - * @param group_number The group number of the group for which we wish to set the peer limit. + * @param group_number The group number of the group for which we wish to set + * the peer limit. * @param peer_limit The maximum number of peers to allow in the group. * * @return true on success. @@ -5383,7 +5524,8 @@ const char *tox_err_group_set_ignore_to_string(Tox_Err_Group_Set_Ignore value); /** * Ignore or unignore a peer. * - * @param group_number The group number of the group in which you wish to ignore a peer. + * @param group_number The group number of the group in which you wish to ignore + * a peer. * @param peer_id The ID of the peer who shall be ignored or unignored. * @param ignore True to ignore the peer, false to unignore the peer. * @@ -5405,7 +5547,8 @@ typedef enum Tox_Err_Group_Set_Role { TOX_ERR_GROUP_SET_ROLE_GROUP_NOT_FOUND, /** - * The ID passed did not designate a valid peer. Note: you cannot set your own role. + * The ID passed did not designate a valid peer. Note: you cannot set your + * own role. */ TOX_ERR_GROUP_SET_ROLE_PEER_NOT_FOUND, @@ -5415,14 +5558,14 @@ typedef enum Tox_Err_Group_Set_Role { TOX_ERR_GROUP_SET_ROLE_PERMISSIONS, /** - * The role assignment is invalid. This will occur if you try to set a peer's role to - * the role they already have. + * The role assignment is invalid. This will occur if you try to set a + * peer's role to the role they already have. */ TOX_ERR_GROUP_SET_ROLE_ASSIGNMENT, /** - * The role was not successfully set. This may occur if the packet failed to send, or - * if the role limit has been reached. + * The role was not successfully set. This may occur if the packet failed to + * send, or if the role limit has been reached. */ TOX_ERR_GROUP_SET_ROLE_FAIL_ACTION, @@ -5438,15 +5581,17 @@ const char *tox_err_group_set_role_to_string(Tox_Err_Group_Set_Role value); /** * Set a peer's role. * - * This function will first remove the peer's previous role and then assign them a new role. - * It will also send a packet to the rest of the group, requesting that they perform - * the role reassignment. + * This function will first remove the peer's previous role and then assign them + * a new role. It will also send a packet to the rest of the group, requesting + * that they perform the role reassignment. * - * Only Founders may promote peers to the Moderator role, and only Founders and Moderators may - * set peers to the Observer or User role. Moderators may not set the role of other Moderators - * or the Founder. Peers may not be promoted to the Founder role. + * Only Founders may promote peers to the Moderator role, and only Founders and + * Moderators may set peers to the Observer or User role. Moderators may not set + * the role of other Moderators or the Founder. Peers may not be promoted to the + * Founder role. * - * @param group_number The group number of the group the in which you wish set the peer's role. + * @param group_number The group number of the group the in which you wish set + * the peer's role. * @param peer_id The ID of the peer whose role you wish to set. * @param role The role you wish to set the peer to. * @@ -5499,10 +5644,12 @@ const char *tox_err_group_kick_peer_to_string(Tox_Err_Group_Kick_Peer value); /** * Kick a peer. * - * This function allows peers with the Founder or Moderator role to silently instruct - * all other peers in the group to remove a particular peer from their peer list. + * This function allows peers with the Founder or Moderator role to silently + * instruct all other peers in the group to remove a particular peer from their + * peer list. * - * Note: This function will not trigger the `group_peer_exit` event for the caller. + * Note: This function will not trigger the `group_peer_exit` event for the + * caller. * * @param group_number The group number of the group the action is intended for. * @param peer_id The ID of the peer who will be kicked. @@ -5513,7 +5660,8 @@ bool tox_group_kick_peer(const Tox *tox, Tox_Group_Number group_number, Tox_Grou Tox_Err_Group_Kick_Peer *error); /** - * Represents moderation events. These should be used with the `group_moderation` event. + * Represents moderation events. These should be used with the + * `group_moderation` event. */ typedef enum Tox_Group_Mod_Event { @@ -5554,12 +5702,13 @@ typedef void tox_group_moderation_cb( /** * Set the callback for the `group_moderation` event. Pass NULL to unset. * - * This event is triggered when a moderator or founder executes a moderation event, with - * the exception of the peer who initiates the event. It is also triggered when the - * observer and moderator lists are silently modified (this may occur during group syncing). + * This event is triggered when a moderator or founder executes a moderation + * event, with the exception of the peer who initiates the event. It is also + * triggered when the observer and moderator lists are silently modified (this + * may occur during group syncing). * - * If either peer id does not designate a valid peer in the group chat, the client should - * manually update all peer roles. + * If either peer id does not designate a valid peer in the group chat, the + * client should manually update all peer roles. */ void tox_callback_group_moderation(Tox *tox, tox_group_moderation_cb *callback); diff --git a/toxcore/tox_private.h b/toxcore/tox_private.h index 92f30d092d..297324db24 100644 --- a/toxcore/tox_private.h +++ b/toxcore/tox_private.h @@ -34,22 +34,22 @@ void tox_unlock(const Tox *tox); const Tox_System *tox_get_system(Tox *tox); /** - * Set the callback for the `friend_lossy_packet` event for a specific packet ID. - * Pass NULL to unset. + * Set the callback for the `friend_lossy_packet` event for a specific packet + * ID. Pass NULL to unset. * * allowed packet ID range: - * from `PACKET_ID_RANGE_LOSSY_START` to `PACKET_ID_RANGE_LOSSY_END` (both inclusive) + * from `PACKET_ID_RANGE_LOSSY_START` to `PACKET_ID_RANGE_LOSSY_END` (both + * inclusive) */ void tox_callback_friend_lossy_packet_per_pktid(Tox *tox, tox_friend_lossy_packet_cb *callback, uint8_t pktid); /** - * Set the callback for the `friend_lossless_packet` event for a specific packet ID. - * Pass NULL to unset. + * Set the callback for the `friend_lossless_packet` event for a specific packet + * ID. Pass NULL to unset. * * allowed packet ID range: - * from `PACKET_ID_RANGE_LOSSLESS_CUSTOM_START` to `PACKET_ID_RANGE_LOSSLESS_CUSTOM_END` (both inclusive) - * and - * `PACKET_ID_MSI` + * from `PACKET_ID_RANGE_LOSSLESS_CUSTOM_START` to + * `PACKET_ID_RANGE_LOSSLESS_CUSTOM_END` (both inclusive) and `PACKET_ID_MSI` */ void tox_callback_friend_lossless_packet_per_pktid(Tox *tox, tox_friend_lossless_packet_cb *callback, uint8_t pktid); @@ -98,7 +98,8 @@ typedef enum Tox_Err_Dht_Get_Nodes { TOX_ERR_DHT_GET_NODES_OK, /** - * UDP is disabled in Tox options; the DHT can only be queried when UDP is enabled. + * UDP is disabled in Tox options; the DHT can only be queried when UDP is + * enabled. */ TOX_ERR_DHT_GET_NODES_UDP_DISABLED, @@ -118,21 +119,24 @@ typedef enum Tox_Err_Dht_Get_Nodes { TOX_ERR_DHT_GET_NODES_BAD_IP, /** - * The getnodes request failed. This usually means the packet failed to send. + * The getnodes request failed. This usually means the packet failed to + * send. */ TOX_ERR_DHT_GET_NODES_FAIL, } Tox_Err_Dht_Get_Nodes; /** * This function sends a getnodes request to a DHT node for its peers that - * are "close" to the passed target public key according to the distance metric used - * by the DHT implementation. + * are "close" to the passed target public key according to the distance metric + * used by the DHT implementation. * - * @param public_key The public key of the node that we wish to query. This key must be - * at least `TOX_DHT_NODE_PUBLIC_KEY_SIZE` bytes in length. - * @param ip A NULL terminated string representing the IP address of the node we wish to query. + * @param public_key The public key of the node that we wish to query. This key + * must be at least `TOX_DHT_NODE_PUBLIC_KEY_SIZE` bytes in length. + * @param ip A 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. + * @param target_public_key The public key for which we want to find close + * nodes. * * @return true on success. */ @@ -140,8 +144,9 @@ bool tox_dht_get_nodes(const Tox *tox, const uint8_t *public_key, const char *ip const uint8_t *target_public_key, Tox_Err_Dht_Get_Nodes *error); /** - * This function returns the ratio of close dht nodes that are known to support announce/store. - * This function returns the number of DHT nodes in the closelist. + * This function returns the ratio of close dht nodes that are known to support + * announce/store. This function returns the number of DHT nodes in the + * closelist. * * @return number */ @@ -169,30 +174,32 @@ uint16_t tox_dht_get_num_closelist_announce_capable(const Tox *tox); uint32_t tox_group_peer_ip_string_max_length(void); /** - * Return the length of the peer's IP address in string form. If the group number or ID - * is invalid, the return value is unspecified. + * Return the length of the peer's IP address in string form. If the group + * number or ID is invalid, the return value is unspecified. * * @param group_number The group number of the group we wish to query. - * @param peer_id The ID of the peer whose IP address length we want to retrieve. + * @param peer_id The ID of the peer whose IP address length we want to + * retrieve. */ size_t tox_group_peer_get_ip_address_size(const Tox *tox, uint32_t group_number, uint32_t peer_id, Tox_Err_Group_Peer_Query *error); /** - * Write the IP address associated with the designated peer_id for the designated group number - * to ip_addr. + * Write the IP address associated with the designated peer_id for the + * designated group number to ip_addr. * - * If the peer is forcing TCP connections a placeholder value will be written instead, - * indicating that their real IP address is unknown to us. + * If the peer is forcing TCP connections a placeholder value will be written + * instead, indicating that their real IP address is unknown to us. * - * If `peer_id` designates ourself, it will write either our own IP address or a placeholder value, - * depending on whether or not we're forcing TCP connections. + * If `peer_id` designates ourself, it will write either our own IP address or a + * placeholder value, depending on whether or not we're forcing TCP connections. * - * Call tox_group_peer_get_ip_address_size to determine the allocation size for the `ip_addr` parameter. + * Call tox_group_peer_get_ip_address_size to determine the allocation size for + * the `ip_addr` parameter. * * @param group_number The group number of the group we wish to query. * @param peer_id The ID of the peer whose public key we wish to retrieve. - * @param ip_addr A valid memory region large enough to store the IP address string. - * If this parameter is NULL, this function call has no effect. + * @param ip_addr A valid memory region large enough to store the IP address + * string. If this parameter is NULL, this function call has no effect. * * @return true on success. */ diff --git a/toxencryptsave/toxencryptsave.c b/toxencryptsave/toxencryptsave.c index c43e357528..f3b88770c1 100644 --- a/toxencryptsave/toxencryptsave.c +++ b/toxencryptsave/toxencryptsave.c @@ -67,7 +67,8 @@ void tox_pass_key_free(Tox_Pass_Key *key) * produce the same key as was previously used. Any data encrypted with this * module can be used as input. * - * The cipher text must be at least TOX_PASS_ENCRYPTION_EXTRA_LENGTH bytes in length. + * The cipher text must be at least TOX_PASS_ENCRYPTION_EXTRA_LENGTH bytes in + * length. * The salt must be TOX_PASS_SALT_LENGTH bytes in length. * If the passed byte arrays are smaller than required, the behaviour is * undefined. @@ -182,10 +183,11 @@ Tox_Pass_Key *tox_pass_key_derive_with_salt( } /** - * Encrypt a plain text with a key produced by tox_pass_key_derive or tox_pass_key_derive_with_salt. + * Encrypt a plain text with a key produced by tox_pass_key_derive or + * tox_pass_key_derive_with_salt. * - * The output array must be at least `plaintext_len + TOX_PASS_ENCRYPTION_EXTRA_LENGTH` - * bytes long. + * The output array must be at least + * `plaintext_len + TOX_PASS_ENCRYPTION_EXTRA_LENGTH` bytes long. * * @param plaintext A byte array of length `plaintext_len`. * @param plaintext_len The length of the plain text array. Bigger than 0. @@ -242,9 +244,9 @@ bool tox_pass_key_encrypt(const Tox_Pass_Key *key, const uint8_t plaintext[], si /** * Encrypts the given data with the given passphrase. * - * The output array must be at least `plaintext_len + TOX_PASS_ENCRYPTION_EXTRA_LENGTH` - * bytes long. This delegates to tox_pass_key_derive and - * tox_pass_key_encrypt. + * The output array must be at least + * `plaintext_len + TOX_PASS_ENCRYPTION_EXTRA_LENGTH` bytes long. This delegates + * to tox_pass_key_derive and tox_pass_key_encrypt. * * @param plaintext A byte array of length `plaintext_len`. * @param plaintext_len The length of the plain text array. Bigger than 0. @@ -280,7 +282,8 @@ bool tox_pass_encrypt(const uint8_t plaintext[], size_t plaintext_len, const uin * tox_pass_key_derive or tox_pass_key_derive_with_salt. * * @param ciphertext A byte array of length `ciphertext_len`. - * @param ciphertext_len The length of the cipher text array. At least TOX_PASS_ENCRYPTION_EXTRA_LENGTH. + * @param ciphertext_len The length of the cipher text array. At least + * TOX_PASS_ENCRYPTION_EXTRA_LENGTH. * @param plaintext The plain text array to write the decrypted data to. * * @return true on success. @@ -326,11 +329,13 @@ bool tox_pass_key_decrypt(const Tox_Pass_Key *key, const uint8_t ciphertext[], s /** * Decrypts the given data with the given passphrase. * - * The output array must be at least `ciphertext_len - TOX_PASS_ENCRYPTION_EXTRA_LENGTH` - * bytes long. This delegates to tox_pass_key_decrypt. + * The output array must be at least + * `ciphertext_len - TOX_PASS_ENCRYPTION_EXTRA_LENGTH` bytes long. This + * delegates to tox_pass_key_decrypt. * * @param ciphertext A byte array of length `ciphertext_len`. - * @param ciphertext_len The length of the cipher text array. At least TOX_PASS_ENCRYPTION_EXTRA_LENGTH. + * @param ciphertext_len The length of the cipher text array. At least + * TOX_PASS_ENCRYPTION_EXTRA_LENGTH. * @param passphrase The user-provided password. Can be empty. * @param passphrase_len The length of the password. * @param plaintext The plain text array to write the decrypted data to. diff --git a/toxencryptsave/toxencryptsave.h b/toxencryptsave/toxencryptsave.h index b9691551c7..e4cf116c97 100644 --- a/toxencryptsave/toxencryptsave.h +++ b/toxencryptsave/toxencryptsave.h @@ -1,5 +1,5 @@ /* SPDX-License-Identifier: GPL-3.0-or-later - * Copyright © 2016-2018 The TokTok team. + * Copyright © 2016-2024 The TokTok team. * Copyright © 2013-2016 Tox Developers. */ @@ -165,9 +165,9 @@ typedef enum Tox_Err_Decryption { /** * Encrypts the given data with the given passphrase. * - * The output array must be at least `plaintext_len + TOX_PASS_ENCRYPTION_EXTRA_LENGTH` - * bytes long. This delegates to tox_pass_key_derive and - * tox_pass_key_encrypt. + * The output array must be at least + * `plaintext_len + TOX_PASS_ENCRYPTION_EXTRA_LENGTH` bytes long. This delegates + * to tox_pass_key_derive and tox_pass_key_encrypt. * * @param plaintext A byte array of length `plaintext_len`. * @param plaintext_len The length of the plain text array. Bigger than 0. @@ -183,11 +183,13 @@ bool tox_pass_encrypt(const uint8_t plaintext[], size_t plaintext_len, const uin /** * Decrypts the given data with the given passphrase. * - * The output array must be at least `ciphertext_len - TOX_PASS_ENCRYPTION_EXTRA_LENGTH` - * bytes long. This delegates to tox_pass_key_decrypt. + * The output array must be at least + * `ciphertext_len - TOX_PASS_ENCRYPTION_EXTRA_LENGTH` bytes long. This + * delegates to tox_pass_key_decrypt. * * @param ciphertext A byte array of length `ciphertext_len`. - * @param ciphertext_len The length of the cipher text array. At least TOX_PASS_ENCRYPTION_EXTRA_LENGTH. + * @param ciphertext_len The length of the cipher text array. At least + * TOX_PASS_ENCRYPTION_EXTRA_LENGTH. * @param passphrase The user-provided password. Can be empty. * @param passphrase_len The length of the password. * @param plaintext The plain text array to write the decrypted data to. @@ -215,7 +217,8 @@ bool tox_pass_decrypt(const uint8_t ciphertext[], size_t ciphertext_len, const u * user-provided password. * * The Tox_Pass_Key structure is hidden in the implementation. It can be created - * using tox_pass_key_derive or tox_pass_key_derive_with_salt and must be deallocated using tox_pass_key_free. + * using tox_pass_key_derive or tox_pass_key_derive_with_salt and must be + * deallocated using tox_pass_key_free. */ #ifndef TOX_PASS_KEY_DEFINED #define TOX_PASS_KEY_DEFINED @@ -261,10 +264,11 @@ Tox_Pass_Key *tox_pass_key_derive_with_salt( const uint8_t salt[TOX_PASS_SALT_LENGTH], Tox_Err_Key_Derivation *error); /** - * Encrypt a plain text with a key produced by tox_pass_key_derive or tox_pass_key_derive_with_salt. + * Encrypt a plain text with a key produced by tox_pass_key_derive or + * tox_pass_key_derive_with_salt. * - * The output array must be at least `plaintext_len + TOX_PASS_ENCRYPTION_EXTRA_LENGTH` - * bytes long. + * The output array must be at least + * `plaintext_len + TOX_PASS_ENCRYPTION_EXTRA_LENGTH` bytes long. * * @param plaintext A byte array of length `plaintext_len`. * @param plaintext_len The length of the plain text array. Bigger than 0. @@ -280,7 +284,8 @@ bool tox_pass_key_encrypt(const Tox_Pass_Key *key, const uint8_t plaintext[], si * tox_pass_key_derive or tox_pass_key_derive_with_salt. * * @param ciphertext A byte array of length `ciphertext_len`. - * @param ciphertext_len The length of the cipher text array. At least TOX_PASS_ENCRYPTION_EXTRA_LENGTH. + * @param ciphertext_len The length of the cipher text array. At least + * TOX_PASS_ENCRYPTION_EXTRA_LENGTH. * @param plaintext The plain text array to write the decrypted data to. * * @return true on success. @@ -315,7 +320,8 @@ typedef enum Tox_Err_Get_Salt { * produce the same key as was previously used. Any data encrypted with this * module can be used as input. * - * The cipher text must be at least TOX_PASS_ENCRYPTION_EXTRA_LENGTH bytes in length. + * The cipher text must be at least TOX_PASS_ENCRYPTION_EXTRA_LENGTH bytes in + * length. * The salt must be TOX_PASS_SALT_LENGTH bytes in length. * If the passed byte arrays are smaller than required, the behaviour is * undefined. From be085db19194034c7b17474d6877781f1ca326c8 Mon Sep 17 00:00:00 2001 From: Maxim Biro Date: Sun, 10 Mar 2024 14:08:27 -0400 Subject: [PATCH 09/13] docs: Public headers, spellcheck --- toxav/toxav.h | 6 +++--- toxcore/tox.h | 12 ++++++------ toxcore/tox_private.h | 2 +- 3 files changed, 10 insertions(+), 10 deletions(-) diff --git a/toxav/toxav.h b/toxav/toxav.h index 57a7ccf741..98001481cd 100644 --- a/toxav/toxav.h +++ b/toxav/toxav.h @@ -39,7 +39,7 @@ * ToxAV thread (see above). Audio and video receive frame events are triggered * from ToxAV thread while all the other events are triggered from Tox thread. * - * Tox thread has priority with mutex mechanisms. Any api function can + * Tox thread has priority with mutex mechanisms. Any API function can * fail if mutexes are held by Tox thread in which case they will set SYNC * error code. * @@ -566,7 +566,7 @@ typedef enum Toxav_Err_Send_Frame { TOXAV_ERR_SEND_FRAME_PAYLOAD_TYPE_DISABLED, /** - * Failed to push frame through rtp interface. + * Failed to push frame through RTP interface. */ TOXAV_ERR_SEND_FRAME_RTP_FAILED, @@ -588,7 +588,7 @@ typedef enum Toxav_Err_Send_Frame { * `sample_count * channels`. * @param sample_count Number of samples in this frame. Valid numbers here are * `((sample rate) * (audio length) / 1000)`, where audio length can be - * 2.5, 5, 10, 20, 40 or 60 millseconds. + * 2.5, 5, 10, 20, 40 or 60 milliseconds. * @param channels Number of audio channels. Supported values are 1 and 2. * @param sampling_rate Audio sampling rate used in this frame. Valid sampling * rates are 8000, 12000, 16000, 24000, or 48000. diff --git a/toxcore/tox.h b/toxcore/tox.h index b74071a326..32cb299c3a 100644 --- a/toxcore/tox.h +++ b/toxcore/tox.h @@ -1587,7 +1587,7 @@ void tox_callback_friend_name(Tox *tox, tox_friend_name_cb *callback); /** * @brief Return the length of the friend's status message. * - * If the friend number isinvalid, the return value is SIZE_MAX. + * If the friend number is invalid, the return value is SIZE_MAX. */ size_t tox_friend_get_status_message_size( const Tox *tox, Tox_Friend_Number friend_number, Tox_Err_Friend_Query *error); @@ -2260,7 +2260,7 @@ const char *tox_err_file_send_to_string(Tox_Err_File_Send value); * - If the file size was decreased * - and sending mode was streaming, the behaviour is as expected. * - and sending mode was file, the callback will return 0 at the new - * (earlier) end-of-file, signalling to the friend that the transfer was + * (earlier) end-of-file, signaling to the friend that the transfer was * cancelled. * - If the file contents were modified * - at a position before the current read, the two files (local and remote) @@ -4376,7 +4376,7 @@ uint32_t tox_group_get_number_groups(const Tox *tox); * The value returned is equal to the data received by the last * `group_privacy_state` callback. * - * @see the `Group chat founder controls` section for the respective set + * @see the `Group chat Founder controls` section for the respective set * function. */ Tox_Group_Privacy_State tox_group_get_privacy_state(const Tox *tox, Tox_Group_Number group_number, @@ -4404,7 +4404,7 @@ void tox_callback_group_privacy_state(Tox *tox, tox_group_privacy_state_cb *call * The value returned is equal to the data received by the last * `group_voice_state` callback. * - * @see the `Group chat founder controls` section for the respective set + * @see the `Group chat Founder controls` section for the respective set * function. */ Tox_Group_Voice_State tox_group_get_voice_state(const Tox *tox, Tox_Group_Number group_number, @@ -4433,7 +4433,7 @@ void tox_callback_group_voice_state(Tox *tox, tox_group_voice_state_cb *callback * The value returned is equal to the data received by the last * `group_topic_lock` callback. * - * @see the `Group chat founder contols` section for the respective set + * @see the `Group chat Founder controls` section for the respective set * function. */ Tox_Group_Topic_Lock tox_group_get_topic_lock(const Tox *tox, Tox_Group_Number group_number, @@ -4461,7 +4461,7 @@ void tox_callback_group_topic_lock(Tox *tox, tox_group_topic_lock_cb *callback); * The value returned is equal to the data received by the last * `group_peer_limit` callback. * - * @see the `Group chat founder controls` section for the respective set + * @see the `Group chat Founder controls` section for the respective set * function. */ uint16_t tox_group_get_peer_limit(const Tox *tox, Tox_Group_Number group_number, Tox_Err_Group_State_Query *error); diff --git a/toxcore/tox_private.h b/toxcore/tox_private.h index 297324db24..c2f875f844 100644 --- a/toxcore/tox_private.h +++ b/toxcore/tox_private.h @@ -154,7 +154,7 @@ uint16_t tox_dht_get_num_closelist(const Tox *tox); /** * This function returns the number of DHT nodes in the closelist, - * that are capable to store annouce data (introduced in version 0.2.18). + * that are capable to store announce data (introduced in version 0.2.18). * * @return number */ From 817518949e723ad1d57eecd65885a39d44b18ec7 Mon Sep 17 00:00:00 2001 From: Maxim Biro Date: Sun, 10 Mar 2024 14:16:45 -0400 Subject: [PATCH 10/13] docs: Public headers, NULL-terminated -> NUL-terminated Matching the way tox.h words it. --- toxcore/tox_private.h | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/toxcore/tox_private.h b/toxcore/tox_private.h index c2f875f844..ac6fd4fa77 100644 --- a/toxcore/tox_private.h +++ b/toxcore/tox_private.h @@ -78,7 +78,7 @@ uint32_t tox_dht_node_public_key_size(void); /** * @param public_key The node's public key. - * @param ip The node's IP address, represented as a NULL terminated string. + * @param ip The node's IP address, represented as a NUL-terminated C string. * @param port The node's port. */ typedef void tox_dht_get_nodes_response_cb(Tox *tox, const uint8_t *public_key, const char *ip, uint16_t port, @@ -132,8 +132,8 @@ typedef enum Tox_Err_Dht_Get_Nodes { * * @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 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. From f78d0f3f39db886a1b0111027d92afa792b1b6e1 Mon Sep 17 00:00:00 2001 From: Maxim Biro Date: Sun, 10 Mar 2024 19:19:56 -0400 Subject: [PATCH 11/13] docs: Public headers, events_alloc -> internal --- toxcore/tox.h | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/toxcore/tox.h b/toxcore/tox.h index 32cb299c3a..acad229474 100644 --- a/toxcore/tox.h +++ b/toxcore/tox.h @@ -459,13 +459,12 @@ typedef enum Tox_Log_Level { TOX_LOG_LEVEL_INFO, /** - * Warnings about events_alloc inconsistency or logic errors. + * Warnings about internal inconsistency or logic errors. */ TOX_LOG_LEVEL_WARNING, /** - * Severe unexpected errors caused by external or events_alloc - * inconsistency. + * Severe unexpected errors caused by external or internal inconsistency. */ TOX_LOG_LEVEL_ERROR, @@ -474,7 +473,7 @@ typedef enum Tox_Log_Level { const char *tox_log_level_to_string(Tox_Log_Level value); /** - * @brief This event is triggered when the toxcore library logs an events_alloc + * @brief This event is triggered when the toxcore library logs an internal * message. * * This is mostly useful for debugging. This callback can be called from any @@ -834,7 +833,7 @@ typedef enum Tox_Err_New { /** * The function was unable to allocate enough memory to store the - * events_alloc structures for the Tox object. + * internal structures for the Tox object. */ TOX_ERR_NEW_MALLOC, @@ -1921,7 +1920,7 @@ typedef uint32_t Tox_File_Number; * If hash is NULL or data is NULL while length is not 0 the function returns * false, otherwise it returns true. * - * This function is a wrapper to events_alloc message-digest functions. + * This function is a wrapper to internal message-digest functions. * * @param hash A valid memory location the hash data. It must be at least * TOX_HASH_LENGTH bytes in size. From a3d1b8595cef1a8f005fac3a56e6e3a7baa37bce Mon Sep 17 00:00:00 2001 From: Maxim Biro Date: Sun, 10 Mar 2024 19:57:36 -0400 Subject: [PATCH 12/13] docs: Public headers, Core/toxcore -> Tox/the Tox library Toxcore public header documentation suffers from an identity crisis. It calls itself three different things: Tox, toxcore and Core, depending on the time period the comment was written in, the author of the comment, whether the comment refers to the Tox instance or the Tox[core] library (it doesn't seem like anything refers to the Tox protocol?), and maybe some other nuances. No one really calls it Core though, so this commit replaces the use of Core with Tox/toxcore, and edits other instances of the documentation referring to the library where I thought rewording was in order, though in the end it's more of a subjective personal preference. --- toxav/toxav.h | 14 +++++++------- toxcore/tox.h | 45 ++++++++++++++++++++++----------------------- 2 files changed, 29 insertions(+), 30 deletions(-) diff --git a/toxav/toxav.h b/toxav/toxav.h index 98001481cd..3b4bd09c23 100644 --- a/toxav/toxav.h +++ b/toxav/toxav.h @@ -12,14 +12,14 @@ * * @section av_events Events and callbacks * - * As in Core API, events are handled by callbacks. One callback can be + * As in the toxcore API, events are handled by callbacks. One callback can be * registered per event. All events have a callback function type named * `toxav_{event}_cb` and a function to register it named * `toxav_callback_{event}`. Passing a NULL callback will result in no callback * being registered for that event. Only one callback per event can be * registered, so if a client needs multiple event listeners, it needs to - * implement the dispatch functionality itself. Unlike Core API, lack of some - * event handlers will cause the the library to drop calls before they are + * implement the dispatch functionality itself. Unlike the toxcore API, lack of + * some event handlers will cause the the library to drop calls before they are * started. Hanging up call from a callback causes undefined behaviour. * * @section av_threading Threading implications @@ -609,8 +609,8 @@ bool toxav_audio_set_bit_rate(ToxAV *av, uint32_t friend_number, uint32_t bit_ra /** * The function type for the audio_bit_rate callback. The event is triggered - * when the network becomes too saturated for current bit rates at which - * point core suggests new bit rates. + * when the network becomes too saturated for current bit rates at which point + * ToxAV suggests new bit rates. * * @param friend_number The friend number of the friend for which to set the * bit rate. @@ -659,8 +659,8 @@ bool toxav_video_set_bit_rate(ToxAV *av, uint32_t friend_number, uint32_t bit_ra /** * The function type for the video_bit_rate callback. The event is triggered - * when the network becomes too saturated for current bit rates at which - * point core suggests new bit rates. + * when the network becomes too saturated for current bit rates at which point + * ToxAV suggests new bit rates. * * @param friend_number The friend number of the friend for which to set the * bit rate. diff --git a/toxcore/tox.h b/toxcore/tox.h index acad229474..5e1be14a28 100644 --- a/toxcore/tox.h +++ b/toxcore/tox.h @@ -197,7 +197,7 @@ bool tox_version_is_compatible(uint32_t major, uint32_t minor, uint32_t patch); * * The values of these are not part of the ABI. Prefer to use the function * versions of them for code that should remain compatible with future versions - * of toxcore. + * of the Tox library. */ /** @@ -473,8 +473,7 @@ typedef enum Tox_Log_Level { const char *tox_log_level_to_string(Tox_Log_Level value); /** - * @brief This event is triggered when the toxcore library logs an internal - * message. + * @brief This event is triggered when Tox logs an internal message. * * This is mostly useful for debugging. This callback can be called from any * function, not just tox_iterate. This means the user data lifetime must at @@ -541,8 +540,8 @@ struct Tox_Options { * need to be relayed through a TCP relay node, potentially slowing them * down. * - * If a proxy is enabled, UDP will be disabled if either toxcore or the - * proxy don't support proxying UDP messages. + * If a proxy is enabled, UDP will be disabled if either the Tox library or + * the proxy don't support proxying UDP messages. */ bool udp_enabled; @@ -621,7 +620,7 @@ struct Tox_Options { uint16_t tcp_port; /** - * Enables or disables UDP hole-punching in toxcore. (Default: enabled). + * Enables or disables UDP hole-punching. (Default: enabled). */ bool hole_punching_enabled; @@ -633,8 +632,8 @@ struct Tox_Options { /** * The savedata. * - * The data pointed at by this member is owned by the user, so must - * outlive the options object. + * The data pointed at by this member is owned by the user, so must outlive + * the options object. */ const uint8_t *savedata_data; @@ -1934,9 +1933,9 @@ bool tox_hash(uint8_t hash[TOX_HASH_LENGTH], const uint8_t data[], size_t length /** * @brief A list of pre-defined file kinds. * - * Toxcore itself does not behave differently for different file kinds. These - * are a hint to the client telling it what use the sender intended for the - * file. The `kind` parameter in the send function and recv callback are + * The Tox library itself does not behave differently for different file kinds. + * These are a hint to the client telling it what use the sender intended for + * the file. The `kind` parameter in the send function and recv callback are * `uint32_t`, not Tox_File_Kind, because clients can invent their own file * kind. Unknown file kinds should be treated as TOX_FILE_KIND_DATA. */ @@ -2240,8 +2239,8 @@ const char *tox_err_file_send_to_string(Tox_Err_File_Send value); * File transmission occurs in chunks, which are requested through the * `file_chunk_request` event. * - * When a friend goes offline, all file transfers associated with the friend are - * purged from core. + * When a friend goes offline, all file transfers associated with the friend get + * purged. * * If the file contents change during a transfer, the behaviour is unspecified * in general. What will actually happen depends on the mode in which the file @@ -2251,7 +2250,7 @@ const char *tox_err_file_send_to_string(Tox_Err_File_Send value); * - and sending mode was streaming (file_size = UINT64_MAX), the behaviour * will be as expected. * - and sending mode was file (file_size != UINT64_MAX), the - * file_chunk_request callback will receive length = 0 when Core thinks the + * file_chunk_request callback will receive length = 0 when Tox thinks the * file transfer has finished. If the client remembers the file size as it * was when sending the request, it will terminate the transfer normally. If * the client re-reads the size, it will think the friend cancelled the @@ -2275,9 +2274,9 @@ const char *tox_err_file_send_to_string(Tox_Err_File_Send value); * @param file_size Size in bytes of the file the client wants to send, * UINT64_MAX if unknown or streaming. * @param file_id A file identifier of length TOX_FILE_ID_LENGTH that can be - * used to uniquely identify file transfers across core restarts. If NULL, a - * random one will be generated by core. It can then be obtained by using - * `tox_file_get_file_id()`. + * used to uniquely identify file transfers across Tox restarts. If NULL, a + * random one will be generated by the library. It can then be obtained by + * using `tox_file_get_file_id()`. * @param filename Name of the file. Does not need to be the actual name. This * name will be sent along with the file send request. * @param filename_length Size in bytes of the filename. @@ -2355,9 +2354,9 @@ const char *tox_err_file_send_chunk_to_string(Tox_Err_File_Send_Chunk value); * This function is called in response to the `file_chunk_request` callback. The * length parameter should be equal to the one received though the callback. * If it is zero, the transfer is assumed complete. For files with known size, - * Core will know that the transfer is complete after the last byte has been + * Tox will know that the transfer is complete after the last byte has been * received, so it is not necessary (though not harmful) to send a zero-length - * chunk to terminate. For streams, core will know that the transfer is finished + * chunk to terminate. For streams, Tox will know that the transfer is finished * if a chunk with length less than the length requested in the callback is * sent. * @@ -2401,7 +2400,7 @@ typedef void tox_file_chunk_request_cb( * * Pass NULL to unset. * - * This event is triggered when Core is ready to send more file data. + * This event is triggered when Tox is ready to send more file data. */ void tox_callback_file_chunk_request(Tox *tox, tox_file_chunk_request_cb *callback); @@ -2921,7 +2920,7 @@ const char *tox_err_conference_join_to_string(Tox_Err_Conference_Join value); * to it until a handshaking procedure has been completed. A * `conference_connected` event will then occur for the conference. The client * will then remain connected to the conference until the conference is deleted, - * even across core restarts. Many operations on a conference will fail with a + * even across Tox restarts. Many operations on a conference will fail with a * corresponding error if attempted on a conference to which the client is not * yet connected. * @@ -3075,8 +3074,8 @@ size_t tox_conference_get_chatlist_size(const Tox *tox); * Determine how much space to allocate for the array with the * `tox_conference_get_chatlist_size` function. * - * Note that `tox_get_savedata` saves all connected conferences; - * when toxcore is created from savedata in which conferences were saved, those + * Note that `tox_get_savedata` saves all connected conferences; when a Tox + * instance is created from savedata in which conferences were saved, those * conferences will be connected at startup, and will be listed by * `tox_conference_get_chatlist`. * From 0ec4978de51a113223c56d44dfe0a23c184e4c6d Mon Sep 17 00:00:00 2001 From: Maxim Biro Date: Sun, 17 Mar 2024 10:43:37 -0400 Subject: [PATCH 13/13] refactor: Don't expose Tox_System in the public API It makes no sense to include it in the public API as clients can't make any meaningful use of it via public API, it can only be used if one also includes other internal/private headers that we don't install. It's used only in the testing code, which has access to the internal headers. Fixes #2739, at least to some degree. I decided against moving things to a separate `tox_testing.h` and leaving only things in `tox_private.h` that we are fine with clients using, as otherwise `tox_lock()` / `tox_unlock()` would have to be moved out of `tox_private.h` to somewhere else, but `tox_private.h` actually sounds like the right place for them, naming-wise. So perhaps it's fine if we have things in `tox_private.h` that we don't want clients to use. --- testing/fuzzing/bootstrap_fuzz_test.cc | 8 ++++-- testing/fuzzing/e2e_fuzz_test.cc | 8 ++++-- testing/fuzzing/fuzz_support.hh | 1 + testing/fuzzing/protodump.cc | 12 ++++++--- testing/fuzzing/protodump_reduce.cc | 8 ++++-- testing/fuzzing/toxsave_fuzz_test.cc | 9 ++++--- toxcore/tox.c | 35 ++++++++++++++++++++++++-- toxcore/tox.h | 19 -------------- toxcore/tox_api.c | 8 ------ toxcore/tox_events.h | 2 ++ toxcore/tox_private.h | 19 +++++++++++--- 11 files changed, 82 insertions(+), 47 deletions(-) diff --git a/testing/fuzzing/bootstrap_fuzz_test.cc b/testing/fuzzing/bootstrap_fuzz_test.cc index f25e24319d..4a784f846a 100644 --- a/testing/fuzzing/bootstrap_fuzz_test.cc +++ b/testing/fuzzing/bootstrap_fuzz_test.cc @@ -104,7 +104,6 @@ void TestBootstrap(Fuzz_Data &input) Ptr opts(tox_options_new(nullptr), tox_options_free); assert(opts != nullptr); - tox_options_set_operating_system(opts.get(), sys.sys.get()); tox_options_set_log_callback(opts.get(), [](Tox *tox, Tox_Log_Level level, const char *file, uint32_t line, const char *func, @@ -134,8 +133,12 @@ void TestBootstrap(Fuzz_Data &input) tox_options_set_tcp_port(opts.get(), 33445); } + Tox_Options_Testing tox_options_testing; + tox_options_testing.operating_system = sys.sys.get(); + Tox_Err_New error_new; - Tox *tox = tox_new(opts.get(), &error_new); + Tox_Err_New_Testing error_new_testing; + Tox *tox = tox_new_testing(opts.get(), &error_new, &tox_options_testing, &error_new_testing); if (tox == nullptr) { // It might fail, because some I/O happens in tox_new, and the fuzzer @@ -144,6 +147,7 @@ void TestBootstrap(Fuzz_Data &input) } assert(error_new == TOX_ERR_NEW_OK); + assert(error_new_testing == TOX_ERR_NEW_TESTING_OK); uint8_t pub_key[TOX_PUBLIC_KEY_SIZE] = {0}; diff --git a/testing/fuzzing/e2e_fuzz_test.cc b/testing/fuzzing/e2e_fuzz_test.cc index 1be228e040..df4e03c698 100644 --- a/testing/fuzzing/e2e_fuzz_test.cc +++ b/testing/fuzzing/e2e_fuzz_test.cc @@ -138,7 +138,6 @@ void TestEndToEnd(Fuzz_Data &input) Ptr opts(tox_options_new(nullptr), tox_options_free); assert(opts != nullptr); - tox_options_set_operating_system(opts.get(), sys.sys.get()); tox_options_set_local_discovery_enabled(opts.get(), false); tox_options_set_log_callback(opts.get(), @@ -151,8 +150,12 @@ void TestEndToEnd(Fuzz_Data &input) } }); + Tox_Options_Testing tox_options_testing; + tox_options_testing.operating_system = sys.sys.get(); + Tox_Err_New error_new; - Tox *tox = tox_new(opts.get(), &error_new); + Tox_Err_New_Testing error_new_testing; + Tox *tox = tox_new_testing(opts.get(), &error_new, &tox_options_testing, &error_new_testing); if (tox == nullptr) { // It might fail, because some I/O happens in tox_new, and the fuzzer @@ -161,6 +164,7 @@ void TestEndToEnd(Fuzz_Data &input) } assert(error_new == TOX_ERR_NEW_OK); + assert(error_new_testing == TOX_ERR_NEW_TESTING_OK); tox_events_init(tox); diff --git a/testing/fuzzing/fuzz_support.hh b/testing/fuzzing/fuzz_support.hh index 7f03d341e1..6a370f3dfd 100644 --- a/testing/fuzzing/fuzz_support.hh +++ b/testing/fuzzing/fuzz_support.hh @@ -16,6 +16,7 @@ #include #include "../../toxcore/tox.h" +#include "../../toxcore/tox_private.h" struct Fuzz_Data { static constexpr bool DEBUG = false; diff --git a/testing/fuzzing/protodump.cc b/testing/fuzzing/protodump.cc index 1a3f8c0700..28df05a02a 100644 --- a/testing/fuzzing/protodump.cc +++ b/testing/fuzzing/protodump.cc @@ -195,13 +195,16 @@ void RecordBootstrap(const char *init, const char *bootstrap) }); Tox_Err_New error_new; + Tox_Err_New_Testing error_new_testing; + Tox_Options_Testing tox_options_testing; Record_System sys1(global, 4, "tox1"); // fair dice roll tox_options_set_log_user_data(opts, &sys1); - tox_options_set_operating_system(opts, sys1.sys.get()); - Tox *tox1 = tox_new(opts, &error_new); + tox_options_testing.operating_system = sys1.sys.get(); + Tox *tox1 = tox_new_testing(opts, &error_new, &tox_options_testing, &error_new_testing); assert(tox1 != nullptr); assert(error_new == TOX_ERR_NEW_OK); + assert(error_new_testing == TOX_ERR_NEW_TESTING_OK); std::array address1; tox_self_get_address(tox1, address1.data()); std::array pk1; @@ -211,10 +214,11 @@ void RecordBootstrap(const char *init, const char *bootstrap) Record_System sys2(global, 5, "tox2"); // unfair dice roll tox_options_set_log_user_data(opts, &sys2); - tox_options_set_operating_system(opts, sys2.sys.get()); - Tox *tox2 = tox_new(opts, &error_new); + tox_options_testing.operating_system = sys2.sys.get(); + Tox *tox2 = tox_new_testing(opts, &error_new, &tox_options_testing, &error_new_testing); assert(tox2 != nullptr); assert(error_new == TOX_ERR_NEW_OK); + assert(error_new_testing == TOX_ERR_NEW_TESTING_OK); std::array address2; tox_self_get_address(tox2, address2.data()); std::array pk2; diff --git a/testing/fuzzing/protodump_reduce.cc b/testing/fuzzing/protodump_reduce.cc index ae9676ca31..820a3fc7b8 100644 --- a/testing/fuzzing/protodump_reduce.cc +++ b/testing/fuzzing/protodump_reduce.cc @@ -142,9 +142,11 @@ void TestEndToEnd(Fuzz_Data &input) Ptr opts(tox_options_new(nullptr), tox_options_free); assert(opts != nullptr); - tox_options_set_operating_system(opts.get(), sys.sys.get()); tox_options_set_local_discovery_enabled(opts.get(), false); + Tox_Options_Testing tox_options_testing; + tox_options_testing.operating_system = sys.sys.get(); + tox_options_set_log_callback(opts.get(), [](Tox *tox, Tox_Log_Level level, const char *file, uint32_t line, const char *func, const char *message, void *user_data) { @@ -156,7 +158,8 @@ void TestEndToEnd(Fuzz_Data &input) }); Tox_Err_New error_new; - Tox *tox = tox_new(opts.get(), &error_new); + Tox_Err_New_Testing error_new_testing; + Tox *tox = tox_new_testing(opts.get(), &error_new, &tox_options_testing, &error_new_testing); if (tox == nullptr) { // It might fail, because some I/O happens in tox_new, and the fuzzer @@ -165,6 +168,7 @@ void TestEndToEnd(Fuzz_Data &input) } assert(error_new == TOX_ERR_NEW_OK); + assert(error_new_testing == TOX_ERR_NEW_TESTING_OK); tox_events_init(tox); diff --git a/testing/fuzzing/toxsave_fuzz_test.cc b/testing/fuzzing/toxsave_fuzz_test.cc index 2cb134cbc1..f48c2bf013 100644 --- a/testing/fuzzing/toxsave_fuzz_test.cc +++ b/testing/fuzzing/toxsave_fuzz_test.cc @@ -20,14 +20,15 @@ void TestSaveDataLoading(Fuzz_Data &input) const size_t savedata_size = input.size(); CONSUME_OR_RETURN(const uint8_t *savedata, input, savedata_size); - Null_System sys; - tox_options_set_operating_system(tox_options, sys.sys.get()); - // pass test data to Tox tox_options_set_savedata_data(tox_options, savedata, savedata_size); tox_options_set_savedata_type(tox_options, TOX_SAVEDATA_TYPE_TOX_SAVE); - Tox *tox = tox_new(tox_options, nullptr); + Tox_Options_Testing tox_options_testing; + Null_System sys; + tox_options_testing.operating_system = sys.sys.get(); + + Tox *tox = tox_new_testing(tox_options, nullptr, &tox_options_testing, nullptr); tox_options_free(tox_options); if (tox == nullptr) { // Tox save was invalid, we're finished here diff --git a/toxcore/tox.c b/toxcore/tox.c index 679f1d89fd..03e34414a8 100644 --- a/toxcore/tox.c +++ b/toxcore/tox.c @@ -712,7 +712,8 @@ static int tox_load(Tox *tox, const uint8_t *data, uint32_t length) length - cookie_len, STATE_COOKIE_TYPE); } -Tox *tox_new(const struct Tox_Options *options, Tox_Err_New *error) +nullable(1, 2, 3) +static Tox *tox_new_system(const struct Tox_Options *options, Tox_Err_New *error, const Tox_System *sys) { struct Tox_Options *default_options = nullptr; @@ -736,7 +737,6 @@ Tox *tox_new(const struct Tox_Options *options, Tox_Err_New *error) const struct Tox_Options *const opts = options != nullptr ? options : default_options; assert(opts != nullptr); - const Tox_System *sys = tox_options_get_operating_system(opts); const Tox_System default_system = tox_default_system(); if (sys == nullptr) { @@ -1020,6 +1020,37 @@ Tox *tox_new(const struct Tox_Options *options, Tox_Err_New *error) return tox; } +Tox *tox_new(const struct Tox_Options *options, Tox_Err_New *error) +{ + return tox_new_system(options, error, nullptr); +} + +Tox *tox_new_testing(const Tox_Options *options, Tox_Err_New *error, const Tox_Options_Testing *testing, Tox_Err_New_Testing *testing_error) +{ + if (testing == nullptr) { + SET_ERROR_PARAMETER(error, TOX_ERR_NEW_NULL); + SET_ERROR_PARAMETER(testing_error, TOX_ERR_NEW_TESTING_NULL); + return nullptr; + } + + if (testing->operating_system == nullptr) { + SET_ERROR_PARAMETER(error, TOX_ERR_NEW_NULL); + SET_ERROR_PARAMETER(testing_error, TOX_ERR_NEW_TESTING_NULL); + return nullptr; + } + + const Tox_System *sys = testing->operating_system; + + if (sys->rng == nullptr || sys->ns == nullptr || sys->mem == nullptr) { + SET_ERROR_PARAMETER(error, TOX_ERR_NEW_NULL); + SET_ERROR_PARAMETER(testing_error, TOX_ERR_NEW_TESTING_NULL); + return nullptr; + } + + SET_ERROR_PARAMETER(testing_error, TOX_ERR_NEW_TESTING_OK); + return tox_new_system(options, error, sys); +} + void tox_kill(Tox *tox) { if (tox == nullptr) { diff --git a/toxcore/tox.h b/toxcore/tox.h index 5e1be14a28..c3b4ad71b5 100644 --- a/toxcore/tox.h +++ b/toxcore/tox.h @@ -496,15 +496,6 @@ const char *tox_log_level_to_string(Tox_Log_Level value); typedef void tox_log_cb(Tox *tox, Tox_Log_Level level, const char *file, uint32_t line, const char *func, const char *message, void *user_data); -/** - * @brief Operating system functions used by Tox. - * - * This struct is opaque and generally shouldn't be used in clients, but in - * combination with tox_private.h, it allows tests to inject non-IO (hermetic) - * versions of low level network, RNG, and time keeping functions. - */ -typedef struct Tox_System Tox_System; - /** * @brief This struct contains all the startup options for Tox. * @@ -665,12 +656,6 @@ struct Tox_Options { */ bool experimental_thread_safety; - /** - * Low level operating system functionality such as send/recv, random - * number generation, and memory allocation. - */ - const Tox_System *operating_system; - /** * Enable saving DHT-based group chats to Tox save data (via * `tox_get_savedata`). This format will change in the future, so don't rely @@ -753,10 +738,6 @@ bool tox_options_get_experimental_thread_safety(const Tox_Options *options); void tox_options_set_experimental_thread_safety(Tox_Options *options, bool experimental_thread_safety); -const Tox_System *tox_options_get_operating_system(const Tox_Options *options); - -void tox_options_set_operating_system(Tox_Options *options, const Tox_System *operating_system); - bool tox_options_get_experimental_groups_persistence(const Tox_Options *options); void tox_options_set_experimental_groups_persistence(Tox_Options *options, bool experimental_groups_persistence); diff --git a/toxcore/tox_api.c b/toxcore/tox_api.c index 26da9b2490..6d0d9851c7 100644 --- a/toxcore/tox_api.c +++ b/toxcore/tox_api.c @@ -265,14 +265,6 @@ void tox_options_set_experimental_thread_safety( { options->experimental_thread_safety = experimental_thread_safety; } -const Tox_System *tox_options_get_operating_system(const Tox_Options *options) -{ - return options->operating_system; -} -void tox_options_set_operating_system(Tox_Options *options, const Tox_System *operating_system) -{ - options->operating_system = operating_system; -} bool tox_options_get_experimental_groups_persistence(const Tox_Options *options) { return options->experimental_groups_persistence; diff --git a/toxcore/tox_events.h b/toxcore/tox_events.h index b69683e9c0..1c9b1b455c 100644 --- a/toxcore/tox_events.h +++ b/toxcore/tox_events.h @@ -570,6 +570,8 @@ void tox_events_free(Tox_Events *events); uint32_t tox_events_bytes_size(const Tox_Events *events); bool tox_events_get_bytes(const Tox_Events *events, uint8_t *bytes); +typedef struct Tox_System Tox_System; + Tox_Events *tox_events_load(const Tox_System *sys, const uint8_t *bytes, uint32_t bytes_size); bool tox_events_equal(const Tox_System *sys, const Tox_Events *a, const Tox_Events *b); diff --git a/toxcore/tox_private.h b/toxcore/tox_private.h index ac6fd4fa77..fe86479a5d 100644 --- a/toxcore/tox_private.h +++ b/toxcore/tox_private.h @@ -18,21 +18,32 @@ extern "C" { typedef uint64_t tox_mono_time_cb(void *user_data); -struct Tox_System { +typedef 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_System tox_default_system(void); +const Tox_System *tox_get_system(Tox *tox); + +typedef struct Tox_Options_Testing { + const struct Tox_System *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 *tox_new_testing(const Tox_Options *options, Tox_Err_New *error, const Tox_Options_Testing *testing, Tox_Err_New_Testing *testing_error); + 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.