261d2e53b7
11ab1d2a723 fix: reduce memory usage in group chats by 75% Significantly reduced the memory usage of groups since all message slots are preallocated for every peer for send and receive buffers of buffer size (hundreds of MiB peak when save contained alot of peers to try to connect to) 4f09f4e147c chore: Fix tsan build by moving it to GitHub CI. 6460c25c9e0 refactor: Use `merge_sort` instead of `qsort` for sorting. c660bbe8c95 test: Fix crypto_test to initialise its plain text buffer. 0204db6184b cleanup: Fix layering check warnings. df2211e1548 refactor: Use tox memory allocator for temporary buffers in crypto. ac812871a2e feat: implement the last 2 missing network struct functions and make use of them 29d1043be0b test: friend request test now tests min/max message sizes 93aafd78c1f fix: friend requests with very long messages are no longer dropped 819aa2b2618 feat: Add option to disable DNS lookups in toxcore. 0ac23cee035 fix: windows use of REUSEADDR 7d2811d302d chore(ci): make bazel server shutdown faster 1dc399ba20d chore: Use vcpkg instead of conan in the MSVC build. 14d823165d9 chore: Migrate to conan 2. bdd17c16787 cleanup: Allocate logger using tox memory allocator. b396c061515 chore(deps): bump third_party/cmp from `2ac6bca` to `52bfcfa` 2e94da60d09 feat(net): add missing connect to network struct 41fb1839c7b chore: Add check to ensure version numbers agree. 934a8301113 chore: Release 0.2.20 3acef4bf044 fix: Add missing free in dht_get_nodes_response event. git-subtree-dir: external/toxcore/c-toxcore git-subtree-split: 11ab1d2a7232eee19b51ce126ccce267d6578903
5789 lines
178 KiB
C
5789 lines
178 KiB
C
/* SPDX-License-Identifier: GPL-3.0-or-later
|
|
* Copyright © 2016-2024 The TokTok team.
|
|
* Copyright © 2013 Tox project.
|
|
*/
|
|
|
|
/** @file
|
|
* @brief Public core API for Tox clients.
|
|
*
|
|
* Every function that can fail takes a function-specific error code pointer
|
|
* that can be used to diagnose problems with the Tox state or the function
|
|
* arguments. The error code pointer can be NULL, which does not influence the
|
|
* function's behaviour, but can be done if the reason for failure is irrelevant
|
|
* to the client.
|
|
*
|
|
* The exception to this rule are simple allocation functions whose only failure
|
|
* mode is allocation failure. They return NULL in that case, and do not set an
|
|
* error code.
|
|
*
|
|
* Every error code type has an OK value to which functions will set their error
|
|
* code value on success. Clients can keep their error code uninitialised before
|
|
* passing it to a function. The library guarantees that after returning, the
|
|
* value pointed to by the error code pointer has been initialised.
|
|
*
|
|
* Functions with pointer parameters often have a NULL error code, meaning they
|
|
* 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.
|
|
*
|
|
* All functions that take a Tox instance pointer will cause undefined behaviour
|
|
* when passed a NULL Tox pointer.
|
|
*
|
|
* All integer values are expected in host byte order.
|
|
*
|
|
* Functions with parameters with enum types cause unspecified behaviour if the
|
|
* enumeration value is outside the valid range of the type. If possible, the
|
|
* function will try to use a sane default, but there will be no error code,
|
|
* and one possible action for the function to take is to have no effect.
|
|
*
|
|
* Integer constants and the memory layout of publicly exposed structs are not
|
|
* part of the ABI.
|
|
*
|
|
* @section events Events and callbacks
|
|
*
|
|
* Events are handled by callbacks. One callback can be registered per event.
|
|
* All events have a callback function type named `tox_{event}_cb` and a
|
|
* function to register it named `tox_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.
|
|
*
|
|
* 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.
|
|
*
|
|
* @section threading Threading implications
|
|
*
|
|
* It is possible to run multiple concurrent threads with a Tox instance for
|
|
* each thread. It is also possible to run all Tox instances in the same thread.
|
|
* A common way to run Tox (multiple or single instance) is to have one thread
|
|
* running a simple tox_iterate loop, sleeping for tox_iteration_interval
|
|
* milliseconds on each iteration.
|
|
*
|
|
* If you want to access a single Tox instance from multiple threads, access
|
|
* to the instance must be synchronised. While multiple threads can concurrently
|
|
* access multiple different Tox instances, no more than one API function can
|
|
* operate on a single instance at any given time.
|
|
*
|
|
* Functions that write to variable length byte arrays will always have a size
|
|
* function associated with them. The result of this size function is only valid
|
|
* until another mutating function (one that takes a pointer to non-const Tox)
|
|
* is called. Thus, clients must ensure that no other thread calls a mutating
|
|
* function between the call to the size function and the call to the retrieval
|
|
* function.
|
|
*
|
|
* E.g. to get the current nickname, one would write
|
|
*
|
|
* @code
|
|
* size_t length = tox_self_get_name_size(tox);
|
|
* uint8_t *name = malloc(length);
|
|
* if (!name) abort();
|
|
* tox_self_get_name(tox, name);
|
|
* @endcode
|
|
*
|
|
* If any other thread calls tox_self_set_name while this thread is allocating
|
|
* memory, the length may have become invalid, and the call to
|
|
* tox_self_get_name may cause undefined behaviour.
|
|
*/
|
|
#ifndef C_TOXCORE_TOXCORE_TOX_H
|
|
#define C_TOXCORE_TOXCORE_TOX_H
|
|
|
|
#include <stdbool.h>
|
|
#include <stddef.h>
|
|
#include <stdint.h>
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/** @{ @namespace tox */
|
|
|
|
#ifndef TOX_DEFINED
|
|
#define TOX_DEFINED
|
|
/**
|
|
* @brief The Tox instance type.
|
|
*
|
|
* All the state associated with a connection is held
|
|
* within the instance. Multiple instances can exist and operate concurrently.
|
|
* The maximum number of Tox instances that can exist on a single network
|
|
* device is limited. Note that this is not just a per-process limit, since the
|
|
* limiting factor is the number of usable ports on a device.
|
|
*/
|
|
typedef struct Tox Tox;
|
|
#endif /* TOX_DEFINED */
|
|
|
|
/** @{
|
|
* @name API version
|
|
*/
|
|
|
|
/**
|
|
* @brief The major version number.
|
|
*
|
|
* Incremented when the API or ABI changes in an incompatible way.
|
|
*
|
|
* The function variants of these constants return the version number of the
|
|
* library. They can be used to display the Tox library version or to check
|
|
* whether the client is compatible with the dynamically linked version of Tox.
|
|
*/
|
|
#define TOX_VERSION_MAJOR 0
|
|
|
|
uint32_t tox_version_major(void);
|
|
|
|
/**
|
|
* @brief The minor version number.
|
|
*
|
|
* Incremented when functionality is added without breaking the API or ABI.
|
|
* Set to 0 when the major version number is incremented.
|
|
*/
|
|
#define TOX_VERSION_MINOR 2
|
|
|
|
uint32_t tox_version_minor(void);
|
|
|
|
/**
|
|
* @brief The patch or revision number.
|
|
*
|
|
* Incremented when bugfixes are applied without changing any functionality or
|
|
* API or ABI.
|
|
*/
|
|
#define TOX_VERSION_PATCH 20
|
|
|
|
uint32_t tox_version_patch(void);
|
|
|
|
//!TOKSTYLE-
|
|
/**
|
|
* @brief A macro to check at preprocessing time whether the client code is
|
|
* compatible with the installed version of Tox.
|
|
*
|
|
* Leading zeros in the version number are ignored. E.g. 0.1.5 is to 0.1.4
|
|
* what 1.5 is to 1.4, that is: it can add new features, but can't break the
|
|
* API.
|
|
*/
|
|
#define TOX_VERSION_IS_API_COMPATIBLE(MAJOR, MINOR, PATCH) \
|
|
((TOX_VERSION_MAJOR > 0 && TOX_VERSION_MAJOR == MAJOR) && ( \
|
|
/* 1.x.x, 2.x.x, etc. with matching major version. */ \
|
|
TOX_VERSION_MINOR > MINOR || \
|
|
(TOX_VERSION_MINOR == MINOR && TOX_VERSION_PATCH >= PATCH) \
|
|
)) || ((TOX_VERSION_MAJOR == 0 && MAJOR == 0) && ( \
|
|
/* 0.x.x makes minor behave like major above. */ \
|
|
((TOX_VERSION_MINOR > 0 && TOX_VERSION_MINOR == MINOR) && ( \
|
|
TOX_VERSION_PATCH >= PATCH \
|
|
)) || ((TOX_VERSION_MINOR == 0 && MINOR == 0) && ( \
|
|
/* 0.0.x and 0.0.y are only compatible if x == y. */ \
|
|
TOX_VERSION_PATCH == PATCH \
|
|
)) \
|
|
))
|
|
//!TOKSTYLE+
|
|
|
|
/**
|
|
* @brief Return whether the compiled library version is compatible with the
|
|
* passed version numbers.
|
|
*/
|
|
bool tox_version_is_compatible(uint32_t major, uint32_t minor, uint32_t patch);
|
|
|
|
/**
|
|
* @brief A convenience macro to call tox_version_is_compatible with the
|
|
* currently compiling API version.
|
|
*/
|
|
#define TOX_VERSION_IS_ABI_COMPATIBLE() \
|
|
tox_version_is_compatible(TOX_VERSION_MAJOR, TOX_VERSION_MINOR, TOX_VERSION_PATCH)
|
|
|
|
/** @} */
|
|
|
|
/** @{
|
|
* @name Numeric constants
|
|
*
|
|
* 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 the Tox library.
|
|
*/
|
|
|
|
/**
|
|
* @brief The size of a Tox Public Key in bytes.
|
|
*/
|
|
#define TOX_PUBLIC_KEY_SIZE 32
|
|
|
|
uint32_t tox_public_key_size(void);
|
|
|
|
/**
|
|
* @brief The size of a Tox Secret Key in bytes.
|
|
*/
|
|
#define TOX_SECRET_KEY_SIZE 32
|
|
|
|
uint32_t tox_secret_key_size(void);
|
|
|
|
/**
|
|
* @brief The size of a Tox Conference unique id in bytes.
|
|
*
|
|
* @deprecated Use TOX_CONFERENCE_ID_SIZE instead.
|
|
*/
|
|
#define TOX_CONFERENCE_UID_SIZE 32
|
|
|
|
uint32_t tox_conference_uid_size(void);
|
|
|
|
/**
|
|
* @brief The size of a Tox Conference unique id in bytes.
|
|
*/
|
|
#define TOX_CONFERENCE_ID_SIZE 32
|
|
|
|
uint32_t tox_conference_id_size(void);
|
|
|
|
/**
|
|
* @brief The size of the nospam in bytes when written in a Tox address.
|
|
*/
|
|
#define TOX_NOSPAM_SIZE (sizeof(uint32_t))
|
|
|
|
uint32_t tox_nospam_size(void);
|
|
|
|
/**
|
|
* @brief The size of a Tox address in bytes.
|
|
*
|
|
* Tox addresses are in the format
|
|
* `[Public Key (TOX_PUBLIC_KEY_SIZE bytes)][nospam (4 bytes)][checksum (2 bytes)]`.
|
|
*
|
|
* The checksum is computed over the Public Key and the nospam value. The first
|
|
* byte is an XOR of all the even bytes (0, 2, 4, ...), the second byte is an
|
|
* XOR of all the odd bytes (1, 3, 5, ...) of the Public Key and nospam.
|
|
*/
|
|
#define TOX_ADDRESS_SIZE (TOX_PUBLIC_KEY_SIZE + TOX_NOSPAM_SIZE + sizeof(uint16_t))
|
|
|
|
uint32_t tox_address_size(void);
|
|
|
|
/**
|
|
* @brief Maximum length of a nickname in bytes.
|
|
*
|
|
* @deprecated The macro will be removed in 0.3.0. Use the function instead.
|
|
*/
|
|
#define TOX_MAX_NAME_LENGTH 128
|
|
|
|
uint32_t tox_max_name_length(void);
|
|
|
|
/**
|
|
* @brief Maximum length of a status message in bytes.
|
|
*
|
|
* @deprecated The macro will be removed in 0.3.0. Use the function instead.
|
|
*/
|
|
#define TOX_MAX_STATUS_MESSAGE_LENGTH 1007
|
|
|
|
uint32_t tox_max_status_message_length(void);
|
|
|
|
/**
|
|
* @brief Maximum length of a friend request message in bytes.
|
|
*
|
|
* @deprecated The macro will be removed in 0.3.0. Use the function instead.
|
|
*/
|
|
#define TOX_MAX_FRIEND_REQUEST_LENGTH 921
|
|
|
|
uint32_t tox_max_friend_request_length(void);
|
|
|
|
/**
|
|
* @brief Maximum length of a single message after which it should be split.
|
|
*
|
|
* @deprecated The macro will be removed in 0.3.0. Use the function instead.
|
|
*/
|
|
#define TOX_MAX_MESSAGE_LENGTH 1372
|
|
|
|
uint32_t tox_max_message_length(void);
|
|
|
|
/**
|
|
* @brief Maximum size of custom packets. TODO(iphydf): should be LENGTH?
|
|
*
|
|
* @deprecated The macro will be removed in 0.3.0. Use the function instead.
|
|
*/
|
|
#define TOX_MAX_CUSTOM_PACKET_SIZE 1373
|
|
|
|
uint32_t tox_max_custom_packet_size(void);
|
|
|
|
/**
|
|
* @brief The number of bytes in a hash generated by tox_hash.
|
|
*/
|
|
#define TOX_HASH_LENGTH 32
|
|
|
|
uint32_t tox_hash_length(void);
|
|
|
|
/**
|
|
* @brief The number of bytes in a file id.
|
|
*/
|
|
#define TOX_FILE_ID_LENGTH 32
|
|
|
|
uint32_t tox_file_id_length(void);
|
|
|
|
/**
|
|
* @brief Maximum file name length for file transfers.
|
|
*
|
|
* @deprecated The macro will be removed in 0.3.0. Use the function instead.
|
|
*/
|
|
#define TOX_MAX_FILENAME_LENGTH 255
|
|
|
|
uint32_t tox_max_filename_length(void);
|
|
|
|
/**
|
|
* @brief Maximum length of a hostname, e.g. proxy or bootstrap node names.
|
|
*
|
|
* This length does not include the NUL byte. Hostnames are NUL-terminated C
|
|
* strings, so they are 255 characters plus one NUL byte.
|
|
*
|
|
* @deprecated The macro will be removed in 0.3.0. Use the function instead.
|
|
*/
|
|
#define TOX_MAX_HOSTNAME_LENGTH 255
|
|
|
|
uint32_t tox_max_hostname_length(void);
|
|
|
|
/** @} */
|
|
|
|
/** @{
|
|
* @name Global enumerations
|
|
*/
|
|
|
|
/**
|
|
* @brief Represents the possible statuses a client can have.
|
|
*/
|
|
typedef enum Tox_User_Status {
|
|
|
|
/**
|
|
* User is online and available.
|
|
*/
|
|
TOX_USER_STATUS_NONE,
|
|
|
|
/**
|
|
* User is away. Clients can set this e.g. after a user defined
|
|
* inactivity time.
|
|
*/
|
|
TOX_USER_STATUS_AWAY,
|
|
|
|
/**
|
|
* User is busy. Signals to other clients that this client does not
|
|
* currently wish to communicate.
|
|
*/
|
|
TOX_USER_STATUS_BUSY,
|
|
|
|
} Tox_User_Status;
|
|
|
|
const char *tox_user_status_to_string(Tox_User_Status value);
|
|
|
|
/**
|
|
* @brief Represents message types for tox_friend_send_message and conference
|
|
* messages.
|
|
*/
|
|
typedef enum Tox_Message_Type {
|
|
|
|
/**
|
|
* Normal text message. Similar to PRIVMSG on IRC.
|
|
*/
|
|
TOX_MESSAGE_TYPE_NORMAL,
|
|
|
|
/**
|
|
* A message describing an user action. This is similar to /me (CTCP ACTION)
|
|
* on IRC.
|
|
*/
|
|
TOX_MESSAGE_TYPE_ACTION,
|
|
|
|
} Tox_Message_Type;
|
|
|
|
const char *tox_message_type_to_string(Tox_Message_Type value);
|
|
|
|
/** @} */
|
|
|
|
/** @{
|
|
* @name Startup options
|
|
*/
|
|
|
|
/**
|
|
* @brief Type of proxy used to connect to TCP relays.
|
|
*/
|
|
typedef enum Tox_Proxy_Type {
|
|
|
|
/**
|
|
* Don't use a proxy.
|
|
*/
|
|
TOX_PROXY_TYPE_NONE,
|
|
|
|
/**
|
|
* HTTP proxy using CONNECT.
|
|
*/
|
|
TOX_PROXY_TYPE_HTTP,
|
|
|
|
/**
|
|
* SOCKS proxy for simple socket pipes.
|
|
*/
|
|
TOX_PROXY_TYPE_SOCKS5,
|
|
|
|
} Tox_Proxy_Type;
|
|
|
|
const char *tox_proxy_type_to_string(Tox_Proxy_Type value);
|
|
|
|
/**
|
|
* @brief Type of savedata to create the Tox instance from.
|
|
*/
|
|
typedef enum Tox_Savedata_Type {
|
|
|
|
/**
|
|
* No savedata.
|
|
*/
|
|
TOX_SAVEDATA_TYPE_NONE,
|
|
|
|
/**
|
|
* Savedata is one that was obtained from tox_get_savedata.
|
|
*/
|
|
TOX_SAVEDATA_TYPE_TOX_SAVE,
|
|
|
|
/**
|
|
* Savedata is a secret key of length TOX_SECRET_KEY_SIZE.
|
|
*/
|
|
TOX_SAVEDATA_TYPE_SECRET_KEY,
|
|
|
|
} Tox_Savedata_Type;
|
|
|
|
const char *tox_savedata_type_to_string(Tox_Savedata_Type value);
|
|
|
|
/**
|
|
* @brief Severity level of log messages.
|
|
*/
|
|
typedef enum Tox_Log_Level {
|
|
|
|
/**
|
|
* Very detailed traces including all network activity.
|
|
*/
|
|
TOX_LOG_LEVEL_TRACE,
|
|
|
|
/**
|
|
* Debug messages such as which port we bind to.
|
|
*/
|
|
TOX_LOG_LEVEL_DEBUG,
|
|
|
|
/**
|
|
* Informational log messages such as video call status changes.
|
|
*/
|
|
TOX_LOG_LEVEL_INFO,
|
|
|
|
/**
|
|
* Warnings about internal inconsistency or logic errors.
|
|
*/
|
|
TOX_LOG_LEVEL_WARNING,
|
|
|
|
/**
|
|
* Severe unexpected errors caused by external or internal inconsistency.
|
|
*/
|
|
TOX_LOG_LEVEL_ERROR,
|
|
|
|
} Tox_Log_Level;
|
|
|
|
const char *tox_log_level_to_string(Tox_Log_Level value);
|
|
|
|
/**
|
|
* @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
|
|
* least extend between registering and unregistering it or tox_kill.
|
|
*
|
|
* Other toxcore modules such as toxav may concurrently call this callback at
|
|
* any time. Thus, user code must make sure it is equipped to handle concurrent
|
|
* execution, e.g. by employing appropriate mutex locking.
|
|
*
|
|
* When using the experimental_thread_safety option, no Tox API functions can
|
|
* be called from within the log callback.
|
|
*
|
|
* @param level The severity of the log message.
|
|
* @param file The source file from which the message originated.
|
|
* @param line The source line from which the message originated.
|
|
* @param func The function from which the message originated.
|
|
* @param message The log message.
|
|
* @param user_data The user data pointer passed to tox_new in options.
|
|
*/
|
|
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 This struct contains all the startup options for Tox.
|
|
*
|
|
* You must tox_options_new to allocate an object of this type.
|
|
*
|
|
* WARNING: Although this struct happens to be visible in the API, it is
|
|
* effectively private. Do not allocate this yourself or access members
|
|
* directly, as it *will* break binary compatibility frequently.
|
|
*
|
|
* @deprecated The memory layout of this struct (size, alignment, and field
|
|
* order) is not part of the ABI. To remain compatible, prefer to use
|
|
* tox_options_new to allocate the object and accessor functions to set the
|
|
* members. The struct will become opaque (i.e. the definition will become
|
|
* private) in v0.3.0.
|
|
*/
|
|
typedef struct Tox_Options Tox_Options;
|
|
struct Tox_Options {
|
|
|
|
/**
|
|
* The type of socket to create.
|
|
*
|
|
* If this is set to false, an IPv4 socket is created, which subsequently
|
|
* only allows IPv4 communication.
|
|
* If it is set to true, an IPv6 socket is created, allowing both IPv4 and
|
|
* IPv6 communication.
|
|
*/
|
|
bool ipv6_enabled;
|
|
|
|
/**
|
|
* 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.
|
|
*
|
|
* 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;
|
|
|
|
/**
|
|
* Enable local network peer discovery.
|
|
*
|
|
* Disabling this will cause Tox to not look for peers on the local network.
|
|
*/
|
|
bool local_discovery_enabled;
|
|
|
|
/**
|
|
* Enable storing DHT announcements and forwarding corresponding requests.
|
|
*
|
|
* Disabling this will cause Tox to ignore the relevant packets.
|
|
*/
|
|
bool dht_announcements_enabled;
|
|
|
|
/**
|
|
* Pass communications through a proxy.
|
|
*/
|
|
Tox_Proxy_Type proxy_type;
|
|
|
|
/**
|
|
* 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).
|
|
*
|
|
* 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.
|
|
*/
|
|
const char *proxy_host;
|
|
|
|
/**
|
|
* The port to use to connect to the proxy server.
|
|
*
|
|
* Ports must be in the range (1, 65535). The value is ignored if
|
|
* proxy_type is TOX_PROXY_TYPE_NONE.
|
|
*/
|
|
uint16_t proxy_port;
|
|
|
|
/**
|
|
* The start port of the inclusive port range to attempt to use.
|
|
*
|
|
* If both start_port and end_port are 0, the default port range will be
|
|
* used: `[33445, 33545]`.
|
|
*
|
|
* 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.
|
|
*/
|
|
uint16_t start_port;
|
|
|
|
/**
|
|
* The end port of the inclusive port range to attempt to use.
|
|
*/
|
|
uint16_t end_port;
|
|
|
|
/**
|
|
* The port to use for the TCP server (relay). If 0, the TCP server is
|
|
* disabled.
|
|
*
|
|
* Enabling it is not required for Tox to function properly.
|
|
*
|
|
* When enabled, your Tox instance can act as a TCP relay for other Tox
|
|
* instance. This leads to increased traffic, thus when writing a client
|
|
* it is recommended to enable TCP server only if the user has an option
|
|
* to disable it.
|
|
*/
|
|
uint16_t tcp_port;
|
|
|
|
/**
|
|
* Enables or disables UDP hole-punching. (Default: enabled).
|
|
*/
|
|
bool hole_punching_enabled;
|
|
|
|
/**
|
|
* The type of savedata to load from.
|
|
*/
|
|
Tox_Savedata_Type savedata_type;
|
|
|
|
/**
|
|
* The savedata.
|
|
*
|
|
* The data pointed at by this member is owned by the user, so must outlive
|
|
* the options object.
|
|
*/
|
|
const uint8_t *savedata_data;
|
|
|
|
/**
|
|
* The length of the savedata.
|
|
*/
|
|
size_t savedata_length;
|
|
|
|
/**
|
|
* Logging callback for the new Tox instance.
|
|
*/
|
|
tox_log_cb *log_callback;
|
|
|
|
/**
|
|
* User data pointer passed to the logging callback.
|
|
*/
|
|
void *log_user_data;
|
|
|
|
/**
|
|
* These options are experimental, so avoid writing code that depends on
|
|
* them. Options marked "experimental" may change their behaviour or go away
|
|
* entirely in the future, or may be renamed to something non-experimental
|
|
* if they become part of the supported API.
|
|
*/
|
|
/**
|
|
* Make public API functions thread-safe using a per-instance lock.
|
|
*
|
|
* Default: false.
|
|
*/
|
|
bool experimental_thread_safety;
|
|
|
|
/**
|
|
* 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`
|
|
* with the saved chat ID to recreate the group chat.
|
|
*
|
|
* Default: false.
|
|
*/
|
|
bool experimental_groups_persistence;
|
|
|
|
/**
|
|
* @brief Disable DNS hostname resolution.
|
|
*
|
|
* Hostnames or IP addresses are passed to the bootstrap/add_tcp_relay
|
|
* function and proxy host options. If disabled (this flag is true), only
|
|
* IP addresses are allowed.
|
|
*
|
|
* If this is set to true, the library will not attempt to resolve
|
|
* hostnames. This is useful for clients that want to resolve hostnames
|
|
* themselves and pass the resolved IP addresses to the library (e.g. in
|
|
* case it wants to use Tor).
|
|
* Passing hostnames will result in a TOX_ERR_BOOTSTRAP_BAD_HOST error if
|
|
* this is set to true.
|
|
*
|
|
* Default: false. May become true in the future (0.3.0).
|
|
*/
|
|
bool experimental_disable_dns;
|
|
};
|
|
|
|
bool tox_options_get_ipv6_enabled(const Tox_Options *options);
|
|
|
|
void tox_options_set_ipv6_enabled(Tox_Options *options, bool ipv6_enabled);
|
|
|
|
bool tox_options_get_udp_enabled(const Tox_Options *options);
|
|
|
|
void tox_options_set_udp_enabled(Tox_Options *options, bool udp_enabled);
|
|
|
|
bool tox_options_get_local_discovery_enabled(const Tox_Options *options);
|
|
|
|
void tox_options_set_local_discovery_enabled(Tox_Options *options, bool local_discovery_enabled);
|
|
|
|
bool tox_options_get_dht_announcements_enabled(const Tox_Options *options);
|
|
|
|
void tox_options_set_dht_announcements_enabled(Tox_Options *options, bool dht_announcements_enabled);
|
|
|
|
Tox_Proxy_Type tox_options_get_proxy_type(const Tox_Options *options);
|
|
|
|
void tox_options_set_proxy_type(Tox_Options *options, Tox_Proxy_Type proxy_type);
|
|
|
|
const char *tox_options_get_proxy_host(const Tox_Options *options);
|
|
|
|
void tox_options_set_proxy_host(Tox_Options *options, const char *proxy_host);
|
|
|
|
uint16_t tox_options_get_proxy_port(const Tox_Options *options);
|
|
|
|
void tox_options_set_proxy_port(Tox_Options *options, uint16_t proxy_port);
|
|
|
|
uint16_t tox_options_get_start_port(const Tox_Options *options);
|
|
|
|
void tox_options_set_start_port(Tox_Options *options, uint16_t start_port);
|
|
|
|
uint16_t tox_options_get_end_port(const Tox_Options *options);
|
|
|
|
void tox_options_set_end_port(Tox_Options *options, uint16_t end_port);
|
|
|
|
uint16_t tox_options_get_tcp_port(const Tox_Options *options);
|
|
|
|
void tox_options_set_tcp_port(Tox_Options *options, uint16_t tcp_port);
|
|
|
|
bool tox_options_get_hole_punching_enabled(const Tox_Options *options);
|
|
|
|
void tox_options_set_hole_punching_enabled(Tox_Options *options, bool hole_punching_enabled);
|
|
|
|
Tox_Savedata_Type tox_options_get_savedata_type(const Tox_Options *options);
|
|
|
|
void tox_options_set_savedata_type(Tox_Options *options, Tox_Savedata_Type savedata_type);
|
|
|
|
const uint8_t *tox_options_get_savedata_data(const Tox_Options *options);
|
|
|
|
void tox_options_set_savedata_data(Tox_Options *options, const uint8_t savedata_data[], size_t length);
|
|
|
|
size_t tox_options_get_savedata_length(const Tox_Options *options);
|
|
|
|
void tox_options_set_savedata_length(Tox_Options *options, size_t savedata_length);
|
|
|
|
tox_log_cb *tox_options_get_log_callback(const Tox_Options *options);
|
|
|
|
void tox_options_set_log_callback(Tox_Options *options, tox_log_cb *log_callback);
|
|
|
|
void *tox_options_get_log_user_data(const Tox_Options *options);
|
|
|
|
void tox_options_set_log_user_data(Tox_Options *options, void *log_user_data);
|
|
|
|
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);
|
|
|
|
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);
|
|
|
|
bool tox_options_get_experimental_disable_dns(const Tox_Options *options);
|
|
|
|
void tox_options_set_experimental_disable_dns(Tox_Options *options, bool experimental_disable_dns);
|
|
|
|
/**
|
|
* @brief Initialises a Tox_Options object with the default options.
|
|
*
|
|
* The result of this function is independent of the original options. All
|
|
* values will be overwritten, no values will be read (so it is permissible
|
|
* to pass an uninitialised object).
|
|
*
|
|
* If options is NULL, this function has no effect.
|
|
*
|
|
* @param options An options object to be filled with default options.
|
|
*/
|
|
void tox_options_default(Tox_Options *options);
|
|
|
|
typedef enum Tox_Err_Options_New {
|
|
|
|
/**
|
|
* The function returned successfully.
|
|
*/
|
|
TOX_ERR_OPTIONS_NEW_OK,
|
|
|
|
/**
|
|
* The function failed to allocate enough memory for the options struct.
|
|
*/
|
|
TOX_ERR_OPTIONS_NEW_MALLOC,
|
|
|
|
} Tox_Err_Options_New;
|
|
|
|
const char *tox_err_options_new_to_string(Tox_Err_Options_New value);
|
|
|
|
/**
|
|
* @brief Allocates a new Tox_Options object and initialises it with the default
|
|
* options.
|
|
*
|
|
* This function can be used to preserve long term ABI compatibility by
|
|
* giving the responsibility of allocation and deallocation to the Tox library.
|
|
*
|
|
* Objects returned from this function must be freed using the tox_options_free
|
|
* function.
|
|
*
|
|
* @return A new Tox_Options object with default options or NULL on failure.
|
|
*/
|
|
Tox_Options *tox_options_new(Tox_Err_Options_New *error);
|
|
|
|
/**
|
|
* @brief Releases all resources associated with an options objects.
|
|
*
|
|
* Passing a pointer that was not returned by tox_options_new results in
|
|
* undefined behaviour.
|
|
*/
|
|
void tox_options_free(Tox_Options *options);
|
|
|
|
/** @} */
|
|
|
|
/** @{
|
|
* @name Creation and destruction
|
|
*/
|
|
|
|
typedef enum Tox_Err_New {
|
|
|
|
/**
|
|
* The function returned successfully.
|
|
*/
|
|
TOX_ERR_NEW_OK,
|
|
|
|
/**
|
|
* One of the arguments to the function was NULL when it was not expected.
|
|
*/
|
|
TOX_ERR_NEW_NULL,
|
|
|
|
/**
|
|
* The function was unable to allocate enough memory to store the
|
|
* internal 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.
|
|
*/
|
|
TOX_ERR_NEW_PORT_ALLOC,
|
|
|
|
/**
|
|
* proxy_type was invalid.
|
|
*/
|
|
TOX_ERR_NEW_PROXY_BAD_TYPE,
|
|
|
|
/**
|
|
* proxy_type was valid but the proxy_host passed had an invalid format
|
|
* or was NULL.
|
|
*/
|
|
TOX_ERR_NEW_PROXY_BAD_HOST,
|
|
|
|
/**
|
|
* proxy_type was valid, but the proxy_port was invalid.
|
|
*/
|
|
TOX_ERR_NEW_PROXY_BAD_PORT,
|
|
|
|
/**
|
|
* The proxy address passed could not be resolved.
|
|
*/
|
|
TOX_ERR_NEW_PROXY_NOT_FOUND,
|
|
|
|
/**
|
|
* The byte array to be loaded contained an encrypted save.
|
|
*/
|
|
TOX_ERR_NEW_LOAD_ENCRYPTED,
|
|
|
|
/**
|
|
* The data format was invalid. This can happen when loading data that was
|
|
* saved by an older version of Tox, or when the data has been corrupted.
|
|
* When loading from badly formatted data, some data may have been loaded,
|
|
* and the rest is discarded. Passing an invalid length parameter also
|
|
* causes this error.
|
|
*/
|
|
TOX_ERR_NEW_LOAD_BAD_FORMAT,
|
|
|
|
} Tox_Err_New;
|
|
|
|
const char *tox_err_new_to_string(Tox_Err_New value);
|
|
|
|
/**
|
|
* @brief Creates and initialises a new Tox instance with the options passed.
|
|
*
|
|
* This function will bring the instance into a valid state. Running the event
|
|
* loop with a new instance will operate correctly.
|
|
*
|
|
* @param options An options object as described above. If this parameter is
|
|
* NULL, the default options are used.
|
|
*
|
|
* @see tox_iterate for the event loop.
|
|
*
|
|
* @return A new Tox instance pointer on success or NULL on failure.
|
|
*/
|
|
Tox *tox_new(const Tox_Options *options, Tox_Err_New *error);
|
|
|
|
/**
|
|
* @brief Releases all resources associated with the Tox instance and
|
|
* disconnects from the network.
|
|
*
|
|
* After calling this function, the Tox pointer becomes invalid. No other
|
|
* functions can be called, and the pointer value can no longer be read.
|
|
*/
|
|
void tox_kill(Tox *tox);
|
|
|
|
/**
|
|
* @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.
|
|
*
|
|
* @see threading for concurrency implications.
|
|
*/
|
|
size_t tox_get_savedata_size(const Tox *tox);
|
|
|
|
/**
|
|
* @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.
|
|
*/
|
|
void tox_get_savedata(const Tox *tox, uint8_t savedata[]);
|
|
|
|
/** @} */
|
|
|
|
/** @{
|
|
* @name Connection lifecycle and event loop
|
|
*/
|
|
|
|
typedef enum Tox_Err_Bootstrap {
|
|
|
|
/**
|
|
* The function returned successfully.
|
|
*/
|
|
TOX_ERR_BOOTSTRAP_OK,
|
|
|
|
/**
|
|
* One of the arguments to the function was NULL when it was not expected.
|
|
*/
|
|
TOX_ERR_BOOTSTRAP_NULL,
|
|
|
|
/**
|
|
* The hostname could not be resolved to an IP address, the IP address
|
|
* passed was invalid, or the function failed to send the initial request
|
|
* packet to the bootstrap node or TCP relay.
|
|
*/
|
|
TOX_ERR_BOOTSTRAP_BAD_HOST,
|
|
|
|
/**
|
|
* The port passed was invalid. The valid port range is (1, 65535).
|
|
*/
|
|
TOX_ERR_BOOTSTRAP_BAD_PORT,
|
|
|
|
} Tox_Err_Bootstrap;
|
|
|
|
const char *tox_err_bootstrap_to_string(Tox_Err_Bootstrap value);
|
|
|
|
/**
|
|
* @brief Sends a "get nodes" request to the given bootstrap node with IP, port,
|
|
* and public key to setup connections.
|
|
*
|
|
* This function will attempt to connect to the node using UDP. You must use
|
|
* this function even if Tox_Options.udp_enabled was set to false.
|
|
*
|
|
* @param host The hostname or IP address (IPv4 or IPv6) of the node. Must be
|
|
* at most TOX_MAX_HOSTNAME_LENGTH chars, including the NUL byte.
|
|
* @param port The port on the host on which the bootstrap Tox instance is
|
|
* listening.
|
|
* @param public_key The long term public key of the bootstrap node
|
|
* (TOX_PUBLIC_KEY_SIZE bytes).
|
|
* @return true on success.
|
|
*/
|
|
bool tox_bootstrap(Tox *tox, const char *host, uint16_t port, const uint8_t public_key[TOX_PUBLIC_KEY_SIZE], Tox_Err_Bootstrap *error);
|
|
|
|
/**
|
|
* @brief Adds additional host:port pair as TCP relay.
|
|
*
|
|
* This function can be used to initiate TCP connections to different ports on
|
|
* the same bootstrap node, or to add TCP relays without using them as
|
|
* bootstrap nodes.
|
|
*
|
|
* @param host The hostname or IP address (IPv4 or IPv6) of the TCP relay.
|
|
* Must be at most TOX_MAX_HOSTNAME_LENGTH chars, including the NUL byte.
|
|
* @param port The port on the host on which the TCP relay is listening.
|
|
* @param public_key The long term public key of the TCP relay
|
|
* (TOX_PUBLIC_KEY_SIZE bytes).
|
|
* @return true on success.
|
|
*/
|
|
bool tox_add_tcp_relay(Tox *tox, const char *host, uint16_t port, const uint8_t public_key[TOX_PUBLIC_KEY_SIZE], Tox_Err_Bootstrap *error);
|
|
|
|
/**
|
|
* @brief Protocols that can be used to connect to the network or friends.
|
|
*/
|
|
typedef enum Tox_Connection {
|
|
|
|
/**
|
|
* @brief There is no connection.
|
|
*
|
|
* This instance, or the friend the state change is about, is now offline.
|
|
*/
|
|
TOX_CONNECTION_NONE,
|
|
|
|
/**
|
|
* @brief A TCP connection has been established.
|
|
*
|
|
* For the own instance, this means it is connected through a TCP relay,
|
|
* only. For a friend, this means that the connection to that particular
|
|
* friend goes through a TCP relay.
|
|
*/
|
|
TOX_CONNECTION_TCP,
|
|
|
|
/**
|
|
* @brief A UDP connection has been established.
|
|
*
|
|
* For the own instance, this means it is able to send UDP packets to DHT
|
|
* nodes, but may still be connected to a TCP relay. For a friend, this
|
|
* means that the connection to that particular friend was built using
|
|
* direct UDP packets.
|
|
*/
|
|
TOX_CONNECTION_UDP,
|
|
|
|
} Tox_Connection;
|
|
|
|
const char *tox_connection_to_string(Tox_Connection value);
|
|
|
|
/**
|
|
* @brief Return whether we are connected to the DHT.
|
|
*
|
|
* The return value is equal to the last value received through the
|
|
* `self_connection_status` callback.
|
|
*
|
|
* @deprecated This getter is deprecated. Use the event and store the status
|
|
* in the client state.
|
|
*/
|
|
Tox_Connection tox_self_get_connection_status(const Tox *tox);
|
|
|
|
/**
|
|
* @param connection_status Whether we are connected to the DHT.
|
|
*/
|
|
typedef void tox_self_connection_status_cb(Tox *tox, Tox_Connection connection_status, void *user_data);
|
|
|
|
/**
|
|
* @brief Set the callback for the `self_connection_status` event.
|
|
*
|
|
* Pass NULL to unset.
|
|
*
|
|
* This event is triggered whenever there is a change in the DHT connection
|
|
* state. When disconnected, a client may choose to call tox_bootstrap again, to
|
|
* reconnect to the DHT. Note that this state may frequently change for short
|
|
* amounts of time. Clients should therefore not immediately bootstrap on
|
|
* receiving a disconnect.
|
|
*
|
|
* TODO(iphydf): how long should a client wait before bootstrapping again?
|
|
*/
|
|
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.
|
|
*/
|
|
uint32_t tox_iteration_interval(const Tox *tox);
|
|
|
|
/**
|
|
* @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);
|
|
|
|
/** @} */
|
|
|
|
/** @{
|
|
* @name Internal client information (Tox address/id)
|
|
*/
|
|
|
|
/**
|
|
* @brief Writes the Tox friend address of the client to a byte array.
|
|
*
|
|
* The address is not in human-readable format. If a client wants to display
|
|
* the address, formatting is required.
|
|
*
|
|
* @param address A memory region of at least TOX_ADDRESS_SIZE bytes. If this
|
|
* parameter is NULL, this function has no effect.
|
|
* @see TOX_ADDRESS_SIZE for the address format.
|
|
*/
|
|
void tox_self_get_address(const Tox *tox, uint8_t address[TOX_ADDRESS_SIZE]);
|
|
|
|
/**
|
|
* @brief Set the 4-byte nospam part of the address.
|
|
*
|
|
* This value is expected in host byte order. I.e. 0x12345678 will form the
|
|
* bytes `[12, 34, 56, 78]` in the nospam part of the Tox friend address.
|
|
*
|
|
* @param nospam Any 32 bit unsigned integer.
|
|
*/
|
|
void tox_self_set_nospam(Tox *tox, uint32_t nospam);
|
|
|
|
/**
|
|
* @brief Get the 4-byte nospam part of the address.
|
|
*
|
|
* This value is returned in host byte order.
|
|
*/
|
|
uint32_t tox_self_get_nospam(const Tox *tox);
|
|
|
|
/**
|
|
* @brief Copy the Tox Public Key (long term) from the Tox object.
|
|
*
|
|
* @param public_key A memory region of at least TOX_PUBLIC_KEY_SIZE bytes. If
|
|
* this parameter is NULL, this function has no effect.
|
|
*/
|
|
void tox_self_get_public_key(const Tox *tox, uint8_t public_key[TOX_PUBLIC_KEY_SIZE]);
|
|
|
|
/**
|
|
* @brief Copy the Tox Secret Key from the Tox object.
|
|
*
|
|
* @param secret_key A memory region of at least TOX_SECRET_KEY_SIZE bytes. If
|
|
* this parameter is NULL, this function has no effect.
|
|
*/
|
|
void tox_self_get_secret_key(const Tox *tox, uint8_t secret_key[TOX_SECRET_KEY_SIZE]);
|
|
|
|
/** @} */
|
|
|
|
/** @{
|
|
* @name User-visible client information (nickname/status)
|
|
*/
|
|
|
|
/**
|
|
* @brief Common error codes for all functions that set a piece of user-visible
|
|
* client information.
|
|
*/
|
|
typedef enum Tox_Err_Set_Info {
|
|
|
|
/**
|
|
* The function returned successfully.
|
|
*/
|
|
TOX_ERR_SET_INFO_OK,
|
|
|
|
/**
|
|
* One of the arguments to the function was NULL when it was not expected.
|
|
*/
|
|
TOX_ERR_SET_INFO_NULL,
|
|
|
|
/**
|
|
* Information length exceeded maximum permissible size.
|
|
*/
|
|
TOX_ERR_SET_INFO_TOO_LONG,
|
|
|
|
} Tox_Err_Set_Info;
|
|
|
|
const char *tox_err_set_info_to_string(Tox_Err_Set_Info value);
|
|
|
|
/**
|
|
* @brief Set the nickname for the Tox client.
|
|
*
|
|
* Nickname length cannot exceed TOX_MAX_NAME_LENGTH. If length is 0, the name
|
|
* parameter is ignored (it can be NULL), and the nickname is set back to empty.
|
|
*
|
|
* @param name A byte array containing the new nickname.
|
|
* @param length The size of the name byte array.
|
|
*
|
|
* @return true on success.
|
|
*/
|
|
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.
|
|
*
|
|
* If no nickname was set before calling this function, the name is empty,
|
|
* and this function returns 0.
|
|
*
|
|
* @see threading for concurrency implications.
|
|
*/
|
|
size_t tox_self_get_name_size(const Tox *tox);
|
|
|
|
/**
|
|
* @brief Write the nickname set by tox_self_set_name to a byte array.
|
|
*
|
|
* If no nickname was set before calling this function, the name is empty,
|
|
* and this function has no effect.
|
|
*
|
|
* Call tox_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.
|
|
*/
|
|
void tox_self_get_name(const Tox *tox, uint8_t name[]);
|
|
|
|
/**
|
|
* @brief Set the client's status message.
|
|
*
|
|
* Status message length cannot exceed TOX_MAX_STATUS_MESSAGE_LENGTH. If
|
|
* length is 0, the status parameter is ignored (it can be NULL), and the
|
|
* user status is set back to empty.
|
|
*/
|
|
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.
|
|
*
|
|
* If no status message was set before calling this function, the status
|
|
* is empty, and this function returns 0.
|
|
*
|
|
* @see threading for concurrency implications.
|
|
*/
|
|
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.
|
|
*
|
|
* 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.
|
|
*
|
|
* @param status_message A valid memory location large enough to hold the
|
|
* status message. If this parameter is NULL, the function has no effect.
|
|
*/
|
|
void tox_self_get_status_message(const Tox *tox, uint8_t status_message[]);
|
|
|
|
/**
|
|
* @brief Set the client's user status.
|
|
*
|
|
* @param status One of the user statuses listed in the enumeration above.
|
|
*/
|
|
void tox_self_set_status(Tox *tox, Tox_User_Status status);
|
|
|
|
/**
|
|
* @brief Returns the client's user status.
|
|
*/
|
|
Tox_User_Status tox_self_get_status(const Tox *tox);
|
|
|
|
/** @} */
|
|
|
|
/** @{
|
|
* @name Friend list management
|
|
*/
|
|
|
|
typedef uint32_t Tox_Friend_Number;
|
|
|
|
typedef enum Tox_Err_Friend_Add {
|
|
|
|
/**
|
|
* The function returned successfully.
|
|
*/
|
|
TOX_ERR_FRIEND_ADD_OK,
|
|
|
|
/**
|
|
* One of the arguments to the function was NULL when it was not expected.
|
|
*/
|
|
TOX_ERR_FRIEND_ADD_NULL,
|
|
|
|
/**
|
|
* The length of the friend request message exceeded
|
|
* TOX_MAX_FRIEND_REQUEST_LENGTH.
|
|
*/
|
|
TOX_ERR_FRIEND_ADD_TOO_LONG,
|
|
|
|
/**
|
|
* The friend request message was empty. This, and the TOO_LONG code will
|
|
* never be returned from tox_friend_add_norequest.
|
|
*/
|
|
TOX_ERR_FRIEND_ADD_NO_MESSAGE,
|
|
|
|
/**
|
|
* The friend address belongs to the sending client.
|
|
*/
|
|
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.
|
|
*/
|
|
TOX_ERR_FRIEND_ADD_ALREADY_SENT,
|
|
|
|
/**
|
|
* The friend address checksum failed.
|
|
*/
|
|
TOX_ERR_FRIEND_ADD_BAD_CHECKSUM,
|
|
|
|
/**
|
|
* The friend was already there, but the nospam value was different.
|
|
*/
|
|
TOX_ERR_FRIEND_ADD_SET_NEW_NOSPAM,
|
|
|
|
/**
|
|
* A memory allocation failed when trying to increase the friend list size.
|
|
*/
|
|
TOX_ERR_FRIEND_ADD_MALLOC,
|
|
|
|
} Tox_Err_Friend_Add;
|
|
|
|
const char *tox_err_friend_add_to_string(Tox_Err_Friend_Add value);
|
|
|
|
/**
|
|
* @brief Add a friend to the friend list and send a friend request.
|
|
*
|
|
* A friend request message must be at least 1 byte long and at most
|
|
* TOX_MAX_FRIEND_REQUEST_LENGTH.
|
|
*
|
|
* Friend numbers are unique identifiers used in all functions that operate on
|
|
* friends. Once added, a friend number is stable for the lifetime of the Tox
|
|
* object. After saving the state and reloading it, the friend numbers may not
|
|
* be the same as before. Deleting a friend creates a gap in the friend number
|
|
* set, which is filled by the next adding of a friend. Any pattern in friend
|
|
* numbers should not be relied on.
|
|
*
|
|
* If more than INT32_MAX friends are added, this function causes undefined
|
|
* behaviour.
|
|
*
|
|
* @param address The address of the friend (returned by tox_self_get_address of
|
|
* the friend you wish to add) it must be TOX_ADDRESS_SIZE bytes.
|
|
* @param message The message that will be sent along with the friend request.
|
|
* @param length The length of the data byte array.
|
|
*
|
|
* @return the friend number on success, an unspecified value on failure.
|
|
*/
|
|
Tox_Friend_Number tox_friend_add(
|
|
Tox *tox, const uint8_t address[TOX_ADDRESS_SIZE],
|
|
const uint8_t message[], size_t length,
|
|
Tox_Err_Friend_Add *error);
|
|
|
|
/**
|
|
* @brief Add a friend without sending a friend request.
|
|
*
|
|
* This function is used to add a friend in response to a friend request. If the
|
|
* client receives a friend request, it can be reasonably sure that the other
|
|
* client added this client as a friend, eliminating the need for a friend
|
|
* request.
|
|
*
|
|
* This function is also useful in a situation where both instances are
|
|
* controlled by the same entity, so that this entity can perform the mutual
|
|
* friend adding. In this case, there is no need for a friend request, either.
|
|
*
|
|
* @param public_key A byte array of length TOX_PUBLIC_KEY_SIZE containing the
|
|
* Public Key (not the Address) of the friend to add.
|
|
*
|
|
* @return the friend number on success, an unspecified value on failure.
|
|
* @see tox_friend_add for a more detailed description of friend numbers.
|
|
*/
|
|
Tox_Friend_Number tox_friend_add_norequest(
|
|
Tox *tox, const uint8_t public_key[TOX_PUBLIC_KEY_SIZE], Tox_Err_Friend_Add *error);
|
|
|
|
typedef enum Tox_Err_Friend_Delete {
|
|
|
|
/**
|
|
* The function returned successfully.
|
|
*/
|
|
TOX_ERR_FRIEND_DELETE_OK,
|
|
|
|
/**
|
|
* There was no friend with the given friend number. No friends were
|
|
* deleted.
|
|
*/
|
|
TOX_ERR_FRIEND_DELETE_FRIEND_NOT_FOUND,
|
|
|
|
} Tox_Err_Friend_Delete;
|
|
|
|
const char *tox_err_friend_delete_to_string(Tox_Err_Friend_Delete value);
|
|
|
|
/**
|
|
* @brief Remove a friend from the friend list.
|
|
*
|
|
* This does not notify the friend of their deletion. After calling this
|
|
* function, this client will appear offline to the friend and no communication
|
|
* can occur between the two.
|
|
*
|
|
* @param friend_number Friend number for the friend to be deleted.
|
|
*
|
|
* @return true on success.
|
|
*/
|
|
bool tox_friend_delete(Tox *tox, Tox_Friend_Number friend_number, Tox_Err_Friend_Delete *error);
|
|
|
|
/** @} */
|
|
|
|
/** @{
|
|
* @name Friend list queries
|
|
*/
|
|
|
|
typedef enum Tox_Err_Friend_By_Public_Key {
|
|
|
|
/**
|
|
* The function returned successfully.
|
|
*/
|
|
TOX_ERR_FRIEND_BY_PUBLIC_KEY_OK,
|
|
|
|
/**
|
|
* One of the arguments to the function was NULL when it was not expected.
|
|
*/
|
|
TOX_ERR_FRIEND_BY_PUBLIC_KEY_NULL,
|
|
|
|
/**
|
|
* No friend with the given Public Key exists on the friend list.
|
|
*/
|
|
TOX_ERR_FRIEND_BY_PUBLIC_KEY_NOT_FOUND,
|
|
|
|
} Tox_Err_Friend_By_Public_Key;
|
|
|
|
const char *tox_err_friend_by_public_key_to_string(Tox_Err_Friend_By_Public_Key value);
|
|
|
|
/**
|
|
* @brief Return the friend number associated with that Public Key.
|
|
*
|
|
* @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.
|
|
*/
|
|
bool tox_friend_exists(const Tox *tox, Tox_Friend_Number friend_number);
|
|
|
|
/**
|
|
* @brief Return the number of friends on the friend list.
|
|
*
|
|
* This function can be used to determine how much memory to allocate for
|
|
* tox_self_get_friend_list.
|
|
*/
|
|
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.
|
|
*
|
|
* @param friend_list A memory region with enough space to hold the friend
|
|
* list. If this parameter is NULL, this function has no effect.
|
|
*/
|
|
void tox_self_get_friend_list(const Tox *tox, Tox_Friend_Number friend_list[]);
|
|
|
|
typedef enum Tox_Err_Friend_Get_Public_Key {
|
|
|
|
/**
|
|
* The function returned successfully.
|
|
*/
|
|
TOX_ERR_FRIEND_GET_PUBLIC_KEY_OK,
|
|
|
|
/**
|
|
* No friend with the given number exists on the friend list.
|
|
*/
|
|
TOX_ERR_FRIEND_GET_PUBLIC_KEY_FRIEND_NOT_FOUND,
|
|
|
|
} 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.
|
|
*
|
|
* @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
|
|
* this parameter is NULL, this function has no effect.
|
|
*
|
|
* @return true on success.
|
|
*/
|
|
bool tox_friend_get_public_key(
|
|
const Tox *tox, Tox_Friend_Number friend_number, uint8_t public_key[TOX_PUBLIC_KEY_SIZE],
|
|
Tox_Err_Friend_Get_Public_Key *error);
|
|
|
|
typedef enum Tox_Err_Friend_Get_Last_Online {
|
|
|
|
/**
|
|
* The function returned successfully.
|
|
*/
|
|
TOX_ERR_FRIEND_GET_LAST_ONLINE_OK,
|
|
|
|
/**
|
|
* No friend with the given number exists on the friend list.
|
|
*/
|
|
TOX_ERR_FRIEND_GET_LAST_ONLINE_FRIEND_NOT_FOUND,
|
|
|
|
} 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.
|
|
*
|
|
* This function will return UINT64_MAX on error.
|
|
*
|
|
* @param friend_number The friend number you want to query.
|
|
*/
|
|
uint64_t tox_friend_get_last_online(
|
|
const Tox *tox, Tox_Friend_Number friend_number, Tox_Err_Friend_Get_Last_Online *error);
|
|
|
|
/** @} */
|
|
|
|
/** @{
|
|
* @name Friend-specific state queries (can also be received through callbacks)
|
|
*/
|
|
|
|
/**
|
|
* @brief Common error codes for friend state query functions.
|
|
*/
|
|
typedef enum Tox_Err_Friend_Query {
|
|
|
|
/**
|
|
* The function returned successfully.
|
|
*/
|
|
TOX_ERR_FRIEND_QUERY_OK,
|
|
|
|
/**
|
|
* 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.
|
|
*/
|
|
TOX_ERR_FRIEND_QUERY_NULL,
|
|
|
|
/**
|
|
* The friend_number did not designate a valid friend.
|
|
*/
|
|
TOX_ERR_FRIEND_QUERY_FRIEND_NOT_FOUND,
|
|
|
|
} Tox_Err_Friend_Query;
|
|
|
|
const char *tox_err_friend_query_to_string(Tox_Err_Friend_Query value);
|
|
|
|
/**
|
|
* @brief Return the length of the friend's name.
|
|
*
|
|
* If the friend number is invalid, the return value is unspecified.
|
|
*
|
|
* The return value is equal to the `length` argument received by the last
|
|
* `friend_name` callback.
|
|
*/
|
|
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.
|
|
*
|
|
* Call tox_friend_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
|
|
* `friend_name` callback.
|
|
*
|
|
* @param name A valid memory region large enough to store the friend's name.
|
|
*
|
|
* @return true on success.
|
|
*/
|
|
bool tox_friend_get_name(
|
|
const Tox *tox, Tox_Friend_Number friend_number, uint8_t name[], Tox_Err_Friend_Query *error);
|
|
|
|
/**
|
|
* @param friend_number The friend number of the friend whose name changed.
|
|
* @param name A byte array containing the same data as
|
|
* tox_friend_get_name would write to its `name` parameter.
|
|
* @param length A value equal to the return value of
|
|
* tox_friend_get_name_size.
|
|
*/
|
|
typedef void tox_friend_name_cb(
|
|
Tox *tox, Tox_Friend_Number friend_number,
|
|
const uint8_t name[], size_t length, void *user_data);
|
|
|
|
/**
|
|
* @brief Set the callback for the `friend_name` event.
|
|
*
|
|
* Pass NULL to unset.
|
|
*
|
|
* This event is triggered when a friend changes their name.
|
|
*/
|
|
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 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);
|
|
|
|
/**
|
|
* @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.
|
|
*
|
|
* 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.
|
|
*/
|
|
bool tox_friend_get_status_message(
|
|
const Tox *tox, Tox_Friend_Number friend_number, uint8_t status_message[],
|
|
Tox_Err_Friend_Query *error);
|
|
|
|
/**
|
|
* @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.
|
|
* @param length A value equal to the return value of
|
|
* tox_friend_get_status_message_size.
|
|
*/
|
|
typedef void tox_friend_status_message_cb(
|
|
Tox *tox, Tox_Friend_Number friend_number,
|
|
const uint8_t message[], size_t length, void *user_data);
|
|
|
|
/**
|
|
* @brief Set the callback for the `friend_status_message` event.
|
|
*
|
|
* Pass NULL to unset.
|
|
*
|
|
* This event is triggered when a friend changes their status message.
|
|
*/
|
|
void tox_callback_friend_status_message(Tox *tox, tox_friend_status_message_cb *callback);
|
|
|
|
/**
|
|
* @brief Return the friend's user status (away/busy/...).
|
|
*
|
|
* If the friend number is invalid, the return value is unspecified.
|
|
*
|
|
* The status returned is equal to the last status received through the
|
|
* `friend_status` callback.
|
|
*
|
|
* @deprecated This getter is deprecated. Use the event and store the status
|
|
* in the client state.
|
|
*/
|
|
Tox_User_Status tox_friend_get_status(
|
|
const Tox *tox, Tox_Friend_Number friend_number, Tox_Err_Friend_Query *error);
|
|
|
|
/**
|
|
* @param friend_number The friend number of the friend whose user status
|
|
* changed.
|
|
* @param status The new user status.
|
|
*/
|
|
typedef void tox_friend_status_cb(
|
|
Tox *tox, Tox_Friend_Number friend_number, Tox_User_Status status, void *user_data);
|
|
|
|
/**
|
|
* @brief Set the callback for the `friend_status` event.
|
|
*
|
|
* Pass NULL to unset.
|
|
*
|
|
* This event is triggered when a friend changes their user status.
|
|
*/
|
|
void tox_callback_friend_status(Tox *tox, tox_friend_status_cb *callback);
|
|
|
|
/**
|
|
* @brief Check whether a friend is currently connected to this client.
|
|
*
|
|
* The result of this function is equal to the last value received by the
|
|
* `friend_connection_status` callback.
|
|
*
|
|
* @param friend_number The friend number for which to query the connection
|
|
* status.
|
|
*
|
|
* @return the friend's connection status as it was received through the
|
|
* `friend_connection_status` event.
|
|
*
|
|
* @deprecated This getter is deprecated. Use the event and store the status
|
|
* in the client state.
|
|
*/
|
|
Tox_Connection tox_friend_get_connection_status(
|
|
const Tox *tox, Tox_Friend_Number friend_number, Tox_Err_Friend_Query *error);
|
|
|
|
/**
|
|
* @param friend_number The friend number of the friend whose connection status
|
|
* changed.
|
|
* @param connection_status The result of calling
|
|
* tox_friend_get_connection_status on the passed friend_number.
|
|
*/
|
|
typedef void tox_friend_connection_status_cb(
|
|
Tox *tox, Tox_Friend_Number friend_number, Tox_Connection connection_status, void *user_data);
|
|
|
|
/**
|
|
* @brief Set the callback for the `friend_connection_status` event.
|
|
*
|
|
* Pass NULL to unset.
|
|
*
|
|
* This event is triggered when a friend goes offline after having been online,
|
|
* or when a friend goes online.
|
|
*
|
|
* This callback is not called when adding friends. It is assumed that when
|
|
* adding friends, their connection status is initially offline.
|
|
*/
|
|
void tox_callback_friend_connection_status(Tox *tox, tox_friend_connection_status_cb *callback);
|
|
|
|
/**
|
|
* @brief Check whether a friend is currently typing a message.
|
|
*
|
|
* @param friend_number The friend number for which to query the typing status.
|
|
*
|
|
* @return true if the friend is typing.
|
|
* @return false if the friend is not typing, or the friend number was
|
|
* invalid. Inspect the error code to determine which case it is.
|
|
*
|
|
* @deprecated This getter is deprecated. Use the event and store the status
|
|
* in the client state.
|
|
*/
|
|
bool tox_friend_get_typing(
|
|
const Tox *tox, Tox_Friend_Number friend_number, Tox_Err_Friend_Query *error);
|
|
|
|
/**
|
|
* @param friend_number The friend number of the friend who started or stopped
|
|
* typing.
|
|
* @param typing The result of calling tox_friend_get_typing on the passed
|
|
* friend_number.
|
|
*/
|
|
typedef void tox_friend_typing_cb(
|
|
Tox *tox, Tox_Friend_Number friend_number, bool typing, void *user_data);
|
|
|
|
/**
|
|
* @brief Set the callback for the `friend_typing` event.
|
|
*
|
|
* Pass NULL to unset.
|
|
*
|
|
* This event is triggered when a friend starts or stops typing.
|
|
*/
|
|
void tox_callback_friend_typing(Tox *tox, tox_friend_typing_cb *callback);
|
|
|
|
/** @} */
|
|
|
|
/** @{
|
|
* @name Sending private messages
|
|
*/
|
|
|
|
typedef enum Tox_Err_Set_Typing {
|
|
|
|
/**
|
|
* The function returned successfully.
|
|
*/
|
|
TOX_ERR_SET_TYPING_OK,
|
|
|
|
/**
|
|
* The friend number did not designate a valid friend.
|
|
*/
|
|
TOX_ERR_SET_TYPING_FRIEND_NOT_FOUND,
|
|
|
|
} Tox_Err_Set_Typing;
|
|
|
|
const char *tox_err_set_typing_to_string(Tox_Err_Set_Typing value);
|
|
|
|
/**
|
|
* @brief Set the client's typing status for a friend.
|
|
*
|
|
* The client is responsible for turning it on or off.
|
|
*
|
|
* @param friend_number The friend to which the client is typing a message.
|
|
* @param typing The typing status. True means the client is typing.
|
|
*
|
|
* @return true on success.
|
|
*/
|
|
bool tox_self_set_typing(
|
|
Tox *tox, Tox_Friend_Number friend_number, bool typing, Tox_Err_Set_Typing *error);
|
|
|
|
typedef enum Tox_Err_Friend_Send_Message {
|
|
|
|
/**
|
|
* The function returned successfully.
|
|
*/
|
|
TOX_ERR_FRIEND_SEND_MESSAGE_OK,
|
|
|
|
/**
|
|
* One of the arguments to the function was NULL when it was not expected.
|
|
*/
|
|
TOX_ERR_FRIEND_SEND_MESSAGE_NULL,
|
|
|
|
/**
|
|
* The friend number did not designate a valid friend.
|
|
*/
|
|
TOX_ERR_FRIEND_SEND_MESSAGE_FRIEND_NOT_FOUND,
|
|
|
|
/**
|
|
* This client is currently not connected to the friend.
|
|
*/
|
|
TOX_ERR_FRIEND_SEND_MESSAGE_FRIEND_NOT_CONNECTED,
|
|
|
|
/**
|
|
* An allocation error occurred while increasing the send queue size.
|
|
*/
|
|
TOX_ERR_FRIEND_SEND_MESSAGE_SENDQ,
|
|
|
|
/**
|
|
* Message length exceeded TOX_MAX_MESSAGE_LENGTH.
|
|
*/
|
|
TOX_ERR_FRIEND_SEND_MESSAGE_TOO_LONG,
|
|
|
|
/**
|
|
* Attempted to send a zero-length message.
|
|
*/
|
|
TOX_ERR_FRIEND_SEND_MESSAGE_EMPTY,
|
|
|
|
} Tox_Err_Friend_Send_Message;
|
|
|
|
const char *tox_err_friend_send_message_to_string(Tox_Err_Friend_Send_Message value);
|
|
|
|
typedef uint32_t Tox_Friend_Message_Id;
|
|
|
|
/**
|
|
* @brief Send a text chat message to an online friend.
|
|
*
|
|
* This function creates a chat message packet and pushes it into the send
|
|
* queue.
|
|
*
|
|
* The message length may not exceed TOX_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 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.
|
|
*
|
|
* 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
|
|
* sent, the next message ID is 0.
|
|
*
|
|
* @param type Message type (normal, action, ...).
|
|
* @param friend_number The friend number of the friend to send the message to.
|
|
* @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.
|
|
*/
|
|
Tox_Friend_Message_Id tox_friend_send_message(
|
|
Tox *tox, Tox_Friend_Number friend_number, Tox_Message_Type type,
|
|
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 message_id The message ID as returned from tox_friend_send_message
|
|
* corresponding to the message sent.
|
|
*/
|
|
typedef void tox_friend_read_receipt_cb(
|
|
Tox *tox, Tox_Friend_Number friend_number, Tox_Friend_Message_Id message_id, void *user_data);
|
|
|
|
/**
|
|
* @brief Set the callback for the `friend_read_receipt` event.
|
|
*
|
|
* Pass NULL to unset.
|
|
*
|
|
* This event is triggered when the friend receives the message sent with
|
|
* tox_friend_send_message with the corresponding message ID.
|
|
*/
|
|
void tox_callback_friend_read_receipt(Tox *tox, tox_friend_read_receipt_cb *callback);
|
|
|
|
/** @} */
|
|
|
|
/** @{
|
|
* @name Receiving private messages and friend requests
|
|
*/
|
|
|
|
/**
|
|
* @param public_key The Public Key of the user who sent the friend request.
|
|
* @param message The message they sent along with the request.
|
|
* @param length The size of the message byte array.
|
|
*/
|
|
typedef void tox_friend_request_cb(
|
|
Tox *tox, const uint8_t public_key[TOX_PUBLIC_KEY_SIZE],
|
|
const uint8_t message[], size_t length,
|
|
void *user_data);
|
|
|
|
/**
|
|
* @brief Set the callback for the `friend_request` event.
|
|
*
|
|
* Pass NULL to unset.
|
|
*
|
|
* This event is triggered when a friend request is received.
|
|
*/
|
|
void tox_callback_friend_request(Tox *tox, tox_friend_request_cb *callback);
|
|
|
|
/**
|
|
* @param friend_number The friend number of the friend who sent the message.
|
|
* @param type The type of the message (normal, action, ...).
|
|
* @param message The message data they sent.
|
|
* @param length The size of the message byte array.
|
|
*/
|
|
typedef void tox_friend_message_cb(
|
|
Tox *tox, Tox_Friend_Number friend_number, Tox_Message_Type type,
|
|
const uint8_t message[], size_t length, void *user_data);
|
|
|
|
/**
|
|
* @brief Set the callback for the `friend_message` event.
|
|
*
|
|
* Pass NULL to unset.
|
|
*
|
|
* This event is triggered when a message from a friend is received.
|
|
*/
|
|
void tox_callback_friend_message(Tox *tox, tox_friend_message_cb *callback);
|
|
|
|
/** @} */
|
|
|
|
/** @{
|
|
* @name File transmission: common between sending and receiving
|
|
*/
|
|
|
|
typedef uint32_t Tox_File_Number;
|
|
|
|
/**
|
|
* @brief Generates a cryptographic hash of the given data.
|
|
*
|
|
* This function may be used by clients for any purpose, but is provided
|
|
* 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.
|
|
*
|
|
* 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.
|
|
* @param data Data to be hashed or NULL.
|
|
* @param length Size of the data array or 0.
|
|
*
|
|
* @return true if hash was not NULL.
|
|
*/
|
|
bool tox_hash(uint8_t hash[TOX_HASH_LENGTH], const uint8_t data[], size_t length);
|
|
|
|
/**
|
|
* @brief A list of pre-defined file kinds.
|
|
*
|
|
* 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.
|
|
*/
|
|
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.
|
|
*/
|
|
TOX_FILE_KIND_DATA,
|
|
|
|
/**
|
|
* 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.
|
|
*
|
|
* 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.
|
|
*
|
|
* When file_size is set to 0 in the transfer request it means that the
|
|
* client has no avatar.
|
|
*/
|
|
TOX_FILE_KIND_AVATAR,
|
|
|
|
};
|
|
|
|
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.
|
|
*/
|
|
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.
|
|
*/
|
|
TOX_FILE_CONTROL_PAUSE,
|
|
|
|
/**
|
|
* Sent by the receiving side to reject a file send request before any other
|
|
* commands are sent. Also sent by either side to terminate a file transfer.
|
|
*/
|
|
TOX_FILE_CONTROL_CANCEL,
|
|
|
|
} Tox_File_Control;
|
|
|
|
const char *tox_file_control_to_string(Tox_File_Control value);
|
|
|
|
typedef enum Tox_Err_File_Control {
|
|
|
|
/**
|
|
* The function returned successfully.
|
|
*/
|
|
TOX_ERR_FILE_CONTROL_OK,
|
|
|
|
/**
|
|
* The friend_number passed did not designate a valid friend.
|
|
*/
|
|
TOX_ERR_FILE_CONTROL_FRIEND_NOT_FOUND,
|
|
|
|
/**
|
|
* This client is currently not connected to the friend.
|
|
*/
|
|
TOX_ERR_FILE_CONTROL_FRIEND_NOT_CONNECTED,
|
|
|
|
/**
|
|
* No file transfer with the given file number was found for the given
|
|
* friend.
|
|
*/
|
|
TOX_ERR_FILE_CONTROL_NOT_FOUND,
|
|
|
|
/**
|
|
* A RESUME control was sent, but the file transfer is running normally.
|
|
*/
|
|
TOX_ERR_FILE_CONTROL_NOT_PAUSED,
|
|
|
|
/**
|
|
* A RESUME control was sent, but the file transfer was paused by the other
|
|
* party. Only the party that paused the transfer can resume it.
|
|
*/
|
|
TOX_ERR_FILE_CONTROL_DENIED,
|
|
|
|
/**
|
|
* A PAUSE control was sent, but the file transfer was already paused.
|
|
*/
|
|
TOX_ERR_FILE_CONTROL_ALREADY_PAUSED,
|
|
|
|
/**
|
|
* Packet queue is full.
|
|
*/
|
|
TOX_ERR_FILE_CONTROL_SENDQ,
|
|
|
|
} Tox_Err_File_Control;
|
|
|
|
const char *tox_err_file_control_to_string(Tox_Err_File_Control value);
|
|
|
|
/**
|
|
* @brief Sends a file control command to a friend for a given file transfer.
|
|
*
|
|
* @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 control The control command to send.
|
|
*
|
|
* @return true on success.
|
|
*/
|
|
bool tox_file_control(
|
|
Tox *tox, Tox_Friend_Number friend_number, Tox_File_Number file_number, Tox_File_Control control,
|
|
Tox_Err_File_Control *error);
|
|
|
|
/**
|
|
* @brief When receiving TOX_FILE_CONTROL_CANCEL, the client should release the
|
|
* resources associated with the file number and consider the transfer failed.
|
|
*
|
|
* @param friend_number The friend number of the friend who is sending the file.
|
|
* @param file_number The friend-specific file number the data received is
|
|
* associated with.
|
|
* @param control The file control command received.
|
|
*/
|
|
typedef void tox_file_recv_control_cb(
|
|
Tox *tox, Tox_Friend_Number friend_number, Tox_File_Number file_number, Tox_File_Control control,
|
|
void *user_data);
|
|
|
|
/**
|
|
* @brief Set the callback for the `file_recv_control` event.
|
|
*
|
|
* Pass NULL to unset.
|
|
*
|
|
* This event is triggered when a file control command is received from a
|
|
* friend.
|
|
*/
|
|
void tox_callback_file_recv_control(Tox *tox, tox_file_recv_control_cb *callback);
|
|
|
|
typedef enum Tox_Err_File_Seek {
|
|
|
|
/**
|
|
* The function returned successfully.
|
|
*/
|
|
TOX_ERR_FILE_SEEK_OK,
|
|
|
|
/**
|
|
* The friend_number passed did not designate a valid friend.
|
|
*/
|
|
TOX_ERR_FILE_SEEK_FRIEND_NOT_FOUND,
|
|
|
|
/**
|
|
* This client is currently not connected to the friend.
|
|
*/
|
|
TOX_ERR_FILE_SEEK_FRIEND_NOT_CONNECTED,
|
|
|
|
/**
|
|
* No file transfer with the given file number was found for the given
|
|
* friend.
|
|
*/
|
|
TOX_ERR_FILE_SEEK_NOT_FOUND,
|
|
|
|
/**
|
|
* File was not in a state where it could be seeked.
|
|
*/
|
|
TOX_ERR_FILE_SEEK_DENIED,
|
|
|
|
/**
|
|
* Seek position was invalid
|
|
*/
|
|
TOX_ERR_FILE_SEEK_INVALID_POSITION,
|
|
|
|
/**
|
|
* Packet queue is full.
|
|
*/
|
|
TOX_ERR_FILE_SEEK_SENDQ,
|
|
|
|
} 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.
|
|
*
|
|
* This function can only be called to resume a file transfer right before
|
|
* TOX_FILE_CONTROL_RESUME is sent.
|
|
*
|
|
* @param friend_number The friend number of the friend the file is being
|
|
* received from.
|
|
* @param file_number The friend-specific identifier for the file transfer.
|
|
* @param position The position that the file should be seeked to.
|
|
*/
|
|
bool tox_file_seek(
|
|
Tox *tox, Tox_Friend_Number friend_number, Tox_File_Number file_number, uint64_t position, Tox_Err_File_Seek *error);
|
|
|
|
typedef enum Tox_Err_File_Get {
|
|
|
|
/**
|
|
* The function returned successfully.
|
|
*/
|
|
TOX_ERR_FILE_GET_OK,
|
|
|
|
/**
|
|
* One of the arguments to the function was NULL when it was not expected.
|
|
*/
|
|
TOX_ERR_FILE_GET_NULL,
|
|
|
|
/**
|
|
* The friend_number passed did not designate a valid friend.
|
|
*/
|
|
TOX_ERR_FILE_GET_FRIEND_NOT_FOUND,
|
|
|
|
/**
|
|
* No file transfer with the given file number was found for the given
|
|
* friend.
|
|
*/
|
|
TOX_ERR_FILE_GET_NOT_FOUND,
|
|
|
|
} Tox_Err_File_Get;
|
|
|
|
const char *tox_err_file_get_to_string(Tox_Err_File_Get value);
|
|
|
|
/**
|
|
* @brief Copy the file id associated to the file transfer to a byte array.
|
|
*
|
|
* @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.
|
|
*
|
|
* @return true on success.
|
|
*/
|
|
bool tox_file_get_file_id(
|
|
const Tox *tox, Tox_Friend_Number friend_number, Tox_File_Number file_number,
|
|
uint8_t file_id[TOX_FILE_ID_LENGTH],
|
|
Tox_Err_File_Get *error);
|
|
|
|
/** @} */
|
|
|
|
/** @{
|
|
* @name File transmission: sending
|
|
*/
|
|
|
|
typedef enum Tox_Err_File_Send {
|
|
|
|
/**
|
|
* The function returned successfully.
|
|
*/
|
|
TOX_ERR_FILE_SEND_OK,
|
|
|
|
/**
|
|
* One of the arguments to the function was NULL when it was not expected.
|
|
*/
|
|
TOX_ERR_FILE_SEND_NULL,
|
|
|
|
/**
|
|
* The friend_number passed did not designate a valid friend.
|
|
*/
|
|
TOX_ERR_FILE_SEND_FRIEND_NOT_FOUND,
|
|
|
|
/**
|
|
* This client is currently not connected to the friend.
|
|
*/
|
|
TOX_ERR_FILE_SEND_FRIEND_NOT_CONNECTED,
|
|
|
|
/**
|
|
* Filename length exceeded TOX_MAX_FILENAME_LENGTH bytes.
|
|
*/
|
|
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).
|
|
*/
|
|
TOX_ERR_FILE_SEND_TOO_MANY,
|
|
|
|
} Tox_Err_File_Send;
|
|
|
|
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.
|
|
*
|
|
* 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
|
|
* streaming data of unknown size.
|
|
*
|
|
* 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 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
|
|
* was modified and how the client determines the file size.
|
|
*
|
|
* - 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 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
|
|
* 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
|
|
* (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)
|
|
* will differ after the transfer terminates.
|
|
* - at a position after the current read, the file transfer will succeed as
|
|
* expected.
|
|
* - In either case, both sides will regard the transfer as complete and
|
|
* successful.
|
|
*
|
|
* @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 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.
|
|
*
|
|
* @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.
|
|
*/
|
|
Tox_File_Number tox_file_send(
|
|
Tox *tox, Tox_Friend_Number friend_number, uint32_t kind, uint64_t file_size,
|
|
const uint8_t file_id[TOX_FILE_ID_LENGTH], const uint8_t filename[], size_t filename_length,
|
|
Tox_Err_File_Send *error);
|
|
|
|
typedef enum Tox_Err_File_Send_Chunk {
|
|
|
|
/**
|
|
* The function returned successfully.
|
|
*/
|
|
TOX_ERR_FILE_SEND_CHUNK_OK,
|
|
|
|
/**
|
|
* The length parameter was non-zero, but data was NULL.
|
|
*/
|
|
TOX_ERR_FILE_SEND_CHUNK_NULL,
|
|
|
|
/**
|
|
* The friend_number passed did not designate a valid friend.
|
|
*/
|
|
TOX_ERR_FILE_SEND_CHUNK_FRIEND_NOT_FOUND,
|
|
|
|
/**
|
|
* This client is currently not connected to the friend.
|
|
*/
|
|
TOX_ERR_FILE_SEND_CHUNK_FRIEND_NOT_CONNECTED,
|
|
|
|
/**
|
|
* 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).
|
|
*/
|
|
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.
|
|
*/
|
|
TOX_ERR_FILE_SEND_CHUNK_INVALID_LENGTH,
|
|
|
|
/**
|
|
* Packet queue is full.
|
|
*/
|
|
TOX_ERR_FILE_SEND_CHUNK_SENDQ,
|
|
|
|
/**
|
|
* Position parameter was wrong.
|
|
*/
|
|
TOX_ERR_FILE_SEND_CHUNK_WRONG_POSITION,
|
|
|
|
} Tox_Err_File_Send_Chunk;
|
|
|
|
const char *tox_err_file_send_chunk_to_string(Tox_Err_File_Send_Chunk value);
|
|
|
|
/**
|
|
* @brief Send a chunk of file data to a friend.
|
|
*
|
|
* 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,
|
|
* 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, Tox will know that the transfer is finished
|
|
* 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.
|
|
* @param position The file or stream position from which to continue reading.
|
|
* @return true on success.
|
|
*/
|
|
bool tox_file_send_chunk(
|
|
Tox *tox, Tox_Friend_Number friend_number, Tox_File_Number file_number, uint64_t position,
|
|
const uint8_t data[], size_t length, Tox_Err_File_Send_Chunk *error);
|
|
|
|
/**
|
|
* If the length parameter is 0, the file transfer is finished, and the client's
|
|
* resources associated with the file number should be released. After a call
|
|
* with zero length, the file number can be reused for future file transfers.
|
|
*
|
|
* If the requested position is not equal to the client's idea of the current
|
|
* file or stream position, it will need to seek. In case of read-once streams,
|
|
* the client should keep the last read chunk so that a seek back can be
|
|
* supported. A seek-back only ever needs to read from the last requested chunk.
|
|
* This happens when a chunk was requested, but the send failed. A seek-back
|
|
* request can occur an arbitrary number of times for any given chunk.
|
|
*
|
|
* In response to receiving this callback, the client should call the function
|
|
* `tox_file_send_chunk` with the requested chunk. If the number of bytes sent
|
|
* through that function is zero, the file transfer is assumed complete. A
|
|
* client must send the full length of data requested with this callback.
|
|
*
|
|
* @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.
|
|
* @param position The file or stream position from which to continue reading.
|
|
* @param length The number of bytes requested for the current chunk.
|
|
*/
|
|
typedef void tox_file_chunk_request_cb(
|
|
Tox *tox, Tox_Friend_Number friend_number, Tox_File_Number file_number, uint64_t position,
|
|
size_t length, void *user_data);
|
|
|
|
/**
|
|
* @brief Set the callback for the `file_chunk_request` event.
|
|
*
|
|
* Pass NULL to unset.
|
|
*
|
|
* 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);
|
|
|
|
/** @} */
|
|
|
|
/** @{
|
|
* @name File transmission: receiving
|
|
*/
|
|
|
|
/**
|
|
* The client should acquire resources to be associated with the file transfer.
|
|
* Incoming file transfers start in the PAUSED state. After this callback
|
|
* returns, a transfer can be rejected by sending a TOX_FILE_CONTROL_CANCEL
|
|
* control command before any other control commands. It can be accepted by
|
|
* sending TOX_FILE_CONTROL_RESUME.
|
|
*
|
|
* @param friend_number The friend number of the friend who is sending the file
|
|
* transfer request.
|
|
* @param file_number The friend-specific file number the data received is
|
|
* associated with.
|
|
* @param kind The meaning of the file that was sent.
|
|
* @param file_size Size in bytes of the file the client wants to send,
|
|
* UINT64_MAX if unknown or streaming.
|
|
* @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.
|
|
*/
|
|
typedef void tox_file_recv_cb(
|
|
Tox *tox, Tox_Friend_Number friend_number, Tox_File_Number file_number, uint32_t kind, uint64_t file_size,
|
|
const uint8_t filename[], size_t filename_length, void *user_data);
|
|
|
|
/**
|
|
* @brief Set the callback for the `file_recv` event.
|
|
*
|
|
* Pass NULL to unset.
|
|
*
|
|
* This event is triggered when a file transfer request is received.
|
|
*/
|
|
void tox_callback_file_recv(Tox *tox, tox_file_recv_cb *callback);
|
|
|
|
/**
|
|
* When length is 0, the transfer is finished and the client should release the
|
|
* resources it acquired for the transfer. After a call with length = 0, the
|
|
* file number can be reused for new file transfers.
|
|
*
|
|
* If position is equal to file_size (received in the file_receive callback)
|
|
* when the transfer finishes, the file was received completely. Otherwise, if
|
|
* file_size was UINT64_MAX, streaming ended successfully when length is 0.
|
|
*
|
|
* @param friend_number The friend number of the friend who is sending the file.
|
|
* @param file_number The friend-specific file number the data received is
|
|
* associated with.
|
|
* @param position The file position of the first byte in data.
|
|
* @param data A byte array containing the received chunk.
|
|
* @param length The length of the received chunk.
|
|
*/
|
|
typedef void tox_file_recv_chunk_cb(
|
|
Tox *tox, Tox_Friend_Number friend_number, Tox_File_Number file_number, uint64_t position,
|
|
const uint8_t data[], size_t length, void *user_data);
|
|
|
|
/**
|
|
* @brief Set the callback for the `file_recv_chunk` event.
|
|
*
|
|
* Pass NULL to unset.
|
|
*
|
|
* This event is first triggered when a file transfer request is received, and
|
|
* subsequently when a chunk of file data for an accepted request was received.
|
|
*/
|
|
void tox_callback_file_recv_chunk(Tox *tox, tox_file_recv_chunk_cb *callback);
|
|
|
|
/** @} */
|
|
|
|
/** @{
|
|
* @name Conference management
|
|
*/
|
|
|
|
typedef uint32_t Tox_Conference_Number;
|
|
typedef uint32_t Tox_Conference_Peer_Number;
|
|
typedef uint32_t Tox_Conference_Offline_Peer_Number;
|
|
|
|
/**
|
|
* @brief Conference types for the conference_invite event.
|
|
*/
|
|
typedef enum Tox_Conference_Type {
|
|
|
|
/**
|
|
* Text-only conferences that must be accepted with the tox_conference_join
|
|
* function.
|
|
*/
|
|
TOX_CONFERENCE_TYPE_TEXT,
|
|
|
|
/**
|
|
* Video conference. The function to accept these is in toxav.
|
|
*/
|
|
TOX_CONFERENCE_TYPE_AV,
|
|
|
|
} Tox_Conference_Type;
|
|
|
|
const char *tox_conference_type_to_string(Tox_Conference_Type value);
|
|
|
|
/**
|
|
* The invitation will remain valid until the inviting friend goes offline
|
|
* or exits the conference.
|
|
*
|
|
* @param friend_number The friend who invited us.
|
|
* @param type The conference type (text only or audio/video).
|
|
* @param cookie A piece of data of variable length required to join the
|
|
* conference.
|
|
* @param length The length of the cookie.
|
|
*/
|
|
typedef void tox_conference_invite_cb(
|
|
Tox *tox, Tox_Friend_Number friend_number, Tox_Conference_Type type,
|
|
const uint8_t cookie[], size_t length, void *user_data);
|
|
|
|
/**
|
|
* @brief Set the callback for the `conference_invite` event.
|
|
*
|
|
* Pass NULL to unset.
|
|
*
|
|
* This event is triggered when the client is invited to join a conference.
|
|
*/
|
|
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, Tox_Conference_Number conference_number, void *user_data);
|
|
|
|
/**
|
|
* @brief 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, ...).
|
|
* @param message The message data.
|
|
* @param length The length of the message.
|
|
*/
|
|
typedef void tox_conference_message_cb(
|
|
Tox *tox, Tox_Conference_Number conference_number, Tox_Conference_Peer_Number peer_number,
|
|
Tox_Message_Type type, const uint8_t message[], size_t length, void *user_data);
|
|
|
|
/**
|
|
* @brief Set the callback for the `conference_message` event.
|
|
*
|
|
* Pass NULL to unset.
|
|
*
|
|
* This event is triggered when the client receives a conference message.
|
|
*/
|
|
void tox_callback_conference_message(Tox *tox, tox_conference_message_cb *callback);
|
|
|
|
/**
|
|
* @param conference_number The conference number of the conference the title
|
|
* change is intended for.
|
|
* @param peer_number The ID of the peer who changed the title.
|
|
* @param title The title data.
|
|
* @param length The title length.
|
|
*/
|
|
typedef void tox_conference_title_cb(
|
|
Tox *tox, Tox_Conference_Number conference_number, Tox_Conference_Peer_Number peer_number,
|
|
const uint8_t title[], size_t length, void *user_data);
|
|
|
|
/**
|
|
* @brief Set the callback for the `conference_title` event.
|
|
*
|
|
* Pass NULL to unset.
|
|
*
|
|
* 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).
|
|
*/
|
|
void tox_callback_conference_title(Tox *tox, tox_conference_title_cb *callback);
|
|
|
|
/**
|
|
* @param conference_number The conference number of the conference the
|
|
* peer is in.
|
|
* @param peer_number The ID of the peer who changed their nickname.
|
|
* @param name A byte array containing the new nickname.
|
|
* @param length The size of the name byte array.
|
|
*/
|
|
typedef void tox_conference_peer_name_cb(
|
|
Tox *tox, Tox_Conference_Number conference_number, Tox_Conference_Peer_Number peer_number,
|
|
const uint8_t name[], size_t length, void *user_data);
|
|
|
|
/**
|
|
* @brief Set the callback for the `conference_peer_name` event.
|
|
*
|
|
* Pass NULL to unset.
|
|
*
|
|
* This event is triggered when a peer changes their name.
|
|
*/
|
|
void tox_callback_conference_peer_name(Tox *tox, tox_conference_peer_name_cb *callback);
|
|
|
|
/**
|
|
* @param conference_number The conference number of the conference the
|
|
* peer is in.
|
|
*/
|
|
typedef void tox_conference_peer_list_changed_cb(Tox *tox, Tox_Conference_Number conference_number, void *user_data);
|
|
|
|
/**
|
|
* @brief Set the callback for the `conference_peer_list_changed` event.
|
|
*
|
|
* Pass NULL to unset.
|
|
*
|
|
* This event is triggered when a peer joins or leaves the conference.
|
|
*/
|
|
void tox_callback_conference_peer_list_changed(Tox *tox, tox_conference_peer_list_changed_cb *callback);
|
|
|
|
typedef enum Tox_Err_Conference_New {
|
|
|
|
/**
|
|
* The function returned successfully.
|
|
*/
|
|
TOX_ERR_CONFERENCE_NEW_OK,
|
|
|
|
/**
|
|
* The conference instance failed to initialize.
|
|
*/
|
|
TOX_ERR_CONFERENCE_NEW_INIT,
|
|
|
|
} Tox_Err_Conference_New;
|
|
|
|
const char *tox_err_conference_new_to_string(Tox_Err_Conference_New value);
|
|
|
|
/**
|
|
* @brief Creates a new conference.
|
|
*
|
|
* This function creates and connects to a new text conference.
|
|
*
|
|
* @return
|
|
* - conference number on success
|
|
* - an unspecified value on failure
|
|
*/
|
|
Tox_Conference_Number tox_conference_new(Tox *tox, Tox_Err_Conference_New *error);
|
|
|
|
typedef enum Tox_Err_Conference_Delete {
|
|
|
|
/**
|
|
* The function returned successfully.
|
|
*/
|
|
TOX_ERR_CONFERENCE_DELETE_OK,
|
|
|
|
/**
|
|
* The conference number passed did not designate a valid conference.
|
|
*/
|
|
TOX_ERR_CONFERENCE_DELETE_CONFERENCE_NOT_FOUND,
|
|
|
|
} Tox_Err_Conference_Delete;
|
|
|
|
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.
|
|
*
|
|
* @return true on success.
|
|
*/
|
|
bool tox_conference_delete(Tox *tox, Tox_Conference_Number conference_number, Tox_Err_Conference_Delete *error);
|
|
|
|
/**
|
|
* @brief Error codes for peer info queries.
|
|
*/
|
|
typedef enum Tox_Err_Conference_Peer_Query {
|
|
|
|
/**
|
|
* The function returned successfully.
|
|
*/
|
|
TOX_ERR_CONFERENCE_PEER_QUERY_OK,
|
|
|
|
/**
|
|
* The conference number passed did not designate a valid conference.
|
|
*/
|
|
TOX_ERR_CONFERENCE_PEER_QUERY_CONFERENCE_NOT_FOUND,
|
|
|
|
/**
|
|
* The peer number passed did not designate a valid peer.
|
|
*/
|
|
TOX_ERR_CONFERENCE_PEER_QUERY_PEER_NOT_FOUND,
|
|
|
|
/**
|
|
* The client is not connected to the conference.
|
|
*/
|
|
TOX_ERR_CONFERENCE_PEER_QUERY_NO_CONNECTION,
|
|
|
|
} Tox_Err_Conference_Peer_Query;
|
|
|
|
const char *tox_err_conference_peer_query_to_string(Tox_Err_Conference_Peer_Query value);
|
|
|
|
/**
|
|
* @brief 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, Tox_Conference_Number conference_number, Tox_Err_Conference_Peer_Query *error);
|
|
|
|
/**
|
|
* @brief Return the length of the peer's name.
|
|
*
|
|
* Return value is unspecified on failure.
|
|
*/
|
|
size_t tox_conference_peer_get_name_size(
|
|
const Tox *tox, Tox_Conference_Number conference_number, Tox_Conference_Peer_Number peer_number,
|
|
Tox_Err_Conference_Peer_Query *error);
|
|
|
|
/**
|
|
* @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.
|
|
*
|
|
* @param name A valid memory region large enough to store the peer's name.
|
|
*
|
|
* @return true on success.
|
|
*/
|
|
bool tox_conference_peer_get_name(
|
|
const Tox *tox, Tox_Conference_Number conference_number, Tox_Conference_Peer_Number peer_number,
|
|
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.
|
|
*
|
|
* public_key must be TOX_PUBLIC_KEY_SIZE long.
|
|
*
|
|
* @return true on success.
|
|
*/
|
|
bool tox_conference_peer_get_public_key(
|
|
const Tox *tox, Tox_Conference_Number conference_number, Tox_Conference_Peer_Number peer_number,
|
|
uint8_t public_key[TOX_PUBLIC_KEY_SIZE], Tox_Err_Conference_Peer_Query *error);
|
|
|
|
/**
|
|
* @brief Return true if passed peer_number corresponds to our own.
|
|
*/
|
|
bool tox_conference_peer_number_is_ours(
|
|
const Tox *tox, Tox_Conference_Number conference_number, Tox_Conference_Peer_Number peer_number,
|
|
Tox_Err_Conference_Peer_Query *error);
|
|
|
|
/**
|
|
* @brief 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, Tox_Conference_Number conference_number,
|
|
Tox_Err_Conference_Peer_Query *error);
|
|
|
|
/**
|
|
* @brief Return the length of the offline peer's name.
|
|
*
|
|
* Return value is unspecified on failure.
|
|
*/
|
|
size_t tox_conference_offline_peer_get_name_size(
|
|
const Tox *tox, Tox_Conference_Number conference_number,
|
|
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.
|
|
*
|
|
* Call tox_conference_offline_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.
|
|
*
|
|
* @return true on success.
|
|
*/
|
|
bool tox_conference_offline_peer_get_name(
|
|
const Tox *tox, Tox_Conference_Number conference_number, Tox_Conference_Offline_Peer_Number offline_peer_number,
|
|
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.
|
|
*
|
|
* public_key must be TOX_PUBLIC_KEY_SIZE long.
|
|
*
|
|
* @return true on success.
|
|
*/
|
|
bool tox_conference_offline_peer_get_public_key(
|
|
const Tox *tox, Tox_Conference_Number conference_number,
|
|
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.
|
|
*/
|
|
uint64_t tox_conference_offline_peer_get_last_active(
|
|
const Tox *tox, Tox_Conference_Number conference_number,
|
|
Tox_Conference_Offline_Peer_Number offline_peer_number, Tox_Err_Conference_Peer_Query *error);
|
|
|
|
typedef enum Tox_Err_Conference_Set_Max_Offline {
|
|
|
|
/**
|
|
* The function returned successfully.
|
|
*/
|
|
TOX_ERR_CONFERENCE_SET_MAX_OFFLINE_OK,
|
|
|
|
/**
|
|
* The conference number passed did not designate a valid conference.
|
|
*/
|
|
TOX_ERR_CONFERENCE_SET_MAX_OFFLINE_CONFERENCE_NOT_FOUND,
|
|
|
|
} Tox_Err_Conference_Set_Max_Offline;
|
|
|
|
const char *tox_err_conference_set_max_offline_to_string(Tox_Err_Conference_Set_Max_Offline value);
|
|
|
|
/**
|
|
* @brief Set maximum number of offline peers to store, overriding the default.
|
|
*/
|
|
bool tox_conference_set_max_offline(
|
|
Tox *tox, Tox_Conference_Number conference_number, uint32_t max_offline,
|
|
Tox_Err_Conference_Set_Max_Offline *error);
|
|
|
|
typedef enum Tox_Err_Conference_Invite {
|
|
|
|
/**
|
|
* The function returned successfully.
|
|
*/
|
|
TOX_ERR_CONFERENCE_INVITE_OK,
|
|
|
|
/**
|
|
* The conference number passed did not designate a valid conference.
|
|
*/
|
|
TOX_ERR_CONFERENCE_INVITE_CONFERENCE_NOT_FOUND,
|
|
|
|
/**
|
|
* The invite packet failed to send.
|
|
*/
|
|
TOX_ERR_CONFERENCE_INVITE_FAIL_SEND,
|
|
|
|
/**
|
|
* The client is not connected to the conference.
|
|
*/
|
|
TOX_ERR_CONFERENCE_INVITE_NO_CONNECTION,
|
|
|
|
} Tox_Err_Conference_Invite;
|
|
|
|
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.
|
|
*
|
|
* @return true on success.
|
|
*/
|
|
bool tox_conference_invite(
|
|
Tox *tox, Tox_Friend_Number friend_number, Tox_Conference_Number conference_number,
|
|
Tox_Err_Conference_Invite *error);
|
|
|
|
typedef enum Tox_Err_Conference_Join {
|
|
|
|
/**
|
|
* The function returned successfully.
|
|
*/
|
|
TOX_ERR_CONFERENCE_JOIN_OK,
|
|
|
|
/**
|
|
* The cookie passed has an invalid length.
|
|
*/
|
|
TOX_ERR_CONFERENCE_JOIN_INVALID_LENGTH,
|
|
|
|
/**
|
|
* The conference is not the expected type. This indicates an invalid
|
|
* cookie.
|
|
*/
|
|
TOX_ERR_CONFERENCE_JOIN_WRONG_TYPE,
|
|
|
|
/**
|
|
* The friend number passed does not designate a valid friend.
|
|
*/
|
|
TOX_ERR_CONFERENCE_JOIN_FRIEND_NOT_FOUND,
|
|
|
|
/**
|
|
* Client is already in this conference.
|
|
*/
|
|
TOX_ERR_CONFERENCE_JOIN_DUPLICATE,
|
|
|
|
/**
|
|
* Conference instance failed to initialize.
|
|
*/
|
|
TOX_ERR_CONFERENCE_JOIN_INIT_FAIL,
|
|
|
|
/**
|
|
* The join packet failed to send.
|
|
*/
|
|
TOX_ERR_CONFERENCE_JOIN_FAIL_SEND,
|
|
|
|
/**
|
|
* The cookie passed was NULL.
|
|
*/
|
|
TOX_ERR_CONFERENCE_JOIN_NULL,
|
|
|
|
} Tox_Err_Conference_Join;
|
|
|
|
const char *tox_err_conference_join_to_string(Tox_Err_Conference_Join value);
|
|
|
|
/**
|
|
* @brief 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 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.
|
|
*
|
|
* @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.
|
|
*
|
|
* @return conference number on success, an unspecified value on failure.
|
|
*/
|
|
Tox_Conference_Number tox_conference_join(
|
|
Tox *tox, Tox_Friend_Number friend_number,
|
|
const uint8_t cookie[], size_t length,
|
|
Tox_Err_Conference_Join *error);
|
|
|
|
typedef enum Tox_Err_Conference_Send_Message {
|
|
|
|
/**
|
|
* The function returned successfully.
|
|
*/
|
|
TOX_ERR_CONFERENCE_SEND_MESSAGE_OK,
|
|
|
|
/**
|
|
* The conference number passed did not designate a valid conference.
|
|
*/
|
|
TOX_ERR_CONFERENCE_SEND_MESSAGE_CONFERENCE_NOT_FOUND,
|
|
|
|
/**
|
|
* The message is too long.
|
|
*/
|
|
TOX_ERR_CONFERENCE_SEND_MESSAGE_TOO_LONG,
|
|
|
|
/**
|
|
* The client is not connected to the conference.
|
|
*/
|
|
TOX_ERR_CONFERENCE_SEND_MESSAGE_NO_CONNECTION,
|
|
|
|
/**
|
|
* The message packet failed to send.
|
|
*/
|
|
TOX_ERR_CONFERENCE_SEND_MESSAGE_FAIL_SEND,
|
|
|
|
} Tox_Err_Conference_Send_Message;
|
|
|
|
const char *tox_err_conference_send_message_to_string(Tox_Err_Conference_Send_Message value);
|
|
|
|
/**
|
|
* @brief Send a text chat message to the conference.
|
|
*
|
|
* This function creates a conference message packet and pushes it into the send
|
|
* queue.
|
|
*
|
|
* The message length may not exceed TOX_MAX_MESSAGE_LENGTH. Larger messages
|
|
* must be split by the client and sent as separate messages. Other clients can
|
|
* then reassemble the fragments.
|
|
*
|
|
* @param conference_number The conference number of the conference the message
|
|
* is intended for.
|
|
* @param 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.
|
|
*
|
|
* @return true on success.
|
|
*/
|
|
bool tox_conference_send_message(
|
|
Tox *tox, Tox_Conference_Number conference_number, Tox_Message_Type type,
|
|
const uint8_t message[], size_t length,
|
|
Tox_Err_Conference_Send_Message *error);
|
|
|
|
typedef enum Tox_Err_Conference_Title {
|
|
|
|
/**
|
|
* The function returned successfully.
|
|
*/
|
|
TOX_ERR_CONFERENCE_TITLE_OK,
|
|
|
|
/**
|
|
* The conference number passed did not designate a valid conference.
|
|
*/
|
|
TOX_ERR_CONFERENCE_TITLE_CONFERENCE_NOT_FOUND,
|
|
|
|
/**
|
|
* The title is too long or empty.
|
|
*/
|
|
TOX_ERR_CONFERENCE_TITLE_INVALID_LENGTH,
|
|
|
|
/**
|
|
* The title packet failed to send.
|
|
*/
|
|
TOX_ERR_CONFERENCE_TITLE_FAIL_SEND,
|
|
|
|
} Tox_Err_Conference_Title;
|
|
|
|
const char *tox_err_conference_title_to_string(Tox_Err_Conference_Title value);
|
|
|
|
/**
|
|
* @brief Return the length of the conference title.
|
|
*
|
|
* Return value is unspecified on failure.
|
|
*
|
|
* The return value is equal to the `length` argument received by the last
|
|
* `conference_title` callback.
|
|
*/
|
|
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.
|
|
*
|
|
* 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.
|
|
*
|
|
* @param title A valid memory region large enough to store the title.
|
|
* If this parameter is NULL, this function has no effect.
|
|
*
|
|
* @return true on success.
|
|
*/
|
|
bool tox_conference_get_title(
|
|
const Tox *tox, Tox_Conference_Number conference_number,
|
|
uint8_t title[],
|
|
Tox_Err_Conference_Title *error);
|
|
|
|
/**
|
|
* @brief Set the conference title and broadcast it to the rest of the
|
|
* conference.
|
|
*
|
|
* Title length cannot be longer than TOX_MAX_NAME_LENGTH.
|
|
*
|
|
* @return true on success.
|
|
*/
|
|
bool tox_conference_set_title(
|
|
Tox *tox, Tox_Conference_Number conference_number,
|
|
const uint8_t title[], size_t length,
|
|
Tox_Err_Conference_Title *error);
|
|
|
|
/**
|
|
* @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`.
|
|
*/
|
|
size_t tox_conference_get_chatlist_size(const Tox *tox);
|
|
|
|
/**
|
|
* @brief Copy a list of valid conference numbers into the array chatlist.
|
|
*
|
|
* 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 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`.
|
|
*
|
|
* 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, Tox_Conference_Number chatlist[]);
|
|
|
|
/**
|
|
* @brief Returns the type of conference (Tox_Conference_Type) that
|
|
* conference_number is.
|
|
*
|
|
* Return value is unspecified on failure.
|
|
*/
|
|
typedef enum Tox_Err_Conference_Get_Type {
|
|
|
|
/**
|
|
* The function returned successfully.
|
|
*/
|
|
TOX_ERR_CONFERENCE_GET_TYPE_OK,
|
|
|
|
/**
|
|
* The conference number passed did not designate a valid conference.
|
|
*/
|
|
TOX_ERR_CONFERENCE_GET_TYPE_CONFERENCE_NOT_FOUND,
|
|
|
|
} Tox_Err_Conference_Get_Type;
|
|
|
|
const char *tox_err_conference_get_type_to_string(Tox_Err_Conference_Get_Type value);
|
|
|
|
/**
|
|
* @brief Get the type (text or A/V) for the conference.
|
|
*/
|
|
Tox_Conference_Type tox_conference_get_type(
|
|
const Tox *tox, Tox_Conference_Number conference_number,
|
|
Tox_Err_Conference_Get_Type *error);
|
|
|
|
/**
|
|
* @brief Get the conference unique ID.
|
|
*
|
|
* If id is NULL, this function has no effect.
|
|
*
|
|
* @param id A memory region large enough to store TOX_CONFERENCE_ID_SIZE bytes.
|
|
*
|
|
* @return true on success.
|
|
*/
|
|
bool tox_conference_get_id(
|
|
const Tox *tox, Tox_Conference_Number conference_number, uint8_t id[TOX_CONFERENCE_ID_SIZE]);
|
|
|
|
typedef enum Tox_Err_Conference_By_Id {
|
|
|
|
/**
|
|
* The function returned successfully.
|
|
*/
|
|
TOX_ERR_CONFERENCE_BY_ID_OK,
|
|
|
|
/**
|
|
* One of the arguments to the function was NULL when it was not expected.
|
|
*/
|
|
TOX_ERR_CONFERENCE_BY_ID_NULL,
|
|
|
|
/**
|
|
* No conference with the given id exists on the conference list.
|
|
*/
|
|
TOX_ERR_CONFERENCE_BY_ID_NOT_FOUND,
|
|
|
|
} Tox_Err_Conference_By_Id;
|
|
|
|
const char *tox_err_conference_by_id_to_string(Tox_Err_Conference_By_Id value);
|
|
|
|
/**
|
|
* @brief Return the conference number associated with the specified id.
|
|
*
|
|
* @param id A byte array containing the conference id (TOX_CONFERENCE_ID_SIZE).
|
|
*
|
|
* @return the conference number on success, an unspecified value on failure.
|
|
*/
|
|
Tox_Conference_Number tox_conference_by_id(
|
|
const Tox *tox, const uint8_t id[TOX_CONFERENCE_ID_SIZE], Tox_Err_Conference_By_Id *error);
|
|
|
|
/**
|
|
* @brief Get the conference unique ID.
|
|
*
|
|
* If uid is NULL, this function has no effect.
|
|
*
|
|
* @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).
|
|
*/
|
|
bool tox_conference_get_uid(
|
|
const Tox *tox, Tox_Conference_Number conference_number, uint8_t uid[TOX_CONFERENCE_UID_SIZE]);
|
|
|
|
typedef enum Tox_Err_Conference_By_Uid {
|
|
|
|
/**
|
|
* The function returned successfully.
|
|
*/
|
|
TOX_ERR_CONFERENCE_BY_UID_OK,
|
|
|
|
/**
|
|
* One of the arguments to the function was NULL when it was not expected.
|
|
*/
|
|
TOX_ERR_CONFERENCE_BY_UID_NULL,
|
|
|
|
/**
|
|
* No conference with the given uid exists on the conference list.
|
|
*/
|
|
TOX_ERR_CONFERENCE_BY_UID_NOT_FOUND,
|
|
|
|
} Tox_Err_Conference_By_Uid;
|
|
|
|
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).
|
|
*
|
|
* @return the conference number on success, an unspecified value on failure.
|
|
* @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);
|
|
|
|
/** @} */
|
|
|
|
/** @{
|
|
* @name Low-level custom packet sending and receiving
|
|
*/
|
|
|
|
typedef enum Tox_Err_Friend_Custom_Packet {
|
|
|
|
/**
|
|
* The function returned successfully.
|
|
*/
|
|
TOX_ERR_FRIEND_CUSTOM_PACKET_OK,
|
|
|
|
/**
|
|
* One of the arguments to the function was NULL when it was not expected.
|
|
*/
|
|
TOX_ERR_FRIEND_CUSTOM_PACKET_NULL,
|
|
|
|
/**
|
|
* The friend number did not designate a valid friend.
|
|
*/
|
|
TOX_ERR_FRIEND_CUSTOM_PACKET_FRIEND_NOT_FOUND,
|
|
|
|
/**
|
|
* This client is currently not connected to the friend.
|
|
*/
|
|
TOX_ERR_FRIEND_CUSTOM_PACKET_FRIEND_NOT_CONNECTED,
|
|
|
|
/**
|
|
* The first byte of data was not one of the permitted values;
|
|
* for lossy packets the first byte must be in the range 192-254,
|
|
* and for lossless packets it must be either 69 or in the range 160-191.
|
|
*/
|
|
TOX_ERR_FRIEND_CUSTOM_PACKET_INVALID,
|
|
|
|
/**
|
|
* Attempted to send an empty packet.
|
|
*/
|
|
TOX_ERR_FRIEND_CUSTOM_PACKET_EMPTY,
|
|
|
|
/**
|
|
* Packet data length exceeded TOX_MAX_CUSTOM_PACKET_SIZE.
|
|
*/
|
|
TOX_ERR_FRIEND_CUSTOM_PACKET_TOO_LONG,
|
|
|
|
/**
|
|
* Packet queue is full.
|
|
*/
|
|
TOX_ERR_FRIEND_CUSTOM_PACKET_SENDQ,
|
|
|
|
} Tox_Err_Friend_Custom_Packet;
|
|
|
|
const char *tox_err_friend_custom_packet_to_string(Tox_Err_Friend_Custom_Packet value);
|
|
|
|
/**
|
|
* @brief Send a custom lossy packet to a friend.
|
|
*
|
|
* The first byte of data must be in the range 192-254. Maximum length of a
|
|
* custom packet is TOX_MAX_CUSTOM_PACKET_SIZE.
|
|
*
|
|
* 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, it is recommended that you use lossless custom
|
|
* packets instead.
|
|
*
|
|
* @param friend_number The friend number of the friend this lossy packet
|
|
* should be sent to.
|
|
* @param data A byte array containing the packet data.
|
|
* @param length The length of the packet data byte array.
|
|
*
|
|
* @return true on success.
|
|
*/
|
|
bool tox_friend_send_lossy_packet(
|
|
Tox *tox, Tox_Friend_Number friend_number,
|
|
const uint8_t data[], size_t length,
|
|
Tox_Err_Friend_Custom_Packet *error);
|
|
|
|
/**
|
|
* @brief Send a custom lossless packet to a friend.
|
|
*
|
|
* The first byte of data must be either 69 or in the range 160-191. Maximum length of a
|
|
* custom packet is TOX_MAX_CUSTOM_PACKET_SIZE.
|
|
*
|
|
* Lossless packet behaviour is comparable to TCP (reliability, arrive in order)
|
|
* but with packets instead of a stream.
|
|
*
|
|
* @param friend_number The friend number of the friend this lossless packet
|
|
* should be sent to.
|
|
* @param data A byte array containing the packet data.
|
|
* @param length The length of the packet data byte array.
|
|
*
|
|
* @return true on success.
|
|
*/
|
|
bool tox_friend_send_lossless_packet(
|
|
Tox *tox, Tox_Friend_Number friend_number,
|
|
const uint8_t data[], size_t length,
|
|
Tox_Err_Friend_Custom_Packet *error);
|
|
|
|
/**
|
|
* tox_callback_friend_lossy_packet is the compatibility function to
|
|
* set the callback for all packet IDs except those reserved for ToxAV.
|
|
*
|
|
* @param friend_number The friend number of the friend who sent a lossy packet.
|
|
* @param data A byte array containing the received packet data.
|
|
* @param length The length of the packet data byte array.
|
|
*/
|
|
typedef void tox_friend_lossy_packet_cb(
|
|
Tox *tox, Tox_Friend_Number friend_number,
|
|
const uint8_t data[], size_t length,
|
|
void *user_data);
|
|
|
|
/**
|
|
* @brief Set the callback for the `friend_lossy_packet` event.
|
|
*
|
|
* Pass NULL to unset.
|
|
*/
|
|
void tox_callback_friend_lossy_packet(Tox *tox, tox_friend_lossy_packet_cb *callback);
|
|
|
|
/**
|
|
* @param friend_number The friend number of the friend who sent the packet.
|
|
* @param data A byte array containing the received packet data.
|
|
* @param length The length of the packet data byte array.
|
|
*/
|
|
typedef void tox_friend_lossless_packet_cb(
|
|
Tox *tox, Tox_Friend_Number friend_number,
|
|
const uint8_t data[], size_t length,
|
|
void *user_data);
|
|
|
|
/**
|
|
* @brief Set the callback for the `friend_lossless_packet` event.
|
|
*
|
|
* Pass NULL to unset.
|
|
*/
|
|
void tox_callback_friend_lossless_packet(Tox *tox, tox_friend_lossless_packet_cb *callback);
|
|
|
|
/** @} */
|
|
|
|
/** @{
|
|
* @name Low-level network information
|
|
*/
|
|
|
|
typedef enum Tox_Err_Get_Port {
|
|
|
|
/**
|
|
* The function returned successfully.
|
|
*/
|
|
TOX_ERR_GET_PORT_OK,
|
|
|
|
/**
|
|
* The instance was not bound to any port.
|
|
*/
|
|
TOX_ERR_GET_PORT_NOT_BOUND,
|
|
|
|
} Tox_Err_Get_Port;
|
|
|
|
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.
|
|
*
|
|
* 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.
|
|
*
|
|
* @param dht_id A memory region of at least TOX_PUBLIC_KEY_SIZE bytes. If this
|
|
* parameter is NULL, this function has no effect.
|
|
*/
|
|
void tox_self_get_dht_id(const Tox *tox, uint8_t dht_id[TOX_PUBLIC_KEY_SIZE]);
|
|
|
|
/**
|
|
* @brief Return the UDP port this Tox instance is bound to.
|
|
*/
|
|
uint16_t tox_self_get_udp_port(const Tox *tox, Tox_Err_Get_Port *error);
|
|
|
|
/**
|
|
* @brief Return the TCP port this Tox instance is bound to.
|
|
*
|
|
* This is only relevant if the instance is acting as a TCP relay.
|
|
*/
|
|
uint16_t tox_self_get_tcp_port(const Tox *tox, Tox_Err_Get_Port *error);
|
|
|
|
/** @} */
|
|
|
|
/** @{
|
|
* @name Group chats
|
|
*/
|
|
|
|
typedef uint32_t Tox_Group_Number;
|
|
typedef uint32_t Tox_Group_Peer_Number;
|
|
typedef uint32_t Tox_Group_Message_Id;
|
|
|
|
/*******************************************************************************
|
|
*
|
|
* :: Group chat numeric constants
|
|
*
|
|
******************************************************************************/
|
|
|
|
/**
|
|
* Maximum length of a group topic.
|
|
*/
|
|
#define TOX_GROUP_MAX_TOPIC_LENGTH 512
|
|
|
|
uint32_t tox_group_max_topic_length(void);
|
|
|
|
/**
|
|
* Maximum length of a peer part message.
|
|
*/
|
|
#define TOX_GROUP_MAX_PART_LENGTH 128
|
|
|
|
uint32_t tox_group_max_part_length(void);
|
|
|
|
/**
|
|
* Maximum length of a group text message.
|
|
*/
|
|
#define TOX_GROUP_MAX_MESSAGE_LENGTH 1372
|
|
|
|
uint32_t tox_group_max_message_length(void);
|
|
|
|
/**
|
|
* Maximum length of a group custom lossy packet.
|
|
*/
|
|
#define TOX_GROUP_MAX_CUSTOM_LOSSY_PACKET_LENGTH 1373
|
|
|
|
uint32_t tox_group_max_custom_lossy_packet_length(void);
|
|
|
|
/**
|
|
* Maximum length of a group custom lossless packet.
|
|
*/
|
|
#define TOX_GROUP_MAX_CUSTOM_LOSSLESS_PACKET_LENGTH 1373
|
|
|
|
uint32_t tox_group_max_custom_lossless_packet_length(void);
|
|
|
|
/**
|
|
* Maximum length of a group name.
|
|
*/
|
|
#define TOX_GROUP_MAX_GROUP_NAME_LENGTH 48
|
|
|
|
uint32_t tox_group_max_group_name_length(void);
|
|
|
|
/**
|
|
* Maximum length of a group password.
|
|
*/
|
|
#define TOX_GROUP_MAX_PASSWORD_SIZE 32
|
|
|
|
uint32_t tox_group_max_password_size(void);
|
|
|
|
/**
|
|
* Number of bytes in a group Chat ID.
|
|
*/
|
|
#define TOX_GROUP_CHAT_ID_SIZE 32
|
|
|
|
uint32_t tox_group_chat_id_size(void);
|
|
|
|
/**
|
|
* Size of a peer public key.
|
|
*/
|
|
#define TOX_GROUP_PEER_PUBLIC_KEY_SIZE 32
|
|
|
|
uint32_t tox_group_peer_public_key_size(void);
|
|
|
|
/*******************************************************************************
|
|
*
|
|
* :: Group chat state enumerators
|
|
*
|
|
******************************************************************************/
|
|
|
|
/**
|
|
* Represents the group privacy state.
|
|
*/
|
|
typedef enum Tox_Group_Privacy_State {
|
|
|
|
/**
|
|
* 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.
|
|
*/
|
|
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.
|
|
*
|
|
* 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,
|
|
|
|
} Tox_Group_Privacy_State;
|
|
|
|
const char *tox_group_privacy_state_to_string(Tox_Group_Privacy_State value);
|
|
|
|
/**
|
|
* Represents the state of the group topic lock.
|
|
*
|
|
* The default is enabled.
|
|
*/
|
|
typedef enum Tox_Group_Topic_Lock {
|
|
|
|
/**
|
|
* 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.
|
|
*/
|
|
TOX_GROUP_TOPIC_LOCK_DISABLED,
|
|
|
|
} 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.
|
|
*/
|
|
typedef enum Tox_Group_Voice_State {
|
|
/**
|
|
* All group roles above Observer have permission to speak.
|
|
*/
|
|
TOX_GROUP_VOICE_STATE_ALL,
|
|
|
|
/**
|
|
* Moderators and Founders have permission to speak.
|
|
*/
|
|
TOX_GROUP_VOICE_STATE_MODERATOR,
|
|
|
|
/**
|
|
* Only the founder may speak.
|
|
*/
|
|
TOX_GROUP_VOICE_STATE_FOUNDER,
|
|
} Tox_Group_Voice_State;
|
|
|
|
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.
|
|
*/
|
|
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.
|
|
*/
|
|
TOX_GROUP_ROLE_FOUNDER,
|
|
|
|
/**
|
|
* May kick and set the user and observer roles for peers below this role.
|
|
* May also set the group topic.
|
|
*/
|
|
TOX_GROUP_ROLE_MODERATOR,
|
|
|
|
/**
|
|
* May communicate with other peers normally.
|
|
*/
|
|
TOX_GROUP_ROLE_USER,
|
|
|
|
/**
|
|
* May observe the group and ignore peers; may not communicate with other
|
|
* peers or with the group.
|
|
*/
|
|
TOX_GROUP_ROLE_OBSERVER,
|
|
|
|
} Tox_Group_Role;
|
|
|
|
const char *tox_group_role_to_string(Tox_Group_Role value);
|
|
|
|
/*******************************************************************************
|
|
*
|
|
* :: Group chat instance management
|
|
*
|
|
******************************************************************************/
|
|
|
|
typedef enum Tox_Err_Group_New {
|
|
|
|
/**
|
|
* The function returned successfully.
|
|
*/
|
|
TOX_ERR_GROUP_NEW_OK,
|
|
|
|
/**
|
|
* name exceeds TOX_MAX_NAME_LENGTH or group_name exceeded
|
|
* TOX_GROUP_MAX_GROUP_NAME_LENGTH.
|
|
*/
|
|
TOX_ERR_GROUP_NEW_TOO_LONG,
|
|
|
|
/**
|
|
* name or group_name is NULL or length is zero.
|
|
*/
|
|
TOX_ERR_GROUP_NEW_EMPTY,
|
|
|
|
/**
|
|
* The group instance failed to initialize.
|
|
*/
|
|
TOX_ERR_GROUP_NEW_INIT,
|
|
|
|
/**
|
|
* 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.
|
|
*/
|
|
TOX_ERR_GROUP_NEW_ANNOUNCE,
|
|
|
|
} Tox_Err_Group_New;
|
|
|
|
const char *tox_err_group_new_to_string(Tox_Err_Group_New value);
|
|
|
|
/**
|
|
* Creates a new group chat.
|
|
*
|
|
* This function creates a new group chat object and adds it to the chats 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.
|
|
*
|
|
* @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 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.
|
|
*
|
|
* @return group_number on success, UINT32_MAX on failure.
|
|
*/
|
|
Tox_Group_Number tox_group_new(
|
|
Tox *tox, Tox_Group_Privacy_State privacy_state,
|
|
const uint8_t group_name[], size_t group_name_length,
|
|
const uint8_t name[], size_t name_length, Tox_Err_Group_New *error);
|
|
|
|
typedef enum Tox_Err_Group_Join {
|
|
|
|
/**
|
|
* The function returned successfully.
|
|
*/
|
|
TOX_ERR_GROUP_JOIN_OK,
|
|
|
|
/**
|
|
* The group instance failed to initialize.
|
|
*/
|
|
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.
|
|
*/
|
|
TOX_ERR_GROUP_JOIN_BAD_CHAT_ID,
|
|
|
|
/**
|
|
* name is NULL or name_length is zero.
|
|
*/
|
|
TOX_ERR_GROUP_JOIN_EMPTY,
|
|
|
|
/**
|
|
* name exceeds TOX_MAX_NAME_LENGTH.
|
|
*/
|
|
TOX_ERR_GROUP_JOIN_TOO_LONG,
|
|
|
|
/**
|
|
* Failed to set password. This usually occurs if the password exceeds
|
|
* TOX_GROUP_MAX_PASSWORD_SIZE.
|
|
*/
|
|
TOX_ERR_GROUP_JOIN_PASSWORD,
|
|
|
|
/**
|
|
* There was a core error when initiating the group.
|
|
*/
|
|
TOX_ERR_GROUP_JOIN_CORE,
|
|
|
|
} Tox_Err_Group_Join;
|
|
|
|
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.
|
|
* @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.
|
|
*
|
|
* @return group_number on success, UINT32_MAX on failure.
|
|
*/
|
|
Tox_Group_Number tox_group_join(
|
|
Tox *tox, const uint8_t chat_id[TOX_GROUP_CHAT_ID_SIZE],
|
|
const uint8_t name[], size_t name_length,
|
|
const uint8_t password[], size_t password_length,
|
|
Tox_Err_Group_Join *error);
|
|
|
|
typedef enum Tox_Err_Group_Is_Connected {
|
|
|
|
/**
|
|
* The function returned successfully.
|
|
*/
|
|
TOX_ERR_GROUP_IS_CONNECTED_OK,
|
|
|
|
/**
|
|
* The group number passed did not designate a valid group.
|
|
*/
|
|
TOX_ERR_GROUP_IS_CONNECTED_GROUP_NOT_FOUND,
|
|
|
|
} 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.
|
|
*
|
|
* @param group_number The group number of the designated group.
|
|
*/
|
|
bool tox_group_is_connected(const Tox *tox, Tox_Group_Number group_number, Tox_Err_Group_Is_Connected *error);
|
|
|
|
typedef enum Tox_Err_Group_Disconnect {
|
|
|
|
/**
|
|
* The function returned successfully.
|
|
*/
|
|
TOX_ERR_GROUP_DISCONNECT_OK,
|
|
|
|
/**
|
|
* The group number passed did not designate a valid group.
|
|
*/
|
|
TOX_ERR_GROUP_DISCONNECT_GROUP_NOT_FOUND,
|
|
|
|
/**
|
|
* The group is already disconnected.
|
|
*/
|
|
TOX_ERR_GROUP_DISCONNECT_ALREADY_DISCONNECTED,
|
|
} 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.
|
|
*
|
|
* Returns true if we successfully disconnect from the group.
|
|
*
|
|
* @param group_number The group number of the designated group.
|
|
*/
|
|
bool tox_group_disconnect(const Tox *tox, Tox_Group_Number group_number, Tox_Err_Group_Disconnect *error);
|
|
|
|
typedef enum Tox_Err_Group_Reconnect {
|
|
|
|
/**
|
|
* The function returned successfully.
|
|
*/
|
|
TOX_ERR_GROUP_RECONNECT_OK,
|
|
|
|
/**
|
|
* The group number passed did not designate a valid group.
|
|
*/
|
|
TOX_ERR_GROUP_RECONNECT_GROUP_NOT_FOUND,
|
|
|
|
/**
|
|
* There was a core error when initiating the group.
|
|
*/
|
|
TOX_ERR_GROUP_RECONNECT_CORE,
|
|
|
|
} Tox_Err_Group_Reconnect;
|
|
|
|
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.).
|
|
*
|
|
* @param group_number The group number of the group we wish to reconnect to.
|
|
*
|
|
* @return true on success.
|
|
*/
|
|
bool tox_group_reconnect(Tox *tox, Tox_Group_Number group_number, Tox_Err_Group_Reconnect *error);
|
|
|
|
typedef enum Tox_Err_Group_Leave {
|
|
|
|
/**
|
|
* The function returned successfully.
|
|
*/
|
|
TOX_ERR_GROUP_LEAVE_OK,
|
|
|
|
/**
|
|
* The group number passed did not designate a valid group.
|
|
*/
|
|
TOX_ERR_GROUP_LEAVE_GROUP_NOT_FOUND,
|
|
|
|
/**
|
|
* Message length exceeded TOX_GROUP_MAX_PART_LENGTH.
|
|
*/
|
|
TOX_ERR_GROUP_LEAVE_TOO_LONG,
|
|
|
|
/**
|
|
* The parting packet failed to send.
|
|
*/
|
|
TOX_ERR_GROUP_LEAVE_FAIL_SEND,
|
|
} Tox_Err_Group_Leave;
|
|
|
|
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.
|
|
*
|
|
* @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.
|
|
*
|
|
* @return true if the group chat instance is successfully deleted.
|
|
*/
|
|
bool tox_group_leave(
|
|
Tox *tox, Tox_Group_Number group_number,
|
|
const uint8_t part_message[], size_t length,
|
|
Tox_Err_Group_Leave *error);
|
|
|
|
/*******************************************************************************
|
|
*
|
|
* :: Group user-visible client information (nickname/status/role/public key)
|
|
*
|
|
******************************************************************************/
|
|
|
|
/**
|
|
* General error codes for self state get and size functions.
|
|
*/
|
|
typedef enum Tox_Err_Group_Self_Query {
|
|
|
|
/**
|
|
* The function returned successfully.
|
|
*/
|
|
TOX_ERR_GROUP_SELF_QUERY_OK,
|
|
|
|
/**
|
|
* The group number passed did not designate a valid group.
|
|
*/
|
|
TOX_ERR_GROUP_SELF_QUERY_GROUP_NOT_FOUND,
|
|
|
|
} Tox_Err_Group_Self_Query;
|
|
|
|
const char *tox_err_group_self_query_to_string(Tox_Err_Group_Self_Query value);
|
|
|
|
/**
|
|
* Error codes for self name setting.
|
|
*/
|
|
typedef enum Tox_Err_Group_Self_Name_Set {
|
|
|
|
/**
|
|
* The function returned successfully.
|
|
*/
|
|
TOX_ERR_GROUP_SELF_NAME_SET_OK,
|
|
|
|
/**
|
|
* The group number passed did not designate a valid group.
|
|
*/
|
|
TOX_ERR_GROUP_SELF_NAME_SET_GROUP_NOT_FOUND,
|
|
|
|
/**
|
|
* Name length exceeded TOX_MAX_NAME_LENGTH.
|
|
*/
|
|
TOX_ERR_GROUP_SELF_NAME_SET_TOO_LONG,
|
|
|
|
/**
|
|
* The length given to the set function is zero or name is a NULL pointer.
|
|
*/
|
|
TOX_ERR_GROUP_SELF_NAME_SET_INVALID,
|
|
|
|
/**
|
|
* The packet failed to send.
|
|
*/
|
|
TOX_ERR_GROUP_SELF_NAME_SET_FAIL_SEND,
|
|
|
|
} 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.
|
|
*
|
|
* 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.
|
|
*
|
|
* @return true on success.
|
|
*/
|
|
bool tox_group_self_set_name(
|
|
Tox *tox, Tox_Group_Number group_number,
|
|
const uint8_t name[], size_t length,
|
|
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.
|
|
*
|
|
* If no nickname was set before calling this function, the name is empty,
|
|
* and this function returns 0.
|
|
*
|
|
* @see threading for concurrency implications.
|
|
*/
|
|
size_t tox_group_self_get_name_size(const Tox *tox, Tox_Group_Number group_number, Tox_Err_Group_Self_Query *error);
|
|
|
|
/**
|
|
* Write the nickname set by tox_group_self_set_name to a byte array.
|
|
*
|
|
* 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.
|
|
*
|
|
* @param name A valid memory location large enough to hold the nickname.
|
|
* If this parameter is NULL, the function has no effect.
|
|
*
|
|
* @return true on success.
|
|
*/
|
|
bool tox_group_self_get_name(
|
|
const Tox *tox, Tox_Group_Number group_number,
|
|
uint8_t name[], Tox_Err_Group_Self_Query *error);
|
|
|
|
/**
|
|
* Error codes for self status setting.
|
|
*/
|
|
typedef enum Tox_Err_Group_Self_Status_Set {
|
|
|
|
/**
|
|
* The function returned successfully.
|
|
*/
|
|
TOX_ERR_GROUP_SELF_STATUS_SET_OK,
|
|
|
|
/**
|
|
* The group number passed did not designate a valid group.
|
|
*/
|
|
TOX_ERR_GROUP_SELF_STATUS_SET_GROUP_NOT_FOUND,
|
|
|
|
/**
|
|
* The packet failed to send.
|
|
*/
|
|
TOX_ERR_GROUP_SELF_STATUS_SET_FAIL_SEND,
|
|
|
|
} 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.
|
|
*
|
|
* @return true on success.
|
|
*/
|
|
bool tox_group_self_set_status(Tox *tox, Tox_Group_Number group_number, Tox_User_Status status,
|
|
Tox_Err_Group_Self_Status_Set *error);
|
|
|
|
/**
|
|
* returns the client's status for the group instance on success.
|
|
* return value is unspecified on failure.
|
|
*/
|
|
Tox_User_Status tox_group_self_get_status(const Tox *tox, Tox_Group_Number group_number, Tox_Err_Group_Self_Query *error);
|
|
|
|
/**
|
|
* returns the client's role for the group instance on success.
|
|
* return value is unspecified on failure.
|
|
*/
|
|
Tox_Group_Role tox_group_self_get_role(const Tox *tox, Tox_Group_Number group_number, Tox_Err_Group_Self_Query *error);
|
|
|
|
/**
|
|
* returns the client's peer id for the group instance on success.
|
|
* return value is unspecified on failure.
|
|
*/
|
|
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.
|
|
*
|
|
* 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.
|
|
*
|
|
* @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.
|
|
*
|
|
* @return true on success.
|
|
*/
|
|
bool tox_group_self_get_public_key(const Tox *tox, Tox_Group_Number group_number, uint8_t public_key[TOX_PUBLIC_KEY_SIZE],
|
|
Tox_Err_Group_Self_Query *error);
|
|
|
|
/*******************************************************************************
|
|
*
|
|
* :: Peer-specific group state queries.
|
|
*
|
|
******************************************************************************/
|
|
|
|
/**
|
|
* Error codes for peer info queries.
|
|
*/
|
|
typedef enum Tox_Err_Group_Peer_Query {
|
|
|
|
/**
|
|
* The function returned successfully.
|
|
*/
|
|
TOX_ERR_GROUP_PEER_QUERY_OK,
|
|
|
|
/**
|
|
* The group number passed did not designate a valid group.
|
|
*/
|
|
TOX_ERR_GROUP_PEER_QUERY_GROUP_NOT_FOUND,
|
|
|
|
/**
|
|
* The ID passed did not designate a valid peer.
|
|
*/
|
|
TOX_ERR_GROUP_PEER_QUERY_PEER_NOT_FOUND,
|
|
|
|
} 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.
|
|
*
|
|
* @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.
|
|
*
|
|
* The return value is equal to the `length` argument received by the last
|
|
* `group_peer_name` callback.
|
|
*/
|
|
size_t tox_group_peer_get_name_size(const Tox *tox, Tox_Group_Number group_number, Tox_Group_Peer_Number peer_id,
|
|
Tox_Err_Group_Peer_Query *error);
|
|
|
|
/**
|
|
* 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.
|
|
*
|
|
* The data written to `name` is equal to the data received by the last
|
|
* `group_peer_name` callback.
|
|
*
|
|
* @param group_number The group number of the group we wish to query.
|
|
* @param peer_id The ID of the peer whose name we wish to retrieve.
|
|
* @param name A valid memory region large enough to store the friend's name.
|
|
*
|
|
* @return true on success.
|
|
*/
|
|
bool tox_group_peer_get_name(
|
|
const Tox *tox, Tox_Group_Number group_number, Tox_Group_Peer_Number peer_id,
|
|
uint8_t name[], Tox_Err_Group_Peer_Query *error);
|
|
|
|
/**
|
|
* Return the peer's user status (away/busy/...). 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 status we wish to query.
|
|
*
|
|
* The status returned is equal to the last status received through the
|
|
* `group_peer_status` callback.
|
|
*/
|
|
Tox_User_Status tox_group_peer_get_status(const Tox *tox, Tox_Group_Number group_number, Tox_Group_Peer_Number peer_id,
|
|
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.
|
|
*
|
|
* @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.
|
|
*
|
|
* The role returned is equal to the last role received through the
|
|
* `group_moderation` callback.
|
|
*/
|
|
Tox_Group_Role tox_group_peer_get_role(const Tox *tox, Tox_Group_Number group_number, Tox_Group_Peer_Number peer_id,
|
|
Tox_Err_Group_Peer_Query *error);
|
|
|
|
/**
|
|
* 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.
|
|
*
|
|
* @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.
|
|
*/
|
|
Tox_Connection tox_group_peer_get_connection_status(const Tox *tox, Tox_Group_Number group_number, Tox_Group_Peer_Number peer_id,
|
|
Tox_Err_Group_Peer_Query *error);
|
|
|
|
/**
|
|
* 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.
|
|
*
|
|
* `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.
|
|
* @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.
|
|
*
|
|
* @return true on success.
|
|
*/
|
|
bool tox_group_peer_get_public_key(
|
|
const Tox *tox, Tox_Group_Number group_number, Tox_Group_Peer_Number peer_id,
|
|
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 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.
|
|
*/
|
|
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 name_length, void *user_data);
|
|
|
|
/**
|
|
* Set the callback for the `group_peer_name` event. Pass NULL to unset.
|
|
*
|
|
* This event is triggered when a peer changes their nickname.
|
|
*/
|
|
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 peer_id The ID of the peer who has changed their status.
|
|
* @param status The new status of the peer.
|
|
*/
|
|
typedef void tox_group_peer_status_cb(Tox *tox, Tox_Group_Number group_number, Tox_Group_Peer_Number peer_id, Tox_User_Status status,
|
|
void *user_data);
|
|
|
|
/**
|
|
* Set the callback for the `group_peer_status` event. Pass NULL to unset.
|
|
*
|
|
* This event is triggered when a peer changes their status.
|
|
*/
|
|
void tox_callback_group_peer_status(Tox *tox, tox_group_peer_status_cb *callback);
|
|
|
|
/*******************************************************************************
|
|
*
|
|
* :: Group chat state queries and events.
|
|
*
|
|
******************************************************************************/
|
|
|
|
/**
|
|
* General error codes for group state get and size functions.
|
|
*/
|
|
typedef enum Tox_Err_Group_State_Query {
|
|
|
|
/**
|
|
* The function returned successfully.
|
|
*/
|
|
TOX_ERR_GROUP_STATE_QUERY_OK,
|
|
|
|
/**
|
|
* The group number passed did not designate a valid group.
|
|
*/
|
|
TOX_ERR_GROUP_STATE_QUERY_GROUP_NOT_FOUND,
|
|
|
|
} Tox_Err_Group_State_Query;
|
|
|
|
const char *tox_err_group_state_query_to_string(Tox_Err_Group_State_Query value);
|
|
|
|
/**
|
|
* Error codes for group topic setting.
|
|
*/
|
|
typedef enum Tox_Err_Group_Topic_Set {
|
|
|
|
/**
|
|
* The function returned successfully.
|
|
*/
|
|
TOX_ERR_GROUP_TOPIC_SET_OK,
|
|
|
|
/**
|
|
* The group number passed did not designate a valid group.
|
|
*/
|
|
TOX_ERR_GROUP_TOPIC_SET_GROUP_NOT_FOUND,
|
|
|
|
/**
|
|
* Topic length exceeded TOX_GROUP_MAX_TOPIC_LENGTH.
|
|
*/
|
|
TOX_ERR_GROUP_TOPIC_SET_TOO_LONG,
|
|
|
|
/**
|
|
* The caller does not have the required permissions to set the topic.
|
|
*/
|
|
TOX_ERR_GROUP_TOPIC_SET_PERMISSIONS,
|
|
|
|
/**
|
|
* The packet could not be created. This error is usually related to
|
|
* cryptographic signing.
|
|
*/
|
|
TOX_ERR_GROUP_TOPIC_SET_FAIL_CREATE,
|
|
|
|
/**
|
|
* The packet failed to send.
|
|
*/
|
|
TOX_ERR_GROUP_TOPIC_SET_FAIL_SEND,
|
|
|
|
/**
|
|
* The group is disconnected.
|
|
*/
|
|
TOX_ERR_GROUP_TOPIC_SET_DISCONNECTED,
|
|
|
|
} Tox_Err_Group_Topic_Set;
|
|
|
|
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 the length
|
|
* is equal to zero or topic is set to NULL, the topic will be unset.
|
|
*
|
|
* @return true on success.
|
|
*/
|
|
bool tox_group_set_topic(
|
|
Tox *tox, Tox_Group_Number group_number,
|
|
const uint8_t topic[], size_t length,
|
|
Tox_Err_Group_Topic_Set *error);
|
|
|
|
/**
|
|
* Return the length of the group topic. If the group number is invalid, the
|
|
* return value is unspecified.
|
|
*
|
|
* The return value is equal to the `length` argument received by the last
|
|
* `group_topic` callback.
|
|
*/
|
|
size_t tox_group_get_topic_size(const Tox *tox, Tox_Group_Number group_number, Tox_Err_Group_State_Query *error);
|
|
|
|
/**
|
|
* 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.
|
|
*
|
|
* The data written to `topic` is equal to the data received by the last
|
|
* `group_topic` callback.
|
|
*
|
|
* @param topic A valid memory region large enough to store the topic.
|
|
* If this parameter is NULL, this function has no effect.
|
|
*
|
|
* @return true on success.
|
|
*/
|
|
bool tox_group_get_topic(
|
|
const Tox *tox, Tox_Group_Number group_number,
|
|
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 topic The topic data.
|
|
* @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 topic_length,
|
|
void *user_data);
|
|
|
|
/**
|
|
* Set the callback for the `group_topic` event. Pass NULL to unset.
|
|
*
|
|
* This event is triggered when a peer changes the group topic.
|
|
*/
|
|
void tox_callback_group_topic(Tox *tox, tox_group_topic_cb *callback);
|
|
|
|
/**
|
|
* Return the length of the group name. If the group number is invalid, the
|
|
* return value is unspecified.
|
|
*/
|
|
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.
|
|
*
|
|
* 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.
|
|
*
|
|
* @return true on success.
|
|
*/
|
|
bool tox_group_get_name(
|
|
const Tox *tox, Tox_Group_Number group_number,
|
|
uint8_t name[], Tox_Err_Group_State_Query *error);
|
|
|
|
/**
|
|
* Write the Chat ID designated by the given group number to a byte array.
|
|
*
|
|
* `chat_id` should have room for at least TOX_GROUP_CHAT_ID_SIZE bytes.
|
|
*
|
|
* @param chat_id A valid memory region large enough to store the Chat ID.
|
|
* If this parameter is NULL, this function call has no effect.
|
|
*
|
|
* @return true on success.
|
|
*/
|
|
bool tox_group_get_chat_id(
|
|
const Tox *tox, Tox_Group_Number group_number, uint8_t chat_id[TOX_GROUP_CHAT_ID_SIZE],
|
|
Tox_Err_Group_State_Query *error);
|
|
|
|
/**
|
|
* Return the number of groups in the Tox chats array.
|
|
*/
|
|
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.
|
|
*
|
|
* 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.
|
|
*/
|
|
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 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,
|
|
void *user_data);
|
|
|
|
/**
|
|
* Set the callback for the `group_privacy_state` event. Pass NULL to unset.
|
|
*
|
|
* This event is triggered when the group founder changes the privacy state.
|
|
*/
|
|
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.
|
|
*
|
|
* 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.
|
|
*/
|
|
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 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,
|
|
void *user_data);
|
|
|
|
/**
|
|
* Set the callback for the `group_privacy_state` event. Pass NULL to unset.
|
|
*
|
|
* This event is triggered when the group founder changes the voice state.
|
|
*/
|
|
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
|
|
* 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 controls` 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 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);
|
|
|
|
/**
|
|
* Set the callback for the `group_topic_lock` event. Pass NULL to unset.
|
|
*
|
|
* This event is triggered when the group founder changes the topic lock status.
|
|
*/
|
|
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.
|
|
*
|
|
* 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.
|
|
*/
|
|
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 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);
|
|
|
|
/**
|
|
* 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.
|
|
*/
|
|
void tox_callback_group_peer_limit(Tox *tox, tox_group_peer_limit_cb *callback);
|
|
|
|
/**
|
|
* Return the length of the group password. If the group number is invalid, the
|
|
* return value is unspecified.
|
|
*/
|
|
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.
|
|
*
|
|
* 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.
|
|
*
|
|
* @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.
|
|
*
|
|
* @return true on success.
|
|
*/
|
|
bool tox_group_get_password(
|
|
const Tox *tox, Tox_Group_Number group_number, uint8_t password[],
|
|
Tox_Err_Group_State_Query *error);
|
|
|
|
/**
|
|
* @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.
|
|
*/
|
|
typedef void tox_group_password_cb(
|
|
Tox *tox, Tox_Group_Number group_number,
|
|
const uint8_t password[], size_t password_length,
|
|
void *user_data);
|
|
|
|
/**
|
|
* Set the callback for the `group_password` event. Pass NULL to unset.
|
|
*
|
|
* This event is triggered when the group founder changes the group password.
|
|
*/
|
|
void tox_callback_group_password(Tox *tox, tox_group_password_cb *callback);
|
|
|
|
/*******************************************************************************
|
|
*
|
|
* :: Group chat message sending
|
|
*
|
|
******************************************************************************/
|
|
|
|
typedef enum Tox_Err_Group_Send_Message {
|
|
|
|
/**
|
|
* The function returned successfully.
|
|
*/
|
|
TOX_ERR_GROUP_SEND_MESSAGE_OK,
|
|
|
|
/**
|
|
* The group number passed did not designate a valid group.
|
|
*/
|
|
TOX_ERR_GROUP_SEND_MESSAGE_GROUP_NOT_FOUND,
|
|
|
|
/**
|
|
* Message length exceeded TOX_GROUP_MAX_MESSAGE_LENGTH.
|
|
*/
|
|
TOX_ERR_GROUP_SEND_MESSAGE_TOO_LONG,
|
|
|
|
/**
|
|
* The message pointer is NULL or length is zero.
|
|
*/
|
|
TOX_ERR_GROUP_SEND_MESSAGE_EMPTY,
|
|
|
|
/**
|
|
* The message type is invalid.
|
|
*/
|
|
TOX_ERR_GROUP_SEND_MESSAGE_BAD_TYPE,
|
|
|
|
/**
|
|
* The caller does not have the required permissions to send group messages.
|
|
*/
|
|
TOX_ERR_GROUP_SEND_MESSAGE_PERMISSIONS,
|
|
|
|
/**
|
|
* Packet failed to send.
|
|
*/
|
|
TOX_ERR_GROUP_SEND_MESSAGE_FAIL_SEND,
|
|
|
|
/**
|
|
* The group is disconnected.
|
|
*/
|
|
TOX_ERR_GROUP_SEND_MESSAGE_DISCONNECTED,
|
|
|
|
} Tox_Err_Group_Send_Message;
|
|
|
|
const char *tox_err_group_send_message_to_string(Tox_Err_Group_Send_Message value);
|
|
|
|
/**
|
|
* Send a text chat message to the group.
|
|
*
|
|
* 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.
|
|
*
|
|
* @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.
|
|
* @param length Length of the message to be sent.
|
|
*
|
|
* @return The message_id of this message. If this function has an error, the
|
|
* 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 message_type,
|
|
const uint8_t message[], size_t length,
|
|
Tox_Err_Group_Send_Message *error);
|
|
|
|
typedef enum Tox_Err_Group_Send_Private_Message {
|
|
|
|
/**
|
|
* The function returned successfully.
|
|
*/
|
|
TOX_ERR_GROUP_SEND_PRIVATE_MESSAGE_OK,
|
|
|
|
/**
|
|
* The group number passed did not designate a valid group.
|
|
*/
|
|
TOX_ERR_GROUP_SEND_PRIVATE_MESSAGE_GROUP_NOT_FOUND,
|
|
|
|
/**
|
|
* The peer ID passed did not designate a valid peer.
|
|
*/
|
|
TOX_ERR_GROUP_SEND_PRIVATE_MESSAGE_PEER_NOT_FOUND,
|
|
|
|
/**
|
|
* Message length exceeded TOX_GROUP_MAX_MESSAGE_LENGTH.
|
|
*/
|
|
TOX_ERR_GROUP_SEND_PRIVATE_MESSAGE_TOO_LONG,
|
|
|
|
/**
|
|
* The message pointer is NULL or length is zero.
|
|
*/
|
|
TOX_ERR_GROUP_SEND_PRIVATE_MESSAGE_EMPTY,
|
|
|
|
/**
|
|
* The message type is invalid.
|
|
*/
|
|
TOX_ERR_GROUP_SEND_PRIVATE_MESSAGE_BAD_TYPE,
|
|
|
|
/**
|
|
* The caller does not have the required permissions to send group messages.
|
|
*/
|
|
TOX_ERR_GROUP_SEND_PRIVATE_MESSAGE_PERMISSIONS,
|
|
|
|
/**
|
|
* Packet failed to send.
|
|
*/
|
|
TOX_ERR_GROUP_SEND_PRIVATE_MESSAGE_FAIL_SEND,
|
|
|
|
/**
|
|
* The group is disconnected.
|
|
*/
|
|
TOX_ERR_GROUP_SEND_PRIVATE_MESSAGE_DISCONNECTED,
|
|
|
|
} Tox_Err_Group_Send_Private_Message;
|
|
|
|
const char *tox_err_group_send_private_message_to_string(Tox_Err_Group_Send_Private_Message value);
|
|
|
|
/**
|
|
* 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.
|
|
*
|
|
* 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 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.
|
|
*
|
|
* @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 message_type,
|
|
const uint8_t message[], size_t length,
|
|
Tox_Err_Group_Send_Private_Message *error);
|
|
|
|
typedef enum Tox_Err_Group_Send_Custom_Packet {
|
|
|
|
/**
|
|
* The function returned successfully.
|
|
*/
|
|
TOX_ERR_GROUP_SEND_CUSTOM_PACKET_OK,
|
|
|
|
/**
|
|
* The group number passed did not designate a valid group.
|
|
*/
|
|
TOX_ERR_GROUP_SEND_CUSTOM_PACKET_GROUP_NOT_FOUND,
|
|
|
|
/**
|
|
* Message length exceeded TOX_GROUP_MAX_CUSTOM_LOSSY_PACKET_LENGTH if the
|
|
* packet was lossy, or TOX_GROUP_MAX_CUSTOM_LOSSLESS_PACKET_LENGTH if the
|
|
* packet was lossless.
|
|
*/
|
|
TOX_ERR_GROUP_SEND_CUSTOM_PACKET_TOO_LONG,
|
|
|
|
/**
|
|
* The message pointer is NULL or length is zero.
|
|
*/
|
|
TOX_ERR_GROUP_SEND_CUSTOM_PACKET_EMPTY,
|
|
|
|
/**
|
|
* The group is disconnected.
|
|
*/
|
|
TOX_ERR_GROUP_SEND_CUSTOM_PACKET_DISCONNECTED,
|
|
|
|
/**
|
|
* The packet did not successfully send to any peer. This often indicates
|
|
* a connection issue on the sender's side.
|
|
*/
|
|
TOX_ERR_GROUP_SEND_CUSTOM_PACKET_FAIL_SEND,
|
|
|
|
} Tox_Err_Group_Send_Custom_Packet;
|
|
|
|
const char *tox_err_group_send_custom_packet_to_string(Tox_Err_Group_Send_Custom_Packet value);
|
|
|
|
/**
|
|
* 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 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.
|
|
*
|
|
* 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
|
|
* then reassemble the fragments. Packets may not be empty.
|
|
*
|
|
* @param group_number The group number of the group the packet is intended for.
|
|
* @param lossless True if the packet should be lossless.
|
|
* @param data A byte array containing the packet data.
|
|
* @param length The length of the packet data byte array.
|
|
*
|
|
* @return true on success.
|
|
*/
|
|
bool tox_group_send_custom_packet(
|
|
const Tox *tox, Tox_Group_Number group_number, bool lossless,
|
|
const uint8_t data[], size_t length,
|
|
Tox_Err_Group_Send_Custom_Packet *error);
|
|
|
|
typedef enum Tox_Err_Group_Send_Custom_Private_Packet {
|
|
|
|
/**
|
|
* The function returned successfully.
|
|
*/
|
|
TOX_ERR_GROUP_SEND_CUSTOM_PRIVATE_PACKET_OK,
|
|
|
|
/**
|
|
* The group number passed did not designate a valid group.
|
|
*/
|
|
TOX_ERR_GROUP_SEND_CUSTOM_PRIVATE_PACKET_GROUP_NOT_FOUND,
|
|
|
|
/**
|
|
* Message length exceeded TOX_GROUP_MAX_CUSTOM_LOSSY_PACKET_LENGTH if the
|
|
* packet was lossy, or TOX_GROUP_MAX_CUSTOM_LOSSLESS_PACKET_LENGTH if the
|
|
* packet was lossless.
|
|
*/
|
|
TOX_ERR_GROUP_SEND_CUSTOM_PRIVATE_PACKET_TOO_LONG,
|
|
|
|
/**
|
|
* The message pointer is NULL or length is zero.
|
|
*/
|
|
TOX_ERR_GROUP_SEND_CUSTOM_PRIVATE_PACKET_EMPTY,
|
|
|
|
/**
|
|
* The peer ID passed did no designate a valid peer.
|
|
*/
|
|
TOX_ERR_GROUP_SEND_CUSTOM_PRIVATE_PACKET_PEER_NOT_FOUND,
|
|
|
|
/**
|
|
* The packet failed to send.
|
|
*/
|
|
TOX_ERR_GROUP_SEND_CUSTOM_PRIVATE_PACKET_FAIL_SEND,
|
|
|
|
/**
|
|
* The group is disconnected.
|
|
*/
|
|
TOX_ERR_GROUP_SEND_CUSTOM_PRIVATE_PACKET_DISCONNECTED,
|
|
|
|
} Tox_Err_Group_Send_Custom_Private_Packet;
|
|
|
|
const char *tox_err_group_send_custom_private_packet_to_string(Tox_Err_Group_Send_Custom_Private_Packet value);
|
|
|
|
/**
|
|
* 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 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.
|
|
*
|
|
* 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
|
|
* then reassemble the fragments. Packets may not be empty.
|
|
*
|
|
* @param group_number The group number of the group the packet is intended for.
|
|
* @param peer_id The ID of the peer the packet is intended for.
|
|
* @param lossless True if the packet should be lossless.
|
|
* @param data A byte array containing the packet data.
|
|
* @param length The length of the packet data byte array.
|
|
*
|
|
* @return true on success.
|
|
*/
|
|
bool tox_group_send_custom_private_packet(const Tox *tox, Tox_Group_Number group_number, Tox_Group_Peer_Number peer_id, bool lossless,
|
|
const uint8_t data[], size_t length,
|
|
Tox_Err_Group_Send_Custom_Private_Packet *error);
|
|
|
|
/*******************************************************************************
|
|
*
|
|
* :: Group chat message receiving
|
|
*
|
|
******************************************************************************/
|
|
|
|
/**
|
|
* @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.
|
|
*/
|
|
typedef void tox_group_message_cb(
|
|
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);
|
|
|
|
/**
|
|
* Set the callback for the `group_message` event. Pass NULL to unset.
|
|
*
|
|
* This event is triggered when the client receives a group message.
|
|
*/
|
|
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 message_type,
|
|
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.
|
|
*
|
|
* This event is triggered when the client receives a private message.
|
|
*/
|
|
void tox_callback_group_private_message(Tox *tox, tox_group_private_message_cb *callback);
|
|
|
|
/**
|
|
* @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 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 data_length, void *user_data);
|
|
|
|
/**
|
|
* Set the callback for the `group_custom_packet` event. Pass NULL to unset.
|
|
*
|
|
* This event is triggered when the client receives a custom packet.
|
|
*/
|
|
void tox_callback_group_custom_packet(Tox *tox, tox_group_custom_packet_cb *callback);
|
|
|
|
/**
|
|
* @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 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 data_length, void *user_data);
|
|
|
|
/**
|
|
* 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.
|
|
*/
|
|
void tox_callback_group_custom_private_packet(Tox *tox, tox_group_custom_private_packet_cb *callback);
|
|
|
|
/*******************************************************************************
|
|
*
|
|
* :: Group chat inviting and join/part events
|
|
*
|
|
******************************************************************************/
|
|
|
|
typedef enum Tox_Err_Group_Invite_Friend {
|
|
|
|
/**
|
|
* The function returned successfully.
|
|
*/
|
|
TOX_ERR_GROUP_INVITE_FRIEND_OK,
|
|
|
|
/**
|
|
* The group number passed did not designate a valid group.
|
|
*/
|
|
TOX_ERR_GROUP_INVITE_FRIEND_GROUP_NOT_FOUND,
|
|
|
|
/**
|
|
* The friend number passed did not designate a valid friend.
|
|
*/
|
|
TOX_ERR_GROUP_INVITE_FRIEND_FRIEND_NOT_FOUND,
|
|
|
|
/**
|
|
* Creation of the invite packet failed. This indicates a network related
|
|
* error.
|
|
*/
|
|
TOX_ERR_GROUP_INVITE_FRIEND_INVITE_FAIL,
|
|
|
|
/**
|
|
* Packet failed to send.
|
|
*/
|
|
TOX_ERR_GROUP_INVITE_FRIEND_FAIL_SEND,
|
|
|
|
/**
|
|
* The group is disconnected.
|
|
*/
|
|
TOX_ERR_GROUP_INVITE_FRIEND_DISCONNECTED,
|
|
|
|
} Tox_Err_Group_Invite_Friend;
|
|
|
|
const char *tox_err_group_invite_friend_to_string(Tox_Err_Group_Invite_Friend value);
|
|
|
|
/**
|
|
* Invite a friend to a group.
|
|
*
|
|
* 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.
|
|
*
|
|
* @return true on success.
|
|
*/
|
|
bool tox_group_invite_friend(
|
|
const Tox *tox, Tox_Group_Number group_number, Tox_Friend_Number friend_number,
|
|
Tox_Err_Group_Invite_Friend *error);
|
|
|
|
typedef enum Tox_Err_Group_Invite_Accept {
|
|
|
|
/**
|
|
* The function returned successfully.
|
|
*/
|
|
TOX_ERR_GROUP_INVITE_ACCEPT_OK,
|
|
|
|
/**
|
|
* The invite data is not in the expected format.
|
|
*/
|
|
TOX_ERR_GROUP_INVITE_ACCEPT_BAD_INVITE,
|
|
|
|
/**
|
|
* The group instance failed to initialize.
|
|
*/
|
|
TOX_ERR_GROUP_INVITE_ACCEPT_INIT_FAILED,
|
|
|
|
/**
|
|
* name exceeds TOX_MAX_NAME_LENGTH
|
|
*/
|
|
TOX_ERR_GROUP_INVITE_ACCEPT_TOO_LONG,
|
|
|
|
/**
|
|
* name is NULL or name_length is zero.
|
|
*/
|
|
TOX_ERR_GROUP_INVITE_ACCEPT_EMPTY,
|
|
|
|
/**
|
|
* Failed to set password. This usually occurs if the password exceeds
|
|
* TOX_GROUP_MAX_PASSWORD_SIZE.
|
|
*/
|
|
TOX_ERR_GROUP_INVITE_ACCEPT_PASSWORD,
|
|
|
|
/**
|
|
* The friend number passed did not designate a valid friend.
|
|
*/
|
|
TOX_ERR_GROUP_INVITE_ACCEPT_FRIEND_NOT_FOUND,
|
|
|
|
/**
|
|
* Packet failed to send.
|
|
*/
|
|
TOX_ERR_GROUP_INVITE_ACCEPT_FAIL_SEND,
|
|
|
|
/**
|
|
* Invite data or name is NULL.
|
|
*/
|
|
TOX_ERR_GROUP_INVITE_ACCEPT_NULL,
|
|
|
|
} 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.
|
|
*
|
|
* @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.
|
|
*
|
|
* @return the group_number on success, UINT32_MAX on failure.
|
|
*/
|
|
Tox_Group_Number tox_group_invite_accept(
|
|
Tox *tox, Tox_Friend_Number friend_number,
|
|
const uint8_t invite_data[], size_t length,
|
|
const uint8_t name[], size_t name_length,
|
|
const uint8_t password[], size_t password_length,
|
|
Tox_Err_Group_Invite_Accept *error);
|
|
|
|
/**
|
|
* @param friend_number The friend number of the contact who sent the invite.
|
|
* @param invite_data The invite data.
|
|
* @param invite_data_length The length of invite_data.
|
|
* @param group_name The name of the group. In conferences, this is "title".
|
|
* @param group_name_length The length of the group name.
|
|
*/
|
|
typedef void tox_group_invite_cb(
|
|
Tox *tox, Tox_Friend_Number 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);
|
|
|
|
/**
|
|
* 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.
|
|
*/
|
|
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.
|
|
*/
|
|
typedef void tox_group_peer_join_cb(Tox *tox, Tox_Group_Number group_number, Tox_Group_Peer_Number peer_id, void *user_data);
|
|
|
|
/**
|
|
* Set the callback for the `group_peer_join` event. Pass NULL to unset.
|
|
*
|
|
* This event is triggered when a peer other than self joins the group.
|
|
*/
|
|
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.
|
|
*/
|
|
typedef enum Tox_Group_Exit_Type {
|
|
|
|
/**
|
|
* The peer has quit the group.
|
|
*/
|
|
TOX_GROUP_EXIT_TYPE_QUIT,
|
|
|
|
/**
|
|
* Your connection with this peer has timed out.
|
|
*/
|
|
TOX_GROUP_EXIT_TYPE_TIMEOUT,
|
|
|
|
/**
|
|
* Your connection with this peer has been severed.
|
|
*/
|
|
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.
|
|
*/
|
|
TOX_GROUP_EXIT_TYPE_SELF_DISCONNECTED,
|
|
|
|
/**
|
|
* The peer has been kicked.
|
|
*/
|
|
TOX_GROUP_EXIT_TYPE_KICK,
|
|
|
|
/**
|
|
* The peer provided invalid group sync information.
|
|
*/
|
|
TOX_GROUP_EXIT_TYPE_SYNC_ERROR,
|
|
|
|
} Tox_Group_Exit_Type;
|
|
|
|
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 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.
|
|
* @param part_message The parting message data.
|
|
* @param part_message_length The length of the parting message.
|
|
*/
|
|
typedef void tox_group_peer_exit_cb(
|
|
Tox *tox, Tox_Group_Number group_number, Tox_Group_Peer_Number peer_id, Tox_Group_Exit_Type exit_type,
|
|
const uint8_t name[], size_t name_length,
|
|
const uint8_t part_message[], size_t part_message_length, void *user_data);
|
|
|
|
/**
|
|
* Set the callback for the `group_peer_exit` event. Pass NULL to unset.
|
|
*
|
|
* This event is triggered when a peer other than self exits the group.
|
|
*/
|
|
void tox_callback_group_peer_exit(Tox *tox, tox_group_peer_exit_cb *callback);
|
|
|
|
/**
|
|
* @param group_number The group number of the group that the client has joined.
|
|
*/
|
|
typedef void tox_group_self_join_cb(Tox *tox, Tox_Group_Number group_number, void *user_data);
|
|
|
|
/**
|
|
* 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.
|
|
*/
|
|
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.
|
|
*/
|
|
typedef enum Tox_Group_Join_Fail {
|
|
|
|
/**
|
|
* The group peer limit has been reached.
|
|
*/
|
|
TOX_GROUP_JOIN_FAIL_PEER_LIMIT,
|
|
|
|
/**
|
|
* You have supplied an invalid password.
|
|
*/
|
|
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.
|
|
*/
|
|
TOX_GROUP_JOIN_FAIL_UNKNOWN,
|
|
|
|
} 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 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);
|
|
|
|
/**
|
|
* Set the callback for the `group_join_fail` event. Pass NULL to unset.
|
|
*
|
|
* This event is triggered when the client fails to join a group.
|
|
*/
|
|
void tox_callback_group_join_fail(Tox *tox, tox_group_join_fail_cb *callback);
|
|
|
|
/*******************************************************************************
|
|
*
|
|
* :: Group chat Founder controls
|
|
*
|
|
******************************************************************************/
|
|
|
|
typedef enum Tox_Err_Group_Set_Password {
|
|
|
|
/**
|
|
* The function returned successfully.
|
|
*/
|
|
TOX_ERR_GROUP_SET_PASSWORD_OK,
|
|
|
|
/**
|
|
* The group number passed did not designate a valid group.
|
|
*/
|
|
TOX_ERR_GROUP_SET_PASSWORD_GROUP_NOT_FOUND,
|
|
|
|
/**
|
|
* The caller does not have the required permissions to set the password.
|
|
*/
|
|
TOX_ERR_GROUP_SET_PASSWORD_PERMISSIONS,
|
|
|
|
/**
|
|
* Password length exceeded TOX_GROUP_MAX_PASSWORD_SIZE.
|
|
*/
|
|
TOX_ERR_GROUP_SET_PASSWORD_TOO_LONG,
|
|
|
|
/**
|
|
* The packet failed to send.
|
|
*/
|
|
TOX_ERR_GROUP_SET_PASSWORD_FAIL_SEND,
|
|
|
|
/**
|
|
* The function failed to allocate enough memory for the operation.
|
|
*/
|
|
TOX_ERR_GROUP_SET_PASSWORD_MALLOC,
|
|
|
|
/**
|
|
* The group is disconnected.
|
|
*/
|
|
TOX_ERR_GROUP_SET_PASSWORD_DISCONNECTED,
|
|
|
|
} Tox_Err_Group_Set_Password;
|
|
|
|
const char *tox_err_group_set_password_to_string(Tox_Err_Group_Set_Password value);
|
|
|
|
/**
|
|
* 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.
|
|
*
|
|
* @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.
|
|
*/
|
|
bool tox_group_set_password(
|
|
Tox *tox, Tox_Group_Number group_number,
|
|
const uint8_t password[], size_t length,
|
|
Tox_Err_Group_Set_Password *error);
|
|
|
|
typedef enum Tox_Err_Group_Set_Topic_Lock {
|
|
|
|
/**
|
|
* The function returned successfully.
|
|
*/
|
|
TOX_ERR_GROUP_SET_TOPIC_LOCK_OK,
|
|
|
|
/**
|
|
* The group number passed did not designate a valid group.
|
|
*/
|
|
TOX_ERR_GROUP_SET_TOPIC_LOCK_GROUP_NOT_FOUND,
|
|
|
|
/**
|
|
* Tox_Group_Topic_Lock is an invalid type.
|
|
*/
|
|
TOX_ERR_GROUP_SET_TOPIC_LOCK_INVALID,
|
|
|
|
/**
|
|
* The caller does not have the required permissions to set the 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.
|
|
*/
|
|
TOX_ERR_GROUP_SET_TOPIC_LOCK_FAIL_SET,
|
|
|
|
/**
|
|
* The packet failed to send.
|
|
*/
|
|
TOX_ERR_GROUP_SET_TOPIC_LOCK_FAIL_SEND,
|
|
|
|
/**
|
|
* The group is disconnected.
|
|
*/
|
|
TOX_ERR_GROUP_SET_TOPIC_LOCK_DISCONNECTED,
|
|
|
|
} Tox_Err_Group_Set_Topic_Lock;
|
|
|
|
const char *tox_err_group_set_topic_lock_to_string(Tox_Err_Group_Set_Topic_Lock value);
|
|
|
|
/**
|
|
* 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.
|
|
*
|
|
* 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 topic_lock The state we wish to set the topic lock to.
|
|
*
|
|
* @return true on success.
|
|
*/
|
|
bool tox_group_set_topic_lock(Tox *tox, Tox_Group_Number group_number, Tox_Group_Topic_Lock topic_lock,
|
|
Tox_Err_Group_Set_Topic_Lock *error);
|
|
|
|
typedef enum Tox_Err_Group_Set_Voice_State {
|
|
|
|
/**
|
|
* The function returned successfully.
|
|
*/
|
|
TOX_ERR_GROUP_SET_VOICE_STATE_OK,
|
|
|
|
/**
|
|
* The group number passed did not designate a valid group.
|
|
*/
|
|
TOX_ERR_GROUP_SET_VOICE_STATE_GROUP_NOT_FOUND,
|
|
|
|
/**
|
|
* 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.
|
|
*/
|
|
TOX_ERR_GROUP_SET_VOICE_STATE_FAIL_SET,
|
|
|
|
/**
|
|
* The packet failed to send.
|
|
*/
|
|
TOX_ERR_GROUP_SET_VOICE_STATE_FAIL_SEND,
|
|
|
|
/**
|
|
* The group is disconnected.
|
|
*/
|
|
TOX_ERR_GROUP_SET_VOICE_STATE_DISCONNECTED,
|
|
|
|
} Tox_Err_Group_Set_Voice_State;
|
|
|
|
const char *tox_err_group_set_voice_state_to_string(Tox_Err_Group_Set_Voice_State value);
|
|
|
|
/**
|
|
* 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.
|
|
*
|
|
* 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 voice_state The voice state we wish to set the group to.
|
|
*
|
|
* @return true on success.
|
|
*/
|
|
bool tox_group_set_voice_state(Tox *tox, Tox_Group_Number group_number, Tox_Group_Voice_State voice_state,
|
|
Tox_Err_Group_Set_Voice_State *error);
|
|
|
|
typedef enum Tox_Err_Group_Set_Privacy_State {
|
|
|
|
/**
|
|
* The function returned successfully.
|
|
*/
|
|
TOX_ERR_GROUP_SET_PRIVACY_STATE_OK,
|
|
|
|
/**
|
|
* The group number passed did not designate a valid group.
|
|
*/
|
|
TOX_ERR_GROUP_SET_PRIVACY_STATE_GROUP_NOT_FOUND,
|
|
|
|
/**
|
|
* 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.
|
|
*/
|
|
TOX_ERR_GROUP_SET_PRIVACY_STATE_FAIL_SET,
|
|
|
|
/**
|
|
* The packet failed to send.
|
|
*/
|
|
TOX_ERR_GROUP_SET_PRIVACY_STATE_FAIL_SEND,
|
|
|
|
/**
|
|
* The group is disconnected.
|
|
*/
|
|
TOX_ERR_GROUP_SET_PRIVACY_STATE_DISCONNECTED,
|
|
|
|
} Tox_Err_Group_Set_Privacy_State;
|
|
|
|
const char *tox_err_group_set_privacy_state_to_string(Tox_Err_Group_Set_Privacy_State value);
|
|
|
|
/**
|
|
* 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.
|
|
*
|
|
* 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 privacy_state The privacy state we wish to set the group to.
|
|
*
|
|
* @return true on success.
|
|
*/
|
|
bool tox_group_set_privacy_state(Tox *tox, Tox_Group_Number group_number, Tox_Group_Privacy_State privacy_state,
|
|
Tox_Err_Group_Set_Privacy_State *error);
|
|
|
|
typedef enum Tox_Err_Group_Set_Peer_Limit {
|
|
|
|
/**
|
|
* The function returned successfully.
|
|
*/
|
|
TOX_ERR_GROUP_SET_PEER_LIMIT_OK,
|
|
|
|
/**
|
|
* The group number passed did not designate a valid group.
|
|
*/
|
|
TOX_ERR_GROUP_SET_PEER_LIMIT_GROUP_NOT_FOUND,
|
|
|
|
/**
|
|
* The caller does not have the required permissions to set the 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.
|
|
*/
|
|
TOX_ERR_GROUP_SET_PEER_LIMIT_FAIL_SET,
|
|
|
|
/**
|
|
* The packet failed to send.
|
|
*/
|
|
TOX_ERR_GROUP_SET_PEER_LIMIT_FAIL_SEND,
|
|
|
|
/**
|
|
* The group is disconnected.
|
|
*/
|
|
TOX_ERR_GROUP_SET_PEER_LIMIT_DISCONNECTED,
|
|
|
|
} Tox_Err_Group_Set_Peer_Limit;
|
|
|
|
const char *tox_err_group_set_peer_limit_to_string(Tox_Err_Group_Set_Peer_Limit value);
|
|
|
|
/**
|
|
* 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.
|
|
*
|
|
* @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.
|
|
*/
|
|
bool tox_group_set_peer_limit(Tox *tox, Tox_Group_Number group_number, uint16_t peer_limit,
|
|
Tox_Err_Group_Set_Peer_Limit *error);
|
|
|
|
/*******************************************************************************
|
|
*
|
|
* :: Group chat moderation controls
|
|
*
|
|
******************************************************************************/
|
|
|
|
typedef enum Tox_Err_Group_Set_Ignore {
|
|
|
|
/**
|
|
* The function returned successfully.
|
|
*/
|
|
TOX_ERR_GROUP_SET_IGNORE_OK,
|
|
|
|
/**
|
|
* The group number passed did not designate a valid group.
|
|
*/
|
|
TOX_ERR_GROUP_SET_IGNORE_GROUP_NOT_FOUND,
|
|
|
|
/**
|
|
* The ID passed did not designate a valid peer.
|
|
*/
|
|
TOX_ERR_GROUP_SET_IGNORE_PEER_NOT_FOUND,
|
|
|
|
/**
|
|
* The caller attempted to ignore himself.
|
|
*/
|
|
TOX_ERR_GROUP_SET_IGNORE_SELF,
|
|
|
|
} Tox_Err_Group_Set_Ignore;
|
|
|
|
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 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.
|
|
*
|
|
* @return true on success.
|
|
*/
|
|
bool tox_group_set_ignore(Tox *tox, Tox_Group_Number group_number, Tox_Group_Peer_Number peer_id, bool ignore,
|
|
Tox_Err_Group_Set_Ignore *error);
|
|
|
|
typedef enum Tox_Err_Group_Set_Role {
|
|
|
|
/**
|
|
* The function returned successfully.
|
|
*/
|
|
TOX_ERR_GROUP_SET_ROLE_OK,
|
|
|
|
/**
|
|
* The group number passed did not designate a valid group.
|
|
*/
|
|
TOX_ERR_GROUP_SET_ROLE_GROUP_NOT_FOUND,
|
|
|
|
/**
|
|
* The ID passed did not designate a valid peer. Note: you cannot set your
|
|
* own role.
|
|
*/
|
|
TOX_ERR_GROUP_SET_ROLE_PEER_NOT_FOUND,
|
|
|
|
/**
|
|
* The caller does not have the required permissions for this action.
|
|
*/
|
|
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.
|
|
*/
|
|
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.
|
|
*/
|
|
TOX_ERR_GROUP_SET_ROLE_FAIL_ACTION,
|
|
|
|
/**
|
|
* The caller attempted to set their own role.
|
|
*/
|
|
TOX_ERR_GROUP_SET_ROLE_SELF,
|
|
|
|
} Tox_Err_Group_Set_Role;
|
|
|
|
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.
|
|
*
|
|
* 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 peer_id The ID of the peer whose role you wish to set.
|
|
* @param role The role you wish to set the peer to.
|
|
*
|
|
* @return true on success.
|
|
*/
|
|
bool tox_group_set_role(Tox *tox, Tox_Group_Number group_number, Tox_Group_Peer_Number peer_id, Tox_Group_Role role,
|
|
Tox_Err_Group_Set_Role *error);
|
|
|
|
typedef enum Tox_Err_Group_Kick_Peer {
|
|
|
|
/**
|
|
* The function returned successfully.
|
|
*/
|
|
TOX_ERR_GROUP_KICK_PEER_OK,
|
|
|
|
/**
|
|
* The group number passed did not designate a valid group.
|
|
*/
|
|
TOX_ERR_GROUP_KICK_PEER_GROUP_NOT_FOUND,
|
|
|
|
/**
|
|
* The ID passed did not designate a valid peer.
|
|
*/
|
|
TOX_ERR_GROUP_KICK_PEER_PEER_NOT_FOUND,
|
|
|
|
/**
|
|
* The caller does not have the required permissions for this action.
|
|
*/
|
|
TOX_ERR_GROUP_KICK_PEER_PERMISSIONS,
|
|
|
|
/**
|
|
* The peer could not be kicked from the group.
|
|
*/
|
|
TOX_ERR_GROUP_KICK_PEER_FAIL_ACTION,
|
|
|
|
/**
|
|
* The packet failed to send.
|
|
*/
|
|
TOX_ERR_GROUP_KICK_PEER_FAIL_SEND,
|
|
|
|
/**
|
|
* The caller attempted to set their own role.
|
|
*/
|
|
TOX_ERR_GROUP_KICK_PEER_SELF,
|
|
|
|
} Tox_Err_Group_Kick_Peer;
|
|
|
|
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.
|
|
*
|
|
* 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.
|
|
*
|
|
* @return true on success.
|
|
*/
|
|
bool tox_group_kick_peer(const Tox *tox, Tox_Group_Number group_number, Tox_Group_Peer_Number peer_id,
|
|
Tox_Err_Group_Kick_Peer *error);
|
|
|
|
/**
|
|
* Represents moderation events. These should be used with the
|
|
* `group_moderation` event.
|
|
*/
|
|
typedef enum Tox_Group_Mod_Event {
|
|
|
|
/**
|
|
* A peer has been kicked from the group.
|
|
*/
|
|
TOX_GROUP_MOD_EVENT_KICK,
|
|
|
|
/**
|
|
* A peer as been given the observer role.
|
|
*/
|
|
TOX_GROUP_MOD_EVENT_OBSERVER,
|
|
|
|
/**
|
|
* A peer has been given the user role.
|
|
*/
|
|
TOX_GROUP_MOD_EVENT_USER,
|
|
|
|
/**
|
|
* A peer has been given the moderator role.
|
|
*/
|
|
TOX_GROUP_MOD_EVENT_MODERATOR,
|
|
|
|
} Tox_Group_Mod_Event;
|
|
|
|
const char *tox_group_mod_event_to_string(Tox_Group_Mod_Event value);
|
|
|
|
/**
|
|
* @param group_number The group number of the group the event is intended for.
|
|
* @param source_peer_id The ID of the peer who initiated the event.
|
|
* @param target_peer_id The ID of the peer who is the target of the event.
|
|
* @param mod_type The type of event.
|
|
*/
|
|
typedef void tox_group_moderation_cb(
|
|
Tox *tox, Tox_Group_Number group_number, Tox_Group_Peer_Number source_peer_id, Tox_Group_Peer_Number target_peer_id,
|
|
Tox_Group_Mod_Event mod_type, void *user_data);
|
|
|
|
/**
|
|
* 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).
|
|
*
|
|
* 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);
|
|
|
|
/** @} */
|
|
|
|
/** @} */
|
|
|
|
#ifdef __cplusplus
|
|
} /* extern "C" */
|
|
#endif
|
|
|
|
//!TOKSTYLE-
|
|
#ifndef DOXYGEN_IGNORE
|
|
|
|
typedef Tox_Err_Options_New TOX_ERR_OPTIONS_NEW;
|
|
typedef Tox_Err_New TOX_ERR_NEW;
|
|
typedef Tox_Err_Bootstrap TOX_ERR_BOOTSTRAP;
|
|
typedef Tox_Err_Set_Info TOX_ERR_SET_INFO;
|
|
typedef Tox_Err_Friend_Add TOX_ERR_FRIEND_ADD;
|
|
typedef Tox_Err_Friend_Delete TOX_ERR_FRIEND_DELETE;
|
|
typedef Tox_Err_Friend_By_Public_Key TOX_ERR_FRIEND_BY_PUBLIC_KEY;
|
|
typedef Tox_Err_Friend_Get_Public_Key TOX_ERR_FRIEND_GET_PUBLIC_KEY;
|
|
typedef Tox_Err_Friend_Get_Last_Online TOX_ERR_FRIEND_GET_LAST_ONLINE;
|
|
typedef Tox_Err_Friend_Query TOX_ERR_FRIEND_QUERY;
|
|
typedef Tox_Err_Set_Typing TOX_ERR_SET_TYPING;
|
|
typedef Tox_Err_Friend_Send_Message TOX_ERR_FRIEND_SEND_MESSAGE;
|
|
typedef Tox_Err_File_Control TOX_ERR_FILE_CONTROL;
|
|
typedef Tox_Err_File_Seek TOX_ERR_FILE_SEEK;
|
|
typedef Tox_Err_File_Get TOX_ERR_FILE_GET;
|
|
typedef Tox_Err_File_Send TOX_ERR_FILE_SEND;
|
|
typedef Tox_Err_File_Send_Chunk TOX_ERR_FILE_SEND_CHUNK;
|
|
typedef Tox_Err_Conference_New TOX_ERR_CONFERENCE_NEW;
|
|
typedef Tox_Err_Conference_Delete TOX_ERR_CONFERENCE_DELETE;
|
|
typedef Tox_Err_Conference_Peer_Query TOX_ERR_CONFERENCE_PEER_QUERY;
|
|
typedef Tox_Err_Conference_Set_Max_Offline TOX_ERR_CONFERENCE_SET_MAX_OFFLINE;
|
|
typedef Tox_Err_Conference_By_Id TOX_ERR_CONFERENCE_BY_ID;
|
|
typedef Tox_Err_Conference_By_Uid TOX_ERR_CONFERENCE_BY_UID;
|
|
typedef Tox_Err_Conference_Invite TOX_ERR_CONFERENCE_INVITE;
|
|
typedef Tox_Err_Conference_Join TOX_ERR_CONFERENCE_JOIN;
|
|
typedef Tox_Err_Conference_Send_Message TOX_ERR_CONFERENCE_SEND_MESSAGE;
|
|
typedef Tox_Err_Conference_Title TOX_ERR_CONFERENCE_TITLE;
|
|
typedef Tox_Err_Conference_Get_Type TOX_ERR_CONFERENCE_GET_TYPE;
|
|
typedef Tox_Err_Friend_Custom_Packet TOX_ERR_FRIEND_CUSTOM_PACKET;
|
|
typedef Tox_Err_Get_Port TOX_ERR_GET_PORT;
|
|
typedef Tox_User_Status TOX_USER_STATUS;
|
|
typedef Tox_Message_Type TOX_MESSAGE_TYPE;
|
|
typedef Tox_Proxy_Type TOX_PROXY_TYPE;
|
|
typedef Tox_Savedata_Type TOX_SAVEDATA_TYPE;
|
|
typedef Tox_Log_Level TOX_LOG_LEVEL;
|
|
typedef Tox_Connection TOX_CONNECTION;
|
|
typedef Tox_File_Control TOX_FILE_CONTROL;
|
|
typedef Tox_Conference_Type TOX_CONFERENCE_TYPE;
|
|
typedef enum Tox_File_Kind TOX_FILE_KIND;
|
|
|
|
#endif
|
|
//!TOKSTYLE+
|
|
|
|
#endif /* C_TOXCORE_TOXCORE_TOX_H */
|