From 684ddd7667b7f7da1283e157948d54fdcda57392 Mon Sep 17 00:00:00 2001
From: Jfreegman <jfreegman@gmail.com>
Date: Sun, 28 Jun 2015 21:36:35 -0400
Subject: [PATCH] Clarifications for the TCP API

---
 toxcore/TCP_connection.c | 17 ++++++++++++++---
 toxcore/TCP_connection.h | 12 ++++++++++++
 2 files changed, 26 insertions(+), 3 deletions(-)

diff --git a/toxcore/TCP_connection.c b/toxcore/TCP_connection.c
index d26a60de..7a84c0c2 100644
--- a/toxcore/TCP_connection.c
+++ b/toxcore/TCP_connection.c
@@ -422,6 +422,8 @@ static int find_tcp_connection_relay(TCP_Connections *tcp_c, const uint8_t *rela
 }
 
 /* Create a new TCP connection to public_key.
+ *
+ * public_key must be the counterpart to the secret key that the other peer used with new_tcp_connections().
  *
  * id is the id in the callbacks for that connection.
  *
@@ -1006,7 +1008,7 @@ static int tcp_relay_on_online(TCP_Connections *tcp_c, int tcp_connections_numbe
     return 0;
 }
 
-static int add_tcp_relay(TCP_Connections *tcp_c, IP_Port ip_port, const uint8_t *relay_pk)
+static int add_tcp_relay_instance(TCP_Connections *tcp_c, IP_Port ip_port, const uint8_t *relay_pk)
 {
     if (ip_port.ip.family == TCP_INET) {
         ip_port.ip.family = AF_INET;
@@ -1036,7 +1038,7 @@ static int add_tcp_relay(TCP_Connections *tcp_c, IP_Port ip_port, const uint8_t
     return tcp_connections_number;
 }
 
-/* Add a TCP relay to the instance.
+/* Add a TCP relay to the TCP_Connections instance.
  *
  * return 0 on success.
  * return -1 on failure.
@@ -1048,7 +1050,7 @@ int add_tcp_relay_global(TCP_Connections *tcp_c, IP_Port ip_port, const uint8_t
     if (tcp_connections_number != -1)
         return -1;
 
-    if (add_tcp_relay(tcp_c, ip_port, relay_pk) == -1)
+    if (add_tcp_relay_instance(tcp_c, ip_port, relay_pk) == -1)
         return -1;
 
     return 0;
@@ -1088,6 +1090,8 @@ int add_tcp_number_relay_connection(TCP_Connections *tcp_c, int connections_numb
 }
 
 /* Add a TCP relay tied to a connection.
+ *
+ * This should be called with the same relay by two peers who want to create a TCP connection with each other.
  *
  * return 0 on success.
  * return -1 on failure.
@@ -1237,6 +1241,13 @@ int set_tcp_onion_status(TCP_Connections *tcp_c, _Bool status)
     return 0;
 }
 
+/* Returns a new TCP_Connections object associated with the secret_key.
+ *
+ * In order for others to connect to this instance new_tcp_connection_to() must be called with the
+ * public_key associated with secret_key.
+ *
+ * Returns NULL on failure.
+ */
 TCP_Connections *new_tcp_connections(const uint8_t *secret_key, TCP_Proxy_Info *proxy_info)
 {
     if (secret_key == NULL)
diff --git a/toxcore/TCP_connection.h b/toxcore/TCP_connection.h
index 140d6de3..7bc34f86 100644
--- a/toxcore/TCP_connection.h
+++ b/toxcore/TCP_connection.h
@@ -164,6 +164,8 @@ void set_oob_packet_tcp_connection_callback(TCP_Connections *tcp_c, int (*tcp_oo
         const uint8_t *public_key, unsigned int tcp_connections_number, const uint8_t *data, uint16_t length), void *object);
 
 /* Create a new TCP connection to public_key.
+ *
+ * public_key must be the counterpart to the secret key that the other peer used with new_tcp_connections().
  *
  * id is the id in the callbacks for that connection.
  *
@@ -205,6 +207,8 @@ int add_tcp_number_relay_connection(TCP_Connections *tcp_c, int connections_numb
                                     unsigned int tcp_connections_number);
 
 /* Add a TCP relay tied to a connection.
+ *
+ * This should be called with the same relay by two peers who want to create a TCP connection with each other.
  *
  * return 0 on success.
  * return -1 on failure.
@@ -226,7 +230,15 @@ int add_tcp_relay_global(TCP_Connections *tcp_c, IP_Port ip_port, const uint8_t
  */
 unsigned int tcp_copy_connected_relays(TCP_Connections *tcp_c, Node_format *tcp_relays, uint16_t max_num);
 
+/* Returns a new TCP_Connections object associated with the secret_key.
+ *
+ * In order for others to connect to this instance new_tcp_connection_to() must be called with the
+ * public_key associated with secret_key.
+ *
+ * Returns NULL on failure.
+ */
 TCP_Connections *new_tcp_connections(const uint8_t *secret_key, TCP_Proxy_Info *proxy_info);
+
 void do_tcp_connections(TCP_Connections *tcp_c);
 void kill_tcp_connections(TCP_Connections *tcp_c);