org.klomp.snark

## Interface PeerListener

- All Known Implementing Classes:
    PeerCoordinator

      interface PeerListener

  Listener for Peer events.

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `connected(Peer peer)` Called when the connection to the peer has started and the handshake was successfull.
    `void` | `disconnected(Peer peer)` Called when the connection to the peer was terminated or the connection handshake failed.
    `void` | `downloaded(Peer peer, int size)` Called when a (partial) piece has been downloaded from the peer.
    `PartialPiece` | `getPartialPiece(Peer peer, BitField havePieces)` Called when a peer has connected and there may be a partially downloaded piece that the coordinatorator can give the peer task
    `boolean` | `gotBitField(Peer peer, BitField bitfield)` Called when a bitmap message is received.
    `void` | `gotChoke(Peer peer, boolean choke)` Called when a choke message is received.
    `void` | `gotExtension(Peer peer, int id, byte[] bs)` Called when an extension message is received.
    `boolean` | `gotHave(Peer peer, int piece)` Called when a have piece message is received.
    `void` | `gotInterest(Peer peer, boolean interest)` Called when an interested message is received.
    `void` | `gotPeers(Peer peer, List<PeerID> pIDList)` Called when peers are received via PEX
    `boolean` | `gotPiece(Peer peer, int piece, byte[] bs)` Called when a piece is received from the peer.
    `void` | `gotPort(Peer peer, int port)` Called when a port message is received.
    `byte[]` | `gotRequest(Peer peer, int piece, int off, int len)` Called when the peer wants (part of) a piece from us.
    `boolean` | `needPiece(Peer peer, BitField bitfield)` Called when we are downloading from the peer and may need to ask for a new piece.
    `void` | `savePartialPieces(Peer peer, List<PartialPiece> pcs)` Called when the peer has disconnected and the peer task may have a partially downloaded piece that the PeerCoordinator can save
    `void` | `uploaded(Peer peer, int size)` Called when a (partial) piece has been uploaded to the peer.
    `int` | `wantPiece(Peer peer, BitField bitfield)` Called when we are downloading from the peer and need to ask for a new piece.

- - ### Method Detail

    - #### connected

          void connected(Peer peer)

      Called when the connection to the peer has started and the handshake was successfull.
      Parameters:
        `peer` - the Peer that just got connected.

    - #### disconnected

          void disconnected(Peer peer)

      Called when the connection to the peer was terminated or the connection handshake failed.
      Parameters:
        `peer` - the Peer that just got disconnected.

    - #### gotChoke

          void gotChoke(Peer peer,
                      boolean choke)

      Called when a choke message is received.
      Parameters:
        `peer` - the Peer that got the message.
        `choke` - true when the peer got a choke message, false when the peer got an unchoke message.

    - #### gotInterest

          void gotInterest(Peer peer,
                         boolean interest)

      Called when an interested message is received.
      Parameters:
        `peer` - the Peer that got the message.
        `interest` - true when the peer got a interested message, false when the peer got an uninterested message.

    - #### gotHave

          boolean gotHave(Peer peer,
                        int piece)

      Called when a have piece message is received. If the method returns true and the peer has not yet received a interested message or we indicated earlier to be not interested then an interested message will be send.
      Parameters:
        `peer` - the Peer that got the message.
        `piece` - the piece number that the per just got.
      Returns:
        true when it is a piece that we want, false if the piece is already known.

    - #### gotBitField

          boolean gotBitField(Peer peer,
                            BitField bitfield)

      Called when a bitmap message is received. If this method returns true a interested message will be send back to the peer.
      Parameters:
        `peer` - the Peer that got the message.
        `bitfield` - a BitField containing the pieces that the other side has.
      Returns:
        true when the BitField contains pieces we want, false if the piece is already known.

    - #### gotPiece

          boolean gotPiece(Peer peer,
                         int piece,
                         byte[] bs)

      Called when a piece is received from the peer. The piece must be requested by Peer.request() first. If this method returns false that means the Peer provided a corrupted piece and the connection will be closed.
      Parameters:
        `peer` - the Peer that got the piece.
        `piece` - the piece number received.
        `bs` - the byte array containing the piece.
      Returns:
        true when the bytes represent the piece, false otherwise.

    - #### gotRequest

          byte[] gotRequest(Peer peer,
                          int piece,
                          int off,
                          int len)

      Called when the peer wants (part of) a piece from us. Only called when the peer is not choked by us (`peer.choke(false)` was called).
      Parameters:
        `peer` - the Peer that wants the piece.
        `piece` - the piece number requested.
        `off` - byte offset into the piece.
        `len` - length of the chunk requested.
      Returns:
        a byte array containing the piece or null when the piece is not available (which is a protocol error).

    - #### downloaded

          void downloaded(Peer peer,
                        int size)

      Called when a (partial) piece has been downloaded from the peer.
      Parameters:
        `peer` - the Peer from which size bytes where downloaded.
        `size` - the number of bytes that where downloaded.

    - #### uploaded

          void uploaded(Peer peer,
                      int size)

      Called when a (partial) piece has been uploaded to the peer.
      Parameters:
        `peer` - the Peer to which size bytes where uploaded.
        `size` - the number of bytes that where uploaded.

    - #### wantPiece

          int wantPiece(Peer peer,
                      BitField bitfield)

      Called when we are downloading from the peer and need to ask for a new piece. Might be called multiple times before `gotPiece()` is called.
      Parameters:
        `peer` - the Peer that will be asked to provide the piece.
        `bitfield` - a BitField containing the pieces that the other side has.
      Returns:
        one of the pieces from the bitfield that we want or -1 if we are no longer interested in the peer.

    - #### needPiece

          boolean needPiece(Peer peer,
                          BitField bitfield)

      Called when we are downloading from the peer and may need to ask for a new piece. Returns true if wantPiece() or getPartialPiece() would return a piece.
      Parameters:
        `peer` - the Peer that will be asked to provide the piece.
        `bitfield` - a BitField containing the pieces that the other side has.
      Returns:
        if we want any of what the peer has
      Since:
        0.8.2

    - #### savePartialPieces

          void savePartialPieces(Peer peer,
                               List<PartialPiece> pcs)

      Called when the peer has disconnected and the peer task may have a partially downloaded piece that the PeerCoordinator can save
      Parameters:
        `peer` - the peer
      Since:
        0.8.2

    - #### getPartialPiece

          PartialPiece getPartialPiece(Peer peer,
                                     BitField havePieces)

      Called when a peer has connected and there may be a partially downloaded piece that the coordinatorator can give the peer task
      Parameters:
        `havePieces` - the have-pieces bitmask for the peer
      Returns:
        request (contains the partial data and valid length)
      Since:
        0.8.2

    - #### gotExtension

          void gotExtension(Peer peer,
                          int id,
                          byte[] bs)

      Called when an extension message is received.
      Parameters:
        `peer` - the Peer that got the message.
        `id` - the message ID
        `bs` - the message payload
      Since:
        0.8.4

    - #### gotPort

          void gotPort(Peer peer,
                     int port)

      Called when a port message is received.
      Parameters:
        `peer` - the Peer that got the message.
        `port` - the port
      Since:
        0.8.4

    - #### gotPeers

          void gotPeers(Peer peer,
                      List<PeerID> pIDList)

      Called when peers are received via PEX
      Parameters:
        `peer` - the Peer that got the message.
        `pIDList` - the peer IDs (dest hashes)
      Since:
        0.8.4