## org.klomp.snark
Interface PeerListener

All Known Implementing Classes:
  PeerCoordinator

    interface PeerListener

Listener for Peer events.

Method Summary
`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