Package com.frostwire.jlibtorrent

Class PeerRequest

java.lang.Object
com.frostwire.jlibtorrent.PeerRequest
public final class PeerRequest extends Object
Represents a byte range request within a piece in the BitTorrent protocol.

PeerRequest describes a contiguous byte range inside a piece that a peer has requested (or that you're requesting from a peer). BitTorrent breaks pieces into smaller blocks for transmission; when requesting blocks from peers or receiving requests from peers, each request specifies a piece number, byte offset within that piece, and the length of bytes to transfer.

Understanding Piece Requests:
Piece requests are the fundamental unit of BitTorrent data transfer:

  • Block Size: Typically 16KB (16,384 bytes) per request
  • Piece Composition: Pieces are split into many blocks
  • Request Protocol: "request" message sends PeerRequest to peer
  • Incoming Requests: Peers request blocks from you
  • Verification: Each received block is verified after transfer

PeerRequest Structure: 

 Piece #5 (256 KB total)
 ┌────────────────────────────────────┐
 │ Block 0 (16KB) [bytes 0-16383]    │
 │ Block 1 (16KB) [bytes 16384-32767]│ ← PeerRequest(5, 16384, 16384)
 │ Block 2 (16KB) [bytes 32768-49151]│
 │ ...                                │
 └────────────────────────────────────┘

Creating PeerRequests:

PeerRequest objects are not typically constructed directly; they're provided by the library when receiving incoming peer requests or mapped from file offsets. 

 // From TorrentInfo - map a file offset to a piece request
 TorrentInfo info = new TorrentInfo(torrentFile);

 // Request first 32KB of file 0
 // This gets mapped to piece/block coordinates
 PeerRequest req = info.mapFile(0, 0, 32768);
 System.out.println("Piece: " + req.piece());      // e.g., 0
 System.out.println("Start: " + req.start());      // e.g., 0
 System.out.println("Length: " + req.length());    // e.g., 32768

Interpreting PeerRequest Components: 

 PeerRequest req = ...;  // Received from alert or library

 // Get piece index
 int pieceIdx = req.piece();
 System.out.println("Requesting piece " + pieceIdx);

 // Get byte offset within that piece
 int offset = req.start();
 System.out.println("Starting at byte " + offset + " in piece");

 // Get length of block/range
 int blockSize = req.length();
 System.out.println("Block size: " + blockSize + " bytes");

 // Typical block is 16KB
 if (blockSize == 16384) {
     System.out.println("Standard block size\");
 } else if (blockSize < 16384) {
     System.out.println("Last block in piece (partial)\");
 }

Incoming Peer Requests:

When peers request data from you, you receive IncomingRequestAlert containing the peer's requested block: 

 sm.addListener(new AlertListener() {
     public int[] types() {
         return new int[] {AlertType.INCOMING_REQUEST.swig()};
     }

     public void alert(Alert<?> alert) {
         IncomingRequestAlert a = (IncomingRequestAlert) alert;
         PeerRequest req = a.getRequest();

         System.out.println("Peer requesting: \" + req);
         // Output: PeerRequest(piece: 0, start: 0, length: 16384)

         // Load the requested block and send it
         byte[] blockData = loadBlock(req.piece(), req.start(), req.length());
         // ... send blockData to peer ...
     }
 });

Invalid Peer Requests:

Peers sometimes request blocks outside torrent bounds or with invalid parameters. The library reports these as InvalidRequestAlert: 

 sm.addListener(new AlertListener() {
     public int[] types() {
         return new int[] {AlertType.INVALID_REQUEST.swig()};
     }

     public void alert(Alert<?> alert) {
         InvalidRequestAlert a = (InvalidRequestAlert) alert;
         PeerRequest badReq = a.getRequest();

         System.err.println(\"Peer sent invalid request: \" + badReq);
         // This peer is misbehaving or buggy
     }
 });

Block Sizes in BitTorrent: 

 // Standard block size (most common)
 int STANDARD_BLOCK_SIZE = 16384;  // 16 KB

 // Typical piece breakdown (assuming 256 KB piece)
 // Piece 0:
 //   Block 0: bytes 0-16383 (16 KB)
 //   Block 1: bytes 16384-32767 (16 KB)
 //   Block 2: bytes 32768-49151 (16 KB)
 //   ... (15 blocks total)

 // Last piece may have fewer blocks
 // If torrent is 1MB and pieces are 256KB:
 // Piece 3: bytes 786432-1048575 (262143 bytes, not aligned to blocks)

Mapping File Offsets to PeerRequests: 

 TorrentInfo info = new TorrentInfo(torrentFile);

 // What piece/block is at byte offset 50000 of file 0?
 PeerRequest fileReq = info.mapFile(0, 50000, 1);

 System.out.println("File byte 50000 is in piece \" + fileReq.piece());
 System.out.println(\"At offset \" + fileReq.start());

 // Map a 32KB range starting at byte 100000 of file 0
 PeerRequest rangeReq = info.mapFile(0, 100000, 32768);
 System.out.println(\"File bytes 100000-132767 span pieces:\");
 System.out.println(\"  Start: piece \" + rangeReq.piece() + \", offset \" + rangeReq.start());

Performance Notes:

  • PeerRequest is a lightweight value object; safe to create/pass frequently
  • Typical BitTorrent sessions handle thousands of PeerRequest objects
  • Block transfers are pipelined; multiple requests outstanding per peer
  • Request/response is the fundamental BitTorrent protocol message
See Also:

  • Constructor Summary

    Constructors
    Constructor
    Description
    PeerRequest(com.frostwire.jlibtorrent.swig.peer_request r)
     

  • Method Summary

    Modifier and Type
    Method
    Description
    int
    length()
    The size of the range, in bytes.
    int
    piece()
    The index of the piece in which the range starts.
    int
    start()
    The offset within that piece where the range starts.
    com.frostwire.jlibtorrent.swig.peer_request
    swig()
     
    String
    toString()
     

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • PeerRequest

      public PeerRequest(com.frostwire.jlibtorrent.swig.peer_request r)

  • Method Details

    • swig

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

    • piece

      public int piece()
      The index of the piece in which the range starts.
      Returns:
      the piece index

    • start

      public int start()
      The offset within that piece where the range starts.
      Returns:
      the start offset

    • length

      public int length()
      The size of the range, in bytes.
      Returns:
      the range length

    • toString

      public String toString()
      Overrides:
      toString in class Object
      Returns:
      string representation