Package com.frostwire.jlibtorrent

Class AddTorrentParams

java.lang.Object
com.frostwire.jlibtorrent.AddTorrentParams
public final class AddTorrentParams extends Object
Configuration parameters for adding a torrent to the session.

AddTorrentParams is a configuration bundle that specifies everything needed to add a torrent to a session. You must provide one of three sources:

  • Torrent File: - Direct .torrent file
  • Magnet Link: - Magnet link or HTTP URL to .torrent
  • Info-Hash Only: or

Additionally, you must specify - where to save downloaded files.

Creating AddTorrentParams for Different Scenarios:

From .torrent File (Most Common): 

 TorrentInfo ti = new TorrentInfo(new File("ubuntu.torrent"));

 AddTorrentParams params = new AddTorrentParams();
 params.torrentInfo(ti);
 params.savePath("/path/to/downloads");

 // Optional: Set file priorities
 Priority[] priorities = {Priority.NORMAL, Priority.IGNORE, Priority.NORMAL};
 params.filePriorities(priorities);

 // Optional: Set storage mode
 params.storageMode(StorageMode.STORAGE_MODE_SPARSE);

 sm.download(ti, new File("/path/to/downloads"));

From Magnet Link: 

 String magnetLink = "magnet:?xt=urn:btih:C1939CA413B9302..." +
                     "&dn=Ubuntu+20.04.iso&tr=http%3A%2F%2Ftracker.example.com";

 AddTorrentParams params = new AddTorrentParams();
 params.url(magnetLink);
 params.savePath("/path/to/downloads");

 // The session will fetch metadata from peers
 // Listen for METADATA_RECEIVED alert to know when ready

From Info-Hash Only (DHT/PEX Discovery): 

 // You have an info-hash, no metadata yet
 Sha1Hash infoHash = new Sha1Hash("d8e8fca2dc0f896fd7cb4cb0031ba249");

 AddTorrentParams params = new AddTorrentParams();
 params.infoHashV1(infoHash);
 params.name("Unknown Torrent");  // Temporary name until metadata arrives
 params.savePath("/path/to/downloads");

 // Session will download metadata from peers

Advanced Configuration: 

 AddTorrentParams params = new AddTorrentParams();
 params.torrentInfo(ti);
 params.savePath("/path/to/downloads");

 // Advanced options:
 params.resume(resumeData);            // Resume from saved state
 params.filePriorities(priorities);    // Skip some files
 params.storageMode(StorageMode.STORAGE_MODE_ALLOCATE); // Pre-allocate

 // Flags control behavior
 params.flags(new torrent_flags_t());  // Can set multiple flags
 params.name("Custom Name");           // For display
 params.comment("Download added via API");

 // Ports and endpoints
 List<TcpEndpoint> peers = ...;
 params.peers(peers);  // Pre-seed with known peers

 // Max upload rate for this torrent
 params.uploadLimit(500 * 1024);  // 500 KB/s max

Metadata Extensions: When adding a torrent with only an info-hash (no .torrent file), metadata must be downloaded from peers. This requires BEP 9 support (metadata extension) on peers. 

 AddTorrentParams params = new AddTorrentParams();
 params.infoHashV1(sha1Hash);
 params.savePath("/downloads");

 // Listen for metadata updates
 sm.addListener(new AlertListener() {
     public int[] types() {
         return new int[] {AlertType.METADATA_RECEIVED.swig()};
     }

     public void alert(Alert<?> alert) {
         if (alert instanceof MetadataReceivedAlert) {
             System.out.println("Metadata received!");
             TorrentHandle th = ((MetadataReceivedAlert) alert).handle();
         }
     }
 });

Resume Data: You can resume an incomplete download using saved resume data: 

 // From a previous session
 byte[] resumeData = Files.readAllBytes(Paths.get("resume.data"));

 AddTorrentParams params = new AddTorrentParams();
 params.torrentInfo(ti);
 params.savePath("/path/to/downloads");
 params.resume(resumeData);  // Skip checking already-downloaded pieces

 // This resumes quickly without re-checking files
See Also:

  • Constructor Details

    • AddTorrentParams

      public AddTorrentParams(com.frostwire.jlibtorrent.swig.add_torrent_params p)
      The native object
      Parameters:
      p - the native object

    • AddTorrentParams

      public AddTorrentParams()
      Creates an empty parameters object with the default storage.

  • Method Details

    • swig

      public com.frostwire.jlibtorrent.swig.add_torrent_params swig()
      Returns:
      the native object

    • version

      public int version()
      Filled in by the constructor. It is used for forward binary compatibility.
      Returns:
      the version

    • torrentInfo

      public TorrentInfo torrentInfo()
      object with the torrent to add.
      Returns:
      the torrent info or null if not set

    • torrentInfo

      public void torrentInfo(TorrentInfo ti)
      object with the torrent to add.
      Parameters:
      ti - the torrent info

    • trackers

      public ArrayList<String> trackers()
      If the torrent doesn't have a tracker, but relies on the DHT to find peers, the can specify tracker URLs for the torrent.
      Returns:
      the list of trackers

    • trackers

      public void trackers(List<String> value)
      If the torrent doesn't have a tracker, but relies on the DHT to find peers, this method can specify tracker URLs for the torrent.
      Parameters:
      value - the list of trackers

    • trackerTiers

      public ArrayList<Integer> trackerTiers()
      The tiers the URLs in belong to. Trackers belonging to different tiers may be treated differently, as defined by the multi tracker extension. This is optional, if not specified trackers are assumed to be part of tier 0, or whichever the last tier was as iterating over the trackers.
      Returns:
      the list of trackers tiers

    • trackerTiers

      public void trackerTiers(List<Integer> value)
      The tiers the URLs in belong to. Trackers belonging to different tiers may be treated differently, as defined by the multi tracker extension. This is optional, if not specified trackers are assumed to be part of tier 0, or whichever the last tier was as iterating over the trackers.
      Parameters:
      value - the list of trackers tiers

    • dhtNodes

      public ArrayList<Pair<String,Integer>> dhtNodes()
      A list of hostname and port pairs, representing DHT nodes to be added to the session (if DHT is enabled). The hostname may be an IP address.
      Returns:
      the list of DHT nodes

    • get_verified_leaf_hashes

      public List<List<Boolean>> get_verified_leaf_hashes()

    • dhtNodes

      public void dhtNodes(List<Pair<String,Integer>> value)
      A list of hostname and port pairs, representing DHT nodes to be added to the session (if DHT is enabled). The hostname may be an IP address.
      Parameters:
      value - the list of DHT nodes

    • name

      public String name()
      Returns:
      the name

    • name

      public void name(String value)
      Parameters:
      value - the name

    • savePath

      public String savePath()
      The path where the torrent is or will be stored. Note that this may also be stored in resume data. If you want the save path saved in the resume data to be used, you need to set the flag_use_resume_save_path flag.

      .. note:: On windows this path (and other paths) are interpreted as UNC paths. This means they must use backslashes as directory separators

      Returns:
      the save path

    • savePath

      public void savePath(String value)
      The path where the torrent is or will be stored. Note that this may also be stored in resume data. If you want the save path saved in the resume data to be used, you need to set the flag_use_resume_save_path flag.

      .. note:: On windows this path (and other paths) are interpreted as UNC paths. This means they must use backslashes as directory separators

      Parameters:
      value - the save path

    • storageMode

      public StorageMode storageMode()
      Returns:
      the storage mode
      See Also:

    • storageMode

      public void storageMode(StorageMode value)
      Parameters:
      value - the storage mode
      See Also:

    • trackerId

      public String trackerId()
      The default tracker id to be used when announcing to trackers. By default this is empty, and no tracker ID is used, since this is an optional argument. If a tracker returns a tracker ID, that ID is used instead of this.
      Returns:
      the trackerid url parameter

    • trackerId

      public void trackerId(String value)
      The default tracker id to be used when announcing to trackers. By default this is empty, and no tracker ID is used, since this is an optional argument. If a tracker returns a tracker ID, that ID is used instead of this.
      Parameters:
      value - the trackerid url parameter

    • getInfoHashes

      public InfoHash getInfoHashes()
      Set this to the info hash of the torrent to add in case the info-hash is the only known property of the torrent. i.e. you don't have a .torrent file nor a magnet link.
      Returns:
      the info-hash

    • setInfoHashes

      public void setInfoHashes(InfoHash value)
      Set this to the info hash of the torrent to add in case the info-hash is the only known property of the torrent. i.e. you don't have a .torrent file nor a magnet link.
      Parameters:
      value - the info-hash

    • maxUploads

      public int maxUploads()
      Returns:
      max uploads limit

    • maxUploads

      public void maxUploads(int value)
      Parameters:
      value - max uploads limit

    • maxConnections

      public int maxConnections()
      Returns:
      max connections limit

    • maxConnections

      public void maxConnections(int value)
      Parameters:
      value - max connections limit

    • uploadLimit

      public int uploadLimit()
      Returns:
      upload limit

    • uploadLimit

      public void uploadLimit(int value)
      Parameters:
      value - upload limit

    • downloadLimit

      public int downloadLimit()
      Returns:
      download limit

    • downloadLimit

      public void downloadLimit(int value)
      Parameters:
      value - download limit

    • flags

      public com.frostwire.jlibtorrent.swig.torrent_flags_t flags()
      Flags controlling aspects of this torrent and how it's added.
      Returns:
      the flags

    • flags

      public void flags(com.frostwire.jlibtorrent.swig.torrent_flags_t flags)
      Flags controlling aspects of this torrent and how it's added.
      Parameters:
      flags - the flags

    • urlSeeds

      public ArrayList<String> urlSeeds()
      Url seeds to be added to the torrent (`BEP 17`_).
      Returns:
      the url seeds

    • urlSeeds

      public void urlSeeds(List<String> value)
      Url seeds to be added to the torrent (`BEP 17`_).
      Parameters:
      value - the url seeds

    • filePriorities

      public void filePriorities(Priority[] priorities)
      Can be set to control the initial file priorities when adding a torrent. The semantics are the same as for TorrentHandle.prioritizeFiles(Priority[]).
      Parameters:
      priorities - the priorities

    • piecePriorities

      public void piecePriorities(Priority[] priorities)
      This sets the priorities for each individual piece in the torrent. Each element in the vector represent the piece with the same index. If you set both file- and piece priorities, file priorities will take precedence.
      Parameters:
      priorities - the priorities

    • peers

      public ArrayList<TcpEndpoint> peers()
      Peers to add to the torrent, to be tried to be connected to as bittorrent peers.
      Returns:
      the peers list

    • peers

      public void peers(List<TcpEndpoint> value)
      Peers to add to the torrent, to be tried to be connected to as bittorrent peers.
      Parameters:
      value - the peers list

    • bannedPeers

      public ArrayList<TcpEndpoint> bannedPeers()
      Peers banned from this torrent. The will not be connected to.
      Returns:
      the peers list

    • bannedPeers

      public void bannedPeers(List<TcpEndpoint> value)
      Peers banned from this torrent. The will not be connected to.
      Parameters:
      value - the peers list

    • createInstance

      public static AddTorrentParams createInstance()
      Returns:
      an instance with the default storage

    • parseMagnetUri

      public static AddTorrentParams parseMagnetUri(String uri)
      Helper function to parse a magnet uri and fill the parameters.
      Parameters:
      uri - the magnet uri
      Returns:
      the params object filled with the data from the magnet

    • writeResumeData

      public static Entry writeResumeData(AddTorrentParams params)
      Turns the resume data in an `AddTorrentParams` object into a bencoded structure.