/work/toxcore/group_chats.h

Source (jump to first uncovered line)
/* SPDX-License-Identifier: GPL-3.0-or-later
 * Copyright © 2016-2020 The TokTok team.
 * Copyright © 2015 Tox project.
 */

/**
 * An implementation of massive text only group chats.
 */

#ifndef C_TOXCORE_TOXCORE_GROUP_CHATS_H
#define C_TOXCORE_TOXCORE_GROUP_CHATS_H

#include <stdbool.h>
#include <stdint.h>

#include "TCP_connection.h"
#include "attributes.h"
#include "bin_pack.h"
#include "bin_unpack.h"
#include "crypto_core.h"
#include "group_announce.h"
#include "group_common.h"
#include "group_connection.h"
#include "logger.h"
#include "mem.h"
#include "network.h"

#ifdef __cplusplus
extern "C" {
#endif

#define GC_PING_TIMEOUT 12
#define GC_SEND_IP_PORT_INTERVAL (GC_PING_TIMEOUT * 5)
#define GC_CONFIRMED_PEER_TIMEOUT (GC_PING_TIMEOUT * 4 + 10)
#define GC_UNCONFIRMED_PEER_TIMEOUT GC_PING_TIMEOUT

#define GC_JOIN_DATA_LENGTH (ENC_PUBLIC_KEY_SIZE + CHAT_ID_SIZE)

/** Group topic lock states. */
typedef enum Group_Topic_Lock {
    TL_ENABLED  = 0x00,  // Only the Founder and moderators may set the topic
    TL_DISABLED = 0x01,  // Anyone except Observers may set the topic
} Group_Topic_Lock;

/** Group moderation events. */
typedef enum Group_Moderation_Event {
    MV_KICK      = 0x00,  // A peer has been kicked
    MV_OBSERVER  = 0x01,  // A peer has been demoted to Observer
    MV_USER      = 0x02,  // A peer has been demoted or promoted to User
    MV_MOD       = 0x03,  // A peer has been promoted to or demoted from Moderator
} Group_Moderation_Event;

/** Messenger level group invite types */
typedef enum Group_Invite_Message_Type {
    GROUP_INVITE              = 0x00,  // Peer has initiated an invite
    GROUP_INVITE_ACCEPTED     = 0x01,  // Peer has accepted the invite
    GROUP_INVITE_CONFIRMATION = 0x02,  // Peer has confirmed the accepted invite
} Group_Invite_Message_Type;

/** Group join rejection types. */
typedef enum Group_Join_Rejected {
    GJ_GROUP_FULL       = 0x00,
    GJ_INVALID_PASSWORD = 0x01,
    GJ_INVITE_FAILED    = 0x02,
    GJ_INVALID          = 0x03,
} Group_Join_Rejected;

/** Group broadcast packet types */
typedef enum Group_Broadcast_Type {
    GM_STATUS          = 0x00,  // Peer changed their status
    GM_NICK            = 0x01,  // Peer changed their nickname
    GM_PLAIN_MESSAGE   = 0x02,  // Peer sent a normal message
    GM_ACTION_MESSAGE  = 0x03,  // Peer sent an action message
    GM_PRIVATE_MESSAGE = 0x04,  // Peer sent a private message
    GM_PEER_EXIT       = 0x05,  // Peer left the group
    GM_KICK_PEER       = 0x06,  // Peer was kicked from the group
    GM_SET_MOD         = 0x07,  // Peer was promoted to or demoted from Moderator role
    GM_SET_OBSERVER    = 0x08,  // Peer was demoted to or promoted from Observer role
} Group_Broadcast_Type;

/***
 * Group packet types.
 *
 * For a detailed spec, see docs/DHT_Group_Chats_Packet_Spec.md
 */
typedef enum Group_Packet_Type {
    /* lossy packets (ID 0 is reserved) */
    GP_PING                     = 0x01,
    GP_MESSAGE_ACK              = 0x02,
    GP_INVITE_RESPONSE_REJECT   = 0x03,

    /* lossless packets */
    GP_CUSTOM_PRIVATE_PACKET    = 0xee,
    GP_FRAGMENT                 = 0xef,
    GP_KEY_ROTATION             = 0xf0,
    GP_TCP_RELAYS               = 0xf1,
    GP_CUSTOM_PACKET            = 0xf2,
    GP_BROADCAST                = 0xf3,
    GP_PEER_INFO_REQUEST        = 0xf4,
    GP_PEER_INFO_RESPONSE       = 0xf5,
    GP_INVITE_REQUEST           = 0xf6,
    GP_INVITE_RESPONSE          = 0xf7,
    GP_SYNC_REQUEST             = 0xf8,
    GP_SYNC_RESPONSE            = 0xf9,
    GP_TOPIC                    = 0xfa,
    GP_SHARED_STATE             = 0xfb,
    GP_MOD_LIST                 = 0xfc,
    GP_SANCTIONS_LIST           = 0xfd,
    GP_FRIEND_INVITE            = 0xfe,
    GP_HS_RESPONSE_ACK          = 0xff,
} Group_Packet_Type;

/** Lossless message acknowledgement types. */
typedef enum Group_Message_Ack_Type {
    GR_ACK_RECV    = 0x00,  // indicates a message has been received
    GR_ACK_REQ     = 0x01,  // indicates a message needs to be re-sent
} Group_Message_Ack_Type;

/** @brief Returns the GC_Connection object associated with `peer_number`.
 * Returns null if peer_number does not designate a valid peer.
 */
GC_Connection *_Nullable get_gc_connection(const GC_Chat *_Nonnull chat, int peer_number);

/** @brief Returns the jenkins hash of a 32 byte public encryption key. */
uint32_t gc_get_pk_jenkins_hash(const uint8_t *_Nonnull public_key);

/** @brief Check if peer with the public encryption key is in peer list.
 *
 * Returns the peer number if peer is in the peer list.
 * Returns -1 if peer is not in the peer list.
 *
 * If `confirmed` is true the peer number will only be returned if the peer is confirmed.
 */
int get_peer_number_of_enc_pk(const GC_Chat *_Nonnull chat, const uint8_t *_Nonnull public_enc_key, bool confirmed);

/** @brief Encrypts `data` of size `length` using the peer's shared key and a new nonce.
 *
 * Adds encrypted header consisting of: packet type, message_id (only for lossless packets).
 * Adds plaintext header consisting of: packet identifier, self public encryption key, nonce.
 *
 * Return length of encrypted packet on success.
 * Return -1 if plaintext length is invalid.
 * Return -2 if malloc fails.
 * Return -3 if encryption fails.
 */
int group_packet_wrap(
    const Logger *_Nonnull log, const Memory *_Nonnull mem, const Random *_Nonnull rng, const uint8_t *_Nonnull self_pk, const uint8_t *_Nonnull shared_key, uint8_t *_Nonnull packet,
    uint16_t packet_size, const uint8_t *_Nullable data, uint16_t length, uint64_t message_id,
    uint8_t gp_packet_type, Net_Packet_Type net_packet_type);
/** @brief Returns the size of a wrapped/encrypted packet with a plain size of `length`.
 *
 * `packet_type` should be either NET_PACKET_GC_LOSSY or NET_PACKET_GC_LOSSLESS.
 */
uint16_t gc_get_wrapped_packet_size(uint16_t length, Net_Packet_Type packet_type);

/** @brief Sends a plain message or an action, depending on type.
 *
 * `length` must not exceed MAX_GC_MESSAGE_SIZE and must not be equal to zero.
 * `message_id` should either point to a uint32_t or be NULL.
 *
 * Returns 0 on success.
 * Returns -1 if the message is too long.
 * Returns -2 if the message pointer is NULL or length is zero.
 * Returns -3 if the message type is invalid.
 * Returns -4 if the sender does not have permission to speak.
 * Returns -5 if the packet fails to send.
 */
int gc_send_message(const GC_Chat *_Nonnull chat, const uint8_t *_Nonnull message, uint16_t length, uint8_t type,
                    uint32_t *_Nullable message_id);
/** @brief Sends a private message to peer_id.
 *
 * `length` must not exceed MAX_GC_MESSAGE_SIZE and must not be equal to zero.
 *
 * Returns 0 on success.
 * Returns -1 if the message is too long.
 * Returns -2 if the message pointer is NULL or length is zero.
 * Returns -3 if the peer_id is invalid.
 * Returns -4 if the message type is invalid.
 * Returns -5 if the sender has the observer role.
 * Returns -6 if the packet fails to send.
 */
int gc_send_private_message(const GC_Chat *_Nonnull chat, GC_Peer_Id peer_id, uint8_t type, const uint8_t *_Nonnull message,
                            uint16_t length, uint32_t *_Nullable message_id);
/** @brief Sends a custom packet to the group. If lossless is true, the packet will be lossless.
 *
 * `length` must not exceed MAX_GC_MESSAGE_SIZE and must not be equal to zero.
 *
 * Returns 0 on success.
 * Returns -1 if the message is too long.
 * Returns -2 if the message pointer is NULL or length is zero.
 * Returns -3 if the packet did not successfully send to any peer.
 */
int gc_send_custom_packet(const GC_Chat *_Nonnull chat, bool lossless, const uint8_t *_Nonnull data, uint16_t length);

/** @brief Sends a custom private packet to the peer designated by peer_id.
 *
 * `length` must not exceed MAX_GC_MESSAGE_SIZE and must not be equal to zero.
 *
 * @retval 0 on success.
 * @retval -1 if the message is too long.
 * @retval -2 if the message pointer is NULL or length is zero.
 * @retval -3 if the supplied peer_id does not designate a valid peer.
 * @retval -4 if the packet fails to send.
 */
int gc_send_custom_private_packet(const GC_Chat *_Nonnull chat, bool lossless, GC_Peer_Id peer_id, const uint8_t *_Nonnull message, uint16_t length);

/** @brief Sets ignore for peer_id.
 *
 * Returns 0 on success.
 * Returns -1 if the peer_id is invalid.
 * Returns -2 if the caller attempted to ignore himself.
 */
int gc_set_ignore(const GC_Chat *_Nonnull chat, GC_Peer_Id peer_id, bool ignore);

/** @brief Sets the group topic and broadcasts it to the group.
 *
 * If `length` is equal to zero the topic will be unset.
 *
 * Returns 0 on success.
 * Returns -1 if the topic is too long (must be `<= MAX_GC_TOPIC_SIZE`).
 * Returns -2 if the caller does not have the required permissions to set the topic.
 * Returns -3 if the packet cannot be created or signing fails.
 * Returns -4 if the packet fails
 */
int gc_set_topic(GC_Chat *_Nonnull chat, const uint8_t *_Nullable topic, uint16_t length);
/** @brief Copies the group topic to `topic`. If topic is null this function has no effect.
 *
 * Call `gc_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 topic callback.
 */
void gc_get_topic(const GC_Chat *_Nonnull chat, uint8_t *_Nullable topic);
/** @brief Returns the topic length.
 *
 * The return value is equal to the `length` agument received by the last topic callback.
 */
uint16_t gc_get_topic_size(const GC_Chat *_Nonnull chat);

/** @brief Copies group name to `group_name`. If `group_name` is null this function has no effect.
 *
 * Call `gc_get_group_name_size` to determine the allocation size for the `group_name`
 * parameter.
 */
void gc_get_group_name(const GC_Chat *_Nonnull chat, uint8_t *_Nonnull group_name);

/** @brief Returns the group name length. */
uint16_t gc_get_group_name_size(const GC_Chat *_Nonnull chat);

/** @brief Copies the group password to password.
 *
 * If password is null this function has no effect.
 *
 * Call the `gc_get_password_size` function to determine the allocation size for
 * the `password` buffer.
 *
 * The data received is equal to the data received by the last password callback.
 */
void gc_get_password(const GC_Chat *_Nonnull chat, uint8_t *_Nonnull password);

/** @brief Returns the group password length. */
uint16_t gc_get_password_size(const GC_Chat *_Nonnull chat);

/** @brief Returns the group privacy state.
 *
 * The value returned is equal to the data receieved by the last privacy_state callback.
 */
Group_Privacy_State gc_get_privacy_state(const GC_Chat *_Nonnull chat);

/** @brief Returns the group topic lock state.
 *
 * The value returned is equal to the data received by the last last topic_lock callback.
 */
Group_Topic_Lock gc_get_topic_lock_state(const GC_Chat *_Nonnull chat);

/** @brief Returns the group voice state.
 *
 * The value returned is equal to the data received by the last voice_state callback.
 */
Group_Voice_State gc_get_voice_state(const GC_Chat *_Nonnull chat);

/** @brief Returns the group peer limit.
 *
 * The value returned is equal to the data receieved by the last peer_limit callback.
 */
uint16_t gc_get_max_peers(const GC_Chat *_Nonnull chat);

/** @brief Sets your own nick to `nick`.
 *
 * `length` cannot exceed MAX_GC_NICK_SIZE. if `length` is zero or `name` is a
 * null pointer the function call will fail.
 *
 * Returns 0 on success.
 * Returns -1 if group_number is invalid.
 * Returns -2 if the length is too long.
 * Returns -3 if the length is zero or nick is a NULL pointer.
 * Returns -4 if the packet fails to send.
 */
int gc_set_self_nick(const Messenger *_Nonnull m, int group_number, const uint8_t *_Nonnull nick, uint16_t length);

/** @brief Copies your own name to `nick`.
 *
 * If `nick` is null this function has no effect.
 */
void gc_get_self_nick(const GC_Chat *_Nonnull chat, uint8_t *_Nonnull nick);

/** @brief Return your own nick length.
 *
 * If no nick was set before calling this function it will return 0.
 */
uint16_t gc_get_self_nick_size(const GC_Chat *_Nonnull chat);

/** @brief Returns your own group role. */
Group_Role gc_get_self_role(const GC_Chat *_Nonnull chat);

/** @brief Return your own status. */
uint8_t gc_get_self_status(const GC_Chat *_Nonnull chat);

/** @brief Returns your own peer id. */
GC_Peer_Id gc_get_self_peer_id(const GC_Chat *_Nonnull chat);

/** @brief Copies self public key to `public_key`.
 *
 * If `public_key` is null this function has no effect.
 *
 * This key is permanently tied to our identity for `chat` until we explicitly
 * exit the group. This key is the only way for other peers to reliably identify
 * us across client restarts.
 */
void gc_get_self_public_key(const GC_Chat *_Nonnull chat, uint8_t *_Nullable public_key);
/** @brief Copies nick designated by `peer_id` to `name`.
 *
 * Call `gc_get_peer_nick_size` to determine the allocation size for the `name` parameter.
 *
 * The data written to `name` is equal to the data received by the last nick_change callback.
 *
 * Returns true on success.
 * Returns false if peer_id is invalid.
 */
bool gc_get_peer_nick(const GC_Chat *_Nonnull chat, GC_Peer_Id peer_id, uint8_t *_Nullable name);
/** @brief Returns the length of the nick for the peer designated by `peer_id`.
 * Returns -1 if peer_id is invalid.
 *
 * The value returned is equal to the `length` argument received by the last
 * nick_change callback.
 */
int gc_get_peer_nick_size(const GC_Chat *_Nonnull chat, GC_Peer_Id peer_id);

/** @brief Copies peer_id's public key to `public_key`.
 *
 * This key is permanently tied to the peer's identity for `chat` until they explicitly
 * exit the group. This key is the only way for to reliably identify the given peer
 * across client restarts.
 *
 * `public_key` shold have room for at least ENC_PUBLIC_KEY_SIZE bytes.
 *
 * Returns 0 on success.
 * Returns -1 if peer_id is invalid or doesn't correspond to a valid peer connection.
 * Returns -2 if `public_key` is null.
 */
int gc_get_peer_public_key_by_peer_id(const GC_Chat *_Nonnull chat, GC_Peer_Id peer_id, uint8_t *_Nullable public_key);
/** @brief Returns the length of the IP address for the peer designated by `peer_id`.
 * Returns -1 if peer_id is invalid.
 */
int gc_get_peer_ip_address_size(const GC_Chat *_Nonnull chat, GC_Peer_Id peer_id);

/** @brief Copies peer_id's IP address to `ip_addr`.
 *
 * If the peer is forcing TCP connections this will be a placeholder value 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.
 *
 * `ip_addr` should have room for at least IP_NTOA_LEN bytes.
 *
 * Returns 0 on success.
 * Returns -1 if peer_id is invalid or doesn't correspond to a valid peer connection.
 * Returns -2 if `ip_addr` is null.
 */
int gc_get_peer_ip_address(const GC_Chat *_Nonnull chat, GC_Peer_Id peer_id, uint8_t *_Nullable ip_addr);
/** @brief Gets the connection status for peer associated with `peer_id`.
 *
 * 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.
 *
 * Returns 2 if we have a direct (UDP) connection with a peer.
 * Returns 1 if we have an indirect (TCP) connection with a peer.
 * Returns 0 if peer_id is invalid.
 *
 * Note: Return values must correspond to Tox_Connection enum in API.
 */
unsigned int gc_get_peer_connection_status(const GC_Chat *_Nonnull chat, GC_Peer_Id peer_id);

/** @brief Sets the caller's status to `status`.
 *
 * Returns 0 on success.
 * Returns -1 if the group_number is invalid.
 * Returns -2 if the packet failed to send.
 */
int gc_set_self_status(const Messenger *_Nonnull m, int group_number, Group_Peer_Status status);

/** @brief Returns the status of peer designated by `peer_id`.
 * Returns UINT8_MAX on failure.
 *
 * The status returned is equal to the last status received through the status_change
 * callback.
 */
uint8_t gc_get_status(const GC_Chat *_Nonnull chat, GC_Peer_Id peer_id);

/** @brief Returns the group role of peer designated by `peer_id`.
 * Returns UINT8_MAX on failure.
 *
 * The role returned is equal to the last role received through the moderation callback.
 */
uint8_t gc_get_role(const GC_Chat *_Nonnull chat, GC_Peer_Id peer_id);

/** @brief Sets the role of peer_id. role must be one of: GR_MODERATOR, GR_USER, GR_OBSERVER
 *
 * Returns 0 on success.
 * Returns -1 if the group_number is invalid.
 * Returns -2 if the peer_id is invalid.
 * Returns -3 if caller does not have sufficient permissions for the action.
 * Returns -4 if the role assignment is invalid.
 * Returns -5 if the role failed to be set.
 * Returns -6 if the caller attempted to kick himself.
 */
int gc_set_peer_role(const Messenger *_Nonnull m, int group_number, GC_Peer_Id peer_id, Group_Role new_role);

/** @brief Sets the group password and distributes the new shared state to the group.
 *
 * This function requires that the shared state be re-signed and will only work for the group founder.
 *
 * If `password` is null or `password_length` is 0 the password will be unset for the group.
 *
 * Returns 0 on success.
 * Returns -1 if the caller does not have sufficient permissions for the action.
 * Returns -2 if the password is too long.
 * Returns -3 if the packet failed to send.
 * Returns -4 if malloc failed.
 */
int gc_founder_set_password(GC_Chat *_Nonnull chat, const uint8_t *_Nullable password, uint16_t password_length);
/** @brief Sets the topic lock and distributes the new shared state to 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.
 *
 * This function requires that the shared state be re-signed and will only work for the group founder.
 *
 * Returns 0 on success.
 * Returns -1 if group_number is invalid.
 * Returns -2 if `topic_lock` is an invalid type.
 * Returns -3 if the caller does not have sufficient permissions for this action.
 * Returns -4 if the group is disconnected.
 * Returns -5 if the topic lock could not be set.
 * Returns -6 if the packet failed to send.
 */
int gc_founder_set_topic_lock(const Messenger *_Nonnull m, int group_number, Group_Topic_Lock new_lock_state);

/** @brief Sets the group privacy state and distributes the new shared state to the group.
 *
 * This function requires that the shared state be re-signed and will only work for the group founder.
 *
 * 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.
 *
 * Returns 0 on success.
 * Returns -1 if group_number is invalid.
 * Returns -2 if the caller does not have sufficient permissions for this action.
 * Returns -3 if the group is disconnected.
 * Returns -4 if the privacy state could not be set.
 * Returns -5 if the packet failed to send.
 */
int gc_founder_set_privacy_state(const Messenger *_Nonnull m, int group_number, Group_Privacy_State new_privacy_state);

/** @brief Sets the group voice state and distributes the new shared state to the group.
 *
 * This function requires that the shared state be re-signed and will only work for the group founder.
 *
 * 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.
 *
 * Returns 0 on success.
 * Returns -1 if group_number is invalid.
 * Returns -2 if the caller does not have sufficient permissions for this action.
 * Returns -3 if the group is disconnected.
 * Returns -4 if the voice state could not be set.
 * Returns -5 if the packet failed to send.
 */
int gc_founder_set_voice_state(const Messenger *_Nonnull m, int group_number, Group_Voice_State new_voice_state);

/** @brief Sets the peer limit to maxpeers and distributes the new shared state to the group.
 *
 * This function requires that the shared state be re-signed and will only work for the group founder.
 *
 * Returns 0 on success.
 * Returns -1 if the caller does not have sufficient permissions for this action.
 * Returns -2 if the peer limit could not be set.
 * Returns -3 if the packet failed to send.
 */
int gc_founder_set_max_peers(GC_Chat *_Nonnull chat, uint16_t max_peers);

/** @brief Removes peer designated by `peer_id` from peer list and sends a broadcast instructing
 * all other peers to remove the peer from their peerlist as well.
 *
 * This function will not trigger the peer_exit callback for the caller.
 *
 * Returns 0 on success.
 * Returns -1 if the group_number is invalid.
 * Returns -2 if the peer_id is invalid.
 * Returns -3 if the caller does not have sufficient permissions for this action.
 * Returns -4 if the action failed.
 * Returns -5 if the packet failed to send.
 * Returns -6 if the caller attempted to kick himself.
 */
int gc_kick_peer(const Messenger *_Nonnull m, int group_number, GC_Peer_Id peer_id);

/** @brief Copies the chat_id to dest. If dest is null this function has no effect.
 *
 * `dest` should have room for at least CHAT_ID_SIZE bytes.
 */
void gc_get_chat_id(const GC_Chat *_Nonnull chat, uint8_t *_Nullable dest);
/** Group callbacks */
void gc_callback_message(const Messenger *_Nonnull m, gc_message_cb *_Nullable function);
void gc_callback_private_message(const Messenger *_Nonnull m, gc_private_message_cb *_Nullable function);
void gc_callback_custom_packet(const Messenger *_Nonnull m, gc_custom_packet_cb *_Nullable function);
void gc_callback_custom_private_packet(const Messenger *_Nonnull m,
                                       gc_custom_private_packet_cb *_Nullable function);
void gc_callback_moderation(const Messenger *_Nonnull m, gc_moderation_cb *_Nullable function);
void gc_callback_nick_change(const Messenger *_Nonnull m, gc_nick_change_cb *_Nullable function);
void gc_callback_status_change(const Messenger *_Nonnull m, gc_status_change_cb *_Nullable function);
void gc_callback_topic_change(const Messenger *_Nonnull m, gc_topic_change_cb *_Nullable function);
void gc_callback_peer_limit(const Messenger *_Nonnull m, gc_peer_limit_cb *_Nullable function);
void gc_callback_privacy_state(const Messenger *_Nonnull m, gc_privacy_state_cb *_Nullable function);
void gc_callback_topic_lock(const Messenger *_Nonnull m, gc_topic_lock_cb *_Nullable function);
void gc_callback_password(const Messenger *_Nonnull m, gc_password_cb *_Nullable function);
void gc_callback_peer_join(const Messenger *_Nonnull m, gc_peer_join_cb *_Nullable function);
void gc_callback_peer_exit(const Messenger *_Nonnull m, gc_peer_exit_cb *_Nullable function);
void gc_callback_self_join(const Messenger *_Nonnull m, gc_self_join_cb *_Nullable function);
void gc_callback_rejected(const Messenger *_Nonnull m, gc_rejected_cb *_Nullable function);
void gc_callback_voice_state(const Messenger *_Nonnull m, gc_voice_state_cb *_Nullable function);

/** @brief The main loop. Should be called with every Messenger iteration. */
void do_gc(GC_Session *_Nonnull c, void *_Nullable userdata);
/**
 * Make sure that DHT is initialized before calling this.
 * Returns a NULL pointer on failure.
 */
GC_Session *_Nullable new_dht_groupchats(Messenger *_Nonnull m);
/** @brief Cleans up groupchat structures and calls `gc_group_exit()` for every group chat */
void kill_dht_groupchats(GC_Session *_Nullable c);
/** @brief Loads a previously saved group and attempts to join it.
 *
 * `bu` is the packed group info.
 *
 * Returns group_number on success.
 * Returns -1 on failure.
 */
int gc_group_load(GC_Session *_Nonnull c, Bin_Unpack *_Nonnull bu);

/**
 * @brief Saves info from `chat` to `bp` in binary format.
 */
void gc_group_save(const GC_Chat *_Nonnull chat, Bin_Pack *_Nonnull bp);

/** @brief Creates a new group and adds it to the group sessions group array.
 *
 * 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.
 *
 * Return -1 if the nick or group name is too long.
 * Return -2 if the nick or group name is empty.
 * Return -3 if the the group object fails to initialize.
 * Return -4 if the group state fails to initialize.
 * Return -5 if the Messenger friend connection fails to initialize.
 */
int gc_group_add(GC_Session *_Nonnull c, Group_Privacy_State privacy_state, const uint8_t *_Nonnull group_name, uint16_t group_name_length, const uint8_t *_Nonnull nick, size_t nick_length);

/** @brief Joins a group designated by `chat_id`.
 *
 * This function creates a new GC_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.
 *
 * If the group is not password protected password should be set to NULL and password_length should be 0.
 *
 * Return group_number on success.
 * Return -1 if the group object fails to initialize.
 * Return -2 if chat_id is NULL.
 * Return -3 if nick is too long.
 * Return -4 if nick is empty or nick length is zero.
 * Return -5 if there is an error setting the group password.
 * Return -6 if the Messenger friend connection fails to initialize.
 */
int gc_group_join(GC_Session *_Nonnull c, const uint8_t *_Nonnull chat_id, const uint8_t *_Nonnull nick, size_t nick_length, const uint8_t *_Nullable passwd,
                  uint16_t passwd_len);
/** @brief Disconnects from all peers in a group but saves the group state for later use.
 *
 * Return true on sucess.
 * Return false if the group handler object or chat object is null.
 */
bool gc_disconnect_from_group(const GC_Session *_Nonnull c, GC_Chat *_Nonnull chat);

/** @brief Disconnects from all peers in a group and attempts to reconnect.
 *
 * All self state and credentials are retained.
 *
 * Returns 0 on success.
 * Returns -1 if the group handler object or chat object is null.
 * Returns -2 if the Messenger friend connection fails to initialize.
 */
int gc_rejoin_group(GC_Session *_Nonnull c, GC_Chat *_Nonnull chat, const uint8_t *_Nullable passwd, uint16_t passwd_len);
/** @brief Joins a group using the invite data received in a friend's group invite.
 *
 * The invite is only valid while the inviter is present in the group.
 *
 * Return group_number on success.
 * Return -1 if the invite data is malformed.
 * Return -2 if the group object fails to initialize.
 * Return -3 if nick is too long.
 * Return -4 if nick is empty or nick length is zero.
 * Return -5 if there is an error setting the password.
 * Return -6 if friend doesn't exist.
 * Return -7 if sending packet failed.
 */
int gc_accept_invite(GC_Session *_Nonnull c, int32_t friend_number, const uint8_t *_Nonnull data, uint16_t length, const uint8_t *_Nonnull nick,
                     size_t nick_length, const uint8_t *_Nullable passwd, uint16_t passwd_len);
typedef bool gc_send_group_invite_packet_cb(const Messenger *_Nonnull m, uint32_t friendnumber, const uint8_t *_Nonnull packet,
        uint16_t length);

/** @brief Invites friend designated by `friendnumber` to chat.
 * Packet includes: Type, chat_id, TCP node or packed IP_Port.
 *
 * Return 0 on success.
 * Return -1 if friendnumber does not exist.
 * Return -2 on failure to create the invite data.
 * Return -3 if the packet fails to send.
 */
int gc_invite_friend(const GC_Session *_Nonnull c, GC_Chat *_Nonnull chat, int32_t friend_number, gc_send_group_invite_packet_cb *_Nonnull callback);

/** @brief Leaves a group and sends an exit broadcast packet with an optional parting message.
 *
 * All group state is permanently lost, including keys and roles.
 *
 * Return 0 on success.
 * Return -1 if the parting message is too long.
 * Return -2 if the parting message failed to send.
 */
int gc_group_exit(GC_Session *_Nonnull c, GC_Chat *_Nonnull chat, const uint8_t *_Nullable message, uint16_t length);
/** @brief Returns true if `chat` is a valid group chat.
 *
 * A valid group chat constitutes an initialized chat instance with a non-zero shared state version.
 * The shared state version will be non-zero either if a peer has created the group, or if
 * they have ever successfully connected to the group.
 */
bool gc_group_is_valid(const GC_Chat *_Nonnull chat);

/** @brief Returns the number of active groups in `c`. */
uint32_t gc_count_groups(const GC_Session *_Nonnull c);

/** @brief Copy a list of valid group numbers into the array group_list. */
uint32_t gc_get_group_list(const GC_Session *_Nonnull c, uint32_t *_Nonnull group_list);

/** @brief Returns true if peer_number exists */
bool gc_peer_number_is_valid(const GC_Chat *_Nonnull chat, int peer_number);

/** @brief Return group_number's GC_Chat pointer on success
 * Return NULL on failure
 */
GC_Chat *_Nullable gc_get_group(const GC_Session *_Nonnull c, int group_number);

/** @brief Sends a lossy message acknowledgement to peer associated with `gconn`.
 *
 * If `type` is GR_ACK_RECV we send a read-receipt for read_id's packet. If `type` is GR_ACK_REQ
 * we send a request for the respective id's packet.
 *
 * Requests are limited to one per second per peer.
 *
 * @retval true on success.
 */
bool gc_send_message_ack(const GC_Chat *_Nonnull chat, GC_Connection *_Nonnull gconn, uint64_t message_id, Group_Message_Ack_Type type);

/** @brief Helper function for `handle_gc_lossless_packet()`.
 *
 * Note: This function may modify the peer list and change peer numbers.
 *
 * @retval true if packet is successfully handled.
 */
bool handle_gc_lossless_helper(const GC_Session *_Nonnull c, GC_Chat *_Nonnull chat, uint32_t peer_number, const uint8_t *_Nullable data,
                               uint16_t length, uint8_t packet_type, void *_Nullable userdata);
/** @brief Handles an invite accept packet.
 *
 * @retval true on success.
 */
bool handle_gc_invite_accepted_packet(const GC_Session *_Nonnull c, int friend_number, const uint8_t *_Nonnull data, uint16_t length);

/** @brief Return true if `chat_id` is not present in our group sessions array.
 *
 * `length` must be at least CHAT_ID_SIZE bytes in length.
 */
bool group_not_added(const GC_Session *_Nonnull c, const uint8_t *_Nonnull chat_id, uint32_t length);

/** @brief Handles an invite confirmed packet.
 *
 * Return 0 on success.
 * Return -1 if length is invalid.
 * Return -2 if data contains invalid chat_id.
 * Return -3 if data contains invalid peer info.
 * Return -4 if `friend_number` does not designate a valid friend.
 * Return -5 if data contains invalid connection info.
 */
int handle_gc_invite_confirmed_packet(const GC_Session *_Nonnull c, int friend_number, const uint8_t *_Nonnull data, uint16_t length);

/** @brief Returns the group designated by `public_key`.
 * Returns null if group does not exist.
 */
GC_Chat *_Nullable gc_get_group_by_public_key(const GC_Session *_Nonnull c, const uint8_t *_Nonnull public_key);

/** @brief Attempts to add peers from `announces` to our peer list and initiate an invite request.
 *
 * Returns the number of peers added on success.
 * Returns -1 on failure.
 */
int gc_add_peers_from_announces(GC_Chat *_Nonnull chat, const GC_Announce *_Nonnull announces, uint8_t gc_announces_count);

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

#endif /* C_TOXCORE_TOXCORE_GROUP_CHATS_H */

Coverage Report

Created: 2026-10-24 08:16