diff options
Diffstat (limited to 'protocols/Tox/include/tox.h')
| -rw-r--r-- | protocols/Tox/include/tox.h | 37 |
1 files changed, 28 insertions, 9 deletions
diff --git a/protocols/Tox/include/tox.h b/protocols/Tox/include/tox.h index 9a6d3ecf79..f2a27006bc 100644 --- a/protocols/Tox/include/tox.h +++ b/protocols/Tox/include/tox.h @@ -31,6 +31,15 @@ extern "C" { #endif + +/******************************************************************************* + * `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` * + ******************************************************************************/ + + + /** \page core Public core API for Tox clients. * * Every function that can fail takes a function-specific error code pointer @@ -450,7 +459,15 @@ struct Tox_Options { /** - * The port to use for the TCP server. If 0, the tcp server is disabled. + * The port to use for the TCP server (relay). If 0, the TCP server is + * disabled. + * + * Enabling it is not required for Tox to function properly. + * + * When enabled, your Tox instance can act as a TCP relay for other Tox + * instance. This leads to increased traffic, thus when writing a client + * it is recommended to enable TCP server only if the user has an option + * to disable it. */ uint16_t tcp_port; @@ -608,6 +625,8 @@ typedef enum TOX_ERR_NEW { * NULL, the default options are used. * * @see tox_iterate for the event loop. + * + * @return A new Tox instance pointer on success or NULL on failure. */ Tox *tox_new(const struct Tox_Options *options, TOX_ERR_NEW *error); @@ -676,13 +695,8 @@ typedef enum TOX_ERR_BOOTSTRAP { * Sends a "get nodes" request to the given bootstrap node with IP, port, and * public key to setup connections. * - * This function will attempt to connect to the node using UDP and TCP at the - * same time. - * - * Tox will use the node as a TCP relay in case Tox_Options.udp_enabled was - * false, and also to connect to friends that are in TCP-only mode. Tox will - * also use the TCP connection when NAT hole punching is slow, and later switch - * to UDP if hole punching succeeds. + * This function will attempt to connect to the node using UDP. You must use + * this function even if Tox_Options.udp_enabled was set to false. * * @param 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 @@ -1593,7 +1607,7 @@ enum TOX_FILE_KIND { TOX_FILE_KIND_DATA, /** - * Avatar filename. This consists of tox_hash(image). + * Avatar file_id. This consists of tox_hash(image). * Avatar data. This consists of the image data. * * Avatars can be sent at any time the client wishes. Generally, a client will @@ -1783,6 +1797,11 @@ typedef enum TOX_ERR_FILE_GET { TOX_ERR_FILE_GET_OK, /** + * One of the arguments to the function was NULL when it was not expected. + */ + TOX_ERR_FILE_GET_NULL, + + /** * The friend_number passed did not designate a valid friend. */ TOX_ERR_FILE_GET_FRIEND_NOT_FOUND, |