Class FileStorage

java.lang.Object
com.frostwire.jlibtorrent.FileStorage
public final class FileStorage extends Object
Represents the file structure and piece mapping for a torrent.

FileStorage contains the list of files in a torrent and maps logical pieces to physical file locations on disk. It's used both for:

  • Inspecting torrents: Querying file names, sizes, and piece mapping
  • Creating torrents: Adding files and setting piece size
  • Modifying torrents: Renaming files or remapping pieces

Understanding Pieces and Files:
In BitTorrent, content is divided into fixed-size "pieces" (typically 16 KB to 16 MB each). A piece might span across multiple files, and a file might contain data from multiple pieces. FileStorage manages this mapping: 

 File1 (1 MB)  |  File2 (2 MB)  |  File3 (500 KB)
 Piece0 [====] | [===Piece1===] | [=Piece2====]

Reading Torrent Files: 

 TorrentInfo ti = new TorrentInfo(new File("download.torrent"));
 FileStorage fs = ti.files();

 long totalSize = fs.totalSize();
 int numFiles = fs.numFiles();
 int pieceLength = fs.pieceLength();
 int numPieces = fs.numPieces();

 // Iterate through files
 for (int i = 0; i < numFiles; i++) {
     String fileName = fs.fileName(i);
     long fileSize = fs.fileSize(i);
     int flags = fs.fileFlags(i);
     System.out.println(fileName + " (" + fileSize + " bytes)");
 }

Creating Torrents: 

 FileStorage fs = new FileStorage();
 fs.setPieceLength(262144); // 256 KB pieces
 fs.addFile("video.mp4", 1000000000L);
 fs.addFile("readme.txt", 5000);

 // Use this storage to create a torrent
 TorrentBuilder tb = new TorrentBuilder(fs, ...);

File Path Conventions: Multi-file torrents have all files under a common root directory (the torrent name). Single-file torrents have no root directory - the path is the file name itself. 

 // Multi-file torrent
 fs.addFile("MyTorrent/file1.txt", 1000);
 fs.addFile("MyTorrent/subdir/file2.txt", 2000);

 // Single-file torrent
 fs.addFile("myfile.iso", 1000000);

File Operations: 

 FileStorage fs = ti.files();

 // Get files that contain a specific piece
 FileSlice slice = fs.mapBlock(pieceIndex, 0, pieceLength);
 System.out.println("Piece in file: " + slice.fileIndex() + ", offset: " + slice.offset());

 // Rename a file (creates a copy for modification)
 TorrentInfo ti2 = new TorrentInfo(ti.swig());
 ti2.renameFile(0, "new-name.txt");
See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final com.frostwire.jlibtorrent.swig.file_flags_t
    FLAG_EXECUTABLE
    This file is executable (sets the executable bit on posix like systems).
    static final com.frostwire.jlibtorrent.swig.file_flags_t
    FLAG_HIDDEN
    This file is hidden (sets the hidden attribute on windows).
    static final com.frostwire.jlibtorrent.swig.file_flags_t
    FLAG_PAD_FILE
    This file is a pad file.
    static final com.frostwire.jlibtorrent.swig.file_flags_t
    FLAG_SYMLINK
    This file is a symlink.

  • Constructor Summary

    Constructors
    Constructor
    Description
    FileStorage(com.frostwire.jlibtorrent.swig.file_storage fs)
     

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    addFile(String p, long size)
    Adds a file to the file storage.
    void
    addFile(String path, long size, com.frostwire.jlibtorrent.swig.file_flags_t flags)
    Adds a file to the file storage.
    void
    addFile(String path, long size, com.frostwire.jlibtorrent.swig.file_flags_t flags, int mtime)
    Adds a file to the file storage.
    void
    addFile(String path, long size, com.frostwire.jlibtorrent.swig.file_flags_t flags, int mtime, String symlink)
    Adds a file to the file storage.
    boolean
    fileAbsolutePath(int index)
    Returns true if the file at the specified index has been renamed to have an absolute path, i.e.
    com.frostwire.jlibtorrent.swig.file_flags_t
    fileFlags(int index)
    Returns a bitmask of flags from file_flags_t that apply to file at index.
    int
    fileIndexAtOffset(long offset)
    Returns the index of the file at the given offset in the torrent.
    String
    fileName(int index)
    Returns only the name of the file, whereas returns the path (inside the torrent file) with the filename appended.
    long
    fileOffset(int index)
    returns the byte offset within the torrent file where this file starts.
    String
    filePath(int index)
    Returns the full path to a file.
    String
    filePath(int index, String savePath)
    returns the full path to a file.
    long
    fileSize(int index)
    returns the size of a file.
    Sha1Hash
    hash(int index)
    Is a sha-1 hash of the file, or 0 if none was provided in the torrent file.
    boolean
    isValid()
    Returns true if the piece length has been initialized on the file_storage.
    ArrayList<FileSlice>
    mapBlock(int piece, long offset, int size)
    Returns a list of FileSlice objects representing the portions of files the specified piece index, byte offset and size range overlaps.
    PeerRequest
    mapFile(int file, long offset, int size)
    Returns a PeerRequest representing the piece index, byte offset and size the specified file range overlaps.
    String
    name()
    Get the name of this torrent.
    void
    name(String name)
    Set the name of this torrent.
    int
    numFiles()
    Returns the number of files in the file_storage.
    int
    numPieces()
    Returns the number of pieces in the torrent.
    void
    numPieces(int n)
    Set the number of pieces in the torrent.
    boolean
    padFileAt(int index)
    returns true if the file at the given index is a pad-file.
    ArrayList<String>
    paths()
     
    int
    pieceLength()
    Get the size of each piece in this torrent.
    void
    pieceLength(int l)
    Set the size of each piece in this torrent.
    int
    pieceSize(int index)
    Returns the piece size of index.
    void
    renameFile(int index, String newFilename)
    Renames the file at index to newFilename.
    void
    reserve(int numFiles)
    Allocates space for numFiles in the internal file list.
    com.frostwire.jlibtorrent.swig.file_storage
    swig()
     
    com.frostwire.jlibtorrent.swig.torrent_info
    ti()
    This methods returns the internal torrent info or null if it was constructed without one.
    long
    totalSize()
    Returns the total number of bytes all the files in this torrent spans.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • FLAG_PAD_FILE

      public static final com.frostwire.jlibtorrent.swig.file_flags_t FLAG_PAD_FILE
      This file is a pad file. The creator of the torrent promises the file is entirely filled with zeroes and does not need to be downloaded. The purpose is just to align the next file to either a block or piece boundary.

    • FLAG_HIDDEN

      public static final com.frostwire.jlibtorrent.swig.file_flags_t FLAG_HIDDEN
      This file is hidden (sets the hidden attribute on windows).

    • FLAG_EXECUTABLE

      public static final com.frostwire.jlibtorrent.swig.file_flags_t FLAG_EXECUTABLE
      This file is executable (sets the executable bit on posix like systems).

  • Constructor Details

    • FileStorage

      public FileStorage(com.frostwire.jlibtorrent.swig.file_storage fs)
      Parameters:
      fs - the native object

  • Method Details

    • swig

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

    • ti

      public com.frostwire.jlibtorrent.swig.torrent_info ti()
      This methods returns the internal torrent info or null if it was constructed without one.

      This also prevent premature garbage collection in case the storage was created from a torrent info.

      Returns:
      the pinned torrent info

    • isValid

      public boolean isValid()
      Returns true if the piece length has been initialized on the file_storage. This is typically taken as a proxy of whether the file_storage as a whole is initialized or not.
      Returns:
      true if valid

    • reserve

      public void reserve(int numFiles)
      Allocates space for numFiles in the internal file list. This can be used to avoid reallocating the internal file list when the number of files to be added is known up-front.
      Parameters:
      numFiles - the number of files

    • addFile

      public void addFile(String path, long size, com.frostwire.jlibtorrent.swig.file_flags_t flags, int mtime, String symlink)
      Adds a file to the file storage. The flags argument sets attributes on the file. The file attributes is an extension and may not work in all bittorrent clients.

      If more files than one are added, certain restrictions to their paths apply. In a multi-file file storage (torrent), all files must share the same root directory.

      That is, the first path element of all files must be the same. This shared path element is also set to the name of the torrent. It can be changed by calling .

      The built in functions to traverse a directory to add files will make sure this requirement is fulfilled.

      Parameters:
      path - the path
      size - the file size
      flags - the file flags
      mtime - the time
      symlink - the symlink

    • addFile

      public void addFile(String path, long size, com.frostwire.jlibtorrent.swig.file_flags_t flags, int mtime)
      Adds a file to the file storage. The flags argument sets attributes on the file. The file attributes is an extension and may not work in all bittorrent clients.

      If more files than one are added, certain restrictions to their paths apply. In a multi-file file storage (torrent), all files must share the same root directory.

      That is, the first path element of all files must be the same. This shared path element is also set to the name of the torrent. It can be changed by calling .

      The built in functions to traverse a directory to add files will make sure this requirement is fulfilled.

      Parameters:
      path - the path
      size - the file size
      flags - the file flags
      mtime - the time

    • addFile

      public void addFile(String path, long size, com.frostwire.jlibtorrent.swig.file_flags_t flags)
      Adds a file to the file storage. The flags argument sets attributes on the file. The file attributes is an extension and may not work in all bittorrent clients.

      If more files than one are added, certain restrictions to their paths apply. In a multi-file file storage (torrent), all files must share the same root directory.

      That is, the first path element of all files must be the same. This shared path element is also set to the name of the torrent. It can be changed by calling .

      The built in functions to traverse a directory to add files will make sure this requirement is fulfilled.

      Parameters:
      path - the path
      size - the file size
      flags - the file flags

    • addFile

      public void addFile(String p, long size)
      Adds a file to the file storage.

      If more files than one are added, certain restrictions to their paths apply. In a multi-file file storage (torrent), all files must share the same root directory.

      That is, the first path element of all files must be the same. This shared path element is also set to the name of the torrent. It can be changed by calling .

      The built in functions to traverse a directory to add files will make sure this requirement is fulfilled.

      Parameters:
      p -
      size -

    • renameFile

      public void renameFile(int index, String newFilename)
      Renames the file at index to newFilename. Keep in mind that filenames are expected to be UTF-8 encoded.
      Parameters:
      index -
      newFilename -

    • mapBlock

      public ArrayList<FileSlice> mapBlock(int piece, long offset, int size)
      Returns a list of FileSlice objects representing the portions of files the specified piece index, byte offset and size range overlaps.

      This is the inverse mapping of .

      Parameters:
      piece -
      offset -
      size -
      Returns:

    • mapFile

      public PeerRequest mapFile(int file, long offset, int size)
      Returns a PeerRequest representing the piece index, byte offset and size the specified file range overlaps. This is the inverse mapping of .

      Note that the return type is meant to hold bittorrent block requests, which may not be larger than 16 kiB. Mapping a range larger than that may return an overflown integer.

      Parameters:
      file -
      offset -
      size -
      Returns:

    • numFiles

      public int numFiles()
      Returns the number of files in the file_storage.
      Returns:

    • totalSize

      public long totalSize()
      Returns the total number of bytes all the files in this torrent spans.
      Returns:

    • numPieces

      public int numPieces()
      Returns the number of pieces in the torrent.
      Returns:
      the number of pieces in the torrent

    • numPieces

      public void numPieces(int n)
      Set the number of pieces in the torrent.
      Parameters:
      n -

    • pieceLength

      public int pieceLength()
      Get the size of each piece in this torrent. This size is typically an even power of 2. It doesn't have to be though. It should be divisible by 16kiB however.
      Returns:

    • pieceLength

      public void pieceLength(int l)
      Set the size of each piece in this torrent. This size is typically an even power of 2. It doesn't have to be though. It should be divisible by 16kiB however.
      Parameters:
      l -

    • pieceSize

      public int pieceSize(int index)
      Returns the piece size of index. This will be the same as , except for the last piece, which may be shorter.
      Parameters:
      index -
      Returns:

    • name

      public String name()
      Get the name of this torrent. For multi-file torrents, this is also the name of the root directory all the files are stored in.
      Returns:

    • name

      public void name(String name)
      Set the name of this torrent. For multi-file torrents, this is also the name of the root directory all the files are stored in.
      Parameters:
      name -

    • hash

      public Sha1Hash hash(int index)
      Is a sha-1 hash of the file, or 0 if none was provided in the torrent file. This can potentially be used to join a bittorrent network with other file sharing networks.
      Parameters:
      index -
      Returns:

    • filePath

      public String filePath(int index, String savePath)
      returns the full path to a file.
      Parameters:
      index -
      savePath -
      Returns:

    • filePath

      public String filePath(int index)
      Returns the full path to a file.
      Parameters:
      index - the file index
      Returns:
      the full path

    • fileName

      public String fileName(int index)
      Returns only the name of the file, whereas returns the path (inside the torrent file) with the filename appended.
      Parameters:
      index - the file index
      Returns:
      the file name

    • fileSize

      public long fileSize(int index)
      returns the size of a file.
      Parameters:
      index -
      Returns:

    • padFileAt

      public boolean padFileAt(int index)
      returns true if the file at the given index is a pad-file.
      Parameters:
      index -
      Returns:

    • fileOffset

      public long fileOffset(int index)
      returns the byte offset within the torrent file where this file starts. It can be used to map the file to a piece index (given the piece size).
      Parameters:
      index -
      Returns:

    • paths

      public ArrayList<String> paths()
      Returns:

    • fileFlags

      public com.frostwire.jlibtorrent.swig.file_flags_t fileFlags(int index)
      Returns a bitmask of flags from file_flags_t that apply to file at index.
      Parameters:
      index -
      Returns:
      the flags

    • fileAbsolutePath

      public boolean fileAbsolutePath(int index)
      Returns true if the file at the specified index has been renamed to have an absolute path, i.e. is not anchored in the save path of the torrent.
      Parameters:
      index -
      Returns:

    • fileIndexAtOffset

      public int fileIndexAtOffset(long offset)
      Returns the index of the file at the given offset in the torrent.
      Parameters:
      offset -
      Returns: