Tox: updated tox core

git-svn-id: http://svn.miranda-ng.org/main/trunk@14333 1316c22d-e87f-b044-9b9b-93d7a3e3ba9c

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,