diff options
Diffstat (limited to 'protocols/Tox/include/tox.h')
| -rw-r--r-- | protocols/Tox/include/tox.h | 797 |
1 files changed, 533 insertions, 264 deletions
diff --git a/protocols/Tox/include/tox.h b/protocols/Tox/include/tox.h index da328b89e9..9a6d3ecf79 100644 --- a/protocols/Tox/include/tox.h +++ b/protocols/Tox/include/tox.h @@ -66,23 +66,21 @@ extern "C" { * 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. */ - /** \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 + * 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. */ - /** \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 + * running a simple tox_iterate loop, sleeping for tox_iteration_interval * milliseconds on each iteration. * * If you want to access a single Tox instance from multiple threads, access @@ -107,12 +105,9 @@ extern "C" { * \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 + * memory, the length may have become invalid, and the call to * tox_self_get_name may cause undefined behaviour. */ - -#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. @@ -120,8 +115,10 @@ extern "C" { * 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. */ +#ifndef TOX_DEFINED +#define TOX_DEFINED typedef struct Tox Tox; -#endif +#endif /* TOX_DEFINED */ /******************************************************************************* @@ -131,17 +128,20 @@ typedef struct Tox Tox; ******************************************************************************/ + /** * The major version number. Incremented when the API or ABI changes in an * incompatible way. */ #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. @@ -165,7 +165,6 @@ typedef struct Tox Tox; #define TOX_VERSION_REQUIRE(MAJOR, MINOR, PATCH) \ typedef char tox_required_version[TOX_IS_COMPATIBLE(MAJOR, MINOR, PATCH) ? 1 : -1] - /** * 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 @@ -204,15 +203,16 @@ bool tox_version_is_compatible(uint32_t major, uint32_t minor, uint32_t patch); ******************************************************************************/ + /** * The size of a Tox Public Key in bytes. */ -#define TOX_PUBLIC_KEY_SIZE 32 +#define TOX_PUBLIC_KEY_SIZE 32 /** * The size of a Tox Secret Key in bytes. */ -#define TOX_SECRET_KEY_SIZE 32 +#define TOX_SECRET_KEY_SIZE 32 /** * The size of a Tox address in bytes. Tox addresses are in the format @@ -222,47 +222,48 @@ bool tox_version_is_compatible(uint32_t major, uint32_t minor, uint32_t patch); * byte is an XOR of all the even bytes (0, 2, 4, ...), the second byte is an * XOR of all the odd bytes (1, 3, 5, ...) of the Public Key and nospam. */ -#define TOX_ADDRESS_SIZE (TOX_PUBLIC_KEY_SIZE + sizeof(uint32_t) + sizeof(uint16_t)) +#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 +#define TOX_MAX_NAME_LENGTH 128 /** * Maximum length of a status message in bytes. */ -#define TOX_MAX_STATUS_MESSAGE_LENGTH 1007 +#define TOX_MAX_STATUS_MESSAGE_LENGTH 1007 /** * Maximum length of a friend request message in bytes. */ -#define TOX_MAX_FRIEND_REQUEST_LENGTH 1016 +#define TOX_MAX_FRIEND_REQUEST_LENGTH 1016 /** * Maximum length of a single message after which it should be split. */ -#define TOX_MAX_MESSAGE_LENGTH 1372 +#define TOX_MAX_MESSAGE_LENGTH 1372 /** * Maximum size of custom packets. TODO: should be LENGTH? */ -#define TOX_MAX_CUSTOM_PACKET_SIZE 1373 +#define TOX_MAX_CUSTOM_PACKET_SIZE 1373 /** * The number of bytes in a hash generated by tox_hash. */ -#define TOX_HASH_LENGTH /*crypto_hash_sha256_BYTES*/ 32 +#define TOX_HASH_LENGTH 32 /** * The number of bytes in a file id. */ -#define TOX_FILE_ID_LENGTH 32 +#define TOX_FILE_ID_LENGTH 32 /** - * Maximum file name length for file tran. + * Maximum file name length for file transfers. */ -#define TOX_MAX_FILENAME_LENGTH 255 +#define TOX_MAX_FILENAME_LENGTH 255 + /******************************************************************************* * @@ -271,42 +272,53 @@ bool tox_version_is_compatible(uint32_t major, uint32_t minor, uint32_t patch); ******************************************************************************/ + /** * Represents the possible statuses a client can have. */ typedef enum TOX_USER_STATUS { + /** * User is online and available. */ TOX_USER_STATUS_NONE, + /** * User is away. Clients can set this e.g. after a user defined * inactivity time. */ TOX_USER_STATUS_AWAY, + /** * User is busy. Signals to other clients that this client does not * currently wish to communicate. */ - TOX_USER_STATUS_BUSY + TOX_USER_STATUS_BUSY, + } TOX_USER_STATUS; + /** - * Represents message types for friend messages and group chat + * Represents message types for tox_friend_send_message 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_ACTION, + } TOX_MESSAGE_TYPE; + + /******************************************************************************* * * :: Startup options @@ -314,28 +326,60 @@ typedef enum TOX_MESSAGE_TYPE { ******************************************************************************/ + +/** + * Type of proxy used to connect to TCP relays. + */ typedef enum TOX_PROXY_TYPE { + /** * Don't use a proxy. */ TOX_PROXY_TYPE_NONE, + /** * HTTP proxy using CONNECT. */ TOX_PROXY_TYPE_HTTP, + /** * SOCKS proxy for simple socket pipes. */ - TOX_PROXY_TYPE_SOCKS5 + TOX_PROXY_TYPE_SOCKS5, + } TOX_PROXY_TYPE; /** + * Type of savedata to create the Tox instance from. + */ +typedef enum TOX_SAVEDATA_TYPE { + + /** + * No savedata. + */ + TOX_SAVEDATA_TYPE_NONE, + + /** + * Savedata is one that was obtained from tox_get_savedata + */ + TOX_SAVEDATA_TYPE_TOX_SAVE, + + /** + * Savedata is a secret key of length TOX_SECRET_KEY_SIZE + */ + TOX_SAVEDATA_TYPE_SECRET_KEY, + +} TOX_SAVEDATA_TYPE; + + +/** * 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. * @@ -346,6 +390,7 @@ struct Tox_Options { */ bool ipv6_enabled; + /** * Enable the use of UDP communication when available. * @@ -355,11 +400,13 @@ struct Tox_Options { */ 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. * @@ -367,18 +414,20 @@ struct Tox_Options { * 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. + * This member is ignored (it can be NULL) if proxy_type is TOX_PROXY_TYPE_NONE. */ 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. + * proxy_type is TOX_PROXY_TYPE_NONE. */ uint16_t proxy_port; + /** * The start port of the inclusive port range to attempt to use. * @@ -393,10 +442,36 @@ struct Tox_Options { */ uint16_t start_port; + /** * The end port of the inclusive port range to attempt to use. */ uint16_t end_port; + + + /** + * The port to use for the TCP server. If 0, the tcp server is disabled. + */ + uint16_t tcp_port; + + + /** + * The type of savedata to load from. + */ + TOX_SAVEDATA_TYPE savedata_type; + + + /** + * The savedata. + */ + const uint8_t *savedata_data; + + + /** + * The length of the savedata. + */ + size_t savedata_length; + }; @@ -413,15 +488,21 @@ struct Tox_Options { */ void tox_options_default(struct Tox_Options *options); - typedef enum TOX_ERR_OPTIONS_NEW { + + /** + * The function returned successfully. + */ TOX_ERR_OPTIONS_NEW_OK, + /** * The function failed to allocate enough memory for the options struct. */ - TOX_ERR_OPTIONS_NEW_MALLOC + TOX_ERR_OPTIONS_NEW_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 @@ -434,7 +515,6 @@ typedef enum TOX_ERR_OPTIONS_NEW { */ struct Tox_Options *tox_options_new(TOX_ERR_OPTIONS_NEW *error); - /** * Releases all resources associated with an options objects. * @@ -451,41 +531,58 @@ void tox_options_free(struct Tox_Options *options); ******************************************************************************/ + typedef enum TOX_ERR_NEW { + + /** + * The function returned successfully. + */ TOX_ERR_NEW_OK, + + /** + * One of the arguments to the function was NULL when it was not expected. + */ TOX_ERR_NEW_NULL, + /** * The function was unable to allocate enough memory to store the internal * structures for the Tox object. */ TOX_ERR_NEW_MALLOC, + /** * The function was unable to bind to a port. This may mean that all ports * have already been bound, e.g. by other Tox instances, or it may mean * a permission error. You may be able to gather more information from errno. */ TOX_ERR_NEW_PORT_ALLOC, + /** * proxy_type was invalid. */ TOX_ERR_NEW_PROXY_BAD_TYPE, + /** * proxy_type was valid but the proxy_host passed had an invalid format * or was NULL. */ TOX_ERR_NEW_PROXY_BAD_HOST, + /** * proxy_type was valid, but the proxy_port was invalid. */ TOX_ERR_NEW_PROXY_BAD_PORT, + /** - * The proxy host passed could not be resolved. + * The proxy address passed could not be resolved. */ TOX_ERR_NEW_PROXY_NOT_FOUND, + /** * The byte array to be loaded contained an encrypted save. */ TOX_ERR_NEW_LOAD_ENCRYPTED, + /** * The data format was invalid. This can happen when loading data that was * saved by an older version of Tox, or when the data has been corrupted. @@ -493,7 +590,8 @@ typedef enum TOX_ERR_NEW { * and the rest is discarded. Passing an invalid length parameter also * causes this error. */ - TOX_ERR_NEW_LOAD_BAD_FORMAT + TOX_ERR_NEW_LOAD_BAD_FORMAT, + } TOX_ERR_NEW; @@ -503,22 +601,15 @@ typedef enum TOX_ERR_NEW { * This function will bring the instance into a valid state. Running the event * loop with a new instance will operate correctly. * - * 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. + * @see tox_iterate for the event loop. */ -Tox *tox_new(const struct Tox_Options *options, const uint8_t *data, size_t length, TOX_ERR_NEW *error); - +Tox *tox_new(const struct Tox_Options *options, TOX_ERR_NEW *error); /** * Releases all resources associated with the Tox instance and disconnects from @@ -529,11 +620,9 @@ Tox *tox_new(const struct Tox_Options *options, const uint8_t *data, size_t leng */ void tox_kill(Tox *tox); - /** * 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. + * tox_get_savedata. This function cannot fail. The result is always greater than 0. * * @see threading for concurrency implications. */ @@ -546,7 +635,7 @@ size_t tox_get_savedata_size(const Tox *tox); * Call tox_get_savedata_size to find the number of bytes required. If this parameter * is NULL, this function has no effect. */ -void tox_get_savedata(const Tox *tox, uint8_t *data); +void tox_get_savedata(const Tox *tox, uint8_t *savedata); /******************************************************************************* @@ -556,20 +645,33 @@ void tox_get_savedata(const Tox *tox, uint8_t *data); ******************************************************************************/ + typedef enum TOX_ERR_BOOTSTRAP { + + /** + * The function returned successfully. + */ TOX_ERR_BOOTSTRAP_OK, + + /** + * One of the arguments to the function was NULL when it was not expected. + */ TOX_ERR_BOOTSTRAP_NULL, + /** - * The host could not be resolved to an IP address, or the IP address + * The address 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_BAD_PORT, + } TOX_ERR_BOOTSTRAP; + /** * Sends a "get nodes" request to the given bootstrap node with IP, port, and * public key to setup connections. @@ -582,15 +684,14 @@ typedef enum TOX_ERR_BOOTSTRAP { * 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 address 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. */ -bool tox_bootstrap(Tox *tox, const char *host, uint16_t port, const uint8_t *public_key, TOX_ERR_BOOTSTRAP *error); - +bool tox_bootstrap(Tox *tox, const char *address, uint16_t port, const uint8_t *public_key, TOX_ERR_BOOTSTRAP *error); /** * Adds additional host:port pair as TCP relay. @@ -599,35 +700,41 @@ bool tox_bootstrap(Tox *tox, const char *host, uint16_t port, const uint8_t *pub * the same bootstrap node, or to add TCP relays without using them as * bootstrap nodes. * - * @param host The hostname or IP address (IPv4 or IPv6) of the TCP relay. + * @param address 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. */ -bool tox_add_tcp_relay(Tox *tox, const char *host, uint16_t port, const uint8_t *public_key, +bool tox_add_tcp_relay(Tox *tox, const char *address, uint16_t port, const uint8_t *public_key, TOX_ERR_BOOTSTRAP *error); - +/** + * Protocols that can be used to connect to the network or friends. + */ 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_UDP, + } TOX_CONNECTION; @@ -638,13 +745,11 @@ typedef enum TOX_CONNECTION { TOX_CONNECTION tox_self_get_connection_status(const Tox *tox); /** - * The function type for the `self_connection_status` callback. - * - * @param connection_status Equal to the return value of - * tox_self_get_connection_status. + * @param connection_status Whether we are connected to the DHT. */ typedef void tox_self_connection_status_cb(Tox *tox, TOX_CONNECTION connection_status, void *user_data); + /** * Set the callback for the `self_connection_status` event. Pass NULL to unset. * @@ -656,16 +761,14 @@ typedef void tox_self_connection_status_cb(Tox *tox, TOX_CONNECTION connection_s * * 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); - +void tox_callback_self_connection_status(Tox *tox, tox_self_connection_status_cb *callback, void *user_data); /** - * Return the time in milliseconds before tox_iteration() should be called again + * Return the time in milliseconds before tox_iterate() should be called again * for optimal performance. */ uint32_t tox_iteration_interval(const Tox *tox); - /** * The main loop that needs to be run in intervals of tox_iteration_interval() * milliseconds. @@ -680,6 +783,7 @@ void tox_iterate(Tox *tox); ******************************************************************************/ + /** * 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, @@ -691,7 +795,6 @@ void tox_iterate(Tox *tox); */ void tox_self_get_address(const Tox *tox, uint8_t *address); - /** * Set the 4-byte nospam part of the address. * @@ -705,7 +808,7 @@ void tox_self_set_nospam(Tox *tox, uint32_t nospam); uint32_t tox_self_get_nospam(const Tox *tox); /** - * Copy the Tox Public Key (long term public key) from the Tox object. + * Copy the Tox Public Key (long term) from the Tox object. * * @param public_key A memory region of at least TOX_PUBLIC_KEY_SIZE bytes. If * this parameter is NULL, this function has no effect. @@ -713,7 +816,7 @@ uint32_t tox_self_get_nospam(const Tox *tox); void tox_self_get_public_key(const Tox *tox, uint8_t *public_key); /** - * Copy the secret key from the Tox object. + * Copy the Tox Secret Key from the Tox object. * * @param secret_key A memory region of at least TOX_SECRET_KEY_SIZE bytes. If * this parameter is NULL, this function has no effect. @@ -728,17 +831,28 @@ void tox_self_get_secret_key(const Tox *tox, uint8_t *secret_key); ******************************************************************************/ + /** * Common error codes for all functions that set a piece of user-visible * client information. */ typedef enum TOX_ERR_SET_INFO { + + /** + * The function returned successfully. + */ TOX_ERR_SET_INFO_OK, + + /** + * One of the arguments to the function was NULL when it was not expected. + */ TOX_ERR_SET_INFO_NULL, + /** * Information length exceeded maximum permissible size. */ - TOX_ERR_SET_INFO_TOO_LONG + TOX_ERR_SET_INFO_TOO_LONG, + } TOX_ERR_SET_INFO; @@ -786,11 +900,10 @@ void tox_self_get_name(const Tox *tox, uint8_t *name); * length is 0, the status parameter is ignored (it can be NULL), and the * user status is set back to empty. */ -bool tox_self_set_status_message(Tox *tox, const uint8_t *status, size_t length, TOX_ERR_SET_INFO *error); +bool tox_self_set_status_message(Tox *tox, const uint8_t *status_message, size_t length, TOX_ERR_SET_INFO *error); /** - * Return the length of the current status message as passed to - * tox_self_set_status_message. + * 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. @@ -805,21 +918,20 @@ size_t tox_self_get_status_message_size(const Tox *tox); * If no status message was set before calling this function, the status is * empty, and this function has no effect. * - * Call tox_self_status_message_size to find out how much memory to allocate for + * Call tox_self_get_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_self_get_status_message(const Tox *tox, uint8_t *status); - +void tox_self_get_status_message(const Tox *tox, uint8_t *status_message); /** * 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); +void tox_self_set_status(Tox *tox, TOX_USER_STATUS status); /** * Returns the client's user status. @@ -834,42 +946,60 @@ TOX_USER_STATUS tox_self_get_status(const Tox *tox); ******************************************************************************/ + typedef enum TOX_ERR_FRIEND_ADD { + + /** + * The function returned successfully. + */ TOX_ERR_FRIEND_ADD_OK, + + /** + * One of the arguments to the function was NULL when it was not expected. + */ TOX_ERR_FRIEND_ADD_NULL, + /** * The length of the friend request message exceeded * TOX_MAX_FRIEND_REQUEST_LENGTH. */ TOX_ERR_FRIEND_ADD_TOO_LONG, + /** * The friend request message was empty. This, and the TOO_LONG code will * never be returned from tox_friend_add_norequest. */ TOX_ERR_FRIEND_ADD_NO_MESSAGE, + /** * The friend address belongs to the sending client. */ TOX_ERR_FRIEND_ADD_OWN_KEY, + /** * A friend request has already been sent, or the address belongs to a friend * that is already on the friend list. */ TOX_ERR_FRIEND_ADD_ALREADY_SENT, + /** * The friend address checksum failed. */ TOX_ERR_FRIEND_ADD_BAD_CHECKSUM, + /** * The friend was already there, but the nospam value was different. */ TOX_ERR_FRIEND_ADD_SET_NEW_NOSPAM, + /** * A memory allocation failed when trying to increase the friend list size. */ - TOX_ERR_FRIEND_ADD_MALLOC + TOX_ERR_FRIEND_ADD_MALLOC, + } TOX_ERR_FRIEND_ADD; + /** * Add a friend to the friend list and send a friend request. * @@ -896,7 +1026,6 @@ typedef enum TOX_ERR_FRIEND_ADD { uint32_t tox_friend_add(Tox *tox, const uint8_t *address, const uint8_t *message, size_t length, TOX_ERR_FRIEND_ADD *error); - /** * Add a friend without sending a friend request. * @@ -917,28 +1046,31 @@ uint32_t tox_friend_add(Tox *tox, const uint8_t *address, const uint8_t *message */ uint32_t tox_friend_add_norequest(Tox *tox, const uint8_t *public_key, TOX_ERR_FRIEND_ADD *error); - typedef enum TOX_ERR_FRIEND_DELETE { + + /** + * The function returned successfully. + */ TOX_ERR_FRIEND_DELETE_OK, + /** * There was no friend with the given friend number. No friends were deleted. */ - TOX_ERR_FRIEND_DELETE_FRIEND_NOT_FOUND + TOX_ERR_FRIEND_DELETE_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. * - * @friend_number Friend number for the friend to be deleted. + * @param friend_number Friend number for the friend to be deleted. * * @return true on success. - * @see tox_friend_add for detailed description of friend numbers. */ bool tox_friend_delete(Tox *tox, uint32_t friend_number, TOX_ERR_FRIEND_DELETE *error); @@ -950,15 +1082,27 @@ bool tox_friend_delete(Tox *tox, uint32_t friend_number, TOX_ERR_FRIEND_DELETE * ******************************************************************************/ + typedef enum TOX_ERR_FRIEND_BY_PUBLIC_KEY { + + /** + * The function returned successfully. + */ TOX_ERR_FRIEND_BY_PUBLIC_KEY_OK, + + /** + * One of the arguments to the function was NULL when it was not expected. + */ TOX_ERR_FRIEND_BY_PUBLIC_KEY_NULL, + /** * No friend with the given Public Key exists on the friend list. */ - TOX_ERR_FRIEND_BY_PUBLIC_KEY_NOT_FOUND + TOX_ERR_FRIEND_BY_PUBLIC_KEY_NOT_FOUND, + } TOX_ERR_FRIEND_BY_PUBLIC_KEY; + /** * Return the friend number associated with that Public Key. * @@ -967,15 +1111,45 @@ typedef enum TOX_ERR_FRIEND_BY_PUBLIC_KEY { */ uint32_t tox_friend_by_public_key(const Tox *tox, const uint8_t *public_key, TOX_ERR_FRIEND_BY_PUBLIC_KEY *error); +/** + * 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); + +/** + * Return the number of friends on the friend list. + * + * This function can be used to determine how much memory to allocate for + * tox_self_get_friend_list. + */ +size_t tox_self_get_friend_list_size(const Tox *tox); + +/** + * Copy a list of valid friend numbers into an array. + * + * Call tox_self_get_friend_list_size to determine the number of elements to allocate. + * + * @param list A memory region with enough space to hold the friend list. If + * this parameter is NULL, this function has no effect. + */ +void tox_self_get_friend_list(const Tox *tox, uint32_t *friend_list); typedef enum TOX_ERR_FRIEND_GET_PUBLIC_KEY { + + /** + * The function returned successfully. + */ TOX_ERR_FRIEND_GET_PUBLIC_KEY_OK, + /** * No friend with the given number exists on the friend list. */ - TOX_ERR_FRIEND_GET_PUBLIC_KEY_FRIEND_NOT_FOUND + TOX_ERR_FRIEND_GET_PUBLIC_KEY_FRIEND_NOT_FOUND, + } TOX_ERR_FRIEND_GET_PUBLIC_KEY; + /** * Copies the Public Key associated with a given friend number to a byte array. * @@ -988,21 +1162,21 @@ typedef enum TOX_ERR_FRIEND_GET_PUBLIC_KEY { bool tox_friend_get_public_key(const Tox *tox, uint32_t friend_number, uint8_t *public_key, TOX_ERR_FRIEND_GET_PUBLIC_KEY *error); - -/** - * 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 { + + /** + * The function returned successfully. + */ TOX_ERR_FRIEND_GET_LAST_ONLINE_OK, + /** * No friend with the given number exists on the friend list. */ TOX_ERR_FRIEND_GET_LAST_ONLINE_FRIEND_NOT_FOUND, + } TOX_ERR_FRIEND_GET_LAST_ONLINE; + /** * 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. @@ -1011,26 +1185,6 @@ typedef enum TOX_ERR_FRIEND_GET_LAST_ONLINE { */ uint64_t tox_friend_get_last_online(const Tox *tox, uint32_t friend_number, TOX_ERR_FRIEND_GET_LAST_ONLINE *error); -/** - * Return the number of friends on the friend list. - * - * This function can be used to determine how much memory to allocate for - * tox_self_get_friend_list. - */ -size_t tox_self_get_friend_list_size(const Tox *tox); - - -/** - * Copy a list of valid friend numbers into an array. - * - * Call tox_self_get_friend_list_size to determine the number of elements to allocate. - * - * @param list A memory region with enough space to hold the friend list. If - * this parameter is NULL, this function has no effect. - */ -void tox_self_get_friend_list(const Tox *tox, uint32_t *list); - - /******************************************************************************* * @@ -1039,27 +1193,35 @@ void tox_self_get_friend_list(const Tox *tox, uint32_t *list); ******************************************************************************/ + /** * Common error codes for friend state query functions. */ typedef enum TOX_ERR_FRIEND_QUERY { + + /** + * The function returned successfully. + */ TOX_ERR_FRIEND_QUERY_OK, + /** * The pointer parameter for storing the query result (name, message) was * NULL. Unlike the `_self_` variants of these functions, which have no effect * when a parameter is NULL, these functions return an error in that case. */ TOX_ERR_FRIEND_QUERY_NULL, + /** * The friend_number did not designate a valid friend. */ - TOX_ERR_FRIEND_QUERY_FRIEND_NOT_FOUND + TOX_ERR_FRIEND_QUERY_FRIEND_NOT_FOUND, + } TOX_ERR_FRIEND_QUERY; /** * Return the length of the friend's name. If the friend number is invalid, the - * return value is SIZE_MAX. + * return value is unspecified. * * The return value is equal to the `length` argument received by the last * `friend_name` callback. @@ -1083,8 +1245,6 @@ size_t tox_friend_get_name_size(const Tox *tox, uint32_t friend_number, TOX_ERR_ bool tox_friend_get_name(const Tox *tox, uint32_t friend_number, uint8_t *name, TOX_ERR_FRIEND_QUERY *error); /** - * The function type for the `friend_name` callback. - * * @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. @@ -1093,13 +1253,13 @@ bool tox_friend_get_name(const Tox *tox, uint32_t friend_number, 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); + /** * Set the callback for the `friend_name` event. Pass NULL to unset. * * This event is triggered when a friend changes their name. */ -void tox_callback_friend_name(Tox *tox, tox_friend_name_cb *function, void *user_data); - +void tox_callback_friend_name(Tox *tox, tox_friend_name_cb *callback, void *user_data); /** * Return the length of the friend's status message. If the friend number is @@ -1111,37 +1271,35 @@ size_t tox_friend_get_status_message_size(const Tox *tox, uint32_t friend_number * Write the name of the friend designated by the given friend number to a byte * array. * - * Call tox_friend_get_name_size to determine the allocation size for the `name` + * Call tox_friend_get_status_message_size to determine the allocation size for the `status_name` * parameter. * - * The data written to `message` is equal to the data received by the last + * The data written to `status_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. */ -bool tox_friend_get_status_message(const Tox *tox, uint32_t friend_number, uint8_t *message, +bool tox_friend_get_status_message(const Tox *tox, uint32_t friend_number, uint8_t *status_message, TOX_ERR_FRIEND_QUERY *error); /** - * 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. + * tox_friend_get_status_message would write to its `status_message` parameter. * @param length A value equal to the return value of * tox_friend_get_status_message_size. */ typedef void tox_friend_status_message_cb(Tox *tox, uint32_t friend_number, const uint8_t *message, size_t length, - void *user_data); + void *user_data); + /** * Set the callback for the `friend_status_message` event. Pass NULL to unset. * * This event is triggered when a friend changes their status message. */ -void tox_callback_friend_status_message(Tox *tox, tox_friend_status_message_cb *function, void *user_data); - +void tox_callback_friend_status_message(Tox *tox, tox_friend_status_message_cb *callback, void *user_data); /** * Return the friend's user status (away/busy/...). If the friend number is @@ -1153,21 +1311,19 @@ void tox_callback_friend_status_message(Tox *tox, tox_friend_status_message_cb * TOX_USER_STATUS tox_friend_get_status(const Tox *tox, uint32_t friend_number, TOX_ERR_FRIEND_QUERY *error); /** - * The function type for the `friend_status` callback. - * * @param friend_number The friend number of the friend whose user status * changed. * @param status The new user status. */ typedef void tox_friend_status_cb(Tox *tox, uint32_t friend_number, TOX_USER_STATUS status, void *user_data); + /** * Set the callback for the `friend_status` event. Pass NULL to unset. * * This event is triggered when a friend changes their user status. */ -void tox_callback_friend_status(Tox *tox, tox_friend_status_cb *function, void *user_data); - +void tox_callback_friend_status(Tox *tox, tox_friend_status_cb *callback, void *user_data); /** * Check whether a friend is currently connected to this client. @@ -1184,28 +1340,25 @@ void tox_callback_friend_status(Tox *tox, tox_friend_status_cb *function, void * TOX_CONNECTION tox_friend_get_connection_status(const Tox *tox, uint32_t friend_number, TOX_ERR_FRIEND_QUERY *error); /** - * The function type for the `friend_connection_status` callback. - * * @param friend_number The friend number of the friend whose connection status * changed. * @param connection_status The result of calling * tox_friend_get_connection_status on the passed friend_number. */ typedef void tox_friend_connection_status_cb(Tox *tox, uint32_t friend_number, TOX_CONNECTION connection_status, - void *user_data); + void *user_data); + /** - * Set the callback for the `friend_connection_status` event. Pass NULL to - * unset. + * Set the callback for the `friend_connection_status` event. Pass NULL to unset. * * This event is triggered when a friend goes offline after having been online, * or when a friend goes online. * * This callback is not called when adding friends. It is assumed that when - * adding friends, their connection status is offline. + * adding friends, their connection status is initially offline. */ -void tox_callback_friend_connection_status(Tox *tox, tox_friend_connection_status_cb *function, void *user_data); - +void tox_callback_friend_connection_status(Tox *tox, tox_friend_connection_status_cb *callback, void *user_data); /** * Check whether a friend is currently typing a message. @@ -1219,8 +1372,6 @@ void tox_callback_friend_connection_status(Tox *tox, tox_friend_connection_statu 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. - * * @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 @@ -1228,12 +1379,13 @@ bool tox_friend_get_typing(const Tox *tox, uint32_t friend_number, TOX_ERR_FRIEN */ 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. * * This event is triggered when a friend starts or stops typing. */ -void tox_callback_friend_typing(Tox *tox, tox_friend_typing_cb *function, void *user_data); +void tox_callback_friend_typing(Tox *tox, tox_friend_typing_cb *callback, void *user_data); /******************************************************************************* @@ -1243,90 +1395,115 @@ void tox_callback_friend_typing(Tox *tox, tox_friend_typing_cb *function, void * ******************************************************************************/ + typedef enum TOX_ERR_SET_TYPING { + + /** + * The function returned successfully. + */ TOX_ERR_SET_TYPING_OK, + /** * The friend number did not designate a valid friend. */ - TOX_ERR_SET_TYPING_FRIEND_NOT_FOUND + TOX_ERR_SET_TYPING_FRIEND_NOT_FOUND, + } TOX_ERR_SET_TYPING; + /** * Set the client's typing status for a friend. * * The client is responsible for turning it on or off. * * @param friend_number The friend to which the client is typing a message. - * @param is_typing The typing status. True means the client is typing. + * @param typing The typing status. True means the client is typing. * * @return true on success. */ -bool tox_self_set_typing(Tox *tox, uint32_t friend_number, bool is_typing, TOX_ERR_SET_TYPING *error); - +bool tox_self_set_typing(Tox *tox, uint32_t friend_number, bool typing, TOX_ERR_SET_TYPING *error); typedef enum TOX_ERR_FRIEND_SEND_MESSAGE { + + /** + * The function returned successfully. + */ TOX_ERR_FRIEND_SEND_MESSAGE_OK, + + /** + * One of the arguments to the function was NULL when it was not expected. + */ TOX_ERR_FRIEND_SEND_MESSAGE_NULL, + /** * The friend number did not designate a valid friend. */ TOX_ERR_FRIEND_SEND_MESSAGE_FRIEND_NOT_FOUND, + /** * This client is currently not connected to the friend. */ TOX_ERR_FRIEND_SEND_MESSAGE_FRIEND_NOT_CONNECTED, + /** * An allocation error occurred while increasing the send queue size. */ TOX_ERR_FRIEND_SEND_MESSAGE_SENDQ, + /** * Message length exceeded TOX_MAX_MESSAGE_LENGTH. */ TOX_ERR_FRIEND_SEND_MESSAGE_TOO_LONG, + /** * Attempted to send a zero-length message. */ - TOX_ERR_FRIEND_SEND_MESSAGE_EMPTY + TOX_ERR_FRIEND_SEND_MESSAGE_EMPTY, + } TOX_ERR_FRIEND_SEND_MESSAGE; + /** * Send a text chat message to an online friend. * * This function creates a chat message packet and pushes it into the send * queue. * - * Type corresponds to the message type, for a list of valid types see TOX_MESSAGE_TYPE. - * * The message length may not exceed TOX_MAX_MESSAGE_LENGTH. Larger messages * must be split by the client and sent as separate messages. Other clients can * then reassemble the fragments. Messages may not be empty. * * The return value of this function is the message ID. If a read receipt is - * received, the triggered `read_receipt` event will be passed this message ID. + * received, the triggered `friend_read_receipt` event will be passed this message ID. * * Message IDs are unique per friend. The first message ID is 0. Message IDs are * incremented by 1 each time a message is sent. If UINT32_MAX messages were * sent, the next message ID is 0. + * + * @param type Message type (normal, action, ...). + * @param friend_number The friend number of the friend to send the message to. + * @param message A non-NULL pointer to the first element of a byte array + * containing the message text. + * @param length Length of the message to be sent. */ 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); /** - * The function type for the `read_receipt` callback. - * * @param friend_number The friend number of the friend who received the message. * @param message_id The message ID as returned from tox_friend_send_message * corresponding to the message sent. */ typedef void tox_friend_read_receipt_cb(Tox *tox, uint32_t friend_number, uint32_t message_id, void *user_data); + /** - * Set the callback for the `read_receipt` event. Pass NULL to unset. + * Set the callback for the `friend_read_receipt` event. Pass NULL to unset. * * This event is triggered when the friend receives the message sent with * tox_friend_send_message with the corresponding message ID. */ -void tox_callback_friend_read_receipt(Tox *tox, tox_friend_read_receipt_cb *function, void *user_data); +void tox_callback_friend_read_receipt(Tox *tox, tox_friend_read_receipt_cb *callback, void *user_data); /******************************************************************************* @@ -1336,41 +1513,46 @@ void tox_callback_friend_read_receipt(Tox *tox, tox_friend_read_receipt_cb *func ******************************************************************************/ + /** - * The function type for the `friend_request` callback. - * * @param public_key The Public Key of the user who sent the friend request. + * @param time_delta A delta in seconds between when the message was composed + * and when it is being transmitted. For messages that are sent immediately, + * it will be 0. If a message was written and couldn't be sent immediately + * (due to a connection failure, for example), the time_delta is an + * approximation of when it was composed. * @param message The message they sent along with the request. * @param length The size of the message byte array. */ typedef void tox_friend_request_cb(Tox *tox, const uint8_t *public_key, const uint8_t *message, size_t length, void *user_data); + /** * Set the callback for the `friend_request` event. Pass NULL to unset. * * This event is triggered when a friend request is received. */ -void tox_callback_friend_request(Tox *tox, tox_friend_request_cb *function, void *user_data); - +void tox_callback_friend_request(Tox *tox, tox_friend_request_cb *callback, void *user_data); /** - * The function type for the `friend_message` callback. - * * @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 time_delta Time between composition and sending. * @param message The message data they sent. * @param length The size of the message byte array. + * + * @see friend_request for more information on time_delta. */ 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. * * 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); +void tox_callback_friend_message(Tox *tox, tox_friend_message_cb *callback, void *user_data); /******************************************************************************* @@ -1380,12 +1562,36 @@ void tox_callback_friend_message(Tox *tox, tox_friend_message_cb *function, void ******************************************************************************/ + +/** + * Generates a cryptographic hash of the given data. + * + * This function may be used by clients for any purpose, but is provided + * primarily for validating cached avatars. This use is highly recommended to + * avoid unnecessary avatar updates. + * + * If hash is NULL or data is NULL while length is not 0 the function returns false, + * otherwise it returns true. + * + * This function is a wrapper to internal message-digest functions. + * + * @param hash A valid memory location the hash data. It must be at least + * TOX_HASH_LENGTH bytes in size. + * @param data Data to be hashed or NULL. + * @param length Size of the data array or 0. + * + * @return true if hash was not NULL. + */ +bool tox_hash(uint8_t *hash, const uint8_t *data, size_t length); + 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. @@ -1403,41 +1609,22 @@ enum TOX_FILE_KIND { * 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. + * When file_size is set to 0 in the transfer request it means that the client + * has no avatar. */ - TOX_FILE_KIND_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. - * - * 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. - * - * This function is a wrapper to internal message-digest functions. - * - * @param hash A valid memory location the hash data. It must be at least - * TOX_HASH_LENGTH bytes in size. - * @param data Data to be hashed or NULL. - * @param length Size of the data array or 0. - * - * @return true if hash was not NULL. - */ -bool tox_hash(uint8_t *hash, 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 @@ -1445,47 +1632,62 @@ typedef enum TOX_FILE_CONTROL { * 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_CANCEL, + } TOX_FILE_CONTROL; typedef enum TOX_ERR_FILE_CONTROL { + + /** + * The function returned successfully. + */ TOX_ERR_FILE_CONTROL_OK, + /** * The friend_number passed did not designate a valid friend. */ TOX_ERR_FILE_CONTROL_FRIEND_NOT_FOUND, + /** * This client is currently not connected to the friend. */ TOX_ERR_FILE_CONTROL_FRIEND_NOT_CONNECTED, + /** * No file transfer with the given file number was found for the given friend. */ TOX_ERR_FILE_CONTROL_NOT_FOUND, + /** * A RESUME control was sent, but the file transfer is running normally. */ TOX_ERR_FILE_CONTROL_NOT_PAUSED, + /** * A RESUME control was sent, but the file transfer was paused by the other * party. Only the party that paused the transfer can resume it. */ TOX_ERR_FILE_CONTROL_DENIED, + /** * A PAUSE control was sent, but the file transfer was already paused. */ TOX_ERR_FILE_CONTROL_ALREADY_PAUSED, + /** * Packet queue is full. */ - TOX_ERR_FILE_CONTROL_SENDQ + TOX_ERR_FILE_CONTROL_SENDQ, + } TOX_ERR_FILE_CONTROL; + /** * Sends a file control command to a friend for a given file transfer. * @@ -1499,10 +1701,7 @@ typedef enum TOX_ERR_FILE_CONTROL { 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. * @@ -1514,43 +1713,55 @@ bool tox_file_control(Tox *tox, uint32_t friend_number, uint32_t file_number, TO 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. + * Set the callback for the `file_recv_control` event. Pass NULL to unset. * * This event is triggered when a file control command is received from a * friend. */ -void tox_callback_file_recv_control(Tox *tox, tox_file_recv_control_cb *function, void *user_data); - +void tox_callback_file_recv_control(Tox *tox, tox_file_recv_control_cb *callback, void *user_data); typedef enum TOX_ERR_FILE_SEEK { + + /** + * The function returned successfully. + */ TOX_ERR_FILE_SEEK_OK, + /** * The friend_number passed did not designate a valid friend. */ TOX_ERR_FILE_SEEK_FRIEND_NOT_FOUND, + /** * This client is currently not connected to the friend. */ TOX_ERR_FILE_SEEK_FRIEND_NOT_CONNECTED, + /** * No file transfer with the given file number was found for the given friend. */ TOX_ERR_FILE_SEEK_NOT_FOUND, + /** * File was not in a state where it could be seeked. */ TOX_ERR_FILE_SEEK_DENIED, + /** * Seek position was invalid */ TOX_ERR_FILE_SEEK_INVALID_POSITION, + /** * Packet queue is full. */ - TOX_ERR_FILE_SEEK_SENDQ + TOX_ERR_FILE_SEEK_SENDQ, + } TOX_ERR_FILE_SEEK; + /** * Sends a file seek control command to a friend for a given file transfer. * @@ -1562,26 +1773,33 @@ typedef enum TOX_ERR_FILE_SEEK { * @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); +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 { + + /** + * The function returned successfully. + */ 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_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. + * transferred to or received from. * @param file_number The friend-specific identifier for the file transfer. * @param file_id A memory region of at least TOX_FILE_ID_LENGTH bytes. If * this parameter is NULL, this function has no effect. @@ -1591,6 +1809,7 @@ typedef enum TOX_ERR_FILE_GET { 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 @@ -1598,36 +1817,51 @@ bool tox_file_get_file_id(const Tox *tox, uint32_t friend_number, uint32_t file_ ******************************************************************************/ + typedef enum TOX_ERR_FILE_SEND { + + /** + * The function returned successfully. + */ TOX_ERR_FILE_SEND_OK, + + /** + * One of the arguments to the function was NULL when it was not expected. + */ TOX_ERR_FILE_SEND_NULL, + /** * The friend_number passed did not designate a valid friend. */ TOX_ERR_FILE_SEND_FRIEND_NOT_FOUND, + /** * This client is currently not connected to the friend. */ TOX_ERR_FILE_SEND_FRIEND_NOT_CONNECTED, + /** * Filename length exceeded TOX_MAX_FILENAME_LENGTH bytes. */ TOX_ERR_FILE_SEND_NAME_TOO_LONG, + /** * Too many ongoing transfers. The maximum number of concurrent file transfers * is 256 per friend per direction (sending and receiving). */ - TOX_ERR_FILE_SEND_TOO_MANY + TOX_ERR_FILE_SEND_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. + * 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 + * If a non-UINT64_MAX file size is provided, it can be used by both sides to + * determine the sending progress. File size can be set to UINT64_MAX for streaming * data of unknown size. * * File transmission occurs in chunks, which are requested through the @@ -1641,13 +1875,14 @@ typedef enum TOX_ERR_FILE_SEND { * 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. + * - 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 @@ -1675,52 +1910,65 @@ typedef enum TOX_ERR_FILE_SEND { * * @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 + * 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 { + + /** + * The function returned successfully. + */ TOX_ERR_FILE_SEND_CHUNK_OK, + /** * The length parameter was non-zero, but data was NULL. */ TOX_ERR_FILE_SEND_CHUNK_NULL, + /** * The friend_number passed did not designate a valid friend. */ TOX_ERR_FILE_SEND_CHUNK_FRIEND_NOT_FOUND, + /** * This client is currently not connected to the friend. */ TOX_ERR_FILE_SEND_CHUNK_FRIEND_NOT_CONNECTED, + /** * No file transfer with the given file number was found for the given friend. */ TOX_ERR_FILE_SEND_CHUNK_NOT_FOUND, + /** * File transfer was found but isn't in a transferring state: (paused, done, * broken, etc...) (happens only when not called from the request chunk callback). */ TOX_ERR_FILE_SEND_CHUNK_NOT_TRANSFERRING, + /** * Attempted to send more or less data than requested. The requested data size is * adjusted according to maximum transmission unit and the expected end of * the file. Trying to send less or more than requested will return this error. */ TOX_ERR_FILE_SEND_CHUNK_INVALID_LENGTH, + /** * Packet queue is full. */ TOX_ERR_FILE_SEND_CHUNK_SENDQ, + /** * Position parameter was wrong. */ - TOX_ERR_FILE_SEND_CHUNK_WRONG_POSITION + TOX_ERR_FILE_SEND_CHUNK_WRONG_POSITION, + } TOX_ERR_FILE_SEND_CHUNK; + /** * Send a chunk of file data to a friend. * @@ -1740,10 +1988,7 @@ typedef enum TOX_ERR_FILE_SEND_CHUNK { 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. @@ -1768,10 +2013,13 @@ bool tox_file_send_chunk(Tox *tox, uint32_t friend_number, uint32_t file_number, 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); + /** * Set the callback for the `file_chunk_request` event. Pass NULL to unset. + * + * This event is triggered when Core is ready to send more file data. */ -void tox_callback_file_chunk_request(Tox *tox, tox_file_chunk_request_cb *function, void *user_data); +void tox_callback_file_chunk_request(Tox *tox, tox_file_chunk_request_cb *callback, void *user_data); /******************************************************************************* @@ -1781,12 +2029,8 @@ void tox_callback_file_chunk_request(Tox *tox, tox_file_chunk_request_cb *functi ******************************************************************************/ + /** - * 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 @@ -1798,27 +2042,24 @@ void tox_callback_file_chunk_request(Tox *tox, tox_file_chunk_request_cb *functi * @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, + * @param file_size Size in bytes of the file the client wants to send, * UINT64_MAX if unknown or streaming. + * @param filename Name of the file. Does not need to be the actual name. This + * name will be sent along with the file send request. * @param filename_length Size in bytes of the filename. */ -typedef void tox_file_recv_cb(Tox *tox, 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); +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. + * Set the callback for the `file_recv` event. Pass NULL to unset. * * This event is triggered when a file transfer request is received. */ -void tox_callback_file_recv(Tox *tox, tox_file_recv_cb *function, void *user_data); - +void tox_callback_file_recv(Tox *tox, tox_file_recv_cb *callback, void *user_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. - * * 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. @@ -1837,10 +2078,14 @@ void tox_callback_file_recv(Tox *tox, tox_file_recv_cb *function, void *user_dat 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); + /** - * Set the callback for the `file_receive_chunk` event. Pass NULL to unset. + * Set the callback for the `file_recv_chunk` event. Pass NULL to unset. + * + * This event is first triggered when a file transfer request is received, and + * subsequently when a chunk of file data for an accepted request was received. */ -void tox_callback_file_recv_chunk(Tox *tox, tox_file_recv_chunk_cb *function, void *user_data); +void tox_callback_file_recv_chunk(Tox *tox, tox_file_recv_chunk_cb *callback, void *user_data); /******************************************************************************* @@ -1850,13 +2095,16 @@ void tox_callback_file_recv_chunk(Tox *tox, tox_file_recv_chunk_cb *function, vo ******************************************************************************/ -/****************************************************************************** + + +/******************************************************************************* * * :: Group chat message sending and receiving * ******************************************************************************/ -/* See: tox_old.h for now. */ + + /******************************************************************************* * @@ -1865,34 +2113,50 @@ void tox_callback_file_recv_chunk(Tox *tox, tox_file_recv_chunk_cb *function, vo ******************************************************************************/ + typedef enum TOX_ERR_FRIEND_CUSTOM_PACKET { + + /** + * The function returned successfully. + */ TOX_ERR_FRIEND_CUSTOM_PACKET_OK, + + /** + * One of the arguments to the function was NULL when it was not expected. + */ TOX_ERR_FRIEND_CUSTOM_PACKET_NULL, + /** * The friend number did not designate a valid friend. */ TOX_ERR_FRIEND_CUSTOM_PACKET_FRIEND_NOT_FOUND, + /** * This client is currently not connected to the friend. */ TOX_ERR_FRIEND_CUSTOM_PACKET_FRIEND_NOT_CONNECTED, + /** * The first byte of data was not 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. + * Packet queue is full. */ - TOX_ERR_FRIEND_CUSTOM_PACKET_SENDQ + TOX_ERR_FRIEND_CUSTOM_PACKET_SENDQ, + } TOX_ERR_FRIEND_CUSTOM_PACKET; @@ -1920,22 +2184,6 @@ bool tox_friend_send_lossy_packet(Tox *tox, uint32_t friend_number, const uint8_ TOX_ERR_FRIEND_CUSTOM_PACKET *error); /** - * 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); - -/** - * 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); - - -/** * Send a custom lossless packet to a friend. * * The first byte of data must be in the range 160-191. Maximum length of a @@ -1955,20 +2203,34 @@ bool tox_friend_send_lossless_packet(Tox *tox, uint32_t friend_number, const uin TOX_ERR_FRIEND_CUSTOM_PACKET *error); /** - * The function type for the `friend_lossless_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); + + +/** + * Set the callback for the `friend_lossy_packet` event. Pass NULL to unset. * + */ +void tox_callback_friend_lossy_packet(Tox *tox, tox_friend_lossy_packet_cb *callback, void *user_data); + +/** * @param friend_number The friend number of the friend who sent the packet. * @param data A byte array containing the received packet data. * @param length The length of the packet data byte array. */ typedef void tox_friend_lossless_packet_cb(Tox *tox, uint32_t friend_number, const uint8_t *data, size_t length, - void *user_data); + void *user_data); + /** * Set the callback for the `friend_lossless_packet` event. Pass NULL to unset. + * */ -void tox_callback_friend_lossless_packet(Tox *tox, tox_friend_lossless_packet_cb *function, void *user_data); - +void tox_callback_friend_lossless_packet(Tox *tox, tox_friend_lossless_packet_cb *callback, void *user_data); /******************************************************************************* @@ -1978,11 +2240,12 @@ void tox_callback_friend_lossless_packet(Tox *tox, tox_friend_lossless_packet_cb ******************************************************************************/ + /** * 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. + * the bound port (from tox_self_get_udp_port) to run a temporary bootstrap node. * * Be aware that every time a new instance is created, the DHT public key * changes, meaning this cannot be used to run a permanent bootstrap node. @@ -1992,15 +2255,21 @@ void tox_callback_friend_lossless_packet(Tox *tox, tox_friend_lossless_packet_cb */ void tox_self_get_dht_id(const Tox *tox, uint8_t *dht_id); - typedef enum TOX_ERR_GET_PORT { + + /** + * The function returned successfully. + */ TOX_ERR_GET_PORT_OK, + /** * The instance was not bound to any port. */ - TOX_ERR_GET_PORT_NOT_BOUND + TOX_ERR_GET_PORT_NOT_BOUND, + } TOX_ERR_GET_PORT; + /** * Return the UDP port this Tox instance is bound to. */ |