org.klomp.snark

## Interface PeerListener

- All Known Implementing Classes:
    PeerCoordinator

      interface PeerListener

  Listener for Peer events.

- - ### Method Summary

    All Methods Instance Methods Abstract 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.
    `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
    `I2PSnarkUtil` | `getUtil()` Convenience
    `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` | `gotCommentReq(Peer peer, int num)` Called when comments are requested via ut_comment
    `void` | `gotComments(Peer peer, List<Comment> comments)` Called when comments are received via ut_comment
    `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, PartialPiece piece)` Called when a piece is received from the peer.
    `void` | `gotPort(Peer peer, int port, int rport)` Called when a DHT port message is received.
    `ByteArray` | `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<Request> pcs)` Called when the peer has disconnected and the peer task may have a partially downloaded piece that the PeerCoordinator can save

- - ### 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.

    - #### 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)

    - #### getUtil

          I2PSnarkUtil getUtil()

      Convenience

    - #### 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.

    - #### 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.

    - #### gotCommentReq

          void gotCommentReq(Peer peer,
                             int num)

      Called when comments are requested via ut_comment

    - #### gotComments

          void gotComments(Peer peer,
                           List<Comment> comments)

      Called when comments are received via ut_comment

    - #### 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

    - #### 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.

    - #### 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.

    - #### 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)

    - #### gotPiece

          boolean gotPiece(Peer peer,
                           PartialPiece piece)

      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 received.
      Returns:
        true when the bytes represent the piece, false otherwise.

    - #### gotPort

          void gotPort(Peer peer,
                       int port,
                       int rport)

      Called when a DHT port message is received.
      Parameters:
        `peer` - the Peer that got the message.
        `port` - the query port
        `rport` - the response port

    - #### gotRequest

          ByteArray 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).

    - #### 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

    - #### savePartialPieces

          void savePartialPieces(Peer peer,
                                 List<Request> 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