1 files changed, 40 insertions, 12 deletions

diff --git a/toxcore/tox.h b/toxcore/tox.h
index f1b8b893..b255de5e 100644
--- a/toxcore/tox.h
+++ b/toxcore/tox.h
@@ -255,6 +255,11 @@ bool tox_version_is_compatible(uint32_t major, uint32_t minor, uint32_t patch);
  */
 #define TOX_HASH_LENGTH                 /*crypto_hash_sha256_BYTES*/ 32
 
+/**
+ * The number of bytes in a file id.
+ */
+#define TOX_FILE_ID_LENGTH              32
+
 /*******************************************************************************
  *
  * :: Global enumerations
@@ -1412,9 +1417,9 @@ enum TOX_FILE_KIND {
      *
      * Clients who receive avatar send requests can reject it (by sending
      * TOX_FILE_CONTROL_CANCEL before any other controls), or accept it (by
-     * sending TOX_FILE_CONTROL_RESUME). The filename of length TOX_HASH_LENGTH bytes
-     * will contain the hash. A client can compare this hash with a
-     * saved hash and send TOX_FILE_CONTROL_CANCEL to terminate the avatar
+     * sending TOX_FILE_CONTROL_RESUME). The file_id of length TOX_HASH_LENGTH bytes
+     * (same length as TOX_FILE_ID_LENGTH) will contain the hash. A client can compare
+     * this hash with a saved hash and send TOX_FILE_CONTROL_CANCEL to terminate the avatar
      * transfer if it matches.
      */
     TOX_FILE_KIND_AVATAR
@@ -1534,6 +1539,32 @@ typedef void tox_file_recv_control_cb(Tox *tox, uint32_t friend_number, uint32_t
 void tox_callback_file_recv_control(Tox *tox, tox_file_recv_control_cb *function, void *user_data);
 
 
+typedef enum TOX_ERR_FILE_GET {
+    TOX_ERR_FILE_GET_OK,
+    /**
+     * The friend_number passed did not designate a valid friend.
+     */
+    TOX_ERR_FILE_GET_FRIEND_NOT_FOUND,
+    /**
+     * No file transfer with the given file number was found for the given friend.
+     */
+    TOX_ERR_FILE_GET_NOT_FOUND
+} TOX_ERR_FILE_GET;
+
+/**
+ * Copy the file id associated to the file transfer to a byte array.
+ *
+ * @param friend_number The friend number of the friend the file is being
+ *   transferred to.
+ * @param file_number The friend-specific identifier for the file transfer.
+ * @param file_id A memory region of at least TOX_FILE_ID_LENGTH bytes. If
+ *   this parameter is NULL, this function has no effect.
+ *
+ * @return true on success.
+ */
+bool tox_file_get_file_id(const Tox *tox, uint32_t friend_number, uint32_t file_number, uint8_t *file_id,
+                          TOX_ERR_FILE_GET *error);
+
 /*******************************************************************************
  *
  * :: File transmission: sending
@@ -1557,8 +1588,7 @@ typedef enum TOX_ERR_FILE_SEND {
      */
     TOX_ERR_FILE_SEND_NAME_EMPTY,
     /**
-     * Filename length exceeded 255 bytes or if kind was equal to TOX_FILE_KIND_AVATAR
-     * the length was not TOX_HASH_LENGTH.
+     * Filename length exceeded 255 bytes.
      */
     TOX_ERR_FILE_SEND_NAME_INVALID_LENGTH,
     /**
@@ -1581,11 +1611,6 @@ typedef enum TOX_ERR_FILE_SEND {
  * File transmission occurs in chunks, which are requested through the
  * `file_request_chunk` event.
  *
- * File numbers are stable across tox_save/tox_load cycles, so that file
- * transfers can be resumed when a client restarts. The client needs to
- * associate (friend Public Key, file number) with the local path of the file and
- * persist this information to support resuming of transfers across restarts.
- *
  * If the file contents change during a transfer, the behaviour is unspecified
  * in general. What will actually happen depends on the mode in which the file
  * was modified and how the client determines the file size.
@@ -1616,6 +1641,9 @@ typedef enum TOX_ERR_FILE_SEND {
  * @param kind The meaning of the file to be sent.
  * @param file_size Size in bytes of the file the client wants to send, 0 if
  *   unknown or streaming.
+ * @param file_id A file identifier of length TOX_FILE_ID_LENGTH that can be used to
+ *   uniquely identify file transfers across core restarts. If NULL, a random one will
+ *   be generated by core. It can then be obtained by using tox_file_get_file_id().
  * @param filename Name of the file. Does not need to be the actual name. This
  *   name will be sent along with the file send request.
  * @param filename_length Size in bytes of the filename.
@@ -1624,8 +1652,8 @@ typedef enum TOX_ERR_FILE_SEND {
  *   number is per friend. File numbers are reused after a transfer terminates.
  *   on failure, this function returns UINT32_MAX.
  */
-uint32_t tox_file_send(Tox *tox, uint32_t friend_number, uint32_t kind, uint64_t file_size, const uint8_t *filename,
-                       size_t filename_length, TOX_ERR_FILE_SEND *error);
+uint32_t tox_file_send(Tox *tox, uint32_t friend_number, uint32_t kind, uint64_t file_size, const uint8_t *file_id,
+                       const uint8_t *filename, size_t filename_length, TOX_ERR_FILE_SEND *error);
 
 
 typedef enum TOX_ERR_FILE_SEND_CHUNK {