5 files changed, 98 insertions, 62 deletions

diff --git a/toxcore/group.c b/toxcore/group.c
index b42c6b24..75b8697b 100644
--- a/toxcore/group.c
+++ b/toxcore/group.c
@@ -1174,33 +1174,25 @@ int join_groupchat(Group_Chats *g_c, uint32_t friendnumber, uint8_t expected_typ
     return -6;
 }
 
-/* Set handlers for custom lossy packets.
- *
- * NOTE: Handler must return 0 if packet is to be relayed, -1 if the packet should not be relayed.
- *
- * Function(void *group object (set with group_set_object), uint32_t groupnumber, uint32_t friendgroupnumber, void *group peer object (set with group_peer_set_object), const uint8_t *packet, uint16_t length)
- */
+/* Set handlers for custom lossy packets. */
 void group_lossy_packet_registerhandler(Group_Chats *g_c, uint8_t byte, lossy_packet_cb *function)
 {
     g_c->lossy_packethandlers[byte].function = function;
 }
 
-/* Set the callback for group invites.
- *
- *  Function(Group_Chats *g_c, int32_t friendnumber, uint8_t type, uint8_t *data, size_t length, void *userdata)
- *
- *  data of length is what needs to be passed to join_groupchat().
- */
+/* Set the callback for group invites. */
 void g_callback_group_invite(Group_Chats *g_c, g_conference_invite_cb *function)
 {
     g_c->invite_callback = function;
 }
 
-// TODO(sudden6): function signatures in comments are incorrect
-/* Set the callback for group messages.
- *
- *  Function(Group_Chats *g_c, uint32_t groupnumber, uint32_t friendgroupnumber, uint8_t * message, size_t length, void *userdata)
- */
+/* Set the callback for group connection. */
+void g_callback_group_connected(Group_Chats *g_c, g_conference_connected_cb *function)
+{
+    g_c->connected_callback = function;
+}
+
+/* Set the callback for group messages. */
 void g_callback_group_message(Group_Chats *g_c, g_conference_message_cb *function)
 {
     g_c->message_callback = function;
@@ -1209,7 +1201,6 @@ void g_callback_group_message(Group_Chats *g_c, g_conference_message_cb *functio
 /* Set callback function for peer nickname changes.
  *
  * It gets called every time a peer changes their nickname.
- *  Function(Group_Chats *g_c, uint32_t groupnumber, uint32_t peernumber, const uint8_t *nick, size_t nick_len, void *userdata)
  */
 void g_callback_peer_name(Group_Chats *g_c, peer_name_cb *function)
 {
@@ -1219,19 +1210,13 @@ void g_callback_peer_name(Group_Chats *g_c, peer_name_cb *function)
 /* Set callback function for peer list changes.
  *
  * It gets called every time the name list changes(new peer, deleted peer)
- *  Function(Group_Chats *g_c, uint32_t groupnumber, void *userdata)
  */
 void g_callback_peer_list_changed(Group_Chats *g_c, peer_list_changed_cb *function)
 {
     g_c->peer_list_changed_callback = function;
 }
 
-// TODO(sudden6): function signatures are incorrect
-/* Set callback function for title changes.
- *
- * Function(Group_Chats *g_c, int groupnumber, int friendgroupnumber, uint8_t * title, uint8_t length, void *userdata)
- * if friendgroupnumber == -1, then author is unknown (e.g. initial joining the group)
- */
+/* Set callback function for title changes. */
 void g_callback_group_title(Group_Chats *g_c, title_cb *function)
 {
     g_c->title_callback = function;
@@ -1239,8 +1224,6 @@ void g_callback_group_title(Group_Chats *g_c, title_cb *function)
 
 /* Set a function to be called when a new peer joins a group chat.
  *
- * Function(void *group object (set with group_set_object), uint32_t groupnumber, uint32_t friendgroupnumber)
- *
  * return 0 on success.
  * return -1 on failure.
  */
@@ -1258,8 +1241,6 @@ int callback_groupchat_peer_new(const Group_Chats *g_c, uint32_t groupnumber, pe
 
 /* Set a function to be called when a peer leaves a group chat.
  *
- * Function(void *group object (set with group_set_object), uint32_t groupnumber, uint32_t friendgroupnumber, void *group peer object (set with group_peer_set_object))
- *
  * return 0 on success.
  * return -1 on failure.
  */
@@ -1277,8 +1258,6 @@ int callback_groupchat_peer_delete(Group_Chats *g_c, uint32_t groupnumber, peer_
 
 /* Set a function to be called when the group chat is deleted.
  *
- * Function(void *group object (set with group_set_object), int groupnumber)
- *
  * return 0 on success.
  * return -1 on failure.
  */
@@ -1742,6 +1721,11 @@ static int handle_send_peers(Group_Chats *g_c, uint32_t groupnumber, const uint8
                 && public_key_cmp(d, nc_get_self_public_key(g_c->m->net_crypto)) == 0) {
             g->peer_number = peer_num;
             g->status = GROUPCHAT_STATUS_CONNECTED;
+
+            if (g_c->connected_callback) {
+                g_c->connected_callback(g_c->m, groupnumber, userdata);
+            }
+
             group_name_send(g_c, groupnumber, g_c->m->name, g_c->m->name_length);
         }
 
diff --git a/toxcore/group.h b/toxcore/group.h
index 31e0e7e3..175999ae 100644
--- a/toxcore/group.h
+++ b/toxcore/group.h
@@ -132,15 +132,38 @@ typedef struct Group_c {
     group_on_delete_cb *group_on_delete;
 } Group_c;
 
+/* Callback for group invites.
+ *
+ * data of length is what needs to be passed to join_groupchat().
+ */
 typedef void g_conference_invite_cb(Messenger *m, uint32_t friend_number, int type, const uint8_t *cookie,
                                     size_t length, void *user_data);
+
+/* Callback for group connection. */
+typedef void g_conference_connected_cb(Messenger *m, uint32_t conference_number, void *user_data);
+
+/* Callback for group messages. */
 typedef void g_conference_message_cb(Messenger *m, uint32_t conference_number, uint32_t peer_number, int type,
                                      const uint8_t *message, size_t length, void *user_data);
+
+/* Callback for peer nickname changes. */
 typedef void peer_name_cb(Messenger *m, uint32_t conference_number, uint32_t peer_number, const uint8_t *name,
                           size_t length, void *user_data);
+
+/* Set callback function for peer list changes. */
 typedef void peer_list_changed_cb(Messenger *m, uint32_t conference_number, void *user_data);
+
+/* Callback for title changes.
+ *
+ * If peer_number == -1, then author is unknown (e.g. initial joining the group).
+ */
 typedef void title_cb(Messenger *m, uint32_t conference_number, uint32_t peer_number, const uint8_t *title,
                       size_t length, void *user_data);
+
+/* Callback for lossy packets.
+ *
+ * NOTE: Handler must return 0 if packet is to be relayed, -1 if the packet should not be relayed.
+ */
 typedef int lossy_packet_cb(void *object, uint32_t conference_number, uint32_t peer_number, void *peer_object,
                             const uint8_t *packet, uint16_t length);
 
@@ -156,6 +179,7 @@ typedef struct Group_Chats {
     uint16_t num_chats;
 
     g_conference_invite_cb *invite_callback;
+    g_conference_connected_cb *connected_callback;
     g_conference_message_cb *message_callback;
     peer_name_cb *peer_name_callback;
     peer_list_changed_cb *peer_list_changed_callback;
@@ -164,39 +188,28 @@ typedef struct Group_Chats {
     Group_Lossy_Handler lossy_packethandlers[256];
 } Group_Chats;
 
-/* Set the callback for group invites.
- *
- *  Function(Group_Chats *g_c, uint32_t friendnumber, uint8_t type, uint8_t *data, uint16_t length, void *userdata)
- *
- *  data of length is what needs to be passed to join_groupchat().
- */
+/* Set the callback for group invites. */
 void g_callback_group_invite(Group_Chats *g_c, g_conference_invite_cb *function);
 
-/* Set the callback for group messages.
- *
- *  Function(Group_Chats *g_c, uint32_t groupnumber, uint32_t friendgroupnumber, uint8_t * message, uint16_t length, void *userdata)
- */
+/* Set the callback for group connection. */
+void g_callback_group_connected(Group_Chats *g_c, g_conference_connected_cb *function);
+
+/* Set the callback for group messages. */
 void g_callback_group_message(Group_Chats *g_c, g_conference_message_cb *function);
 
 
-/* Set callback function for title changes.
- *
- * Function(Group_Chats *g_c, uint32_t groupnumber, uint32_t friendgroupnumber, uint8_t * title, uint8_t length, void *userdata)
- * if friendgroupnumber == -1, then author is unknown (e.g. initial joining the group)
- */
+/* Set callback function for title changes. */
 void g_callback_group_title(Group_Chats *g_c, title_cb *function);
 
 /* Set callback function for peer nickname changes.
  *
  * It gets called every time a peer changes their nickname.
- *  Function(Group_Chats *g_c, uint32_t groupnumber, uint32_t peernumber, const uint8_t *nick, size_t nick_len, void *userdata)
  */
 void g_callback_peer_name(Group_Chats *g_c, peer_name_cb *function);
 
 /* Set callback function for peer list changes.
  *
  * It gets called every time the name list changes(new peer, deleted peer)
- *  Function(Group_Chats *g_c, uint32_t groupnumber, void *userdata)
  */
 void g_callback_peer_list_changed(Group_Chats *g_c, peer_list_changed_cb *function);
 
@@ -327,12 +340,7 @@ int group_peernumber_is_ours(const Group_Chats *g_c, uint32_t groupnumber, int p
 int group_names(const Group_Chats *g_c, uint32_t groupnumber, uint8_t names[][MAX_NAME_LENGTH], uint16_t lengths[],
                 uint16_t length);
 
-/* Set handlers for custom lossy packets.
- *
- * NOTE: Handler must return 0 if packet is to be relayed, -1 if the packet should not be relayed.
- *
- * Function(void *group object (set with group_set_object), uint32_t groupnumber, uint32_t friendgroupnumber, void *group peer object (set with group_peer_set_object), const uint8_t *packet, uint16_t length)
- */
+/* Set handlers for custom lossy packets. */
 void group_lossy_packet_registerhandler(Group_Chats *g_c, uint8_t byte, lossy_packet_cb *function);
 
 /* High level function to send custom lossy packets.
@@ -389,14 +397,14 @@ int group_set_object(const Group_Chats *g_c, uint32_t groupnumber, void *object)
  */
 int group_peer_set_object(const Group_Chats *g_c, uint32_t groupnumber, int peernumber, void *object);
 
-/* Return the object tide to the group chat previously set by group_set_object.
+/* Return the object tied to the group chat previously set by group_set_object.
  *
  * return NULL on failure.
  * return object on success.
  */
 void *group_get_object(const Group_Chats *g_c, uint32_t groupnumber);
 
-/* Return the object tide to the group chat peer previously set by group_peer_set_object.
+/* Return the object tied to the group chat peer previously set by group_peer_set_object.
  *
  * return NULL on failure.
  * return object on success.
@@ -405,8 +413,6 @@ void *group_peer_get_object(const Group_Chats *g_c, uint32_t groupnumber, int pe
 
 /* Set a function to be called when a new peer joins a group chat.
  *
- * Function(void *group object (set with group_set_object), int groupnumber, int friendgroupnumber)
- *
  * return 0 on success.
  * return -1 on failure.
  */
@@ -414,8 +420,6 @@ int callback_groupchat_peer_new(const Group_Chats *g_c, uint32_t groupnumber, pe
 
 /* Set a function to be called when a peer leaves a group chat.
  *
- * Function(void *group object (set with group_set_object), uint32_t groupnumber, void *group peer object (set with group_peer_set_object))
- *
  * return 0 on success.
  * return -1 on failure.
  */
@@ -423,8 +427,6 @@ int callback_groupchat_peer_delete(Group_Chats *g_c, uint32_t groupnumber, peer_
 
 /* Set a function to be called when the group chat is deleted.
  *
- * Function(void *group object (set with group_set_object), uint32_t groupnumber)
- *
  * return 0 on success.
  * return -1 on failure.
  */
diff --git a/toxcore/tox.api.h b/toxcore/tox.api.h
index 3254db05..d1e01c74 100644
--- a/toxcore/tox.api.h
+++ b/toxcore/tox.api.h
@@ -2157,6 +2157,18 @@ namespace conference {
 
 
   /**
+   * This event is triggered when the client successfully connects to a
+   * conference after joining it with the $join function.
+   */
+  event connected const {
+    /**
+     * @param conference_number The conference number of the conference to which we have connected.
+     */
+    typedef void(uint32_t conference_number);
+  }
+
+
+  /**
    * This event is triggered when the client receives a conference message.
    */
   event message const {
@@ -2313,6 +2325,10 @@ namespace conference {
   /**
    * Invites a friend to a conference.
    *
+   * We must be connected to the conference, meaning that the conference has not
+   * been deleted, and either we created the conference with the $new function,
+   * or a `${event connected}` event has occurred for the 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.
    *
diff --git a/toxcore/tox.c b/toxcore/tox.c
index f7bdba79..2ccbef82 100644
--- a/toxcore/tox.c
+++ b/toxcore/tox.c
@@ -91,6 +91,7 @@ struct Tox {
     tox_file_recv_cb *file_recv_callback;
     tox_file_recv_chunk_cb *file_recv_chunk_callback;
     tox_conference_invite_cb *conference_invite_callback;
+    tox_conference_connected_cb *conference_connected_callback;
     tox_conference_message_cb *conference_message_callback;
     tox_conference_title_cb *conference_title_callback;
     tox_conference_peer_name_cb *conference_peer_name_callback;
@@ -247,6 +248,15 @@ static void tox_conference_invite_handler(Messenger *m, uint32_t friend_number,
     }
 }
 
+static void tox_conference_connected_handler(Messenger *m, uint32_t conference_number, void *user_data)
+{
+    struct Tox_Userdata *tox_data = (struct Tox_Userdata *)user_data;
+
+    if (tox_data->tox->conference_connected_callback != nullptr) {
+        tox_data->tox->conference_connected_callback(tox_data->tox, conference_number, tox_data->user_data);
+    }
+}
+
 static void tox_conference_message_handler(Messenger *m, uint32_t conference_number, uint32_t peer_number, int type,
         const uint8_t *message, size_t length, void *user_data)
 {
@@ -488,6 +498,7 @@ Tox *tox_new(const struct Tox_Options *options, Tox_Err_New *error)
     callback_file_sendrequest(m, tox_file_recv_handler);
     callback_file_data(m, tox_file_recv_chunk_handler);
     g_callback_group_invite((Group_Chats *)m->conferences_object, tox_conference_invite_handler);
+    g_callback_group_connected((Group_Chats *)m->conferences_object, tox_conference_connected_handler);
     g_callback_group_message((Group_Chats *)m->conferences_object, tox_conference_message_handler);
     g_callback_group_title((Group_Chats *)m->conferences_object, tox_conference_title_handler);
     g_callback_peer_name((Group_Chats *)m->conferences_object, tox_conference_peer_name_handler);
@@ -1386,6 +1397,11 @@ void tox_callback_conference_invite(Tox *tox, tox_conference_invite_cb *callback
     tox->conference_invite_callback = callback;
 }
 
+void tox_callback_conference_connected(Tox *tox, tox_conference_connected_cb *callback)
+{
+    tox->conference_connected_callback = callback;
+}
+
 void tox_callback_conference_message(Tox *tox, tox_conference_message_cb *callback)
 {
     tox->conference_message_callback = callback;
diff --git a/toxcore/tox.h b/toxcore/tox.h
index badae42b..2739e1c4 100644
--- a/toxcore/tox.h
+++ b/toxcore/tox.h
@@ -2438,6 +2438,20 @@ typedef void tox_conference_invite_cb(Tox *tox, uint32_t friend_number, TOX_CONF
 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.
+ */
+typedef void tox_conference_connected_cb(Tox *tox, uint32_t conference_number, void *user_data);
+
+
+/**
+ * Set the callback for the `conference_connected` event. Pass NULL to unset.
+ *
+ * This event is triggered when the client successfully connects to a
+ * conference after joining it with the tox_conference_join function.
+ */
+void tox_callback_conference_connected(Tox *tox, tox_conference_connected_cb *callback);
+
+/**
  * @param conference_number The conference number of the conference the message is intended for.
  * @param peer_number The ID of the peer who sent the message.
  * @param type The type of message (normal, action, ...).
@@ -2645,6 +2659,10 @@ typedef enum TOX_ERR_CONFERENCE_INVITE {
 /**
  * Invites a friend to a conference.
  *
+ * We must be connected to the conference, meaning that the conference has not
+ * been deleted, and either we created the conference with the tox_conference_new function,
+ * or a `conference_connected` event has occurred for the 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.
  *