CreateTorrent
Builds a .torrent file from a set of files, piece geometry and pre-computed piece hashes -- pure-Kotlin port of libtorrent's create_torrent (src/create_torrent.cpp, include/libtorrent/create_torrent.hpp).
In libtorrent a torrent is created in four steps:
determine the files that will be part of the torrent,
set torrent properties (trackers, web seeds, DHT nodes ...),
read all file data, SHA-1/SHA-256 it and set the piece hashes,
bencode the result into a buffer or file.
Step 3 (reading and hashing bytes off disk) is intentionally out of scope of the KiteTorrent core, which has no filesystem access in commonMain. Instead the caller supplies the already-computed hashes:
v2: one Sha256Hash per 16 KiB block via setHash2 (BEP 52),
exactly as libtorrent's set_piece_hashes() helper would feed them in. Once the hashes are set, generate produces the bencode tree and generateBuffer the encoded bytes.
v1 / v2 / hybrid
Like libtorrent, the "flavour" produced depends on the flags and which hashes were set:
construct with v1Only = true to force a v1-only torrent (setting v2 hashes is then an error),
construct with v2Only = true to force a v2-only torrent (setting v1 hashes is then an error),
otherwise, if both v1 and v2 hashes are fully set a hybrid torrent is produced; if only one side's hashes are set, that flavour is produced.
A SHA-1/SHA-256 hash of all zeros is the "unset" sentinel: setting such a hash is ignored, and a torrent whose hashes are not all set will not generate that flavour (mirrors validate_v1_hashes / validate_v2_hashes).
Files
Files are added through the constructor's FileStorage (build it directly) or, more conveniently, through a CreateTorrent.Builder. For a single-file torrent the one file's path is the torrent name. For a multi-file torrent every file's path begins with the torrent's root-directory name; in the generated files[] list the leading (root) component is deliberately dropped, exactly like libtorrent.
Parameters
Types
Fluent builder that collects files (path + size) and the torrent name, then produces a CreateTorrent. This is the convenience layer over constructing a FileStorage directly, analogous to libtorrent's add_files + file_storage feeding create_torrent.
Properties
The "creation date" field, a POSIX timestamp in seconds. null (the default) omits the field; libtorrent instead defaults to the wall clock at construction time, but core code has no clock, so omission is the honest default. Set it explicitly via creationDate / setCreationDate.
Functions
Adds a BEP 38 collection name.
Adds an HTTP seed (httpseeds).
Adds a DHT bootstrap node as a host/port pair (nodes).
Adds a BEP 38 "similar torrent" by info-hash.
Adds a tracker. Duplicate URLs are ignored. The tier is the fallback priority (all tier-0 trackers are tried first, then tier-1, ...); the URL list is kept sorted by tier, matching create_torrent::add_tracker.
Adds a BEP 19 web seed (url-list).
The files and piece geometry used to build the torrent.
Builds the .torrent as a bencode Entry tree, ready for Bencode.encode or for adding custom keys before encoding. Mirrors create_torrent::generate.
Bencodes generate into a fresh byte array (= Bencode.encode(generate())).
Number of pieces in the associated FileStorage.
Piece size of all pieces but the last. Forwards to the FileStorage.
Sets the (optional) UTF-8 comment. Passing null clears it.
Sets the "creation date" field (POSIX seconds); 0 or null omits it.
Sets the (optional) UTF-8 creator string, e.g. the software name.
Convenience for the common v2 case where the caller already holds a file's 16 KiB block hashes in order. Equivalent to calling setHash2 for each block.
Sets the private flag (BEP 27). Private torrents ask clients to use only the tracker -- no DHT, no PEX, no other peer sources.
Sets the X.509 root certificate (PEM) for an SSL torrent. The string is the certificate content, not a path.