summaryrefslogtreecommitdiff
path: root/protocols/Tox/include/tox.h
diff options
context:
space:
mode:
authorAlexander Lantsev <aunsane@gmail.com>2015-04-10 12:01:55 +0000
committerAlexander Lantsev <aunsane@gmail.com>2015-04-10 12:01:55 +0000
commit78f97fe198286a120370f6c56921205191f986b0 (patch)
tree96629174df34f22697c5eaad7cfe102f8f7fd5eb /protocols/Tox/include/tox.h
parentbff791f9bd1828c66e1462a4a3f86a800b58ad13 (diff)
Tox:
- switched to new api - updated tox core git-svn-id: http://svn.miranda-ng.org/main/trunk@12726 1316c22d-e87f-b044-9b9b-93d7a3e3ba9c
Diffstat (limited to 'protocols/Tox/include/tox.h')
-rw-r--r--protocols/Tox/include/tox.h2344
1 files changed, 1706 insertions, 638 deletions
diff --git a/protocols/Tox/include/tox.h b/protocols/Tox/include/tox.h
index ee678cc1f5..034b1d786f 100644
--- a/protocols/Tox/include/tox.h
+++ b/protocols/Tox/include/tox.h
@@ -24,928 +24,1996 @@
#ifndef TOX_H
#define TOX_H
+#include <stdbool.h>
+#include <stddef.h>
#include <stdint.h>
-
#ifdef __cplusplus
extern "C" {
#endif
-#define TOX_MAX_NAME_LENGTH 128
+/** \page core 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.
+ */
-/* Maximum length of single messages after which they should be split. */
-#define TOX_MAX_MESSAGE_LENGTH 1368
-#define TOX_MAX_STATUSMESSAGE_LENGTH 1007
-#define TOX_MAX_FRIENDREQUEST_LENGTH 1016
+/** \subsection 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.
+ */
-#define TOX_PUBLIC_KEY_SIZE 32
-/* TODO: remove */
-#define TOX_CLIENT_ID_SIZE TOX_PUBLIC_KEY_SIZE
+/** \subsection 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_iteration 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 will have become invalid, and the call to
+ * tox_self_get_name may cause undefined behaviour.
+ */
-#define TOX_AVATAR_MAX_DATA_LENGTH 16384
-#define TOX_HASH_LENGTH /*crypto_hash_sha256_BYTES*/ 32
+#ifndef TOX_DEFINED
+#define TOX_DEFINED
+/**
+ * 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
-#define TOX_FRIEND_ADDRESS_SIZE (TOX_PUBLIC_KEY_SIZE + sizeof(uint32_t) + sizeof(uint16_t))
-#define TOX_ENABLE_IPV6_DEFAULT 1
+/*******************************************************************************
+ *
+ * :: API version
+ *
+ ******************************************************************************/
-#define TOX_ENC_SAVE_MAGIC_NUMBER "toxEsave"
-#define TOX_ENC_SAVE_MAGIC_LENGTH 8
-/* Errors for m_addfriend
- * FAERR - Friend Add Error
+/**
+ * The major version number. Incremented when the API or ABI changes in an
+ * incompatible way.
*/
-enum {
- TOX_FAERR_TOOLONG = -1,
- TOX_FAERR_NOMESSAGE = -2,
- TOX_FAERR_OWNKEY = -3,
- TOX_FAERR_ALREADYSENT = -4,
- TOX_FAERR_UNKNOWN = -5,
- TOX_FAERR_BADCHECKSUM = -6,
- TOX_FAERR_SETNEWNOSPAM = -7,
- TOX_FAERR_NOMEM = -8
-};
+#define TOX_VERSION_MAJOR 0u
+/**
+ * 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 0u
+/**
+ * The patch or revision number. Incremented when bugfixes are applied without
+ * changing any functionality or API or ABI.
+ */
+#define TOX_VERSION_PATCH 0u
-/* USERSTATUS -
- * Represents userstatuses someone can have.
+/**
+ * A macro to check at preprocessing time whether the client code is compatible
+ * with the installed version of Tox.
*/
-typedef enum {
- TOX_USERSTATUS_NONE,
- TOX_USERSTATUS_AWAY,
- TOX_USERSTATUS_BUSY,
- TOX_USERSTATUS_INVALID
-}
-TOX_USERSTATUS;
+#define TOX_VERSION_IS_API_COMPATIBLE(MAJOR, MINOR, PATCH) \
+ (TOX_VERSION_MAJOR == MAJOR && \
+ (TOX_VERSION_MINOR > MINOR || \
+ (TOX_VERSION_MINOR == MINOR && \
+ TOX_VERSION_PATCH >= PATCH)))
+
+/**
+ * A macro to make compilation fail if the client code is not compatible with
+ * the installed version of Tox.
+ */
+#define TOX_VERSION_REQUIRE(MAJOR, MINOR, PATCH) \
+ typedef char tox_required_version[TOX_IS_COMPATIBLE(MAJOR, MINOR, PATCH) ? 1 : -1]
-/* AVATAR_FORMAT -
- * Data formats for user avatar images
+/**
+ * Return the major version number of the library. Can be used to display the
+ * Tox library version or to check whether the client is compatible with the
+ * dynamically linked version of Tox.
*/
-typedef enum {
- TOX_AVATAR_FORMAT_NONE = 0,
- TOX_AVATAR_FORMAT_PNG
-}
-TOX_AVATAR_FORMAT;
+uint32_t tox_version_major(void);
+
+/**
+ * Return the minor version number of the library.
+ */
+uint32_t tox_version_minor(void);
+
+/**
+ * Return the patch number of the library.
+ */
+uint32_t tox_version_patch(void);
+
+/**
+ * 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);
+
+/**
+ * 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)
-#ifndef __TOX_DEFINED__
-#define __TOX_DEFINED__
-typedef struct Tox Tox;
-#endif
-/* NOTE: Strings in Tox are all UTF-8, (This means that there is no terminating NULL character.)
+/*******************************************************************************
*
- * The exact buffer you send will be received at the other end without modification.
+ * :: Numeric constants
*
- * Do not treat Tox strings as C strings.
+ ******************************************************************************/
+
+
+/**
+ * The size of a Tox Public Key in bytes.
*/
+#define TOX_PUBLIC_KEY_SIZE 32
-/* return TOX_FRIEND_ADDRESS_SIZE byte address to give to others.
- * format: [public_key (32 bytes)][nospam number (4 bytes)][checksum (2 bytes)]
+/**
+ * The size of a Tox Secret Key in bytes.
*/
-void tox_get_address(const Tox *tox, uint8_t *address);
+#define TOX_SECRET_KEY_SIZE 32
-/* Add a friend.
- * Set the data that will be sent along with friend request.
- * address is the address of the friend (returned by getaddress of the friend you wish to add) it must be TOX_FRIEND_ADDRESS_SIZE bytes. TODO: add checksum.
- * data is the data and length is the length (maximum length of data is TOX_MAX_FRIENDREQUEST_LENGTH).
+/**
+ * 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)].
*
- * return the friend number if success.
- * return TOX_FAERR_TOOLONG if message length is too long.
- * return TOX_FAERR_NOMESSAGE if no message (message length must be >= 1 byte).
- * return TOX_FAERR_OWNKEY if user's own key.
- * return TOX_FAERR_ALREADYSENT if friend request already sent or already a friend.
- * return TOX_FAERR_UNKNOWN for unknown error.
- * return TOX_FAERR_BADCHECKSUM if bad checksum in address.
- * return TOX_FAERR_SETNEWNOSPAM if the friend was already there but the nospam was different.
- * (the nospam for that friend was set to the new one).
- * return TOX_FAERR_NOMEM if increasing the friend list size fails.
+ * 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.
*/
-int32_t tox_add_friend(Tox *tox, const uint8_t *address, const uint8_t *data, uint16_t length);
+#define TOX_ADDRESS_SIZE (TOX_PUBLIC_KEY_SIZE + sizeof(uint32_t) + sizeof(uint16_t))
+/**
+ * Maximum length of a nickname in bytes.
+ */
+#define TOX_MAX_NAME_LENGTH 128
-/* Add a friend without sending a friendrequest.
- * return the friend number if success.
- * return -1 if failure.
+/**
+ * Maximum length of a status message in bytes.
*/
-int32_t tox_add_friend_norequest(Tox *tox, const uint8_t *public_key);
+#define TOX_MAX_STATUS_MESSAGE_LENGTH 1007
-/* return the friend number associated to that client id.
- return -1 if no such friend */
-int32_t tox_get_friend_number(const Tox *tox, const uint8_t *public_key);
+/**
+ * Maximum length of a friend request message in bytes.
+ */
+#define TOX_MAX_FRIEND_REQUEST_LENGTH 1016
-/* Copies the public key associated to that friend id into public_key buffer.
- * Make sure that public_key is of size TOX_PUBLIC_KEY_SIZE.
- * return 0 if success.
- * return -1 if failure.
+/**
+ * Maximum length of a single message after which it should be split.
*/
-int tox_get_client_id(const Tox *tox, int32_t friendnumber, uint8_t *public_key);
+#define TOX_MAX_MESSAGE_LENGTH 1372
-/* Remove a friend.
- *
- * return 0 if success.
- * return -1 if failure.
+/**
+ * Maximum size of custom packets. TODO: should be LENGTH?
*/
-int tox_del_friend(Tox *tox, int32_t friendnumber);
+#define TOX_MAX_CUSTOM_PACKET_SIZE 1373
-/* Checks friend's connecting status.
- *
- * return 1 if friend is connected to us (Online).
- * return 0 if friend is not connected to us (Offline).
- * return -1 on failure.
+/**
+ * The number of bytes in a hash generated by tox_hash.
*/
-int tox_get_friend_connection_status(const Tox *tox, int32_t friendnumber);
+#define TOX_HASH_LENGTH /*crypto_hash_sha256_BYTES*/ 32
-/* Checks if there exists a friend with given friendnumber.
+/**
+ * The number of bytes in a file id.
+ */
+#define TOX_FILE_ID_LENGTH 32
+
+/**
+ * Maximum file name length for file tran.
+ */
+#define TOX_MAX_FILENAME_LENGTH 255
+
+/*******************************************************************************
*
- * return 1 if friend exists.
- * return 0 if friend doesn't exist.
+ * :: Global enumerations
+ *
+ ******************************************************************************/
+
+
+/**
+ * Represents the possible statuses a client can have.
*/
-int tox_friend_exists(const Tox *tox, int32_t friendnumber);
+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;
-/* Send a text chat message to an online friend.
+/**
+ * Represents message types for friend messages and group chat
+ * 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;
+
+/*******************************************************************************
*
- * return the message id if packet was successfully put into the send queue.
- * return 0 if it was not.
+ * :: Startup options
*
- * maximum length of messages is TOX_MAX_MESSAGE_LENGTH, your client must split larger messages
- * or else sending them will not work. No the core will not split messages for you because that
- * requires me to parse UTF-8.
+ ******************************************************************************/
+
+
+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;
+
+
+/**
+ * This struct contains all the startup options for Tox. You can either allocate
+ * this object yourself, and pass it to tox_options_default, or call
+ * tox_options_new to get a new default options object.
+ */
+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.
+ * Disabling UDP support is necessary when using anonymous proxies or Tor.
+ */
+ bool udp_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 255 characters, and be in a NUL-terminated C string format
+ * (255 chars + 1 NUL byte).
+ *
+ * This member is ignored (it can be NULL) if proxy_enabled is false.
+ */
+ 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_enabled is false.
+ */
+ 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;
+};
+
+
+/**
+ * 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.
*
- * You will want to retain the return value, it will be passed to your read_receipt callback
- * if one is received.
+ * @param options An options object to be filled with default options.
*/
-uint32_t tox_send_message(Tox *tox, int32_t friendnumber, const uint8_t *message, uint32_t length);
+void tox_options_default(struct Tox_Options *options);
-/* Send an action to an online friend.
+
+typedef enum TOX_ERR_OPTIONS_NEW {
+ 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;
+
+/**
+ * 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.
*
- * return the message id if packet was successfully put into the send queue.
- * return 0 if it was not.
+ * Objects returned from this function must be freed using the tox_options_free
+ * function.
*
- * maximum length of actions is TOX_MAX_MESSAGE_LENGTH, your client must split larger actions
- * or else sending them will not work. No the core will not split actions for you because that
- * requires me to parse UTF-8.
+ * @return A new Tox_Options object with default options or NULL on failure.
+ */
+struct Tox_Options *tox_options_new(TOX_ERR_OPTIONS_NEW *error);
+
+
+/**
+ * Releases all resources associated with an options objects.
*
- * You will want to retain the return value, it will be passed to your read_receipt callback
- * if one is received.
+ * Passing a pointer that was not returned by tox_options_new results in
+ * undefined behaviour.
*/
-uint32_t tox_send_action(Tox *tox, int32_t friendnumber, const uint8_t *action, uint32_t length);
+void tox_options_free(struct Tox_Options *options);
-/* Set our nickname.
- * name must be a string of maximum MAX_NAME_LENGTH length.
- * length must be at least 1 byte.
- * length is the length of name.
+
+/*******************************************************************************
+ *
+ * :: Creation and destruction
+ *
+ ******************************************************************************/
+
+
+typedef enum TOX_ERR_NEW {
+ TOX_ERR_NEW_OK,
+ 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 host 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;
+
+
+/**
+ * @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.
*
- * return 0 if success.
- * return -1 if failure.
+ * If the data parameter is not NULL, this function will load the Tox instance
+ * from a byte array previously filled by tox_get_savedata.
+ *
+ * If loading failed or succeeded only partially, the new or partially loaded
+ * instance is returned and an error code is set.
+ *
+ * @param options An options object as described above. If this parameter is
+ * NULL, the default options are used.
+ * @param data A byte array containing data previously stored by tox_get_savedata.
+ * @param length The length of the byte array data. If this parameter is 0, the
+ * data parameter is ignored.
+ *
+ * @see tox_iteration for the event loop.
+ */
+Tox *tox_new(const struct Tox_Options *options, const uint8_t *data, size_t length, TOX_ERR_NEW *error);
+
+
+/**
+ * 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.
*/
-int tox_set_name(Tox *tox, const uint8_t *name, uint16_t length);
+void tox_kill(Tox *tox);
+
-/*
- * Get your nickname.
- * m - The messenger context to use.
- * name - needs to be a valid memory location with a size of at least MAX_NAME_LENGTH (128) bytes.
+/**
+ * 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.
*
- * return length of name.
- * return 0 on error.
+ * @see threading for concurrency implications.
*/
-uint16_t tox_get_self_name(const Tox *tox, uint8_t *name);
+size_t tox_get_savedata_size(const Tox *tox);
-/* Get name of friendnumber and put it in name.
- * name needs to be a valid memory location with a size of at least MAX_NAME_LENGTH (128) bytes.
+/**
+ * Store all information associated with the tox instance to a byte array.
*
- * return length of name if success.
- * return -1 if failure.
+ * @param data 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.
*/
-int tox_get_name(const Tox *tox, int32_t friendnumber, uint8_t *name);
+void tox_get_savedata(const Tox *tox, uint8_t *data);
+
+
+/*******************************************************************************
+ *
+ * :: Connection lifecycle and event loop
+ *
+ ******************************************************************************/
-/* returns the length of name on success.
- * returns -1 on failure.
+
+typedef enum TOX_ERR_BOOTSTRAP {
+ TOX_ERR_BOOTSTRAP_OK,
+ TOX_ERR_BOOTSTRAP_NULL,
+ /**
+ * The host could not be resolved to an IP address, or the IP address
+ * passed was invalid.
+ */
+ 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;
+
+/**
+ * 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 and TCP at the
+ * same time.
+ *
+ * Tox will use the node as a TCP relay in case Tox_Options.udp_enabled was
+ * false, and also to connect to friends that are in TCP-only mode. Tox will
+ * also use the TCP connection when NAT hole punching is slow, and later switch
+ * to UDP if hole punching succeeds.
+ *
+ * @param host The hostname or IP address (IPv4 or IPv6) of the node.
+ * @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.
*/
-int tox_get_name_size(const Tox *tox, int32_t friendnumber);
-int tox_get_self_name_size(const Tox *tox);
+bool tox_bootstrap(Tox *tox, const char *host, uint16_t port, const uint8_t *public_key, TOX_ERR_BOOTSTRAP *error);
+
-/* Set our user status.
+/**
+ * Adds additional host:port pair as TCP relay.
*
- * userstatus must be one of TOX_USERSTATUS values.
- * max length of the status is TOX_MAX_STATUSMESSAGE_LENGTH.
+ * 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.
*
- * returns 0 on success.
- * returns -1 on failure.
+ * @param host The hostname or IP address (IPv4 or IPv6) of the TCP relay.
+ * @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.
*/
-int tox_set_status_message(Tox *tox, const uint8_t *status, uint16_t length);
-int tox_set_user_status(Tox *tox, uint8_t userstatus);
+bool tox_add_tcp_relay(Tox *tox, const char *host, uint16_t port, const uint8_t *public_key,
+ TOX_ERR_BOOTSTRAP *error);
+
-/* returns the length of status message on success.
- * returns -1 on failure.
+typedef enum TOX_CONNECTION {
+ /**
+ * There is no connection. This instance, or the friend the state change is
+ * about, is now offline.
+ */
+ TOX_CONNECTION_NONE,
+ /**
+ * 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,
+ /**
+ * 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;
+
+
+/**
+ * Return whether we are connected to the DHT. The return value is equal to the
+ * last value received through the `self_connection_status` callback.
*/
-int tox_get_status_message_size(const Tox *tox, int32_t friendnumber);
-int tox_get_self_status_message_size(const Tox *tox);
+TOX_CONNECTION tox_self_get_connection_status(const Tox *tox);
-/* Copy friendnumber's status message into buf, truncating if size is over maxlen.
- * Get the size you need to allocate from m_get_statusmessage_size.
- * The self variant will copy our own status message.
+/**
+ * The function type for the `self_connection_status` callback.
*
- * returns the length of the copied data on success
- * retruns -1 on failure.
+ * @param connection_status Equal to the return value of
+ * tox_self_get_connection_status.
*/
-int tox_get_status_message(const Tox *tox, int32_t friendnumber, uint8_t *buf, uint32_t maxlen);
-int tox_get_self_status_message(const Tox *tox, uint8_t *buf, uint32_t maxlen);
+typedef void tox_self_connection_status_cb(Tox *tox, TOX_CONNECTION connection_status, void *user_data);
-/* return one of TOX_USERSTATUS values.
- * Values unknown to your application should be represented as TOX_USERSTATUS_NONE.
- * As above, the self variant will return our own TOX_USERSTATUS.
- * If friendnumber is invalid, this shall return TOX_USERSTATUS_INVALID.
+/**
+ * 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: how long should a client wait before bootstrapping again?
+ */
+void tox_callback_self_connection_status(Tox *tox, tox_self_connection_status_cb *function, void *user_data);
+
+
+/**
+ * Return the time in milliseconds before tox_iteration() should be called again
+ * for optimal performance.
*/
-uint8_t tox_get_user_status(const Tox *tox, int32_t friendnumber);
-uint8_t tox_get_self_user_status(const Tox *tox);
+uint32_t tox_iteration_interval(const Tox *tox);
-/* returns timestamp of last time friendnumber was seen online, or 0 if never seen.
- * returns -1 on error.
+
+/**
+ * The main loop that needs to be run in intervals of tox_iteration_interval()
+ * milliseconds.
*/
-uint64_t tox_get_last_online(const Tox *tox, int32_t friendnumber);
+void tox_iterate(Tox *tox);
+
-/* Set our typing status for a friend.
- * You are responsible for turning it on or off.
+/*******************************************************************************
*
- * returns 0 on success.
- * returns -1 on failure.
- */
-int tox_set_user_is_typing(Tox *tox, int32_t friendnumber, uint8_t is_typing);
+ * :: Internal client information (Tox address/id)
+ *
+ ******************************************************************************/
-/* Get the typing status of a friend.
+
+/**
+ * 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.
*
- * returns 0 if friend is not typing.
- * returns 1 if friend is typing.
+ * @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.
*/
-uint8_t tox_get_is_typing(const Tox *tox, int32_t friendnumber);
+void tox_self_get_address(const Tox *tox, uint8_t *address);
-/* Return the number of friends in the instance m.
- * You should use this to determine how much memory to allocate
- * for copy_friendlist. */
-uint32_t tox_count_friendlist(const Tox *tox);
-/* Return the number of online friends in the instance m. */
-uint32_t tox_get_num_online_friends(const Tox *tox);
+/**
+ * Set the 4-byte nospam part of the address.
+ *
+ * @param nospam Any 32 bit unsigned integer.
+ */
+void tox_self_set_nospam(Tox *tox, uint32_t nospam);
-/* Copy a list of valid friend IDs into the array out_list.
- * If out_list is NULL, returns 0.
- * Otherwise, returns the number of elements copied.
- * If the array was too small, the contents
- * of out_list will be truncated to list_size. */
-uint32_t tox_get_friendlist(const Tox *tox, int32_t *out_list, uint32_t list_size);
+/**
+ * Get the 4-byte nospam part of the address.
+ */
+uint32_t tox_self_get_nospam(const Tox *tox);
-/* Set the function that will be executed when a friend request is received.
- * Function format is function(Tox *tox, const uint8_t * public_key, const uint8_t * data, uint16_t length, void *userdata)
+/**
+ * Copy the Tox Public Key (long term public key) 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_callback_friend_request(Tox *tox, void (*function)(Tox *tox, const uint8_t *, const uint8_t *, uint16_t,
- void *), void *userdata);
+void tox_self_get_public_key(const Tox *tox, uint8_t *public_key);
-/* Set the function that will be executed when a message from a friend is received.
- * Function format is: function(Tox *tox, int32_t friendnumber, const uint8_t * message, uint16_t length, void *userdata)
+/**
+ * Copy the 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_callback_friend_message(Tox *tox, void (*function)(Tox *tox, int32_t, const uint8_t *, uint16_t, void *),
- void *userdata);
+void tox_self_get_secret_key(const Tox *tox, uint8_t *secret_key);
+
-/* Set the function that will be executed when an action from a friend is received.
- * Function format is: function(Tox *tox, int32_t friendnumber, const uint8_t * action, uint16_t length, void *userdata)
+/*******************************************************************************
+ *
+ * :: User-visible client information (nickname/status)
+ *
+ ******************************************************************************/
+
+
+/**
+ * Common error codes for all functions that set a piece of user-visible
+ * client information.
*/
-void tox_callback_friend_action(Tox *tox, void (*function)(Tox *tox, int32_t, const uint8_t *, uint16_t, void *),
- void *userdata);
+typedef enum TOX_ERR_SET_INFO {
+ TOX_ERR_SET_INFO_OK,
+ TOX_ERR_SET_INFO_NULL,
+ /**
+ * Information length exceeded maximum permissible size.
+ */
+ TOX_ERR_SET_INFO_TOO_LONG
+} TOX_ERR_SET_INFO;
-/* Set the callback for name changes.
- * function(Tox *tox, int32_t friendnumber, const uint8_t *newname, uint16_t length, void *userdata)
- * You are not responsible for freeing newname
+
+/**
+ * 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.
*/
-void tox_callback_name_change(Tox *tox, void (*function)(Tox *tox, int32_t, const uint8_t *, uint16_t, void *),
- void *userdata);
+bool tox_self_set_name(Tox *tox, const uint8_t *name, size_t length, TOX_ERR_SET_INFO *error);
-/* Set the callback for status message changes.
- * function(Tox *tox, int32_t friendnumber, const uint8_t *newstatus, uint16_t length, void *userdata)
- * You are not responsible for freeing newstatus.
+/**
+ * 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.
*/
-void tox_callback_status_message(Tox *tox, void (*function)(Tox *tox, int32_t, const uint8_t *, uint16_t, void *),
- void *userdata);
+size_t tox_self_get_name_size(const Tox *tox);
-/* Set the callback for status type changes.
- * function(Tox *tox, int32_t friendnumber, uint8_t TOX_USERSTATUS, void *userdata)
+/**
+ * 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_callback_user_status(Tox *tox, void (*function)(Tox *tox, int32_t, uint8_t, void *), void *userdata);
+void tox_self_get_name(const Tox *tox, uint8_t *name);
-/* Set the callback for typing changes.
- * function (Tox *tox, int32_t friendnumber, uint8_t is_typing, void *userdata)
+/**
+ * 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.
*/
-void tox_callback_typing_change(Tox *tox, void (*function)(Tox *tox, int32_t, uint8_t, void *), void *userdata);
+bool tox_self_set_status_message(Tox *tox, const uint8_t *status, size_t length, TOX_ERR_SET_INFO *error);
-/* Set the callback for read receipts.
- * function(Tox *tox, int32_t friendnumber, uint32_t receipt, void *userdata)
+/**
+ * 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.
*
- * If you are keeping a record of returns from m_sendmessage;
- * receipt might be one of those values, meaning the message
- * has been received on the other side.
- * Since core doesn't track ids for you, receipt may not correspond to any message.
- * In that case, you should discard it.
+ * @see threading for concurrency implications.
*/
-void tox_callback_read_receipt(Tox *tox, void (*function)(Tox *tox, int32_t, uint32_t, void *), void *userdata);
+size_t tox_self_get_status_message_size(const Tox *tox);
-/* Set the callback for connection status changes.
- * function(Tox *tox, int32_t friendnumber, uint8_t status, void *userdata)
+/**
+ * Write the status message set by tox_self_set_status_message to a byte array.
*
- * Status:
- * 0 -- friend went offline after being previously online
- * 1 -- friend went online
+ * If no status message was set before calling this function, the status is
+ * empty, and this function has no effect.
*
- * NOTE: This callback is not called when adding friends, thus the "after
- * being previously online" part. it's assumed that when adding friends,
- * their connection status is offline.
+ * Call tox_self_status_message_size to find out how much memory to allocate for
+ * the result.
+ *
+ * @param status A valid memory location large enough to hold the status message.
+ * If this parameter is NULL, the function has no effect.
*/
-void tox_callback_connection_status(Tox *tox, void (*function)(Tox *tox, int32_t, uint8_t, void *), void *userdata);
+void tox_self_get_status_message(const Tox *tox, uint8_t *status);
-/**********ADVANCED FUNCTIONS (If you don't know what they do you can safely ignore them.) ************/
+/**
+ * Set the client's user status.
+ *
+ * @param user_status One of the user statuses listed in the enumeration above.
+ */
+void tox_self_set_status(Tox *tox, TOX_USER_STATUS user_status);
-/* Functions to get/set the nospam part of the id.
+/**
+ * Returns the client's user status.
*/
-uint32_t tox_get_nospam(const Tox *tox);
-void tox_set_nospam(Tox *tox, uint32_t nospam);
+TOX_USER_STATUS tox_self_get_status(const Tox *tox);
+
-/* Copy the public and secret key from the Tox object.
- public_key and secret_key must be 32 bytes big.
- if the pointer is NULL, no data will be copied to it.*/
-void tox_get_keys(Tox *tox, uint8_t *public_key, uint8_t *secret_key);
+/*******************************************************************************
+ *
+ * :: Friend list management
+ *
+ ******************************************************************************/
-/* Maximum size of custom packets. */
-#define TOX_MAX_CUSTOM_PACKET_SIZE 1373
-/* Set handlers for custom lossy packets.
- * Set the function to be called when friend sends us a lossy packet starting with byte.
- * byte must be in the 200-254 range.
+typedef enum TOX_ERR_FRIEND_ADD {
+ TOX_ERR_FRIEND_ADD_OK,
+ 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;
+
+/**
+ * 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.
*
- * NOTE: 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.
+ * 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.
*
- * Unless latency is an issue, it is recommended that you use lossless packets instead.
+ * If more than INT32_MAX friends are added, this function causes undefined
+ * behaviour.
*
- * return -1 on failure.
- * return 0 on success.
+ * @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, UINT32_MAX on failure.
*/
-int tox_lossy_packet_registerhandler(Tox *tox, int32_t friendnumber, uint8_t byte,
- int (*packet_handler_callback)(Tox *tox, int32_t friendnumber, const uint8_t *data, uint32_t len, void *object),
- void *object);
+uint32_t tox_friend_add(Tox *tox, const uint8_t *address, const uint8_t *message, size_t length,
+ TOX_ERR_FRIEND_ADD *error);
+
-/* Function to send custom lossy packets.
- * First byte of data must be in the range: 200-254.
+/**
+ * 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.
*
- * return -1 on failure.
- * return 0 on success.
+ * @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, UINT32_MAX on failure.
+ * @see tox_friend_add for a more detailed description of friend numbers.
*/
-int tox_send_lossy_packet(const Tox *tox, int32_t friendnumber, const uint8_t *data, uint32_t length);
+uint32_t tox_friend_add_norequest(Tox *tox, const uint8_t *public_key, TOX_ERR_FRIEND_ADD *error);
+
-/* Set handlers for custom lossless packets.
- * Set the function to be called when friend sends us a lossless packet starting with byte.
- * byte must be in the 160-191 range.
+typedef enum TOX_ERR_FRIEND_DELETE {
+ 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;
+
+/**
+ * Remove a friend from the friend list.
+ * Other friend numbers are unchanged.
+ * The friend_number can be reused by toxcore as a friend number for a new friend.
+ *
+ * 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.
*
- * Lossless packets behave kind of like TCP (reliability, arrive in order.) but with packets instead of a stream.
+ * @friend_number Friend number for the friend to be deleted.
*
- * return -1 on failure.
- * return 0 on success.
+ * @return true on success.
+ * @see tox_friend_add for detailed description of friend numbers.
*/
-int tox_lossless_packet_registerhandler(Tox *tox, int32_t friendnumber, uint8_t byte,
- int (*packet_handler_callback)(Tox *tox, int32_t friendnumber, const uint8_t *data, uint32_t len, void *object),
- void *object);
+bool tox_friend_delete(Tox *tox, uint32_t friend_number, TOX_ERR_FRIEND_DELETE *error);
-/* Function to send custom lossless packets.
- * First byte of data must be in the range: 160-191.
+
+/*******************************************************************************
*
- * return -1 on failure.
- * return 0 on success.
- */
-int tox_send_lossless_packet(const Tox *tox, int32_t friendnumber, const uint8_t *data, uint32_t length);
+ * :: Friend list queries
+ *
+ ******************************************************************************/
+
-/**********GROUP CHAT FUNCTIONS: WARNING Group chats will be rewritten so this might change ************/
+typedef enum TOX_ERR_FRIEND_BY_PUBLIC_KEY {
+ TOX_ERR_FRIEND_BY_PUBLIC_KEY_OK,
+ 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;
-/* Group chat types for tox_callback_group_invite function.
+/**
+ * Return the friend number associated with that Public Key.
*
- * TOX_GROUPCHAT_TYPE_TEXT groupchats must be accepted with the tox_join_groupchat() function.
- * The function to accept TOX_GROUPCHAT_TYPE_AV is in toxav.
+ * @return the friend number on success, UINT32_MAX on failure.
+ * @param public_key A byte array containing the Public Key.
*/
-enum {
- TOX_GROUPCHAT_TYPE_TEXT,
- TOX_GROUPCHAT_TYPE_AV
-};
+uint32_t tox_friend_by_public_key(const Tox *tox, const uint8_t *public_key, TOX_ERR_FRIEND_BY_PUBLIC_KEY *error);
-/* Set the callback for group invites.
- *
- * Function(Tox *tox, int32_t friendnumber, uint8_t type, const uint8_t *data, uint16_t length, void *userdata)
+
+typedef enum TOX_ERR_FRIEND_GET_PUBLIC_KEY {
+ 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;
+
+/**
+ * Copies the Public Key associated with a given friend number to a byte array.
*
- * data of length is what needs to be passed to join_groupchat().
+ * @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.
*
- * for what type means see the enum right above this comment.
+ * @return true on success.
*/
-void tox_callback_group_invite(Tox *tox, void (*function)(Tox *tox, int32_t, uint8_t, const uint8_t *, uint16_t,
- void *), void *userdata);
+bool tox_friend_get_public_key(const Tox *tox, uint32_t friend_number, uint8_t *public_key,
+ TOX_ERR_FRIEND_GET_PUBLIC_KEY *error);
-/* Set the callback for group messages.
+
+/**
+ * Checks if a friend with the given friend number exists and returns true if
+ * it does.
+ */
+bool tox_friend_exists(const Tox *tox, uint32_t friend_number);
+
+typedef enum TOX_ERR_FRIEND_GET_LAST_ONLINE {
+ 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;
+
+/**
+ * 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.
*
- * Function(Tox *tox, int groupnumber, int peernumber, const uint8_t * message, uint16_t length, void *userdata)
+ * @param friend_number The friend number you want to query.
*/
-void tox_callback_group_message(Tox *tox, void (*function)(Tox *tox, int, int, const uint8_t *, uint16_t, void *),
- void *userdata);
+uint64_t tox_friend_get_last_online(const Tox *tox, uint32_t friend_number, TOX_ERR_FRIEND_GET_LAST_ONLINE *error);
-/* Set the callback for group actions.
+/**
+ * Return the number of friends on the friend list.
*
- * Function(Tox *tox, int groupnumber, int peernumber, const uint8_t * action, uint16_t length, void *userdata)
+ * This function can be used to determine how much memory to allocate for
+ * tox_self_get_friend_list.
*/
-void tox_callback_group_action(Tox *tox, void (*function)(Tox *tox, int, int, const uint8_t *, uint16_t, void *),
- void *userdata);
+size_t tox_self_get_friend_list_size(const Tox *tox);
-/* Set callback function for title changes.
+
+/**
+ * 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.
*
- * Function(Tox *tox, int groupnumber, int peernumber, uint8_t * title, uint8_t length, void *userdata)
- * if peernumber == -1, then author is unknown (e.g. initial joining the group)
+ * @param list A memory region with enough space to hold the friend list. If
+ * this parameter is NULL, this function has no effect.
*/
-void tox_callback_group_title(Tox *tox, void (*function)(Tox *tox, int, int, const uint8_t *, uint8_t,
- void *), void *userdata);
+void tox_self_get_friend_list(const Tox *tox, uint32_t *list);
+
-/* Set callback function for peer name list changes.
+
+/*******************************************************************************
+ *
+ * :: Friend-specific state queries (can also be received through callbacks)
*
- * It gets called every time the name list changes(new peer/name, deleted peer)
- * Function(Tox *tox, int groupnumber, int peernumber, TOX_CHAT_CHANGE change, void *userdata)
+ ******************************************************************************/
+
+
+/**
+ * Common error codes for friend state query functions.
*/
-typedef enum {
- TOX_CHAT_CHANGE_PEER_ADD,
- TOX_CHAT_CHANGE_PEER_DEL,
- TOX_CHAT_CHANGE_PEER_NAME,
-} TOX_CHAT_CHANGE;
+typedef enum TOX_ERR_FRIEND_QUERY {
+ 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;
-void tox_callback_group_namelist_change(Tox *tox, void (*function)(Tox *tox, int, int, uint8_t, void *),
- void *userdata);
-/* Creates a new groupchat and puts it in the chats array.
+/**
+ * Return the length of the friend's name. If the friend number is invalid, the
+ * return value is SIZE_MAX.
*
- * return group number on success.
- * return -1 on failure.
+ * The return value is equal to the `length` argument received by the last
+ * `friend_name` callback.
*/
-int tox_add_groupchat(Tox *tox);
+size_t tox_friend_get_name_size(const Tox *tox, uint32_t friend_number, TOX_ERR_FRIEND_QUERY *error);
-/* Delete a groupchat from the chats array.
+/**
+ * Write the name of the friend designated by the given friend number to a byte
+ * array.
*
- * return 0 on success.
- * return -1 if failure.
+ * 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.
*/
-int tox_del_groupchat(Tox *tox, int groupnumber);
+bool tox_friend_get_name(const Tox *tox, uint32_t friend_number, uint8_t *name, TOX_ERR_FRIEND_QUERY *error);
-/* Copy the name of peernumber who is in groupnumber to name.
- * name must be at least TOX_MAX_NAME_LENGTH long.
+/**
+ * The function type for the `friend_name` callback.
*
- * return length of name if success
- * return -1 if failure
+ * @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.
*/
-int tox_group_peername(const Tox *tox, int groupnumber, int peernumber, uint8_t *name);
+typedef void tox_friend_name_cb(Tox *tox, uint32_t friend_number, const uint8_t *name, size_t length, void *user_data);
-/* Copy the public key of peernumber who is in groupnumber to public_key.
- * public_key must be TOX_PUBLIC_KEY_SIZE long.
+/**
+ * Set the callback for the `friend_name` event. Pass NULL to unset.
*
- * returns 0 on success
- * returns -1 on failure
+ * This event is triggered when a friend changes their name.
*/
-int tox_group_peer_pubkey(const Tox *tox, int groupnumber, int peernumber, uint8_t *public_key);
+void tox_callback_friend_name(Tox *tox, tox_friend_name_cb *function, void *user_data);
+
-/* invite friendnumber to groupnumber
- * return 0 on success
- * return -1 on failure
+/**
+ * Return the length of the friend's status message. If the friend number is
+ * invalid, the return value is SIZE_MAX.
*/
-int tox_invite_friend(Tox *tox, int32_t friendnumber, int groupnumber);
+size_t tox_friend_get_status_message_size(const Tox *tox, uint32_t friend_number, TOX_ERR_FRIEND_QUERY *error);
-/* Join a group (you need to have been invited first.) using data of length obtained
- * in the group invite callback.
+/**
+ * Write the name of the friend designated by the given friend number to a byte
+ * array.
*
- * returns group number on success
- * returns -1 on failure.
+ * Call tox_friend_get_name_size to determine the allocation size for the `name`
+ * parameter.
+ *
+ * The data written to `message` is equal to the data received by the last
+ * `friend_status_message` callback.
+ *
+ * @param name A valid memory region large enough to store the friend's name.
*/
-int tox_join_groupchat(Tox *tox, int32_t friendnumber, const uint8_t *data, uint16_t length);
+bool tox_friend_get_status_message(const Tox *tox, uint32_t friend_number, uint8_t *message,
+ TOX_ERR_FRIEND_QUERY *error);
-/* send a group message
- * return 0 on success
- * return -1 on failure
+/**
+ * The function type for the `friend_status_message` callback.
+ *
+ * @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 `message` parameter.
+ * @param length A value equal to the return value of
+ * tox_friend_get_status_message_size.
*/
-int tox_group_message_send(Tox *tox, int groupnumber, const uint8_t *message, uint16_t length);
+typedef void tox_friend_status_message_cb(Tox *tox, uint32_t friend_number, const uint8_t *message, size_t length,
+ void *user_data);
-/* send a group action
- * return 0 on success
- * return -1 on failure
+/**
+ * Set the callback for the `friend_status_message` event. Pass NULL to unset.
+ *
+ * This event is triggered when a friend changes their status message.
*/
-int tox_group_action_send(Tox *tox, int groupnumber, const uint8_t *action, uint16_t length);
+void tox_callback_friend_status_message(Tox *tox, tox_friend_status_message_cb *function, void *user_data);
-/* set the group's title, limited to MAX_NAME_LENGTH
- * return 0 on success
- * return -1 on failure
- */
-int tox_group_set_title(Tox *tox, int groupnumber, const uint8_t *title, uint8_t length);
-/* Get group title from groupnumber and put it in title.
- * title needs to be a valid memory location with a max_length size of at least MAX_NAME_LENGTH (128) bytes.
+/**
+ * Return the friend's user status (away/busy/...). If the friend number is
+ * invalid, the return value is unspecified.
*
- * return length of copied title if success.
- * return -1 if failure.
+ * The status returned is equal to the last status received through the
+ * `friend_status` callback.
*/
-int tox_group_get_title(Tox *tox, int groupnumber, uint8_t *title, uint32_t max_length);
+TOX_USER_STATUS tox_friend_get_status(const Tox *tox, uint32_t friend_number, TOX_ERR_FRIEND_QUERY *error);
-/* Check if the current peernumber corresponds to ours.
+/**
+ * The function type for the `friend_status` callback.
*
- * return 1 if the peernumber corresponds to ours.
- * return 0 on failure.
+ * @param friend_number The friend number of the friend whose user status
+ * changed.
+ * @param status The new user status.
*/
-unsigned int tox_group_peernumber_is_ours(const Tox *tox, int groupnumber, int peernumber);
+typedef void tox_friend_status_cb(Tox *tox, uint32_t friend_number, TOX_USER_STATUS status, void *user_data);
-/* Return the number of peers in the group chat on success.
- * return -1 on failure
+/**
+ * Set the callback for the `friend_status` event. Pass NULL to unset.
+ *
+ * This event is triggered when a friend changes their user status.
*/
-int tox_group_number_peers(const Tox *tox, int groupnumber);
+void tox_callback_friend_status(Tox *tox, tox_friend_status_cb *function, void *user_data);
-/* List all the peers in the group chat.
- *
- * Copies the names of the peers to the name[length][TOX_MAX_NAME_LENGTH] array.
+
+/**
+ * Check whether a friend is currently connected to this client.
*
- * Copies the lengths of the names to lengths[length]
+ * The result of this function is equal to the last value received by the
+ * `friend_connection_status` callback.
*
- * returns the number of peers on success.
+ * @param friend_number The friend number for which to query the connection
+ * status.
*
- * return -1 on failure.
+ * @return the friend's connection status as it was received through the
+ * `friend_connection_status` event.
*/
-int tox_group_get_names(const Tox *tox, int groupnumber, uint8_t names[][TOX_MAX_NAME_LENGTH], uint16_t lengths[],
- uint16_t length);
-
-/* Return the number of chats in the instance m.
- * You should use this to determine how much memory to allocate
- * for copy_chatlist. */
-uint32_t tox_count_chatlist(const Tox *tox);
+TOX_CONNECTION tox_friend_get_connection_status(const Tox *tox, uint32_t friend_number, TOX_ERR_FRIEND_QUERY *error);
-/* Copy a list of valid chat IDs into the array out_list.
- * If out_list is NULL, returns 0.
- * Otherwise, returns the number of elements copied.
- * If the array was too small, the contents
- * of out_list will be truncated to list_size. */
-uint32_t tox_get_chatlist(const Tox *tox, int32_t *out_list, uint32_t list_size);
-
-/* return the type of groupchat (TOX_GROUPCHAT_TYPE_) that groupnumber is.
+/**
+ * The function type for the `friend_connection_status` callback.
*
- * return -1 on failure.
- * return type on success.
+ * @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.
*/
-int tox_group_get_type(const Tox *tox, int groupnumber);
-
-/****************AVATAR FUNCTIONS*****************/
+typedef void tox_friend_connection_status_cb(Tox *tox, uint32_t friend_number, TOX_CONNECTION connection_status,
+ void *user_data);
-/* Set the callback function for avatar information.
- * This callback will be called when avatar information are received from friends. These events
- * can arrive at anytime, but are usually received uppon connection and in reply of avatar
- * information requests.
+/**
+ * Set the callback for the `friend_connection_status` event. Pass NULL to
+ * unset.
*
- * Function format is:
- * function(Tox *tox, int32_t friendnumber, uint8_t format, uint8_t *hash, void *userdata)
- *
- * where 'format' is the avatar image format (see TOX_AVATAR_FORMAT) and 'hash' is the hash of
- * the avatar data for caching purposes and it is exactly TOX_HASH_LENGTH long. If the image
- * format is NONE, the hash is zeroed.
+ * 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 offline.
*/
-void tox_callback_avatar_info(Tox *tox, void (*function)(Tox *tox, int32_t, uint8_t, uint8_t *, void *),
- void *userdata);
+void tox_callback_friend_connection_status(Tox *tox, tox_friend_connection_status_cb *function, void *user_data);
-/* Set the callback function for avatar data.
- * This callback will be called when the complete avatar data was correctly received from a
- * friend. This only happens in reply of a avatar data request (see tox_request_avatar_data);
+/**
+ * Check whether a friend is currently typing a message.
*
- * Function format is:
- * function(Tox *tox, int32_t friendnumber, uint8_t format, uint8_t *hash, uint8_t *data, uint32_t datalen, void *userdata)
+ * @param friend_number The friend number for which to query the typing status.
*
- * where 'format' is the avatar image format (see TOX_AVATAR_FORMAT); 'hash' is the
- * locally-calculated cryptographic hash of the avatar data and it is exactly
- * TOX_HASH_LENGTH long; 'data' is the avatar image data and 'datalen' is the length
- * of such data.
+ * @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.
+ */
+bool tox_friend_get_typing(const Tox *tox, uint32_t friend_number, TOX_ERR_FRIEND_QUERY *error);
+
+/**
+ * The function type for the `friend_typing` callback.
*
- * If format is NONE, 'data' is NULL, 'datalen' is zero, and the hash is zeroed. The hash is
- * always validated locally with the function tox_hash and ensured to match the image data,
- * so this value can be safely used to compare with cached avatars.
+ * @param friend_number The friend number of the friend who started or stopped
+ * typing.
+ * @param is_typing The result of calling tox_friend_get_typing on the passed
+ * friend_number.
+ */
+typedef void tox_friend_typing_cb(Tox *tox, uint32_t friend_number, bool is_typing, void *user_data);
+
+/**
+ * Set the callback for the `friend_typing` event. Pass NULL to unset.
*
- * WARNING: users MUST treat all avatar image data received from another peer as untrusted and
- * potentially malicious. The library only ensures that the data which arrived is the same the
- * other user sent, and does not interpret or validate any image data.
+ * This event is triggered when a friend starts or stops typing.
*/
-void tox_callback_avatar_data(Tox *tox, void (*function)(Tox *tox, int32_t, uint8_t, uint8_t *, uint8_t *, uint32_t,
- void *), void *userdata);
+void tox_callback_friend_typing(Tox *tox, tox_friend_typing_cb *function, void *user_data);
+
+
+/*******************************************************************************
+ *
+ * :: Sending private messages
+ *
+ ******************************************************************************/
+
+
+typedef enum TOX_ERR_SET_TYPING {
+ 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;
-/* Set the user avatar image data.
- * This should be made before connecting, so we will not announce that the user have no avatar
- * before setting and announcing a new one, forcing the peers to re-download it.
+/**
+ * Set the client's typing status for a friend.
*
- * Notice that the library treats the image as raw data and does not interpret it by any way.
+ * The client is responsible for turning it on or off.
*
- * Arguments:
- * format - Avatar image format or NONE for user with no avatar (see TOX_AVATAR_FORMAT);
- * data - pointer to the avatar data (may be NULL it the format is NONE);
- * length - length of image data. Must be <= TOX_AVATAR_MAX_DATA_LENGTH.
+ * @param friend_number The friend to which the client is typing a message.
+ * @param is_typing The typing status. True means the client is typing.
*
- * returns 0 on success
- * returns -1 on failure.
+ * @return true on success.
*/
-int tox_set_avatar(Tox *tox, uint8_t format, const uint8_t *data, uint32_t length);
+bool tox_self_set_typing(Tox *tox, uint32_t friend_number, bool is_typing, TOX_ERR_SET_TYPING *error);
-/* Unsets the user avatar.
- returns 0 on success (currently always returns 0) */
-int tox_unset_avatar(Tox *tox);
+typedef enum TOX_ERR_FRIEND_SEND_MESSAGE {
+ TOX_ERR_FRIEND_SEND_MESSAGE_OK,
+ 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;
-/* Get avatar data from the current user.
- * Copies the current user avatar data to the destination buffer and sets the image format
- * accordingly.
+/**
+ * Send a text chat message to an online friend.
*
- * If the avatar format is NONE, the buffer 'buf' isleft uninitialized, 'hash' is zeroed, and
- * 'length' is set to zero.
+ * This function creates a chat message packet and pushes it into the send
+ * queue.
*
- * If any of the pointers format, buf, length, and hash are NULL, that particular field will be ignored.
+ * Type corresponds to the message type, for a list of valid types see TOX_MESSAGE_TYPE.
*
- * Arguments:
- * format - destination pointer to the avatar image format (see TOX_AVATAR_FORMAT);
- * buf - destination buffer to the image data. Must have at least 'maxlen' bytes;
- * length - destination pointer to the image data length;
- * maxlen - length of the destination buffer 'buf';
- * hash - destination pointer to the avatar hash (it must be exactly TOX_HASH_LENGTH bytes long).
+ * 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.
*
- * returns 0 on success;
- * returns -1 on failure.
+ * The return value of this function is the message ID. If a read receipt is
+ * received, the triggered `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.
*/
-int tox_get_self_avatar(const Tox *tox, uint8_t *format, uint8_t *buf, uint32_t *length, uint32_t maxlen,
- uint8_t *hash);
+uint32_t tox_friend_send_message(Tox *tox, uint32_t friend_number, TOX_MESSAGE_TYPE type, const uint8_t *message,
+ size_t length, TOX_ERR_FRIEND_SEND_MESSAGE *error);
-
-/* 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.
- * This function is a wrapper to internal message-digest functions.
+/**
+ * The function type for the `read_receipt` callback.
*
- * Arguments:
- * hash - destination buffer for the hash data, it must be exactly TOX_HASH_LENGTH bytes long.
- * data - data to be hashed;
- * datalen - length of the data; for avatars, should be TOX_AVATAR_MAX_DATA_LENGTH
- *
- * returns 0 on success
- * returns -1 on failure.
+ * @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.
*/
-int tox_hash(uint8_t *hash, const uint8_t *data, const uint32_t datalen);
+typedef void tox_friend_read_receipt_cb(Tox *tox, uint32_t friend_number, uint32_t message_id, void *user_data);
-/* Request avatar information from a friend.
- * Asks a friend to provide their avatar information (image format and hash). The friend may
- * or may not answer this request and, if answered, the information will be provided through
- * the callback 'avatar_info'.
+/**
+ * Set the callback for the `read_receipt` event. Pass NULL to unset.
*
- * returns 0 on success
- * returns -1 on failure.
+ * This event is triggered when the friend receives the message sent with
+ * tox_friend_send_message with the corresponding message ID.
*/
-int tox_request_avatar_info(const Tox *tox, const int32_t friendnumber);
+void tox_callback_friend_read_receipt(Tox *tox, tox_friend_read_receipt_cb *function, void *user_data);
-/* Send an unrequested avatar information to a friend.
- * Sends our avatar format and hash to a friend; he/she can use this information to validate
- * an avatar from the cache and may (or not) reply with an avatar data request.
+/*******************************************************************************
*
- * Notice: it is NOT necessary to send these notification after changing the avatar or
- * connecting. The library already does this.
+ * :: Receiving private messages and friend requests
*
- * returns 0 on success
- * returns -1 on failure.
- */
-int tox_send_avatar_info(Tox *tox, const int32_t friendnumber);
+ ******************************************************************************/
-/* Request the avatar data from a friend.
- * Ask a friend to send their avatar data. The friend may or may not answer this request and,
- * if answered, the information will be provided in callback 'avatar_data'.
+/**
+ * The function type for the `friend_request` callback.
*
- * returns 0 on sucess
- * returns -1 on failure.
+ * @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.
*/
-int tox_request_avatar_data(const Tox *tox, const int32_t friendnumber);
+typedef void tox_friend_request_cb(Tox *tox, const uint8_t *public_key, const uint8_t *message, size_t length,
+ void *user_data);
-/****************FILE SENDING FUNCTIONS*****************/
-/* NOTE: This how to will be updated.
+/**
+ * Set the callback for the `friend_request` event. Pass NULL to unset.
*
- * HOW TO SEND FILES CORRECTLY:
- * 1. Use tox_new_file_sender(...) to create a new file sender.
- * 2. Wait for the callback set with tox_callback_file_control(...) to be called with receive_send == 1 and control_type == TOX_FILECONTROL_ACCEPT
- * 3. Send the data with tox_file_send_data(...) with chunk size tox_file_data_size(...)
- * 4. When sending is done, send a tox_file_send_control(...) with send_receive = 0 and message_id = TOX_FILECONTROL_FINISHED
- * 5. when the callback set with tox_callback_file_control(...) is called with receive_send == 1 and control_type == TOX_FILECONTROL_FINISHED
- * the other person has received the file correctly.
+ * This event is triggered when a friend request is received.
+ */
+void tox_callback_friend_request(Tox *tox, tox_friend_request_cb *function, void *user_data);
+
+
+/**
+ * The function type for the `friend_message` callback.
*
- * HOW TO RECEIVE FILES CORRECTLY:
- * 1. wait for the callback set with tox_callback_file_send_request(...)
- * 2. accept or refuse the connection with tox_file_send_control(...) with send_receive = 1 and message_id = TOX_FILECONTROL_ACCEPT or TOX_FILECONTROL_KILL
- * 3. save all the data received with the callback set with tox_callback_file_data(...) to a file.
- * 4. when the callback set with tox_callback_file_control(...) is called with receive_send == 0 and control_type == TOX_FILECONTROL_FINISHED
- * the file is done transferring.
- * 5. send a tox_file_send_control(...) with send_receive = 1 and message_id = TOX_FILECONTROL_FINISHED to confirm that we did receive the file.
+ * @param friend_number The friend number of the friend who sent the message.
+ * @param type The message type, for a list of valid types see TOX_MESSAGE_TYPE.
+ * @param message The message data they sent.
+ * @param length The size of the message byte array.
+ */
+typedef void tox_friend_message_cb(Tox *tox, uint32_t friend_number, TOX_MESSAGE_TYPE type, const uint8_t *message,
+ size_t length, void *user_data);
+
+/**
+ * Set the callback for the `friend_message` event. Pass NULL to unset.
*
- * tox_file_data_remaining(...) can be used to know how many bytes are left to send/receive.
+ * This event is triggered when a message from a friend is received.
+ */
+void tox_callback_friend_message(Tox *tox, tox_friend_message_cb *function, void *user_data);
+
+
+/*******************************************************************************
*
- * If the connection breaks during file sending (The other person goes offline without pausing the sending and then comes back)
- * the receiver must send a control packet with send_receive == 1 message_id = TOX_FILECONTROL_RESUME_BROKEN and the data being
- * a uint64_t (in host byte order) containing the number of bytes received.
+ * :: File transmission: common between sending and receiving
*
- * If the sender receives this packet, he must send a control packet with send_receive == 0 and control_type == TOX_FILECONTROL_ACCEPT
- * then he must start sending file data from the position (data , uint64_t in host byte order) received in the TOX_FILECONTROL_RESUME_BROKEN packet.
+ ******************************************************************************/
+
+
+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 filename. 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
+};
+
+
+/**
+ * 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.
*
- * To pause a file transfer send a control packet with control_type == TOX_FILECONTROL_PAUSE.
- * To unpause a file transfer send a control packet with control_type == TOX_FILECONTROL_ACCEPT.
+ * If length is zero or data is NULL, the hash will contain all zero. If hash is
+ * NULL, the function returns false, otherwise it returns true.
*
- * If you receive a control packet with receive_send == 1 and control_type == TOX_FILECONTROL_PAUSE, you must stop sending filenumber until the other
- * person sends a control packet with send_receive == 0 and control_type == TOX_FILECONTROL_ACCEPT with the filenumber being a paused filenumber.
+ * This function is a wrapper to internal message-digest functions.
*
- * If you receive a control packet with receive_send == 0 and control_type == TOX_FILECONTROL_PAUSE, it means the sender of filenumber has paused the
- * transfer and will resume it later with a control packet with send_receive == 1 and control_type == TOX_FILECONTROL_ACCEPT for that file number.
+ * @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, const uint8_t *data, size_t length);
+
+
+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;
+
+
+typedef enum TOX_ERR_FILE_CONTROL {
+ 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;
+
+/**
+ * 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, uint32_t friend_number, uint32_t file_number, TOX_FILE_CONTROL control,
+ TOX_ERR_FILE_CONTROL *error);
+
+
+/**
+ * The function type for the `file_control` callback.
+ *
+ * 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, uint32_t friend_number, uint32_t file_number, TOX_FILE_CONTROL control,
+ void *user_data);
+
+/**
+ * Set the callback for the `file_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 *function, void *user_data);
+
+
+typedef enum TOX_ERR_FILE_SEEK {
+ 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;
+
+/**
+ * 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, uint32_t friend_number, uint32_t file_number, uint64_t position,
+ TOX_ERR_FILE_SEEK *error);
+
+typedef enum TOX_ERR_FILE_GET {
+ TOX_ERR_FILE_GET_OK,
+ /**
+ * 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;
+
+/**
+ * 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.
+ * @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, uint32_t friend_number, uint32_t file_number, uint8_t *file_id,
+ TOX_ERR_FILE_GET *error);
+
+/*******************************************************************************
+ *
+ * :: File transmission: sending
+ *
+ ******************************************************************************/
+
+
+typedef enum TOX_ERR_FILE_SEND {
+ TOX_ERR_FILE_SEND_OK,
+ 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;
+
+/**
+ * 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-zero file size is provided, this can be used by both sides to
+ * determine the sending progress. File size can be set to zero 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 are
+ * purged from core.
+ *
+ * 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 Core thinks the file transfer has
+ * finished. If the client remembers the file size as it was when sending
+ * the request, it will terminate the transfer normally. If the client
+ * re-reads the size, it will think the friend cancelled the transfer.
+ * - If the file size was decreased
+ * - and sending mode was streaming, the behaviour is as expected.
+ * - and sending mode was file, the callback will return 0 at the new
+ * (earlier) end-of-file, signalling 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 core restarts. If NULL, a random one will
+ * be generated by core. It can then be obtained by using tox_file_get_file_id().
+ * @param filename Name of the file. Does not need to be the actual name. This
+ * name will be sent along with the file send request.
+ * @param filename_length Size in bytes of the filename.
+ *
+ * @return A file number used as an identifier in subsequent callbacks. This
+ * number is per friend. File numbers are reused after a transfer terminates.
+ * on failure, this function returns UINT32_MAX. Any pattern in file numbers
+ * should not be relied on.
+ */
+uint32_t tox_file_send(Tox *tox, uint32_t friend_number, uint32_t kind, uint64_t file_size, const uint8_t *file_id,
+ const uint8_t *filename, size_t filename_length, TOX_ERR_FILE_SEND *error);
+
+
+typedef enum TOX_ERR_FILE_SEND_CHUNK {
+ 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;
+
+/**
+ * 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,
+ * Core will know that the transfer is complete after the last byte has been
+ * received, so it is not necessary (though not harmful) to send a zero-length
+ * chunk to terminate. For streams, core will know that the transfer is finished
+ * if a chunk with length less than the length requested in the callback is sent.
+ *
+ * @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, uint32_t friend_number, uint32_t file_number, uint64_t position, const uint8_t *data,
+ size_t length, TOX_ERR_FILE_SEND_CHUNK *error);
+
+
+/**
+ * The function type for the `file_chunk_request` callback.
+ *
+ * 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.
*
- * More to come...
+ * @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, uint32_t friend_number, uint32_t file_number, uint64_t position,
+ size_t length, void *user_data);
-enum {
- TOX_FILECONTROL_ACCEPT,
- TOX_FILECONTROL_PAUSE,
- TOX_FILECONTROL_KILL,
- TOX_FILECONTROL_FINISHED,
- TOX_FILECONTROL_RESUME_BROKEN
-};
-/* Set the callback for file send requests.
- *
- * Function(Tox *tox, int32_t friendnumber, uint8_t filenumber, uint64_t filesize, const uint8_t *filename, uint16_t filename_length, void *userdata)
+/**
+ * Set the callback for the `file_chunk_request` event. Pass NULL to unset.
*/
-void tox_callback_file_send_request(Tox *tox, void (*function)(Tox *m, int32_t, uint8_t, uint64_t, const uint8_t *,
- uint16_t, void *), void *userdata);
+void tox_callback_file_chunk_request(Tox *tox, tox_file_chunk_request_cb *function, void *user_data);
+
-/* Set the callback for file control requests.
+/*******************************************************************************
*
- * receive_send is 1 if the message is for a slot on which we are currently sending a file and 0 if the message
- * is for a slot on which we are receiving the file
+ * :: File transmission: receiving
*
- * Function(Tox *tox, int32_t friendnumber, uint8_t receive_send, uint8_t filenumber, uint8_t control_type, const uint8_t *data, uint16_t length, void *userdata)
+ ******************************************************************************/
+
+
+/**
+ * The function type for the `file_receive` callback.
+ *
+ * Maximum filename length is TOX_MAX_FILENAME_LENGTH bytes. The filename should generally just be
+ * a file name, not a path with directory names.
+ *
+ * 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 to be sent.
+ * @param file_size Size in bytes of the file about to be received from the client,
+ * UINT64_MAX if unknown or streaming.
+ * @param filename_length Size in bytes of the filename.
+ */
+typedef void tox_file_recv_cb(Tox *tox, uint32_t friend_number, uint32_t file_number, uint32_t kind,
+ uint64_t file_size, const uint8_t *filename, size_t filename_length, void *user_data);
+
+/**
+ * Set the callback for the `file_receive` event. Pass NULL to unset.
*
+ * This event is triggered when a file transfer request is received.
*/
-void tox_callback_file_control(Tox *tox, void (*function)(Tox *m, int32_t, uint8_t, uint8_t, uint8_t, const uint8_t *,
- uint16_t, void *), void *userdata);
+void tox_callback_file_recv(Tox *tox, tox_file_recv_cb *function, void *user_data);
-/* Set the callback for file data.
+
+/**
+ * The function type for the `file_receive_chunk` callback.
+ *
+ * This function is first called when a file transfer request is received, and
+ * subsequently when a chunk of file data for an accepted request was received.
*
- * Function(Tox *tox, int32_t friendnumber, uint8_t filenumber, const uint8_t *data, uint16_t length, void *userdata)
+ * 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.
*/
-void tox_callback_file_data(Tox *tox, void (*function)(Tox *m, int32_t, uint8_t, const uint8_t *, uint16_t length,
- void *), void *userdata);
-
+typedef void tox_file_recv_chunk_cb(Tox *tox, uint32_t friend_number, uint32_t file_number, uint64_t position,
+ const uint8_t *data, size_t length, void *user_data);
-/* Send a file send request.
- * Maximum filename length is 255 bytes.
- * return file number on success
- * return -1 on failure
+/**
+ * Set the callback for the `file_receive_chunk` event. Pass NULL to unset.
*/
-int tox_new_file_sender(Tox *tox, int32_t friendnumber, uint64_t filesize, const uint8_t *filename,
- uint16_t filename_length);
+void tox_callback_file_recv_chunk(Tox *tox, tox_file_recv_chunk_cb *function, void *user_data);
+
-/* Send a file control request.
+/*******************************************************************************
*
- * send_receive is 0 if we want the control packet to target a file we are currently sending,
- * 1 if it targets a file we are currently receiving.
+ * :: Group chat management
*
- * return 0 on success
- * return -1 on failure
- */
-int tox_file_send_control(Tox *tox, int32_t friendnumber, uint8_t send_receive, uint8_t filenumber, uint8_t message_id,
- const uint8_t *data, uint16_t length);
+ ******************************************************************************/
+
-/* Send file data.
+/******************************************************************************
*
- * return 0 on success
- * return -1 on failure
- */
-int tox_file_send_data(Tox *tox, int32_t friendnumber, uint8_t filenumber, const uint8_t *data, uint16_t length);
+ * :: Group chat message sending and receiving
+ *
+ ******************************************************************************/
-/* Returns the recommended/maximum size of the filedata you send with tox_file_send_data()
+/* See: tox_old.h for now. */
+
+/*******************************************************************************
*
- * return size on success
- * return -1 on failure (currently will never return -1)
- */
-int tox_file_data_size(const Tox *tox, int32_t friendnumber);
+ * :: Low-level custom packet sending and receiving
+ *
+ ******************************************************************************/
+
-/* Give the number of bytes left to be sent/received.
+typedef enum TOX_ERR_FRIEND_CUSTOM_PACKET {
+ TOX_ERR_FRIEND_CUSTOM_PACKET_OK,
+ 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 in the specified range for the packet type.
+ * This range is 200-254 for lossy, and 160-191 for lossless packets.
+ */
+ 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,
+ /**
+ * Send queue size exceeded.
+ */
+ TOX_ERR_FRIEND_CUSTOM_PACKET_SENDQ
+} TOX_ERR_FRIEND_CUSTOM_PACKET;
+
+
+/**
+ * Send a custom lossy packet to a friend.
+ *
+ * The first byte of data must be in the range 200-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.
*
- * send_receive is 0 if we want the sending files, 1 if we want the receiving.
+ * Unless latency is an issue, it is recommended that you use lossless custom
+ * packets instead.
*
- * return number of bytes remaining to be sent/received on success
- * return 0 on failure
+ * @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.
*/
-uint64_t tox_file_data_remaining(const Tox *tox, int32_t friendnumber, uint8_t filenumber, uint8_t send_receive);
+bool tox_friend_send_lossy_packet(Tox *tox, uint32_t friend_number, const uint8_t *data, size_t length,
+ TOX_ERR_FRIEND_CUSTOM_PACKET *error);
-/***************END OF FILE SENDING FUNCTIONS******************/
+/**
+ * The function type for the `friend_lossy_packet` callback.
+ *
+ * @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, uint32_t friend_number, const uint8_t *data, size_t length,
+ void *user_data);
-/*
- * Use this function to bootstrap the client.
+/**
+ * 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 *function, void *user_data);
-/* Resolves address into an IP address. If successful, sends a "get nodes"
- * request to the given node with ip, port (in host byte order).
- * and public_key to setup connections
+
+/**
+ * Send a custom lossless packet to a friend.
+ *
+ * The first byte of data must be in the range 160-191. Maximum length of a
+ * custom packet is TOX_MAX_CUSTOM_PACKET_SIZE.
*
- * address can be a hostname or an IP address (IPv4 or IPv6).
+ * Lossless packet behaviour is comparable to TCP (reliability, arrive in order)
+ * but with packets instead of a stream.
*
- * returns 1 if the address could be converted into an IP address
- * returns 0 otherwise
+ * @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.
*/
-int tox_bootstrap_from_address(Tox *tox, const char *address, uint16_t port, const uint8_t *public_key);
+bool tox_friend_send_lossless_packet(Tox *tox, uint32_t friend_number, const uint8_t *data, size_t length,
+ TOX_ERR_FRIEND_CUSTOM_PACKET *error);
-/* Like tox_bootstrap_from_address but for TCP relays only.
+/**
+ * The function type for the `friend_lossless_packet` callback.
*
- * return 0 on failure.
- * return 1 on success.
+ * @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.
*/
-int tox_add_tcp_relay(Tox *tox, const char *address, uint16_t port, const uint8_t *public_key);
+typedef void tox_friend_lossless_packet_cb(Tox *tox, uint32_t friend_number, const uint8_t *data, size_t length,
+ void *user_data);
-/* return 0 if we are not connected to the DHT.
- * return 1 if we are.
+/**
+ * Set the callback for the `friend_lossless_packet` event. Pass NULL to unset.
*/
-int tox_isconnected(const Tox *tox);
-
-typedef enum {
- TOX_PROXY_NONE,
- TOX_PROXY_SOCKS5,
- TOX_PROXY_HTTP
-} TOX_PROXY_TYPE;
+void tox_callback_friend_lossless_packet(Tox *tox, tox_friend_lossless_packet_cb *function, void *user_data);
-typedef struct {
- /*
- * The type of UDP socket created depends on ipv6enabled:
- * If set to 0 (zero), creates an IPv4 socket which subsequently only allows
- * IPv4 communication
- * If set to anything else (default), creates an IPv6 socket which allows both IPv4 AND
- * IPv6 communication
- */
- uint8_t ipv6enabled;
- /* Set to 1 to disable udp support. (default: 0)
- This will force Tox to use TCP only which may slow things down.
- Disabling udp support is necessary when using proxies or Tor.*/
- uint8_t udp_disabled;
- uint8_t proxy_type; /* a value from TOX_PROXY_TYPE */
- char proxy_address[256]; /* Proxy ip or domain in NULL terminated string format. */
- uint16_t proxy_port; /* Proxy port in host byte order. */
-} Tox_Options;
-/*
- * Run this function at startup.
- *
- * Options are some options that can be passed to the Tox instance (see above struct).
+/*******************************************************************************
*
- * If options is NULL, tox_new() will use default settings.
+ * :: Low-level network information
*
- * Initializes a tox structure
- * return allocated instance of tox on success.
- * return NULL on failure.
- */
-Tox *tox_new(Tox_Options *options);
+ ******************************************************************************/
-/* Run this before closing shop.
- * Free all datastructures. */
-void tox_kill(Tox *tox);
-/* Return the time in milliseconds before tox_do() should be called again
- * for optimal performance.
+/**
+ * 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_get_udp_port) to run a temporary bootstrap node.
*
- * returns time (in ms) before the next tox_do() needs to be run on success.
+ * 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.
*/
-uint32_t tox_do_interval(Tox *tox);
-
-/* The main loop that needs to be run in intervals of tox_do_interval() ms. */
-void tox_do(Tox *tox);
+void tox_self_get_dht_id(const Tox *tox, uint8_t *dht_id);
-/* SAVING AND LOADING FUNCTIONS: */
-/* return size of messenger data (for saving). */
-uint32_t tox_size(const Tox *tox);
+typedef enum TOX_ERR_GET_PORT {
+ TOX_ERR_GET_PORT_OK,
+ /**
+ * The instance was not bound to any port.
+ */
+ TOX_ERR_GET_PORT_NOT_BOUND
+} TOX_ERR_GET_PORT;
-/* Save the messenger in data (must be allocated memory of size Messenger_size()). */
-void tox_save(const Tox *tox, uint8_t *data);
+/**
+ * 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);
-/* Load the messenger from data of size length.
- * NOTE: The Tox save format isn't stable yet meaning this function sometimes
- * returns -1 when loading older saves. This however does not mean nothing was
- * loaded from the save.
- *
- * returns 0 on success
- * returns -1 on failure
- * returns +1 on finding encrypted save data
+/**
+ * Return the TCP port this Tox instance is bound to. This is only relevant if
+ * the instance is acting as a TCP relay.
*/
-int tox_load(Tox *tox, const uint8_t *data, uint32_t length);
+uint16_t tox_self_get_tcp_port(const Tox *tox, TOX_ERR_GET_PORT *error);
+
+#include "tox_old.h"
#ifdef __cplusplus
}