file_send

Send a file transmission request.

Maximum filename length is MAX_FILENAME_LENGTH bytes. The filename should generally just be a file name, not a path with directory names.

If a non-UINT64_MAX file size is provided, it can be used by both sides to determine the sending progress. File size can be set to UINT64_MAX for streaming data of unknown size.

File transmission occurs in chunks, which are requested through the `file_chunk_request` event.

When a friend goes offline, all file transfers associated with the friend are purged from core.

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.

• If the file size was increased
  • and sending mode was streaming (file_size = UINT64_MAX), the behaviour

    will be as expected.

  • and sending mode was file (file_size != UINT64_MAX), the

    file_chunk_request callback will receive length = 0 when Core thinks

    the file transfer has finished. If the client remembers the file size as

    it was when sending the request, it will terminate the transfer normally.

    If the client re-reads the size, it will think the friend cancelled the

    transfer.

• If the file size was decreased
  • and sending mode was streaming, the behaviour is as expected.
  • and sending mode was file, the callback will return 0 at the new

    (earlier) end-of-file, signalling to the friend that the transfer was

    cancelled.

• If the file contents were modified
  • at a position before the current read, the two files (local and remote)

    will differ after the transfer terminates.

  • at a position after the current read, the file transfer will succeed as

    expected.

  • In either case, both sides will regard the transfer as complete and

    successful.

Parameters:

friend_number	The friend number of the friend the file send request should be sent to.
kind	The meaning of the file to be sent.
file_size	Size in bytes of the file the client wants to send, UINT64_MAX if unknown or streaming.
file_id	A file identifier of length 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().
filename	Name of the file. Does not need to be the actual name. This name will be sent along with the file send request.

Returns:

A file number used as an identifier in subsequent callbacks. This number is per friend. File numbers are reused after a transfer terminates. On failure, this function returns an unspecified value. Any pattern in file numbers should not be relied on.