diff options
| author | aunsane <aunsane@gmail.com> | 2017-02-23 15:04:09 +0300 |
|---|---|---|
| committer | aunsane <aunsane@gmail.com> | 2017-02-23 15:04:09 +0300 |
| commit | 6e1c3bb16e5b0d396810a1a534f4854d55bcf4ac (patch) | |
| tree | d3b0968dbd625150ff95896d5e3d3faf4ada380c /protocols/Tox/include | |
| parent | 81f96a9093d92678a9c78ed248ec966fd941a69c (diff) | |
Tox: it seems that irungentoo/toxcore no longer be updated, so we switch to TokTok/c-toxcore
Diffstat (limited to 'protocols/Tox/include')
| -rw-r--r-- | protocols/Tox/include/tox.h | 832 | ||||
| -rw-r--r-- | protocols/Tox/include/tox_old.h | 173 | ||||
| -rw-r--r-- | protocols/Tox/include/toxav.h | 274 | ||||
| -rw-r--r-- | protocols/Tox/include/toxdns.h | 34 | ||||
| -rw-r--r-- | protocols/Tox/include/toxencryptsave.h | 402 |
5 files changed, 1172 insertions, 543 deletions
diff --git a/protocols/Tox/include/tox.h b/protocols/Tox/include/tox.h index 52e851b5eb..c697be64e9 100644 --- a/protocols/Tox/include/tox.h +++ b/protocols/Tox/include/tox.h @@ -1,30 +1,30 @@ -/* tox.h - * +/* * The Tox public API. + */ + +/* + * Copyright © 2016-2017 The TokTok team. + * Copyright © 2013 Tox project. * - * Copyright (C) 2013 Tox project All Rights Reserved. - * - * This file is part of Tox. - * - * Tox is free software: you can redistribute it and/or modify - * it under the terms of the GNU General Public License as published by - * the Free Software Foundation, either version 3 of the License, or - * (at your option) any later version. + * This file is part of Tox, the free peer to peer instant messenger. * - * Tox is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. + * Tox is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. * - * You should have received a copy of the GNU General Public License - * along with Tox. If not, see <http://www.gnu.org/licenses/>. + * Tox is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. * + * You should have received a copy of the GNU General Public License + * along with Tox. If not, see <http://www.gnu.org/licenses/>. */ - #ifndef TOX_H #define TOX_H -//#include <stdbool.h> +#include <stdbool.h> #include <stddef.h> #include <stdint.h> @@ -35,8 +35,8 @@ extern "C" { /******************************************************************************* * `tox.h` SHOULD *NOT* BE EDITED MANUALLY – any changes should be made to * - * `tox.in.h`, located in `other/apidsl/`. For instructions on how to * - * generate `tox.h` from `tox.in.h` please refer to `other/apidsl/README.md` * + * `tox.api.h`, located in `toxcore/`. For instructions on how to * + * generate `tox.h` from `tox.api.h` please refer to `docs/apidsl.md` * ******************************************************************************/ @@ -75,6 +75,9 @@ extern "C" { * enumeration value is outside the valid range of the type. If possible, the * function will try to use a sane default, but there will be no error code, * and one possible action for the function to take is to have no effect. + * + * Integer constants and the memory layout of publicly exposed structs are not + * part of the ABI. */ /** \subsection events Events and callbacks * @@ -84,6 +87,19 @@ extern "C" { * callback will result in no callback being registered for that event. Only * one callback per event can be registered, so if a client needs multiple * event listeners, it needs to implement the dispatch functionality itself. + * + * The last argument to a callback is the user data pointer. It is passed from + * tox_iterate to each callback in sequence. + * + * The user data pointer is never stored or dereferenced by any library code, so + * can be any pointer, including NULL. Callbacks must all operate on the same + * object type. In the apidsl code (tox.in.h), this is denoted with `any`. The + * `any` in tox_iterate must be the same `any` as in all callbacks. In C, + * lacking parametric polymorphism, this is a pointer to void. + * + * Old style callbacks that are registered together with a user data pointer + * receive that pointer as argument when they are called. They can each have + * their own user data pointer of their own type. */ /** \subsection threading Threading implications * @@ -142,55 +158,52 @@ typedef struct Tox Tox; /** * The major version number. Incremented when the API or ABI changes in an * incompatible way. + * + * The function variants of these constants return the version number of the + * library. They can be used to display the Tox library version or to check + * whether the client is compatible with the dynamically linked version of Tox. */ -#define TOX_VERSION_MAJOR 0u +#define TOX_VERSION_MAJOR 0 + +uint32_t tox_version_major(void); /** * 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 +#define TOX_VERSION_MINOR 1 + +uint32_t tox_version_minor(void); /** * The patch or revision number. Incremented when bugfixes are applied without * changing any functionality or API or ABI. */ -#define TOX_VERSION_PATCH 0u - -/** - * A macro to check at preprocessing time whether the client code is compatible - * with the installed version of Tox. - */ -#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))) +#define TOX_VERSION_PATCH 5 -/** - * 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] - -/** - * 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. - */ -uint32_t tox_version_major(void); - -/** - * Return the minor version number of the library. - */ -uint32_t tox_version_minor(void); +uint32_t tox_version_patch(void); /** - * Return the patch number of the library. - */ -uint32_t tox_version_patch(void); + * A macro to check at preprocessing time whether the client code is compatible + * with the installed version of Tox. Leading zeros in the version number are + * ignored. E.g. 0.1.5 is to 0.1.4 what 1.5 is to 1.4, that is: it can add new + * features, but can't break the API. + */ +#define TOX_VERSION_IS_API_COMPATIBLE(MAJOR, MINOR, PATCH) \ + (TOX_VERSION_MAJOR > 0 && TOX_VERSION_MAJOR == MAJOR) && ( \ + /* 1.x.x, 2.x.x, etc. with matching major version. */ \ + TOX_VERSION_MINOR > MINOR || \ + TOX_VERSION_MINOR == MINOR && TOX_VERSION_PATCH >= PATCH \ + ) || (TOX_VERSION_MAJOR == 0 && MAJOR == 0) && ( \ + /* 0.x.x makes minor behave like major above. */ \ + (TOX_VERSION_MINOR > 0 && TOX_VERSION_MINOR == MINOR) && ( \ + TOX_VERSION_PATCH >= PATCH \ + ) || (TOX_VERSION_MINOR == 0 && MINOR == 0) && ( \ + /* 0.0.x and 0.0.y are only compatible if x == y. */ \ + TOX_VERSION_PATCH == PATCH \ + ) \ + ) /** * Return whether the compiled library version is compatible with the passed @@ -210,6 +223,10 @@ bool tox_version_is_compatible(uint32_t major, uint32_t minor, uint32_t patch); * * :: Numeric constants * + * The values of these are not part of the ABI. Prefer to use the function + * versions of them for code that should remain compatible with future versions + * of toxcore. + * ******************************************************************************/ @@ -219,11 +236,15 @@ bool tox_version_is_compatible(uint32_t major, uint32_t minor, uint32_t patch); */ #define TOX_PUBLIC_KEY_SIZE 32 +uint32_t tox_public_key_size(void); + /** * The size of a Tox Secret Key in bytes. */ #define TOX_SECRET_KEY_SIZE 32 +uint32_t tox_secret_key_size(void); + /** * 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)]. @@ -234,46 +255,64 @@ bool tox_version_is_compatible(uint32_t major, uint32_t minor, uint32_t patch); */ #define TOX_ADDRESS_SIZE (TOX_PUBLIC_KEY_SIZE + sizeof(uint32_t) + sizeof(uint16_t)) +uint32_t tox_address_size(void); + /** * Maximum length of a nickname in bytes. */ #define TOX_MAX_NAME_LENGTH 128 +uint32_t tox_max_name_length(void); + /** * Maximum length of a status message in bytes. */ #define TOX_MAX_STATUS_MESSAGE_LENGTH 1007 +uint32_t tox_max_status_message_length(void); + /** * Maximum length of a friend request message in bytes. */ #define TOX_MAX_FRIEND_REQUEST_LENGTH 1016 +uint32_t tox_max_friend_request_length(void); + /** * Maximum length of a single message after which it should be split. */ #define TOX_MAX_MESSAGE_LENGTH 1372 +uint32_t tox_max_message_length(void); + /** - * Maximum size of custom packets. TODO: should be LENGTH? + * Maximum size of custom packets. TODO(iphydf): should be LENGTH? */ #define TOX_MAX_CUSTOM_PACKET_SIZE 1373 +uint32_t tox_max_custom_packet_size(void); + /** * The number of bytes in a hash generated by tox_hash. */ #define TOX_HASH_LENGTH 32 +uint32_t tox_hash_length(void); + /** * The number of bytes in a file id. */ #define TOX_FILE_ID_LENGTH 32 +uint32_t tox_file_id_length(void); + /** * Maximum file name length for file transfers. */ #define TOX_MAX_FILENAME_LENGTH 255 +uint32_t tox_max_filename_length(void); + /******************************************************************************* * @@ -309,7 +348,7 @@ typedef enum TOX_USER_STATUS { /** - * Represents message types for tox_friend_send_message and group chat + * Represents message types for tox_friend_send_message and conference * messages. */ typedef enum TOX_MESSAGE_TYPE { @@ -371,12 +410,12 @@ typedef enum TOX_SAVEDATA_TYPE { TOX_SAVEDATA_TYPE_NONE, /** - * Savedata is one that was obtained from tox_get_savedata + * 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 + * Savedata is a secret key of length TOX_SECRET_KEY_SIZE. */ TOX_SAVEDATA_TYPE_SECRET_KEY, @@ -384,9 +423,71 @@ typedef enum 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. + * Severity level of log messages. + */ +typedef enum TOX_LOG_LEVEL { + + /** + * Very detailed traces including all network activity. + */ + TOX_LOG_LEVEL_TRACE, + + /** + * Debug messages such as which port we bind to. + */ + TOX_LOG_LEVEL_DEBUG, + + /** + * Informational log messages such as video call status changes. + */ + TOX_LOG_LEVEL_INFO, + + /** + * Warnings about internal inconsistency or logic errors. + */ + TOX_LOG_LEVEL_WARNING, + + /** + * Severe unexpected errors caused by external or internal inconsistency. + */ + TOX_LOG_LEVEL_ERROR, + +} TOX_LOG_LEVEL; + + +/** + * This event is triggered when the toxcore library logs an internal message. + * This is mostly useful for debugging. This callback can be called from any + * function, not just tox_iterate. This means the user data lifetime must at + * least extend between registering and unregistering it or tox_kill. + * + * Other toxcore modules such as toxav may concurrently call this callback at + * any time. Thus, user code must make sure it is equipped to handle concurrent + * execution, e.g. by employing appropriate mutex locking. + * + * @param level The severity of the log message. + * @param file The source file from which the message originated. + * @param line The source line from which the message originated. + * @param func The function from which the message originated. + * @param message The log message. + * @param user_data The user data pointer passed to tox_new in options. + */ +typedef void tox_log_cb(Tox *tox, TOX_LOG_LEVEL level, const char *file, uint32_t line, const char *func, + const char *message, void *user_data); + + +/** + * This struct contains all the startup options for Tox. You must tox_options_new to + * allocate an object of this type. + * + * WARNING: Although this struct happens to be visible in the API, it is + * effectively private. Do not allocate this yourself or access members + * directly, as it *will* break binary compatibility frequently. + * + * @deprecated The memory layout of this struct (size, alignment, and field + * order) is not part of the ABI. To remain compatible, prefer to use tox_options_new to + * allocate the object and accessor functions to set the members. The struct + * will become opaque (i.e. the definition will become private) in v0.2.0. */ struct Tox_Options { @@ -412,6 +513,14 @@ struct Tox_Options { /** + * Enable local network peer discovery. + * + * Disabling this will cause Tox to not look for peers on the local network. + */ + bool local_discovery_enabled; + + + /** * Pass communications through a proxy. */ TOX_PROXY_TYPE proxy_type; @@ -425,6 +534,9 @@ struct Tox_Options { * (255 chars + 1 NUL byte). * * This member is ignored (it can be NULL) if proxy_type is TOX_PROXY_TYPE_NONE. + * + * The data pointed at by this member is owned by the user, so must + * outlive the options object. */ const char *proxy_host; @@ -474,6 +586,12 @@ struct Tox_Options { /** + * Enables or disables UDP hole-punching in toxcore. (Default: enabled). + */ + bool hole_punching_enabled; + + + /** * The type of savedata to load from. */ TOX_SAVEDATA_TYPE savedata_type; @@ -481,6 +599,9 @@ struct Tox_Options { /** * The savedata. + * + * The data pointed at by this member is owned by the user, so must + * outlive the options object. */ const uint8_t *savedata_data; @@ -490,9 +611,81 @@ struct Tox_Options { */ size_t savedata_length; + + /** + * Logging callback for the new tox instance. + */ + tox_log_cb *log_callback; + + + /** + * User data pointer passed to the logging callback. + */ + void *log_user_data; + }; +bool tox_options_get_ipv6_enabled(const struct Tox_Options *options); + +void tox_options_set_ipv6_enabled(struct Tox_Options *options, bool ipv6_enabled); + +bool tox_options_get_udp_enabled(const struct Tox_Options *options); + +void tox_options_set_udp_enabled(struct Tox_Options *options, bool udp_enabled); + +bool tox_options_get_local_discovery_enabled(const struct Tox_Options *options); + +void tox_options_set_local_discovery_enabled(struct Tox_Options *options, bool local_discovery_enabled); + +TOX_PROXY_TYPE tox_options_get_proxy_type(const struct Tox_Options *options); + +void tox_options_set_proxy_type(struct Tox_Options *options, TOX_PROXY_TYPE type); + +const char *tox_options_get_proxy_host(const struct Tox_Options *options); + +void tox_options_set_proxy_host(struct Tox_Options *options, const char *host); + +uint16_t tox_options_get_proxy_port(const struct Tox_Options *options); + +void tox_options_set_proxy_port(struct Tox_Options *options, uint16_t port); + +uint16_t tox_options_get_start_port(const struct Tox_Options *options); + +void tox_options_set_start_port(struct Tox_Options *options, uint16_t start_port); + +uint16_t tox_options_get_end_port(const struct Tox_Options *options); + +void tox_options_set_end_port(struct Tox_Options *options, uint16_t end_port); + +uint16_t tox_options_get_tcp_port(const struct Tox_Options *options); + +void tox_options_set_tcp_port(struct Tox_Options *options, uint16_t tcp_port); + +bool tox_options_get_hole_punching_enabled(const struct Tox_Options *options); + +void tox_options_set_hole_punching_enabled(struct Tox_Options *options, bool hole_punching_enabled); + +TOX_SAVEDATA_TYPE tox_options_get_savedata_type(const struct Tox_Options *options); + +void tox_options_set_savedata_type(struct Tox_Options *options, TOX_SAVEDATA_TYPE type); + +const uint8_t *tox_options_get_savedata_data(const struct Tox_Options *options); + +void tox_options_set_savedata_data(struct Tox_Options *options, const uint8_t *data, size_t length); + +size_t tox_options_get_savedata_length(const struct Tox_Options *options); + +void tox_options_set_savedata_length(struct Tox_Options *options, size_t length); + +tox_log_cb *tox_options_get_log_callback(const struct Tox_Options *options); + +void tox_options_set_log_callback(struct Tox_Options *options, tox_log_cb *callback); + +void *tox_options_get_log_user_data(const struct Tox_Options *options); + +void tox_options_set_log_user_data(struct Tox_Options *options, void *user_data); + /** * Initialises a Tox_Options object with the default options. * @@ -651,8 +844,8 @@ size_t tox_get_savedata_size(const Tox *tox); /** * Store all information associated with the tox instance to a byte array. * - * @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 + * @param savedata A memory region large enough to store the tox instance + * data. Call tox_get_savedata_size to find the number of bytes required. If this parameter * is NULL, this function has no effect. */ void tox_get_savedata(const Tox *tox, uint8_t *savedata); @@ -774,9 +967,9 @@ typedef void tox_self_connection_status_cb(Tox *tox, TOX_CONNECTION connection_s * amounts of time. Clients should therefore not immediately bootstrap on * receiving a disconnect. * - * TODO: how long should a client wait before bootstrapping again? + * TODO(iphydf): how long should a client wait before bootstrapping again? */ -void tox_callback_self_connection_status(Tox *tox, tox_self_connection_status_cb *callback, void *user_data); +void tox_callback_self_connection_status(Tox *tox, tox_self_connection_status_cb *callback); /** * Return the time in milliseconds before tox_iterate() should be called again @@ -788,7 +981,7 @@ uint32_t tox_iteration_interval(const Tox *tox); * The main loop that needs to be run in intervals of tox_iteration_interval() * milliseconds. */ -void tox_iterate(Tox *tox); +void tox_iterate(Tox *tox, void *user_data); /******************************************************************************* @@ -811,14 +1004,17 @@ 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. + * Set the 4-byte nospam part of the address. This value is expected in host + * byte order. I.e. 0x12345678 will form the bytes [12, 34, 56, 78] in the + * nospam part of the Tox friend address. * * @param nospam Any 32 bit unsigned integer. */ void tox_self_set_nospam(Tox *tox, uint32_t nospam); /** - * Get the 4-byte nospam part of the address. + * Get the 4-byte nospam part of the address. This value is returned in host + * byte order. */ uint32_t tox_self_get_nospam(const Tox *tox); @@ -936,15 +1132,15 @@ size_t tox_self_get_status_message_size(const Tox *tox); * 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. + * @param status_message A valid memory location large enough to hold the + * status message. If this parameter is NULL, the function has no effect. */ void tox_self_get_status_message(const Tox *tox, uint8_t *status_message); /** * Set the client's user status. * - * @param user_status One of the user statuses listed in the enumeration above. + * @param status One of the user statuses listed in the enumeration above. */ void tox_self_set_status(Tox *tox, TOX_USER_STATUS status); @@ -1145,8 +1341,8 @@ size_t tox_self_get_friend_list_size(const Tox *tox); * * 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. + * @param friend_list A memory region with enough space to hold the friend + * list. If this parameter is NULL, this function has no effect. */ void tox_self_get_friend_list(const Tox *tox, uint32_t *friend_list); @@ -1274,7 +1470,7 @@ typedef void tox_friend_name_cb(Tox *tox, uint32_t friend_number, const uint8_t * * This event is triggered when a friend changes their name. */ -void tox_callback_friend_name(Tox *tox, tox_friend_name_cb *callback, void *user_data); +void tox_callback_friend_name(Tox *tox, tox_friend_name_cb *callback); /** * Return the length of the friend's status message. If the friend number is @@ -1314,7 +1510,7 @@ typedef void tox_friend_status_message_cb(Tox *tox, uint32_t friend_number, cons * * This event is triggered when a friend changes their status message. */ -void tox_callback_friend_status_message(Tox *tox, tox_friend_status_message_cb *callback, void *user_data); +void tox_callback_friend_status_message(Tox *tox, tox_friend_status_message_cb *callback); /** * Return the friend's user status (away/busy/...). If the friend number is @@ -1338,7 +1534,7 @@ typedef void tox_friend_status_cb(Tox *tox, uint32_t friend_number, TOX_USER_STA * * This event is triggered when a friend changes their user status. */ -void tox_callback_friend_status(Tox *tox, tox_friend_status_cb *callback, void *user_data); +void tox_callback_friend_status(Tox *tox, tox_friend_status_cb *callback); /** * Check whether a friend is currently connected to this client. @@ -1373,7 +1569,7 @@ typedef void tox_friend_connection_status_cb(Tox *tox, uint32_t friend_number, T * This callback is not called when adding friends. It is assumed that when * adding friends, their connection status is initially offline. */ -void tox_callback_friend_connection_status(Tox *tox, tox_friend_connection_status_cb *callback, void *user_data); +void tox_callback_friend_connection_status(Tox *tox, tox_friend_connection_status_cb *callback); /** * Check whether a friend is currently typing a message. @@ -1400,7 +1596,7 @@ typedef void tox_friend_typing_cb(Tox *tox, uint32_t friend_number, bool is_typi * * This event is triggered when a friend starts or stops typing. */ -void tox_callback_friend_typing(Tox *tox, tox_friend_typing_cb *callback, void *user_data); +void tox_callback_friend_typing(Tox *tox, tox_friend_typing_cb *callback); /******************************************************************************* @@ -1518,7 +1714,7 @@ typedef void tox_friend_read_receipt_cb(Tox *tox, uint32_t friend_number, uint32 * This event is triggered when the friend receives the message sent with * tox_friend_send_message with the corresponding message ID. */ -void tox_callback_friend_read_receipt(Tox *tox, tox_friend_read_receipt_cb *callback, void *user_data); +void tox_callback_friend_read_receipt(Tox *tox, tox_friend_read_receipt_cb *callback); /******************************************************************************* @@ -1531,11 +1727,6 @@ void tox_callback_friend_read_receipt(Tox *tox, tox_friend_read_receipt_cb *call /** * @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. */ @@ -1548,15 +1739,12 @@ typedef void tox_friend_request_cb(Tox *tox, const uint8_t *public_key, const ui * * This event is triggered when a friend request is received. */ -void tox_callback_friend_request(Tox *tox, tox_friend_request_cb *callback, void *user_data); +void tox_callback_friend_request(Tox *tox, tox_friend_request_cb *callback); /** * @param friend_number The friend number of the friend who sent the message. - * @param 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); @@ -1567,7 +1755,7 @@ typedef void tox_friend_message_cb(Tox *tox, uint32_t friend_number, TOX_MESSAGE * * This event is triggered when a message from a friend is received. */ -void tox_callback_friend_message(Tox *tox, tox_friend_message_cb *callback, void *user_data); +void tox_callback_friend_message(Tox *tox, tox_friend_message_cb *callback); /******************************************************************************* @@ -1735,7 +1923,7 @@ typedef void tox_file_recv_control_cb(Tox *tox, uint32_t friend_number, uint32_t * This event is triggered when a file control command is received from a * friend. */ -void tox_callback_file_recv_control(Tox *tox, tox_file_recv_control_cb *callback, void *user_data); +void tox_callback_file_recv_control(Tox *tox, tox_file_recv_control_cb *callback); typedef enum TOX_ERR_FILE_SEEK { @@ -2039,7 +2227,7 @@ typedef void tox_file_chunk_request_cb(Tox *tox, uint32_t friend_number, uint32_ * * 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 *callback, void *user_data); +void tox_callback_file_chunk_request(Tox *tox, tox_file_chunk_request_cb *callback); /******************************************************************************* @@ -2077,7 +2265,7 @@ typedef void tox_file_recv_cb(Tox *tox, uint32_t friend_number, uint32_t file_nu * * This event is triggered when a file transfer request is received. */ -void tox_callback_file_recv(Tox *tox, tox_file_recv_cb *callback, void *user_data); +void tox_callback_file_recv(Tox *tox, tox_file_recv_cb *callback); /** * When length is 0, the transfer is finished and the client should release the @@ -2105,25 +2293,469 @@ typedef void tox_file_recv_chunk_cb(Tox *tox, uint32_t friend_number, uint32_t f * This event is first triggered when a file transfer request is received, and * subsequently when a chunk of file data for an accepted request was received. */ -void tox_callback_file_recv_chunk(Tox *tox, tox_file_recv_chunk_cb *callback, void *user_data); +void tox_callback_file_recv_chunk(Tox *tox, tox_file_recv_chunk_cb *callback); /******************************************************************************* * - * :: Group chat management + * :: Conference management * ******************************************************************************/ +/** + * Conference types for the conference_invite event. + */ +typedef enum TOX_CONFERENCE_TYPE { + + /** + * Text-only conferences that must be accepted with the tox_conference_join function. + */ + TOX_CONFERENCE_TYPE_TEXT, -/******************************************************************************* + /** + * Video conference. The function to accept these is in toxav. + */ + TOX_CONFERENCE_TYPE_AV, + +} TOX_CONFERENCE_TYPE; + + +/** + * The invitation will remain valid until the inviting friend goes offline + * or exits the conference. * - * :: Group chat message sending and receiving + * @param friend_number The friend who invited us. + * @param type The conference type (text only or audio/video). + * @param cookie A piece of data of variable length required to join the + * conference. + * @param length The length of the cookie. + */ +typedef void tox_conference_invite_cb(Tox *tox, uint32_t friend_number, TOX_CONFERENCE_TYPE type, const uint8_t *cookie, + size_t length, void *user_data); + + +/** + * Set the callback for the `conference_invite` event. Pass NULL to unset. * - ******************************************************************************/ + * This event is triggered when the client is invited to join a conference. + */ +void tox_callback_conference_invite(Tox *tox, tox_conference_invite_cb *callback); + +/** + * @param conference_number The conference number of the conference the message is intended for. + * @param peer_number The ID of the peer who sent the message. + * @param type The type of message (normal, action, ...). + * @param message The message data. + * @param length The length of the message. + */ +typedef void tox_conference_message_cb(Tox *tox, uint32_t conference_number, uint32_t peer_number, + TOX_MESSAGE_TYPE type, const uint8_t *message, size_t length, void *user_data); + + +/** + * Set the callback for the `conference_message` event. Pass NULL to unset. + * + * This event is triggered when the client receives a conference message. + */ +void tox_callback_conference_message(Tox *tox, tox_conference_message_cb *callback); + +/** + * @param conference_number The conference number of the conference the title change is intended for. + * @param peer_number The ID of the peer who changed the title. + * @param title The title data. + * @param length The title length. + */ +typedef void tox_conference_title_cb(Tox *tox, uint32_t conference_number, uint32_t peer_number, const uint8_t *title, + size_t length, void *user_data); + + +/** + * Set the callback for the `conference_title` event. Pass NULL to unset. + * + * This event is triggered when a peer changes the conference title. + * + * If peer_number == UINT32_MAX, then author is unknown (e.g. initial joining the conference). + */ +void tox_callback_conference_title(Tox *tox, tox_conference_title_cb *callback); + +/** + * Peer list state change types. + */ +typedef enum TOX_CONFERENCE_STATE_CHANGE { + + /** + * A peer has joined the conference. + */ + TOX_CONFERENCE_STATE_CHANGE_PEER_JOIN, + + /** + * A peer has exited the conference. + */ + TOX_CONFERENCE_STATE_CHANGE_PEER_EXIT, + + /** + * A peer has changed their name. + */ + TOX_CONFERENCE_STATE_CHANGE_PEER_NAME_CHANGE, + +} TOX_CONFERENCE_STATE_CHANGE; + + +/** + * @param conference_number The conference number of the conference the title change is intended for. + * @param peer_number The ID of the peer who changed the title. + * @param change The type of change (one of TOX_CONFERENCE_STATE_CHANGE). + */ +typedef void tox_conference_namelist_change_cb(Tox *tox, uint32_t conference_number, uint32_t peer_number, + TOX_CONFERENCE_STATE_CHANGE change, void *user_data); + + +/** + * Set the callback for the `conference_namelist_change` event. Pass NULL to unset. + * + * This event is triggered when the peer list changes (name change, peer join, peer exit). + */ +void tox_callback_conference_namelist_change(Tox *tox, tox_conference_namelist_change_cb *callback); + +typedef enum TOX_ERR_CONFERENCE_NEW { + + /** + * The function returned successfully. + */ + TOX_ERR_CONFERENCE_NEW_OK, + + /** + * The conference instance failed to initialize. + */ + TOX_ERR_CONFERENCE_NEW_INIT, + +} TOX_ERR_CONFERENCE_NEW; + + +/** + * Creates a new conference. + * + * This function creates a new text conference. + * + * @return conference number on success, or UINT32_MAX on failure. + */ +uint32_t tox_conference_new(Tox *tox, TOX_ERR_CONFERENCE_NEW *error); + +typedef enum TOX_ERR_CONFERENCE_DELETE { + + /** + * The function returned successfully. + */ + TOX_ERR_CONFERENCE_DELETE_OK, + + /** + * The conference number passed did not designate a valid conference. + */ + TOX_ERR_CONFERENCE_DELETE_CONFERENCE_NOT_FOUND, + +} TOX_ERR_CONFERENCE_DELETE; +/** + * This function deletes a conference. + * + * @param conference_number The conference number of the conference to be deleted. + * + * @return true on success. + */ +bool tox_conference_delete(Tox *tox, uint32_t conference_number, TOX_ERR_CONFERENCE_DELETE *error); + +/** + * Error codes for peer info queries. + */ +typedef enum TOX_ERR_CONFERENCE_PEER_QUERY { + + /** + * The function returned successfully. + */ + TOX_ERR_CONFERENCE_PEER_QUERY_OK, + + /** + * The conference number passed did not designate a valid conference. + */ + TOX_ERR_CONFERENCE_PEER_QUERY_CONFERENCE_NOT_FOUND, + + /** + * The peer number passed did not designate a valid peer. + */ + TOX_ERR_CONFERENCE_PEER_QUERY_PEER_NOT_FOUND, + + /** + * The client is not connected to the conference. + */ + TOX_ERR_CONFERENCE_PEER_QUERY_NO_CONNECTION, + +} TOX_ERR_CONFERENCE_PEER_QUERY; + + +/** + * Return the number of peers in the conference. Return value is unspecified on failure. + */ +uint32_t tox_conference_peer_count(const Tox *tox, uint32_t conference_number, TOX_ERR_CONFERENCE_PEER_QUERY *error); + +/** + * Return the length of the peer's name. Return value is unspecified on failure. + */ +size_t tox_conference_peer_get_name_size(const Tox *tox, uint32_t conference_number, uint32_t peer_number, + TOX_ERR_CONFERENCE_PEER_QUERY *error); + +/** + * Copy the name of peer_number who is in conference_number to name. + * name must be at least TOX_MAX_NAME_LENGTH long. + * + * @return true on success. + */ +bool tox_conference_peer_get_name(const Tox *tox, uint32_t conference_number, uint32_t peer_number, uint8_t *name, + TOX_ERR_CONFERENCE_PEER_QUERY *error); + +/** + * Copy the public key of peer_number who is in conference_number to public_key. + * public_key must be TOX_PUBLIC_KEY_SIZE long. + * + * @return true on success. + */ +bool tox_conference_peer_get_public_key(const Tox *tox, uint32_t conference_number, uint32_t peer_number, + uint8_t *public_key, TOX_ERR_CONFERENCE_PEER_QUERY *error); + +/** + * Return true if passed peer_number corresponds to our own. + */ +bool tox_conference_peer_number_is_ours(const Tox *tox, uint32_t conference_number, uint32_t peer_number, + TOX_ERR_CONFERENCE_PEER_QUERY *error); + +typedef enum TOX_ERR_CONFERENCE_INVITE { + + /** + * The function returned successfully. + */ + TOX_ERR_CONFERENCE_INVITE_OK, + + /** + * The conference number passed did not designate a valid conference. + */ + TOX_ERR_CONFERENCE_INVITE_CONFERENCE_NOT_FOUND, + + /** + * The invite packet failed to send. + */ + TOX_ERR_CONFERENCE_INVITE_FAIL_SEND, + +} TOX_ERR_CONFERENCE_INVITE; + + +/** + * Invites a friend to a conference. + * + * @param friend_number The friend number of the friend we want to invite. + * @param conference_number The conference number of the conference we want to invite the friend to. + * + * @return true on success. + */ +bool tox_conference_invite(Tox *tox, uint32_t friend_number, uint32_t conference_number, + TOX_ERR_CONFERENCE_INVITE *error); + +typedef enum TOX_ERR_CONFERENCE_JOIN { + + /** + * The function returned successfully. + */ + TOX_ERR_CONFERENCE_JOIN_OK, + + /** + * The cookie passed has an invalid length. + */ + TOX_ERR_CONFERENCE_JOIN_INVALID_LENGTH, + + /** + * The conference is not the expected type. This indicates an invalid cookie. + */ + TOX_ERR_CONFERENCE_JOIN_WRONG_TYPE, + + /** + * The friend number passed does not designate a valid friend. + */ + TOX_ERR_CONFERENCE_JOIN_FRIEND_NOT_FOUND, + + /** + * Client is already in this conference. + */ + TOX_ERR_CONFERENCE_JOIN_DUPLICATE, + + /** + * Conference instance failed to initialize. + */ + TOX_ERR_CONFERENCE_JOIN_INIT_FAIL, + + /** + * The join packet failed to send. + */ + TOX_ERR_CONFERENCE_JOIN_FAIL_SEND, + +} TOX_ERR_CONFERENCE_JOIN; + + +/** + * Joins a conference that the client has been invited to. + * + * @param friend_number The friend number of the friend who sent the invite. + * @param cookie Received via the `conference_invite` event. + * @param length The size of cookie. + * + * @return conference number on success, UINT32_MAX on failure. + */ +uint32_t tox_conference_join(Tox *tox, uint32_t friend_number, const uint8_t *cookie, size_t length, + TOX_ERR_CONFERENCE_JOIN *error); + +typedef enum TOX_ERR_CONFERENCE_SEND_MESSAGE { + + /** + * The function returned successfully. + */ + TOX_ERR_CONFERENCE_SEND_MESSAGE_OK, + + /** + * The conference number passed did not designate a valid conference. + */ + TOX_ERR_CONFERENCE_SEND_MESSAGE_CONFERENCE_NOT_FOUND, + + /** + * The message is too long. + */ + TOX_ERR_CONFERENCE_SEND_MESSAGE_TOO_LONG, + + /** + * The client is not connected to the conference. + */ + TOX_ERR_CONFERENCE_SEND_MESSAGE_NO_CONNECTION, + + /** + * The message packet failed to send. + */ + TOX_ERR_CONFERENCE_SEND_MESSAGE_FAIL_SEND, + +} TOX_ERR_CONFERENCE_SEND_MESSAGE; + + +/** + * Send a text chat message to the conference. + * + * This function creates a conference message packet and pushes it into the send + * queue. + * + * The message length may not exceed TOX_MAX_MESSAGE_LENGTH. Larger messages + * must be split by the client and sent as separate messages. Other clients can + * then reassemble the fragments. + * + * @param conference_number The conference number of the conference the message is intended for. + * @param type Message type (normal, action, ...). + * @param message A non-NULL pointer to the first element of a byte array + * containing the message text. + * @param length Length of the message to be sent. + * + * @return true on success. + */ +bool tox_conference_send_message(Tox *tox, uint32_t conference_number, TOX_MESSAGE_TYPE type, const uint8_t *message, + size_t length, TOX_ERR_CONFERENCE_SEND_MESSAGE *error); + +typedef enum TOX_ERR_CONFERENCE_TITLE { + + /** + * The function returned successfully. + */ + TOX_ERR_CONFERENCE_TITLE_OK, + + /** + * The conference number passed did not designate a valid conference. + */ + TOX_ERR_CONFERENCE_TITLE_CONFERENCE_NOT_FOUND, + + /** + * The title is too long or empty. + */ + TOX_ERR_CONFERENCE_TITLE_INVALID_LENGTH, + + /** + * The title packet failed to send. + */ + TOX_ERR_CONFERENCE_TITLE_FAIL_SEND, + +} TOX_ERR_CONFERENCE_TITLE; + + +/** + * Return the length of the conference title. Return value is unspecified on failure. + * + * The return value is equal to the `length` argument received by the last + * `conference_title` callback. + */ +size_t tox_conference_get_title_size(const Tox *tox, uint32_t conference_number, TOX_ERR_CONFERENCE_TITLE *error); + +/** + * Write the title designated by the given conference number to a byte array. + * + * Call tox_conference_get_title_size to determine the allocation size for the `title` parameter. + * + * The data written to `title` is equal to the data received by the last + * `conference_title` callback. + * + * @param title A valid memory region large enough to store the title. + * If this parameter is NULL, this function has no effect. + * + * @return true on success. + */ +bool tox_conference_get_title(const Tox *tox, uint32_t conference_number, uint8_t *title, + TOX_ERR_CONFERENCE_TITLE *error); + +/** + * Set the conference title and broadcast it to the rest of the conference. + * + * Title length cannot be longer than TOX_MAX_NAME_LENGTH. + * + * @return true on success. + */ +bool tox_conference_set_title(Tox *tox, uint32_t conference_number, const uint8_t *title, size_t length, + TOX_ERR_CONFERENCE_TITLE *error); + +/** + * Return the number of conferences in the Tox instance. + * This should be used to determine how much memory to allocate for `tox_conference_get_chatlist`. + */ +size_t tox_conference_get_chatlist_size(const Tox *tox); + +/** + * Copy a list of valid conference IDs into the array chatlist. Determine how much space + * to allocate for the array with the `tox_conference_get_chatlist_size` function. + */ +void tox_conference_get_chatlist(const Tox *tox, uint32_t *chatlist); + +/** + * Returns the type of conference (TOX_CONFERENCE_TYPE) that conference_number is. Return value is + * unspecified on failure. + */ +typedef enum TOX_ERR_CONFERENCE_GET_TYPE { + + /** + * The function returned successfully. + */ + TOX_ERR_CONFERENCE_GET_TYPE_OK, + + /** + * The conference number passed did not designate a valid conference. + */ + TOX_ERR_CONFERENCE_GET_TYPE_CONFERENCE_NOT_FOUND, + +} TOX_ERR_CONFERENCE_GET_TYPE; + + +TOX_CONFERENCE_TYPE tox_conference_get_type(const Tox *tox, uint32_t conference_number, + TOX_ERR_CONFERENCE_GET_TYPE *error); /******************************************************************************* @@ -2235,7 +2867,7 @@ typedef void tox_friend_lossy_packet_cb(Tox *tox, uint32_t friend_number, const * 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); +void tox_callback_friend_lossy_packet(Tox *tox, tox_friend_lossy_packet_cb *callback); /** * @param friend_number The friend number of the friend who sent the packet. @@ -2250,7 +2882,7 @@ typedef void tox_friend_lossless_packet_cb(Tox *tox, uint32_t friend_number, con * Set the callback for the `friend_lossless_packet` event. Pass NULL to unset. * */ -void tox_callback_friend_lossless_packet(Tox *tox, tox_friend_lossless_packet_cb *callback, void *user_data); +void tox_callback_friend_lossless_packet(Tox *tox, tox_friend_lossless_packet_cb *callback); /******************************************************************************* @@ -2301,8 +2933,6 @@ uint16_t tox_self_get_udp_port(const Tox *tox, TOX_ERR_GET_PORT *error); */ uint16_t tox_self_get_tcp_port(const Tox *tox, TOX_ERR_GET_PORT *error); -#include "tox_old.h" - #ifdef __cplusplus } #endif diff --git a/protocols/Tox/include/tox_old.h b/protocols/Tox/include/tox_old.h deleted file mode 100644 index a926cdf70e..0000000000 --- a/protocols/Tox/include/tox_old.h +++ /dev/null @@ -1,173 +0,0 @@ -/**********GROUP CHAT FUNCTIONS ************/ - -/* Group chat types for tox_callback_group_invite function. - * - * 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. - */ -enum { - TOX_GROUPCHAT_TYPE_TEXT, - TOX_GROUPCHAT_TYPE_AV -}; - -/* Set the callback for group invites. - * - * Function(Tox *tox, int32_t friendnumber, uint8_t type, const uint8_t *data, uint16_t length, void *userdata) - * - * data of length is what needs to be passed to join_groupchat(). - * - * for what type means see the enum right above this comment. - */ -void tox_callback_group_invite(Tox *tox, void (*function)(Tox *tox, int32_t, uint8_t, const uint8_t *, uint16_t, - void *), void *userdata); - -/* Set the callback for group messages. - * - * Function(Tox *tox, int groupnumber, int peernumber, const uint8_t * message, uint16_t length, void *userdata) - */ -void tox_callback_group_message(Tox *tox, void (*function)(Tox *tox, int, int, const uint8_t *, uint16_t, void *), - void *userdata); - -/* Set the callback for group actions. - * - * Function(Tox *tox, int groupnumber, int peernumber, const uint8_t * action, uint16_t length, void *userdata) - */ -void tox_callback_group_action(Tox *tox, void (*function)(Tox *tox, int, int, const uint8_t *, uint16_t, void *), - void *userdata); - -/* Set callback function for title changes. - * - * 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) - */ -void tox_callback_group_title(Tox *tox, void (*function)(Tox *tox, int, int, const uint8_t *, uint8_t, - void *), void *userdata); - -/* Set callback function for peer name list changes. - * - * 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) - */ -typedef enum { - TOX_CHAT_CHANGE_PEER_ADD, - TOX_CHAT_CHANGE_PEER_DEL, - TOX_CHAT_CHANGE_PEER_NAME, -} TOX_CHAT_CHANGE; - -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 group number on success. - * return -1 on failure. - */ -int tox_add_groupchat(Tox *tox); - -/* Delete a groupchat from the chats array. - * - * return 0 on success. - * return -1 if failure. - */ -int tox_del_groupchat(Tox *tox, int groupnumber); - -/* Copy the name of peernumber who is in groupnumber to name. - * name must be at least TOX_MAX_NAME_LENGTH long. - * - * return length of name if success - * return -1 if failure - */ -int tox_group_peername(const Tox *tox, int groupnumber, int peernumber, uint8_t *name); - -/* Copy the public key of peernumber who is in groupnumber to public_key. - * public_key must be TOX_PUBLIC_KEY_SIZE long. - * - * returns 0 on success - * returns -1 on failure - */ -int tox_group_peer_pubkey(const Tox *tox, int groupnumber, int peernumber, uint8_t *public_key); - -/* invite friendnumber to groupnumber - * return 0 on success - * return -1 on failure - */ -int tox_invite_friend(Tox *tox, int32_t friendnumber, int groupnumber); - -/* Join a group (you need to have been invited first.) using data of length obtained - * in the group invite callback. - * - * returns group number on success - * returns -1 on failure. - */ -int tox_join_groupchat(Tox *tox, int32_t friendnumber, const uint8_t *data, uint16_t length); - -/* send a group message - * return 0 on success - * return -1 on failure - */ -int tox_group_message_send(Tox *tox, int groupnumber, const uint8_t *message, uint16_t length); - -/* send a group action - * return 0 on success - * return -1 on failure - */ -int tox_group_action_send(Tox *tox, int groupnumber, const uint8_t *action, uint16_t length); - -/* 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 length of copied title if success. - * return -1 if failure. - */ -int tox_group_get_title(Tox *tox, int groupnumber, uint8_t *title, uint32_t max_length); - -/* Check if the current peernumber corresponds to ours. - * - * return 1 if the peernumber corresponds to ours. - * return 0 on failure. - */ -unsigned int tox_group_peernumber_is_ours(const Tox *tox, int groupnumber, int peernumber); - -/* Return the number of peers in the group chat on success. - * return -1 on failure - */ -int tox_group_number_peers(const Tox *tox, int groupnumber); - -/* List all the peers in the group chat. - * - * Copies the names of the peers to the name[length][TOX_MAX_NAME_LENGTH] array. - * - * Copies the lengths of the names to lengths[length] - * - * returns the number of peers on success. - * - * return -1 on failure. - */ -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); - -/* 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. - * - * return -1 on failure. - * return type on success. - */ -int tox_group_get_type(const Tox *tox, int groupnumber); - diff --git a/protocols/Tox/include/toxav.h b/protocols/Tox/include/toxav.h index ea58625403..2e48d599ef 100644 --- a/protocols/Tox/include/toxav.h +++ b/protocols/Tox/include/toxav.h @@ -1,8 +1,8 @@ -/* toxav.h +/* + * Copyright © 2016-2017 The TokTok team. + * Copyright © 2013-2015 Tox project. * - * Copyright (C) 2013-2015 Tox project All Rights Reserved. - * - * This file is part of Tox. + * This file is part of Tox, the free peer to peer instant messenger. * * Tox is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by @@ -15,14 +15,12 @@ * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License - * along with Tox. If not, see <http://www.gnu.org/licenses/>. - * + * along with Tox. If not, see <http://www.gnu.org/licenses/>. */ - #ifndef TOXAV_H #define TOXAV_H -//#include <stdbool.h> +#include <stdbool.h> #include <stddef.h> #include <stdint.h> @@ -93,101 +91,38 @@ typedef struct ToxAV ToxAV; /******************************************************************************* * - * :: API version + * :: Creation and destruction * ******************************************************************************/ -/** - * The major version number. Incremented when the API or ABI changes in an - * incompatible way. - */ -#define TOXAV_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 TOXAV_VERSION_MINOR 0u -/** - * The patch or revision number. Incremented when bugfixes are applied without - * changing any functionality or API or ABI. - */ -#define TOXAV_VERSION_PATCH 0u -/** - * A macro to check at preprocessing time whether the client code is compatible - * with the installed version of ToxAV. - */ -#define TOXAV_VERSION_IS_API_COMPATIBLE(MAJOR, MINOR, PATCH) \ - (TOXAV_VERSION_MAJOR == MAJOR && \ - (TOXAV_VERSION_MINOR > MINOR || \ - (TOXAV_VERSION_MINOR == MINOR && \ - TOXAV_VERSION_PATCH >= PATCH))) -/** - * A macro to make compilation fail if the client code is not compatible with - * the installed version of ToxAV. - */ -#define TOXAV_VERSION_REQUIRE(MAJOR, MINOR, PATCH) \ - typedef char toxav_required_version[TOXAV_IS_COMPATIBLE(MAJOR, MINOR, PATCH) ? 1 : -1] - -/** - * A convenience macro to call toxav_version_is_compatible with the currently - * compiling API version. - */ -#define TOXAV_VERSION_IS_ABI_COMPATIBLE() \ - toxav_version_is_compatible(TOXAV_VERSION_MAJOR, TOXAV_VERSION_MINOR, TOXAV_VERSION_PATCH) - -/** - * Return the major version number of the library. Can be used to display the - * ToxAV library version or to check whether the client is compatible with the - * dynamically linked version of ToxAV. - */ -uint32_t toxav_version_major(void); - -/** - * Return the minor version number of the library. - */ -uint32_t toxav_version_minor(void); - -/** - * Return the patch number of the library. - */ -uint32_t toxav_version_patch(void); - -/** - * Return whether the compiled library version is compatible with the passed - * version numbers. - */ -bool toxav_version_is_compatible(uint32_t major, uint32_t minor, uint32_t patch); - - -/******************************************************************************* - * - * :: Creation and destruction - * - ******************************************************************************/ typedef enum TOXAV_ERR_NEW { + /** * The function returned successfully. */ TOXAV_ERR_NEW_OK, + /** * One of the arguments to the function was NULL when it was not expected. */ TOXAV_ERR_NEW_NULL, + /** * Memory allocation failure while trying to allocate structures required for * the A/V session. */ TOXAV_ERR_NEW_MALLOC, + /** * Attempted to create a second session for the same Tox instance. */ TOXAV_ERR_NEW_MULTIPLE, + } TOXAV_ERR_NEW; + /** * Start new A/V session. There can only be only one session per Tox instance. */ @@ -200,12 +135,12 @@ ToxAV *toxav_new(Tox *tox, TOXAV_ERR_NEW *error); * notifying peers. After calling this function, no other functions may be * called and the av pointer becomes invalid. */ -void toxav_kill(ToxAV *toxAV); +void toxav_kill(ToxAV *av); /** * Returns the Tox instance the A/V object was created for. */ -Tox *toxav_get_tox(const ToxAV *toxAV); +Tox *toxav_get_tox(const ToxAV *av); /******************************************************************************* @@ -213,18 +148,21 @@ Tox *toxav_get_tox(const ToxAV *toxAV); * :: A/V event loop * ******************************************************************************/ + + + /** * Returns the interval in milliseconds when the next toxav_iterate call should * be. If no call is active at the moment, this function returns 200. */ -uint32_t toxav_iteration_interval(const ToxAV *toxAV); +uint32_t toxav_iteration_interval(const ToxAV *av); /** * Main loop for the session. This function needs to be called in intervals of * toxav_iteration_interval() milliseconds. It is best called in the separate * thread from tox_iterate. */ -void toxav_iterate(ToxAV *toxAV); +void toxav_iterate(ToxAV *av); /******************************************************************************* @@ -232,39 +170,51 @@ void toxav_iterate(ToxAV *toxAV); * :: Call setup * ******************************************************************************/ + + + typedef enum TOXAV_ERR_CALL { + /** * The function returned successfully. */ TOXAV_ERR_CALL_OK, + /** * A resource allocation error occurred while trying to create the structures * required for the call. */ TOXAV_ERR_CALL_MALLOC, + /** * Synchronization error occurred. */ TOXAV_ERR_CALL_SYNC, + /** * The friend number did not designate a valid friend. */ TOXAV_ERR_CALL_FRIEND_NOT_FOUND, + /** * The friend was valid, but not currently connected. */ TOXAV_ERR_CALL_FRIEND_NOT_CONNECTED, + /** * Attempted to call a friend while already in an audio or video call with * them. */ TOXAV_ERR_CALL_FRIEND_ALREADY_IN_CALL, + /** * Audio or video bit rate is invalid. */ TOXAV_ERR_CALL_INVALID_BIT_RATE, + } TOXAV_ERR_CALL; + /** * Call a friend. This will start ringing the friend. * @@ -279,8 +229,8 @@ typedef enum TOXAV_ERR_CALL { * @param video_bit_rate Video bit rate in Kb/sec. Set this to 0 to disable * video sending. */ -bool toxav_call(ToxAV *toxAV, uint32_t friend_number, uint32_t audio_bit_rate, - uint32_t video_bit_rate, TOXAV_ERR_CALL *error); +bool toxav_call(ToxAV *av, uint32_t friend_number, uint32_t audio_bit_rate, uint32_t video_bit_rate, + TOXAV_ERR_CALL *error); /** * The function type for the call callback. @@ -289,45 +239,53 @@ bool toxav_call(ToxAV *toxAV, uint32_t friend_number, uint32_t audio_bit_rate, * @param audio_enabled True if friend is sending audio. * @param video_enabled True if friend is sending video. */ -typedef void toxav_call_cb(ToxAV *toxAV, uint32_t friend_number, bool audio_enabled, - bool video_enabled, void *user_data); +typedef void toxav_call_cb(ToxAV *av, uint32_t friend_number, bool audio_enabled, bool video_enabled, void *user_data); + /** * Set the callback for the `call` event. Pass NULL to unset. * */ -void toxav_callback_call(ToxAV *toxAV, toxav_call_cb *callback, void *user_data); +void toxav_callback_call(ToxAV *av, toxav_call_cb *callback, void *user_data); typedef enum TOXAV_ERR_ANSWER { + /** * The function returned successfully. */ TOXAV_ERR_ANSWER_OK, + /** * Synchronization error occurred. */ TOXAV_ERR_ANSWER_SYNC, + /** * Failed to initialize codecs for call session. Note that codec initiation * will fail if there is no receive callback registered for either audio or * video. */ TOXAV_ERR_ANSWER_CODEC_INITIALIZATION, + /** * The friend number did not designate a valid friend. */ TOXAV_ERR_ANSWER_FRIEND_NOT_FOUND, + /** * The friend was valid, but they are not currently trying to initiate a call. * This is also returned if this client is already in a call with the friend. */ TOXAV_ERR_ANSWER_FRIEND_NOT_CALLING, + /** * Audio or video bit rate is invalid. */ TOXAV_ERR_ANSWER_INVALID_BIT_RATE, + } TOXAV_ERR_ANSWER; + /** * Accept an incoming call. * @@ -341,7 +299,7 @@ typedef enum TOXAV_ERR_ANSWER { * @param video_bit_rate Video bit rate in Kb/sec. Set this to 0 to disable * video sending. */ -bool toxav_answer(ToxAV *toxAV, uint32_t friend_number, uint32_t audio_bit_rate, uint32_t video_bit_rate, +bool toxav_answer(ToxAV *av, uint32_t friend_number, uint32_t audio_bit_rate, uint32_t video_bit_rate, TOXAV_ERR_ANSWER *error); @@ -350,7 +308,16 @@ bool toxav_answer(ToxAV *toxAV, uint32_t friend_number, uint32_t audio_bit_rate, * :: Call state graph * ******************************************************************************/ + + + enum TOXAV_FRIEND_CALL_STATE { + + /** + * The empty bit mask. None of the bits specified below are set. + */ + TOXAV_FRIEND_CALL_STATE_NONE = 0, + /** * Set by the AV core if an error occurred on the remote end or if friend * timed out. This is the final state after which no more state @@ -358,30 +325,37 @@ enum TOXAV_FRIEND_CALL_STATE { * in combination with other call states. */ TOXAV_FRIEND_CALL_STATE_ERROR = 1, + /** * The call has finished. This is the final state after which no more state * transitions can occur for the call. This call state will never be * triggered in combination with other call states. */ TOXAV_FRIEND_CALL_STATE_FINISHED = 2, + /** * The flag that marks that friend is sending audio. */ TOXAV_FRIEND_CALL_STATE_SENDING_A = 4, + /** * The flag that marks that friend is sending video. */ TOXAV_FRIEND_CALL_STATE_SENDING_V = 8, + /** * The flag that marks that friend is receiving audio. */ TOXAV_FRIEND_CALL_STATE_ACCEPTING_A = 16, + /** * The flag that marks that friend is receiving video. */ TOXAV_FRIEND_CALL_STATE_ACCEPTING_V = 32, + }; + /** * The function type for the call_state callback. * @@ -391,81 +365,102 @@ enum TOXAV_FRIEND_CALL_STATE { * paused. The bitmask represents all the activities currently performed by the * friend. */ -typedef void toxav_call_state_cb(ToxAV *toxAV, uint32_t friend_number, uint32_t state, void *user_data); +typedef void toxav_call_state_cb(ToxAV *av, uint32_t friend_number, uint32_t state, void *user_data); + /** * Set the callback for the `call_state` event. Pass NULL to unset. * */ -void toxav_callback_call_state(ToxAV *toxAV, toxav_call_state_cb *callback, void *user_data); +void toxav_callback_call_state(ToxAV *av, toxav_call_state_cb *callback, void *user_data); + /******************************************************************************* * * :: Call control * ******************************************************************************/ + + + typedef enum TOXAV_CALL_CONTROL { + /** * Resume a previously paused call. Only valid if the pause was caused by this * client, if not, this control is ignored. Not valid before the call is accepted. */ TOXAV_CALL_CONTROL_RESUME, + /** * Put a call on hold. Not valid before the call is accepted. */ TOXAV_CALL_CONTROL_PAUSE, + /** * Reject a call if it was not answered, yet. Cancel a call after it was * answered. */ TOXAV_CALL_CONTROL_CANCEL, + /** * Request that the friend stops sending audio. Regardless of the friend's * compliance, this will cause the audio_receive_frame event to stop being * triggered on receiving an audio frame from the friend. */ TOXAV_CALL_CONTROL_MUTE_AUDIO, + /** * Calling this control will notify client to start sending audio again. */ TOXAV_CALL_CONTROL_UNMUTE_AUDIO, + /** * Request that the friend stops sending video. Regardless of the friend's * compliance, this will cause the video_receive_frame event to stop being * triggered on receiving a video frame from the friend. */ TOXAV_CALL_CONTROL_HIDE_VIDEO, + /** * Calling this control will notify client to start sending video again. */ TOXAV_CALL_CONTROL_SHOW_VIDEO, + } TOXAV_CALL_CONTROL; + typedef enum TOXAV_ERR_CALL_CONTROL { + /** * The function returned successfully. */ TOXAV_ERR_CALL_CONTROL_OK, + /** * Synchronization error occurred. */ TOXAV_ERR_CALL_CONTROL_SYNC, + /** * The friend_number passed did not designate a valid friend. */ TOXAV_ERR_CALL_CONTROL_FRIEND_NOT_FOUND, + /** * This client is currently not in a call with the friend. Before the call is * answered, only CANCEL is a valid control. */ TOXAV_ERR_CALL_CONTROL_FRIEND_NOT_IN_CALL, + /** * Happens if user tried to pause an already paused call or if trying to * resume a call that is not paused. */ TOXAV_ERR_CALL_CONTROL_INVALID_TRANSITION, + } TOXAV_ERR_CALL_CONTROL; + /** * Sends a call control command to a friend. * @@ -475,8 +470,7 @@ typedef enum TOXAV_ERR_CALL_CONTROL { * * @return true on success. */ -bool toxav_call_control(ToxAV *toxAV, uint32_t friend_number, TOXAV_CALL_CONTROL control, - TOXAV_ERR_CALL_CONTROL *error); +bool toxav_call_control(ToxAV *av, uint32_t friend_number, TOXAV_CALL_CONTROL control, TOXAV_ERR_CALL_CONTROL *error); /******************************************************************************* @@ -484,33 +478,44 @@ bool toxav_call_control(ToxAV *toxAV, uint32_t friend_number, TOXAV_CALL_CONTROL * :: Controlling bit rates * ******************************************************************************/ + + + typedef enum TOXAV_ERR_BIT_RATE_SET { + /** * The function returned successfully. */ TOXAV_ERR_BIT_RATE_SET_OK, + /** * Synchronization error occurred. */ TOXAV_ERR_BIT_RATE_SET_SYNC, + /** * The audio bit rate passed was not one of the supported values. */ TOXAV_ERR_BIT_RATE_SET_INVALID_AUDIO_BIT_RATE, + /** * The video bit rate passed was not one of the supported values. */ TOXAV_ERR_BIT_RATE_SET_INVALID_VIDEO_BIT_RATE, + /** * The friend_number passed did not designate a valid friend. */ TOXAV_ERR_BIT_RATE_SET_FRIEND_NOT_FOUND, + /** * This client is currently not in a call with the friend. */ TOXAV_ERR_BIT_RATE_SET_FRIEND_NOT_IN_CALL, + } TOXAV_ERR_BIT_RATE_SET; + /** * Set the bit rate to be used in subsequent audio/video frames. * @@ -522,8 +527,8 @@ typedef enum TOXAV_ERR_BIT_RATE_SET { * video sending. Set to -1 to leave unchanged. * */ -bool toxav_bit_rate_set(ToxAV *toxAV, uint32_t friend_number, int32_t audio_bit_rate, - int32_t video_bit_rate, TOXAV_ERR_BIT_RATE_SET *error); +bool toxav_bit_rate_set(ToxAV *av, uint32_t friend_number, int32_t audio_bit_rate, int32_t video_bit_rate, + TOXAV_ERR_BIT_RATE_SET *error); /** * The function type for the bit_rate_status callback. The event is triggered @@ -535,14 +540,15 @@ bool toxav_bit_rate_set(ToxAV *toxAV, uint32_t friend_number, int32_t audio_bit_ * @param audio_bit_rate Suggested maximum audio bit rate in Kb/sec. * @param video_bit_rate Suggested maximum video bit rate in Kb/sec. */ -typedef void toxav_bit_rate_status_cb(ToxAV *toxAV, uint32_t friend_number, uint32_t audio_bit_rate, +typedef void toxav_bit_rate_status_cb(ToxAV *av, uint32_t friend_number, uint32_t audio_bit_rate, uint32_t video_bit_rate, void *user_data); + /** * Set the callback for the `bit_rate_status` event. Pass NULL to unset. * */ -void toxav_callback_bit_rate_status(ToxAV *toxAV, toxav_bit_rate_status_cb *callback, void *user_data); +void toxav_callback_bit_rate_status(ToxAV *av, toxav_bit_rate_status_cb *callback, void *user_data); /******************************************************************************* @@ -550,44 +556,57 @@ void toxav_callback_bit_rate_status(ToxAV *toxAV, toxav_bit_rate_status_cb *call * :: A/V sending * ******************************************************************************/ + + + typedef enum TOXAV_ERR_SEND_FRAME { + /** * The function returned successfully. */ TOXAV_ERR_SEND_FRAME_OK, + /** * In case of video, one of Y, U, or V was NULL. In case of audio, the samples * data pointer was NULL. */ TOXAV_ERR_SEND_FRAME_NULL, + /** * The friend_number passed did not designate a valid friend. */ TOXAV_ERR_SEND_FRAME_FRIEND_NOT_FOUND, + /** * This client is currently not in a call with the friend. */ TOXAV_ERR_SEND_FRAME_FRIEND_NOT_IN_CALL, + /** * Synchronization error occurred. */ TOXAV_ERR_SEND_FRAME_SYNC, + /** * One of the frame parameters was invalid. E.g. the resolution may be too * small or too large, or the audio sampling rate may be unsupported. */ TOXAV_ERR_SEND_FRAME_INVALID, + /** * Either friend turned off audio or video receiving or we turned off sending * for the said payload. */ TOXAV_ERR_SEND_FRAME_PAYLOAD_TYPE_DISABLED, + /** * Failed to push frame through rtp interface. */ TOXAV_ERR_SEND_FRAME_RTP_FAILED, + } TOXAV_ERR_SEND_FRAME; + /** * Send an audio frame to a friend. * @@ -608,9 +627,8 @@ typedef enum TOXAV_ERR_SEND_FRAME { * @param sampling_rate Audio sampling rate used in this frame. Valid sampling * rates are 8000, 12000, 16000, 24000, or 48000. */ -bool toxav_audio_send_frame(ToxAV *toxAV, uint32_t friend_number, const int16_t *pcm, - size_t sample_count, uint8_t channels, uint32_t sampling_rate, - TOXAV_ERR_SEND_FRAME *error); +bool toxav_audio_send_frame(ToxAV *av, uint32_t friend_number, const int16_t *pcm, size_t sample_count, + uint8_t channels, uint32_t sampling_rate, TOXAV_ERR_SEND_FRAME *error); /** * Send a video frame to a friend. @@ -627,9 +645,8 @@ bool toxav_audio_send_frame(ToxAV *toxAV, uint32_t friend_number, const int16_t * @param u U (Chroma) plane data. * @param v V (Chroma) plane data. */ -bool toxav_video_send_frame(ToxAV *toxAV, uint32_t friend_number, uint16_t width, - uint16_t height, const uint8_t *y, const uint8_t *u, const uint8_t *v, - TOXAV_ERR_SEND_FRAME *error); +bool toxav_video_send_frame(ToxAV *av, uint32_t friend_number, uint16_t width, uint16_t height, const uint8_t *y, + const uint8_t *u, const uint8_t *v, TOXAV_ERR_SEND_FRAME *error); /******************************************************************************* @@ -637,6 +654,9 @@ bool toxav_video_send_frame(ToxAV *toxAV, uint32_t friend_number, uint16_t width * :: A/V receiving * ******************************************************************************/ + + + /** * The function type for the audio_receive_frame callback. The callback can be * called multiple times per single iteration depending on the amount of queued @@ -649,49 +669,51 @@ bool toxav_video_send_frame(ToxAV *toxAV, uint32_t friend_number, uint16_t width * @param sampling_rate Sampling rate used in this frame. * */ -typedef void toxav_audio_receive_frame_cb(ToxAV *toxAV, uint32_t friend_number, const int16_t *pcm, - size_t sample_count, uint8_t channels, uint32_t sampling_rate, - void *user_data); +typedef void toxav_audio_receive_frame_cb(ToxAV *av, uint32_t friend_number, const int16_t *pcm, size_t sample_count, + uint8_t channels, uint32_t sampling_rate, void *user_data); + /** * Set the callback for the `audio_receive_frame` event. Pass NULL to unset. * */ -void toxav_callback_audio_receive_frame(ToxAV *toxAV, toxav_audio_receive_frame_cb *callback, void *user_data); +void toxav_callback_audio_receive_frame(ToxAV *av, toxav_audio_receive_frame_cb *callback, void *user_data); /** * The function type for the video_receive_frame callback. * + * The size of plane data is derived from width and height as documented + * below. + * + * Strides represent padding for each plane that may or may not be present. + * You must handle strides in your image processing code. Strides are + * negative if the image is bottom-up hence why you MUST abs() it when + * calculating plane buffer size. + * * @param friend_number The friend number of the friend who sent a video frame. * @param width Width of the frame in pixels. * @param height Height of the frame in pixels. - * @param y - * @param u - * @param v Plane data. - * The size of plane data is derived from width and height where - * Y = MAX(width, abs(ystride)) * height, - * U = MAX(width/2, abs(ustride)) * (height/2) and - * V = MAX(width/2, abs(vstride)) * (height/2). - * @param ystride - * @param ustride - * @param vstride Strides data. Strides represent padding for each plane - * that may or may not be present. You must handle strides in - * your image processing code. Strides are negative if the - * image is bottom-up hence why you MUST abs() it when - * calculating plane buffer size. - */ -typedef void toxav_video_receive_frame_cb(ToxAV *toxAV, uint32_t friend_number, uint16_t width, - uint16_t height, const uint8_t *y, const uint8_t *u, const uint8_t *v, - int32_t ystride, int32_t ustride, int32_t vstride, void *user_data); + * @param y Luminosity plane. Size = MAX(width, abs(ystride)) * height. + * @param u U chroma plane. Size = MAX(width/2, abs(ustride)) * (height/2). + * @param v V chroma plane. Size = MAX(width/2, abs(vstride)) * (height/2). + * + * @param ystride Luminosity plane stride. + * @param ustride U chroma plane stride. + * @param vstride V chroma plane stride. + */ +typedef void toxav_video_receive_frame_cb(ToxAV *av, uint32_t friend_number, uint16_t width, uint16_t height, + const uint8_t *y, const uint8_t *u, const uint8_t *v, int32_t ystride, int32_t ustride, int32_t vstride, + void *user_data); + /** * Set the callback for the `video_receive_frame` event. Pass NULL to unset. * */ -void toxav_callback_video_receive_frame(ToxAV *toxAV, toxav_video_receive_frame_cb *callback, void *user_data); +void toxav_callback_video_receive_frame(ToxAV *av, toxav_video_receive_frame_cb *callback, void *user_data); /** - * NOTE Compatibility with old toxav group calls TODO remove + * NOTE Compatibility with old toxav group calls. TODO(iphydf): remove */ /* Create a new toxav group. * diff --git a/protocols/Tox/include/toxdns.h b/protocols/Tox/include/toxdns.h index 06071b82d6..b280925eb1 100644 --- a/protocols/Tox/include/toxdns.h +++ b/protocols/Tox/include/toxdns.h @@ -1,26 +1,26 @@ -/* toxdns.h - * +/* * Tox secure username DNS toxid resolving functions. + */ + +/* + * Copyright © 2016-2017 The TokTok team. + * Copyright © 2014 Tox project. * - * Copyright (C) 2014 Tox project All Rights Reserved. - * - * This file is part of Tox. - * - * Tox is free software: you can redistribute it and/or modify - * it under the terms of the GNU General Public License as published by - * the Free Software Foundation, either version 3 of the License, or - * (at your option) any later version. + * This file is part of Tox, the free peer to peer instant messenger. * - * Tox is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. + * Tox is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. * - * You should have received a copy of the GNU General Public License - * along with Tox. If not, see <http://www.gnu.org/licenses/>. + * Tox is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. * + * You should have received a copy of the GNU General Public License + * along with Tox. If not, see <http://www.gnu.org/licenses/>. */ - #ifndef TOXDNS_H #define TOXDNS_H diff --git a/protocols/Tox/include/toxencryptsave.h b/protocols/Tox/include/toxencryptsave.h index 49961fccab..d13ebbc624 100644 --- a/protocols/Tox/include/toxencryptsave.h +++ b/protocols/Tox/include/toxencryptsave.h @@ -1,26 +1,26 @@ -/* toxencryptsave.h - * - * The Tox encrypted save functions. - * - * Copyright (C) 2013 Tox project All Rights Reserved. - * - * This file is part of Tox. +/* + * Batch encryption functions. + */ + +/* + * Copyright © 2016-2017 The TokTok team. + * Copyright © 2013-2016 Tox Developers. * - * Tox is free software: you can redistribute it and/or modify - * it under the terms of the GNU General Public License as published by - * the Free Software Foundation, either version 3 of the License, or - * (at your option) any later version. + * This file is part of Tox, the free peer to peer instant messenger. * - * Tox is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. + * Tox is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. * - * You should have received a copy of the GNU General Public License - * along with Tox. If not, see <http://www.gnu.org/licenses/>. + * Tox is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. * + * You should have received a copy of the GNU General Public License + * along with Tox. If not, see <http://www.gnu.org/licenses/>. */ - #ifndef TOXENCRYPTSAVE_H #define TOXENCRYPTSAVE_H @@ -28,207 +28,357 @@ extern "C" { #endif -#include <stdint.h> +#include <stdbool.h> #include <stddef.h> -//#include <stdbool.h> - -#ifndef TOX_DEFINED -#define TOX_DEFINED -typedef struct Tox Tox; -struct Tox_Options; -#endif +#include <stdint.h> -#define TOX_PASS_SALT_LENGTH 32 -#define TOX_PASS_KEY_LENGTH 32 -#define TOX_PASS_ENCRYPTION_EXTRA_LENGTH 80 -/* This module is conceptually organized into two parts. The first part are the functions - * with "key" in the name. To use these functions, first derive an encryption key - * from a password with tox_derive_key_from_pass, and use the returned key to - * encrypt the data. The second part takes the password itself instead of the key, - * and then delegates to the first part to derive the key before de/encryption, - * which can simplify client code; however, key derivation is very expensive - * compared to the actual encryption, so clients that do a lot of encryption should - * favor using the first part intead of the second part. - * - * The encrypted data is prepended with a magic number, to aid validity checking - * (no guarantees are made of course). Any data to be decrypted must start with - * the magic number. - * - * Clients should consider alerting their users that, unlike plain data, if even one bit - * becomes corrupted, the data will be entirely unrecoverable. +/******************************************************************************* + * + * This module is organized into two parts. + * + * 1. A simple API operating on plain text/cipher text data and a password to + * encrypt or decrypt it. + * 2. A more advanced API that splits key derivation and encryption into two + * separate function calls. + * + * The first part is implemented in terms of the second part and simply calls + * the separate functions in sequence. Since key derivation is very expensive + * compared to the actual encryption, clients that do a lot of crypto should + * prefer the advanced API and reuse pass-key objects. + * + * To use the second part, first derive an encryption key from a password with + * tox_pass_key_derive, then use the derived key to encrypt the data. + * + * The encrypted data is prepended with a magic number, to aid validity + * checking (no guarantees are made of course). Any data to be decrypted must + * start with the magic number. + * + * Clients should consider alerting their users that, unlike plain data, if + * even one bit becomes corrupted, the data will be entirely unrecoverable. * Ditto if they forget their password, there is no way to recover the data. + * + ******************************************************************************/ + + + +/** + * The size of the salt part of a pass-key. + */ +#define TOX_PASS_SALT_LENGTH 32 + +uint32_t tox_pass_salt_length(void); + +/** + * The size of the key part of a pass-key. */ +#define TOX_PASS_KEY_LENGTH 32 + +uint32_t tox_pass_key_length(void); -/* Since apparently no one actually bothered to learn about the module previously, - * the recently removed functions tox_encrypted_new and tox_get_encrypted_savedata - * may be trivially replaced by calls to tox_pass_decrypt -> tox_new or - * tox_get_savedata -> tox_pass_encrypt as appropriate. The removed functions - * were never more than 5 line wrappers of the other public API functions anyways. - * (As has always been, tox_pass_decrypt and tox_pass_encrypt are interchangeable - * with tox_pass_key_decrypt and tox_pass_key_encrypt, as the client program requires.) +/** + * The amount of additional data required to store any encrypted byte array. + * Encrypting an array of N bytes requires N + TOX_PASS_ENCRYPTION_EXTRA_LENGTH + * bytes in the encrypted byte array. */ +#define TOX_PASS_ENCRYPTION_EXTRA_LENGTH 80 + +uint32_t tox_pass_encryption_extra_length(void); typedef enum TOX_ERR_KEY_DERIVATION { + + /** + * The function returned successfully. + */ TOX_ERR_KEY_DERIVATION_OK, + /** - * Some input data, or maybe the output pointer, was null. + * One of the arguments to the function was NULL when it was not expected. */ TOX_ERR_KEY_DERIVATION_NULL, + /** * The crypto lib was unable to derive a key from the given passphrase, * which is usually a lack of memory issue. The functions accepting keys * do not produce this error. */ - TOX_ERR_KEY_DERIVATION_FAILED + TOX_ERR_KEY_DERIVATION_FAILED, + } TOX_ERR_KEY_DERIVATION; + typedef enum TOX_ERR_ENCRYPTION { + + /** + * The function returned successfully. + */ TOX_ERR_ENCRYPTION_OK, + /** - * Some input data, or maybe the output pointer, was null. + * One of the arguments to the function was NULL when it was not expected. */ TOX_ERR_ENCRYPTION_NULL, + /** * The crypto lib was unable to derive a key from the given passphrase, * which is usually a lack of memory issue. The functions accepting keys * do not produce this error. */ TOX_ERR_ENCRYPTION_KEY_DERIVATION_FAILED, + /** * The encryption itself failed. */ - TOX_ERR_ENCRYPTION_FAILED + TOX_ERR_ENCRYPTION_FAILED, + } TOX_ERR_ENCRYPTION; + typedef enum TOX_ERR_DECRYPTION { + + /** + * The function returned successfully. + */ TOX_ERR_DECRYPTION_OK, + /** - * Some input data, or maybe the output pointer, was null. + * One of the arguments to the function was NULL when it was not expected. */ TOX_ERR_DECRYPTION_NULL, + /** * The input data was shorter than TOX_PASS_ENCRYPTION_EXTRA_LENGTH bytes */ TOX_ERR_DECRYPTION_INVALID_LENGTH, + /** * The input data is missing the magic number (i.e. wasn't created by this - * module, or is corrupted) + * module, or is corrupted). */ TOX_ERR_DECRYPTION_BAD_FORMAT, + /** * The crypto lib was unable to derive a key from the given passphrase, * which is usually a lack of memory issue. The functions accepting keys * do not produce this error. */ TOX_ERR_DECRYPTION_KEY_DERIVATION_FAILED, + /** * The encrypted byte array could not be decrypted. Either the data was - * corrupt or the password/key was incorrect. + * corrupted or the password/key was incorrect. */ - TOX_ERR_DECRYPTION_FAILED + TOX_ERR_DECRYPTION_FAILED, + } TOX_ERR_DECRYPTION; -/******************************* BEGIN PART 2 ******************************* - * For simplicty, the second part of the module is presented first. The API for - * the first part is analgous, with some extra functions for key handling. If - * your code spends too much time using these functions, consider using the part - * 1 functions instead. + +/******************************************************************************* + * + * BEGIN PART 1 + * + * The simple API is presented first. If your code spends too much time using + * these functions, consider using the advanced functions instead and caching + * the generated pass-key. + * + ******************************************************************************/ + + + +/** + * Encrypts the given data with the given passphrase. + * + * The output array must be at least `plaintext_len + TOX_PASS_ENCRYPTION_EXTRA_LENGTH` + * bytes long. This delegates to tox_pass_key_derive and + * tox_pass_key_encrypt. + * + * @param plaintext A byte array of length `plaintext_len`. + * @param plaintext_len The length of the plain text array. Bigger than 0. + * @param passphrase The user-provided password. Can be empty. + * @param passphrase_len The length of the password. + * @param ciphertext The cipher text array to write the encrypted data to. + * + * @return true on success. */ +bool tox_pass_encrypt(const uint8_t *plaintext, size_t plaintext_len, const uint8_t *passphrase, size_t passphrase_len, + uint8_t *ciphertext, TOX_ERR_ENCRYPTION *error); -/* Encrypts the given data with the given passphrase. The output array must be - * at least data_len + TOX_PASS_ENCRYPTION_EXTRA_LENGTH bytes long. This delegates - * to tox_derive_key_from_pass and tox_pass_key_encrypt. +/** + * Decrypts the given data with the given passphrase. * - * returns true on success + * The output array must be at least `ciphertext_len - TOX_PASS_ENCRYPTION_EXTRA_LENGTH` + * bytes long. This delegates to tox_pass_key_decrypt. + * + * @param ciphertext A byte array of length `ciphertext_len`. + * @param ciphertext_len The length of the cipher text array. At least TOX_PASS_ENCRYPTION_EXTRA_LENGTH. + * @param passphrase The user-provided password. Can be empty. + * @param passphrase_len The length of the password. + * @param plaintext The plain text array to write the decrypted data to. + * + * @return true on success. */ -bool tox_pass_encrypt(const uint8_t *data, size_t data_len, const uint8_t *passphrase, size_t pplength, uint8_t *out, - TOX_ERR_ENCRYPTION *error); +bool tox_pass_decrypt(const uint8_t *ciphertext, size_t ciphertext_len, const uint8_t *passphrase, + size_t passphrase_len, uint8_t *plaintext, TOX_ERR_DECRYPTION *error); -/* Decrypts the given data with the given passphrase. The output array must be - * at least data_len - TOX_PASS_ENCRYPTION_EXTRA_LENGTH bytes long. This delegates - * to tox_pass_key_decrypt. +/******************************************************************************* * - * the output data has size data_length - TOX_PASS_ENCRYPTION_EXTRA_LENGTH + * BEGIN PART 2 * - * returns true on success - */ -bool tox_pass_decrypt(const uint8_t *data, size_t length, const uint8_t *passphrase, size_t pplength, uint8_t *out, - TOX_ERR_DECRYPTION *error); + * And now part 2, which does the actual encryption, and can be used to write + * less CPU intensive client code than part one. + * + ******************************************************************************/ -/******************************* BEGIN PART 1 ******************************* - * And now part "1", which does the actual encryption, and is rather less cpu - * intensive than part one. The first 3 functions are for key handling. - */ -/* This key structure's internals should not be used by any client program, even - * if they are straightforward here. +/** + * This type represents a pass-key. + * + * A pass-key and a password are two different concepts: a password is given + * by the user in plain text. A pass-key is the generated symmetric key used + * for encryption and decryption. It is derived from a salt and the user- + * provided password. + * + * The Tox_Pass_Key structure is hidden in the implementation. It can be allocated + * using tox_pass_key_new and must be deallocated using tox_pass_key_free. */ -typedef struct { - uint8_t salt[TOX_PASS_SALT_LENGTH]; - uint8_t key[TOX_PASS_KEY_LENGTH]; -} TOX_PASS_KEY; +#ifndef TOX_PASS_KEY_DEFINED +#define TOX_PASS_KEY_DEFINED +typedef struct Tox_Pass_Key Tox_Pass_Key; +#endif /* TOX_PASS_KEY_DEFINED */ -/* Generates a secret symmetric key from the given passphrase. out_key must be at least - * TOX_PASS_KEY_LENGTH bytes long. - * Be sure to not compromise the key! Only keep it in memory, do not write to disk. - * The password is zeroed after key derivation. - * The key should only be used with the other functions in this module, as it - * includes a salt. - * Note that this function is not deterministic; to derive the same key from a - * password, you also must know the random salt that was used. See below. +/** + * Create a new Tox_Pass_Key. The initial value of it is indeterminate. To + * initialise it, use one of the derive_* functions below. * - * returns true on success + * In case of failure, this function returns NULL. The only failure mode at + * this time is memory allocation failure, so this function has no error code. */ -bool tox_derive_key_from_pass(const uint8_t *passphrase, size_t pplength, TOX_PASS_KEY *out_key, - TOX_ERR_KEY_DERIVATION *error); +struct Tox_Pass_Key *tox_pass_key_new(void); -/* Same as above, except use the given salt for deterministic key derivation. - * The salt must be TOX_PASS_SALT_LENGTH bytes in length. +/** + * Deallocate a Tox_Pass_Key. This function behaves like free(), so NULL is an + * acceptable argument value. */ -bool tox_derive_key_with_salt(const uint8_t *passphrase, size_t pplength, const uint8_t *salt, TOX_PASS_KEY *out_key, - TOX_ERR_KEY_DERIVATION *error); +void tox_pass_key_free(struct Tox_Pass_Key *_key); -/* This retrieves the salt used to encrypt the given data, which can then be passed to - * derive_key_with_salt to produce the same key as was previously used. Any encrpyted - * data with this module can be used as input. +/** + * Generates a secret symmetric key from the given passphrase. + * + * Be sure to not compromise the key! Only keep it in memory, do not write + * it to disk. + * + * Note that this function is not deterministic; to derive the same key from + * a password, you also must know the random salt that was used. A + * deterministic version of this function is tox_pass_key_derive_with_salt. * - * returns true if magic number matches - * success does not say anything about the validity of the data, only that data of - * the appropriate size was copied + * @param passphrase The user-provided password. Can be empty. + * @param passphrase_len The length of the password. + * + * @return true on success. */ -bool tox_get_salt(const uint8_t *data, uint8_t *salt); +bool tox_pass_key_derive(struct Tox_Pass_Key *_key, const uint8_t *passphrase, size_t passphrase_len, + TOX_ERR_KEY_DERIVATION *error); -/* Now come the functions that are analogous to the part 2 functions. */ +/** + * Same as above, except use the given salt for deterministic key derivation. + * + * @param passphrase The user-provided password. Can be empty. + * @param passphrase_len The length of the password. + * @param salt An array of at least TOX_PASS_SALT_LENGTH bytes. + * + * @return true on success. + */ +bool tox_pass_key_derive_with_salt(struct Tox_Pass_Key *_key, const uint8_t *passphrase, size_t passphrase_len, + const uint8_t *salt, TOX_ERR_KEY_DERIVATION *error); -/* Encrypt arbitrary with a key produced by tox_derive_key_*. The output - * array must be at least data_len + TOX_PASS_ENCRYPTION_EXTRA_LENGTH bytes long. - * key must be TOX_PASS_KEY_LENGTH bytes. - * If you already have a symmetric key from somewhere besides this module, simply - * call encrypt_data_symmetric in toxcore/crypto_core directly. +/** + * Encrypt a plain text with a key produced by tox_pass_key_derive or tox_pass_key_derive_with_salt. + * + * The output array must be at least `plaintext_len + TOX_PASS_ENCRYPTION_EXTRA_LENGTH` + * bytes long. + * + * @param plaintext A byte array of length `plaintext_len`. + * @param plaintext_len The length of the plain text array. Bigger than 0. + * @param ciphertext The cipher text array to write the encrypted data to. * - * returns true on success + * @return true on success. */ -bool tox_pass_key_encrypt(const uint8_t *data, size_t data_len, const TOX_PASS_KEY *key, uint8_t *out, - TOX_ERR_ENCRYPTION *error); +bool tox_pass_key_encrypt(const struct Tox_Pass_Key *_key, const uint8_t *plaintext, size_t plaintext_len, + uint8_t *ciphertext, TOX_ERR_ENCRYPTION *error); -/* This is the inverse of tox_pass_key_encrypt, also using only keys produced by - * tox_derive_key_from_pass. +/** + * This is the inverse of tox_pass_key_encrypt, also using only keys produced by + * tox_pass_key_derive or tox_pass_key_derive_with_salt. * - * the output data has size data_length - TOX_PASS_ENCRYPTION_EXTRA_LENGTH + * @param ciphertext A byte array of length `ciphertext_len`. + * @param ciphertext_len The length of the cipher text array. At least TOX_PASS_ENCRYPTION_EXTRA_LENGTH. + * @param plaintext The plain text array to write the decrypted data to. * - * returns true on success + * @return true on success. */ -bool tox_pass_key_decrypt(const uint8_t *data, size_t length, const TOX_PASS_KEY *key, uint8_t *out, - TOX_ERR_DECRYPTION *error); +bool tox_pass_key_decrypt(const struct Tox_Pass_Key *_key, const uint8_t *ciphertext, size_t ciphertext_len, + uint8_t *plaintext, TOX_ERR_DECRYPTION *error); -/* Determines whether or not the given data is encrypted (by checking the magic number) +typedef enum TOX_ERR_GET_SALT { + + /** + * The function returned successfully. + */ + TOX_ERR_GET_SALT_OK, + + /** + * One of the arguments to the function was NULL when it was not expected. + */ + TOX_ERR_GET_SALT_NULL, + + /** + * The input data is missing the magic number (i.e. wasn't created by this + * module, or is corrupted). + */ + TOX_ERR_GET_SALT_BAD_FORMAT, + +} TOX_ERR_GET_SALT; + + +/** + * Retrieves the salt used to encrypt the given data. + * + * The retrieved salt can then be passed to tox_pass_key_derive_with_salt to + * produce the same key as was previously used. Any data encrypted with this + * module can be used as input. + * + * The cipher text must be at least TOX_PASS_ENCRYPTION_EXTRA_LENGTH bytes in length. + * The salt must be TOX_PASS_SALT_LENGTH bytes in length. + * If the passed byte arrays are smaller than required, the behaviour is + * undefined. + * + * Success does not say anything about the validity of the data, only that + * data of the appropriate size was copied. + * + * @return true on success. + */ +bool tox_get_salt(const uint8_t *ciphertext, uint8_t *salt, TOX_ERR_GET_SALT *error); + +/** + * Determines whether or not the given data is encrypted by this module. + * + * It does this check by verifying that the magic number is the one put in + * place by the encryption functions. + * + * The data must be at least TOX_PASS_ENCRYPTION_EXTRA_LENGTH bytes in length. + * If the passed byte array is smaller than required, the behaviour is + * undefined. + * + * If the cipher text pointer is NULL, this function returns false. + * + * @return true if the data is encrypted by this module. */ bool tox_is_data_encrypted(const uint8_t *data); + #ifdef __cplusplus } #endif |