clean groups code

* make static functions return bool rather than int to indicate success
* add peer_in_list() to factor out uniformity over peer and frozen lists
* reduce repetition in send_lossy_all_close
* rename 'close' to 'connections'
* use uint32_t for peernumber (in accord with tox.c)
* explain persistence in tox_conference_get_chatlist documentation
* clarify "connectedness" in group API documentation
* clarify that tox_conference_peer_count counts only online peers
* refactor variously

toxav/groupav.h

@@ -19,7 +19,7 @@
 typedef void 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);
 
-/* Create a new toxav group.
+/* Create and connect to a new toxav group.
  *
  * return group number on success.
  * return -1 on failure.

toxcore/group.h

@@ -56,37 +56,37 @@ typedef struct Group_Peer {
     void *object;
 } Group_Peer;
 
-#define DESIRED_CLOSE_CONNECTIONS 4
+#define DESIRED_CLOSEST 4
 #define MAX_GROUP_CONNECTIONS 16
 #define GROUP_ID_LENGTH CRYPTO_SYMMETRIC_KEY_SIZE
 
-typedef enum Groupchat_Close_Type {
+typedef enum Groupchat_Connection_Type {
-    GROUPCHAT_CLOSE_NONE,
+    GROUPCHAT_CONNECTION_NONE,
-    GROUPCHAT_CLOSE_CONNECTION,
+    GROUPCHAT_CONNECTION_CONNECTING,
-    GROUPCHAT_CLOSE_ONLINE,
+    GROUPCHAT_CONNECTION_ONLINE,
-} Groupchat_Close_Type;
+} Groupchat_Connection_Type;
 
-/* Connection is to one of the closest DESIRED_CLOSE_CONNECTIONS peers */
+/* Connection is to one of the closest DESIRED_CLOSEST peers */
-#define GROUPCHAT_CLOSE_REASON_CLOSEST     (1 << 0)
+#define GROUPCHAT_CONNECTION_REASON_CLOSEST     (1 << 0)
 
 /* Connection is to a peer we are introducing to the conference */
-#define GROUPCHAT_CLOSE_REASON_INTRODUCING (1 << 1)
+#define GROUPCHAT_CONNECTION_REASON_INTRODUCING (1 << 1)
 
 /* Connection is to a peer who is introducing us to the conference */
-#define GROUPCHAT_CLOSE_REASON_INTRODUCER  (1 << 2)
+#define GROUPCHAT_CONNECTION_REASON_INTRODUCER  (1 << 2)
 
-typedef struct Groupchat_Close {
+typedef struct Groupchat_Connection {
-    uint8_t type; /* `GROUPCHAT_CLOSE_*` */
+    uint8_t type; /* `GROUPCHAT_CONNECTION_*` */
-    uint8_t reasons; /* bit field with flags `GROUPCHAT_CLOSE_REASON_*` */
+    uint8_t reasons; /* bit field with flags `GROUPCHAT_CONNECTION_REASON_*` */
     uint32_t number;
     uint16_t group_number;
-} Groupchat_Close;
+} Groupchat_Connection;
 
-typedef struct Groupchat_Close_Connection {
+typedef struct Groupchat_Closest {
     uint8_t entry;
     uint8_t real_pk[CRYPTO_PUBLIC_KEY_SIZE];
     uint8_t temp_pk[CRYPTO_PUBLIC_KEY_SIZE];
-} Groupchat_Close_Connection;
+} Groupchat_Closest;
 
 typedef void peer_on_join_cb(void *object, uint32_t conference_number, uint32_t peer_number);
 typedef void peer_on_leave_cb(void *object, uint32_t conference_number, void *peer_object);
@@ -109,11 +109,10 @@ typedef struct Group_c {
 
     uint32_t maxfrozen;
 
-    /* TODO(zugz) rename close to something more accurate - "connected"? */
+    Groupchat_Connection connections[MAX_GROUP_CONNECTIONS];
-    Groupchat_Close close[MAX_GROUP_CONNECTIONS];
 
     uint8_t real_pk[CRYPTO_PUBLIC_KEY_SIZE];
-    Groupchat_Close_Connection closest_peers[DESIRED_CLOSE_CONNECTIONS];
+    Groupchat_Closest closest_peers[DESIRED_CLOSEST];
     uint8_t changed;
 
     uint8_t type;
@@ -245,7 +244,7 @@ int del_groupchat(Group_Chats *g_c, uint32_t groupnumber, bool leave_permanently
  * return -1 if groupnumber is invalid.
  * return -2 if peernumber is invalid.
  */
-int group_peer_pubkey(const Group_Chats *g_c, uint32_t groupnumber, int peernumber, uint8_t *pk, bool frozen);
+int group_peer_pubkey(const Group_Chats *g_c, uint32_t groupnumber, uint32_t peernumber, uint8_t *pk, bool frozen);
 
 /*
  * Return the size of (frozen, if frozen is true) peernumber's name.
@@ -253,7 +252,7 @@ int group_peer_pubkey(const Group_Chats *g_c, uint32_t groupnumber, int peernumb
  * return -1 if groupnumber is invalid.
  * return -2 if peernumber is invalid.
  */
-int group_peername_size(const Group_Chats *g_c, uint32_t groupnumber, int32_t peernumber, bool frozen);
+int group_peername_size(const Group_Chats *g_c, uint32_t groupnumber, uint32_t peernumber, bool frozen);
 
 /* Copy the name of (frozen, if frozen is true) peernumber who is in
  * groupnumber to name.
@@ -263,7 +262,7 @@ int group_peername_size(const Group_Chats *g_c, uint32_t groupnumber, int32_t pe
  * return -1 if groupnumber is invalid.
  * return -2 if peernumber is invalid.
  */
-int group_peername(const Group_Chats *g_c, uint32_t groupnumber, int peernumber, uint8_t *name, bool frozen);
+int group_peername(const Group_Chats *g_c, uint32_t groupnumber, uint32_t peernumber, uint8_t *name, bool frozen);
 
 /* Copy last active timestamp of frozen peernumber who is in groupnumber to
  * last_active.
@@ -272,7 +271,7 @@ int group_peername(const Group_Chats *g_c, uint32_t groupnumber, int peernumber,
  * return -1 if groupnumber is invalid.
  * return -2 if peernumber is invalid.
  */
-int group_frozen_last_active(const Group_Chats *g_c, uint32_t groupnumber, int peernumber,
+int group_frozen_last_active(const Group_Chats *g_c, uint32_t groupnumber, uint32_t peernumber,
                              uint64_t *last_active);
 
 /* Set maximum number of frozen peers.
@@ -292,7 +291,8 @@ int invite_friend(Group_Chats *g_c, uint32_t friendnumber, uint32_t groupnumber)
 
 /* Join a group (you need to have been invited first.)
  *
- * expected_type is the groupchat type we expect the chat we are joining is.
+ * expected_type is the groupchat type we expect the chat we are joining to
+ * have.
  *
  * return group number on success.
  * return -1 if data length is invalid.
@@ -353,7 +353,7 @@ int group_number_peers(const Group_Chats *g_c, uint32_t groupnumber, bool frozen
  * return -2 if peernumber is invalid.
  * return -3 if we are not connected to the group chat.
  */
-int group_peernumber_is_ours(const Group_Chats *g_c, uint32_t groupnumber, int peernumber);
+int group_peernumber_is_ours(const Group_Chats *g_c, uint32_t groupnumber, uint32_t peernumber);
 
 /* List all the (frozen, if frozen is true) peers in the group chat.
  *
@@ -423,7 +423,7 @@ int group_set_object(const Group_Chats *g_c, uint32_t groupnumber, void *object)
  * return 0 on success.
  * return -1 on failure
  */
-int group_peer_set_object(const Group_Chats *g_c, uint32_t groupnumber, int peernumber, void *object);
+int group_peer_set_object(const Group_Chats *g_c, uint32_t groupnumber, uint32_t peernumber, void *object);
 
 /* Return the object tied to the group chat previously set by group_set_object.
  *
@@ -437,7 +437,7 @@ void *group_get_object(const Group_Chats *g_c, uint32_t groupnumber);
  * return NULL on failure.
  * return object on success.
  */
-void *group_peer_get_object(const Group_Chats *g_c, uint32_t groupnumber, int peernumber);
+void *group_peer_get_object(const Group_Chats *g_c, uint32_t groupnumber, uint32_t peernumber);
 
 /* Set a function to be called when a new peer joins a group chat.
  *

toxcore/onion_client.h

@@ -136,8 +136,6 @@ int onion_dht_pk_callback(Onion_Client *onion_c, int friend_num, onion_dht_pk_cb
                           uint32_t number);
 
 /* Set a friends DHT public key.
- * timestamp is the time (current_time_monotonic()) at which the key was last confirmed belonging to
- * the other peer.
  *
  * return -1 on failure.
  * return 0 on success.

toxcore/tox.api.h

@@ -2232,7 +2232,7 @@ namespace conference {
   /**
    * Creates a new conference.
    *
-   * This function creates a new text conference.
+   * This function creates and connects to a new text conference.
    *
    * @return conference number on success, or an unspecified value on failure.
    */
@@ -2279,7 +2279,10 @@ namespace conference {
   namespace peer {
 
     /**
-     * Return the number of peers in the conference. Return value is unspecified on failure.
+     * Return the number of online peers in the conference. The unsigned 
+     * integers less than this number are the valid values of peer_number for 
+     * the functions querying these peers. Return value is unspecified on 
+     * failure.
      */
     const uint32_t count(uint32_t conference_number)
         with error for peer_query;
@@ -2327,7 +2330,9 @@ namespace conference {
   namespace offline_peer {
 
     /**
-     * Return the number of offline peers in the conference. Return value is unspecified on failure.
+     * Return the number of offline peers in the conference. The unsigned 
+     * integers less than this number are the valid values of offline_peer_number for 
+     * the functions querying these peers. Return value is unspecified on failure.
      */
     const uint32_t count(uint32_t conference_number)
         with error for peer_query;
@@ -2388,10 +2393,6 @@ 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.
    *
@@ -2416,6 +2417,14 @@ namespace conference {
   /**
    * Joins a conference that the client has been invited to.
    *
+   * After successfully joining the conference, the client will not be "connected"
+   * to it until a handshaking procedure has been completed. A
+   * `${event 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
+   * corresponding error if attempted on a conference to which the client is not
+   * yet connected.
+   *
    * @param friend_number The friend number of the friend who sent the invite.
    * @param cookie Received via the `${event invite}` event.
    * @param length The size of cookie.
@@ -2552,8 +2561,16 @@ namespace conference {
     size();
 
     /**
-     * Copy a list of valid conference IDs into the array chatlist. Determine how much space
+     * Copy a list of valid conference numbers into the array chatlist. Determine
-     * to allocate for the array with the `$size` function.
+     * how much space to allocate for the array with the `$size` function.
+     *
+     * Note that `${savedata.get}` saves all connected conferences;
+     * when toxcore is created from savedata in which conferences were saved, those
+     * conferences will be connected at startup, and will be listed by
+     * `$get`.
+     *
+     * The conference number of a loaded conference may differ from the conference
+     * number it had when it was saved.
      */
     get();
   }

toxcore/tox.h

@@ -2541,7 +2541,7 @@ typedef enum TOX_ERR_CONFERENCE_NEW {
 /**
  * Creates a new conference.
  *
- * This function creates a new text conference.
+ * This function creates and connects to a new text conference.
  *
  * @return conference number on success, or an unspecified value on failure.
  */
@@ -2600,7 +2600,10 @@ typedef enum TOX_ERR_CONFERENCE_PEER_QUERY {
 
 
 /**
- * Return the number of peers in the conference. Return value is unspecified on failure.
+ * Return the number of online peers in the conference. The unsigned
+ * integers less than this number are the valid values of peer_number for
+ * the functions querying these peers. Return value is unspecified on
+ * failure.
  */
 uint32_t tox_conference_peer_count(const Tox *tox, uint32_t conference_number, TOX_ERR_CONFERENCE_PEER_QUERY *error);
 
@@ -2638,7 +2641,9 @@ bool tox_conference_peer_number_is_ours(const Tox *tox, uint32_t conference_numb
                                         TOX_ERR_CONFERENCE_PEER_QUERY *error);
 
 /**
- * Return the number of offline peers in the conference. Return value is unspecified on failure.
+ * Return the number of offline peers in the conference. The unsigned
+ * integers less than this number are the valid values of offline_peer_number for
+ * the functions querying these peers. Return value is unspecified on failure.
  */
 uint32_t tox_conference_offline_peer_count(const Tox *tox, uint32_t conference_number,
         TOX_ERR_CONFERENCE_PEER_QUERY *error);
@@ -2725,10 +2730,6 @@ 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.
  *
@@ -2780,6 +2781,14 @@ typedef enum TOX_ERR_CONFERENCE_JOIN {
 /**
  * Joins a conference that the client has been invited to.
  *
+ * After successfully joining the conference, the client will not be "connected"
+ * 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
+ * corresponding error if attempted on a conference to which the client is not
+ * yet connected.
+ *
  * @param friend_number The friend number of the friend who sent the invite.
  * @param cookie Received via the `conference_invite` event.
  * @param length The size of cookie.
@@ -2906,8 +2915,16 @@ bool tox_conference_set_title(Tox *tox, uint32_t conference_number, const uint8_
 size_t tox_conference_get_chatlist_size(const Tox *tox);
 
 /**
- * Copy a list of valid conference IDs into the array chatlist. Determine how much space
+ * Copy a list of valid conference numbers into the array chatlist. Determine
- * to allocate for the array with the `tox_conference_get_chatlist_size` function.
+ * 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
+ * conferences will be connected at startup, and will be listed by
+ * `tox_conference_get_chatlist`.
+ *
+ * The conference number of a loaded conference may differ from the conference
+ * number it had when it was saved.
  */
 void tox_conference_get_chatlist(const Tox *tox, uint32_t *chatlist);