org.klomp.snark

## Class MetaInfo

- java.lang.Object
- - org.klomp.snark.MetaInfo

-     public class MetaInfo
      extends Object

  Holds all information extracted from a torrent file.

  This class parses and stores the metadata from .torrent files, including:

  - Tracker announce URLs
  - Info hash for torrent identification
  - File names, sizes, and structure
  - Piece length and piece hashes for integrity verification

  Note: This class has a known limitation where it doesn't propagate custom meta fields into the bencoded info data, and from there to the info_hash. However, it currently works with torrents created by I2P-BT, I2PRufus and Azureus.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `MetaInfo(InputStream in)` Creates a new MetaInfo from the given InputStream.
    `MetaInfo(Map<String,BEValue> m)` Creates a new MetaInfo from a Map of BEValues and the SHA1 over the original bencoded info dictionary (this is a hack, we could reconstruct the bencoded stream and recalculate the hash).
    `MetaInfo(MetaInfo old, String new_announce, List<List<String>> new_announce_list, String new_comment, String new_created_by, List<String> new_url_list)` Will not change infohash.
    `MetaInfo(String announce, String name, String name_utf8, List<List<String>> files, List<Long> lengths, int piece_length, byte[] piece_hashes, long length, boolean privateTorrent, List<List<String>> announce_list, String created_by, List<String> url_list, String comment)` Called by Storage when creating a new torrent from local data
    `MetaInfo(String announce, String name, String name_utf8, List<List<String>> files, List<Long> lengths, int piece_length, byte[] piece_hashes, long length, int privateTorrent, List<List<String>> announce_list, String created_by, List<String> url_list, String comment)` Preserves privateTorrent int value, for main()

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `checkPiece(int piece, byte[] bs, int off, int length)` Checks that the given piece has the same SHA1 hash as the given byte array.
    `(package private) boolean` | `checkPiece(PartialPiece pp)`
    `String` | `getAnnounce()` Returns the string representing the URL of the tracker for this torrent.
    `List<List<String>>` | `getAnnounceList()` Returns a list of lists of urls.
    `String` | `getComment()` The comment string or null.
    `String` | `getCreatedBy()` The created-by string or null.
    `long` | `getCreationDate()` The creation date (ms) or zero.
    `List<List<String>>` | `getFiles()` Returns a list of lists of file name hierarchies or null if it is a single name.
    `byte[]` | `getInfoBytes()` Side effect: Caches infoBytesLength.
    `int` | `getInfoBytesLength()` The size of getInfoBytes().
    `byte[]` | `getInfoHash()` Returns the original 20 byte SHA1 hash over the bencoded info map.
    `List<Long>` | `getLengths()` Returns a list of Longs indication the size of the individual files, or null if it is a single file.
    `String` | `getName()` Returns the requested name for the file or toplevel directory.
    `static String` | `getNameAndInfoHash(InputStream in, byte[] infoHashOut)` Efficiently returns the name and the 20 byte SHA1 hash of the info dictionary in a torrent file Caller must close stream.
    `byte[]` | `getPieceHashes()` Returns the piece hashes.
    `int` | `getPieceLength(int piece)` Return the length of a piece.
    `int` | `getPieces()` Returns the number of pieces.
    `int` | `getPrivateTrackerStatus()`
    `byte[]` | `getTorrentData()` Called by servlet to save a new torrent file generated from local data
    `long` | `getTotalLength()` Returns the total length of the torrent in bytes.
    `List<String>` | `getWebSeedURLs()` Returns a list of urls or null.
    `boolean` | `isPaddingFile(int filenum)` Is this file a padding file?
    `boolean` | `isPrivate()` Is it a private torrent?
    `static void` | `main(String[] args)`
    `MetaInfo` | `reannounce(String announce)` Creates a copy of this MetaInfo that shares everything except the announce URL.
    `String` | `toString()`

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### MetaInfo

          public MetaInfo(InputStream in)
                   throws IOException

      Creates a new MetaInfo from the given InputStream. The InputStream must start with a correctly bencoded dictionary describing the torrent. Caller must close the stream.
      Throws:
        `IOException`

    - #### MetaInfo

          public MetaInfo(Map<String,BEValue> m)
                   throws InvalidBEncodingException

      Creates a new MetaInfo from a Map of BEValues and the SHA1 over the original bencoded info dictionary (this is a hack, we could reconstruct the bencoded stream and recalculate the hash). Will NOT throw a InvalidBEncodingException if the given map does not contain a valid announce string. WILL throw a InvalidBEncodingException if the given map does not contain a valid info dictionary.
      Throws:
        `InvalidBEncodingException`

    - #### MetaInfo

          public MetaInfo(MetaInfo old,
                          String new_announce,
                          List<List<String>> new_announce_list,
                          String new_comment,
                          String new_created_by,
                          List<String> new_url_list)

      Will not change infohash. Retains creation date of old MetaInfo if nonzero.
      Parameters:
        `new_announce` - may be null
        `new_announce_list` - may be null
        `new_comment` - may be null
        `new_created_by` - may be null
        `new_url_list` - may be null

    - #### MetaInfo

          public MetaInfo(String announce,
                          String name,
                          String name_utf8,
                          List<List<String>> files,
                          List<Long> lengths,
                          int piece_length,
                          byte[] piece_hashes,
                          long length,
                          boolean privateTorrent,
                          List<List<String>> announce_list,
                          String created_by,
                          List<String> url_list,
                          String comment)

      Called by Storage when creating a new torrent from local data
      Parameters:
        `announce` - may be null
        `files` - null for single-file torrent
        `lengths` - null for single-file torrent
        `announce_list` - may be null
        `created_by` - may be null and will be ignored
        `url_list` - may be null
        `comment` - may be null

    - #### MetaInfo

          public MetaInfo(String announce,
                          String name,
                          String name_utf8,
                          List<List<String>> files,
                          List<Long> lengths,
                          int piece_length,
                          byte[] piece_hashes,
                          long length,
                          int privateTorrent,
                          List<List<String>> announce_list,
                          String created_by,
                          List<String> url_list,
                          String comment)

      Preserves privateTorrent int value, for main()

  - ### Method Detail

    - #### checkPiece

          public boolean checkPiece(int piece,
                                    byte[] bs,
                                    int off,
                                    int length)

      Checks that the given piece has the same SHA1 hash as the given byte array. Returns random results or IndexOutOfBoundsExceptions when the piece number is unknown.

    - #### checkPiece

          boolean checkPiece(PartialPiece pp)

      Returns:
        good

    - #### getAnnounce

          public String getAnnounce()

      Returns the string representing the URL of the tracker for this torrent.
      Returns:
        may be null!

    - #### getAnnounceList

          public List<List<String>> getAnnounceList()

      Returns a list of lists of urls.

    - #### getComment

          public String getComment()

      The comment string or null. Not available for locally-created torrents.

    - #### getCreatedBy

          public String getCreatedBy()

      The created-by string or null. Not available for locally-created torrents.

    - #### getCreationDate

          public long getCreationDate()

      The creation date (ms) or zero. As of 0.9.19, available for locally-created torrents.

    - #### getFiles

          public List<List<String>> getFiles()

      Returns a list of lists of file name hierarchies or null if it is a single name. It has the same size as the list returned by getLengths().

    - #### getInfoBytes

          public byte[] getInfoBytes()

      Side effect: Caches infoBytesLength.

    - #### getInfoBytesLength

          public int getInfoBytesLength()

      The size of getInfoBytes(). Cached.

    - #### getInfoHash

          public byte[] getInfoHash()

      Returns the original 20 byte SHA1 hash over the bencoded info map.

    - #### getLengths

          public List<Long> getLengths()

      Returns a list of Longs indication the size of the individual files, or null if it is a single file. It has the same size as the list returned by getFiles().

    - #### getName

          public String getName()

      Returns the requested name for the file or toplevel directory. If it is a toplevel directory name getFiles() will return a non-null List of file name hierarchy name.

    - #### getNameAndInfoHash

          public static String getNameAndInfoHash(InputStream in,
                                                  byte[] infoHashOut)
                                           throws IOException

      Efficiently returns the name and the 20 byte SHA1 hash of the info dictionary in a torrent file Caller must close stream.
      Parameters:
        `infoHashOut` - 20-byte out parameter
      Throws:
        `IOException`

    - #### getPieceHashes

          public byte[] getPieceHashes()

      Returns the piece hashes.
      Returns:
        not a copy, do not modify

    - #### getPieceLength

          public int getPieceLength(int piece)

      Return the length of a piece. All pieces are of equal length except for the last one (`getPieces()-1`).
      Throws:
        `IndexOutOfBoundsException` - when piece is equal to or greater then the number of pieces in the torrent.

    - #### getPieces

          public int getPieces()

      Returns the number of pieces.

    - #### getPrivateTrackerStatus

          public int getPrivateTrackerStatus()

      Returns:
        0 (default), 1 (set to 1), -1 (set to 0)

    - #### getTorrentData

          public byte[] getTorrentData()

      Called by servlet to save a new torrent file generated from local data

    - #### getTotalLength

          public long getTotalLength()

      Returns the total length of the torrent in bytes. This includes any padding files.

    - #### getWebSeedURLs

          public List<String> getWebSeedURLs()

      Returns a list of urls or null.

    - #### isPaddingFile

          public boolean isPaddingFile(int filenum)

      Is this file a padding file?

    - #### isPrivate

          public boolean isPrivate()

      Is it a private torrent?

    - #### main

          public static void main(String[] args)

    - #### reannounce

          public MetaInfo reannounce(String announce)
                              throws InvalidBEncodingException

      Creates a copy of this MetaInfo that shares everything except the announce URL. Drops any announce-list. Preserves infohash and info map, including any non-standard fields.
      Parameters:
        `announce` - may be null
      Throws:
        `InvalidBEncodingException`

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`