org.klomp.snark

## Class UDPTrackerClient

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

- All Implemented Interfaces:
    I2PSessionListener, I2PSessionMuxedListener

      class UDPTrackerClient
      extends Object
      implements I2PSessionMuxedListener

  One of these for all trackers and info hashes. Ref: BEP 15, proposal 160

  The main difference from BEP 15 is that the announce response contains a 32-byte hash instead of a 4-byte IP and a 2-byte port.

  We send both repliable and raw datagrams, but we only receive raw datagrams, as follows:

          client      tracker          type
          ----------+----------------+--------------------
          conn req  | -->            | repliable Datagram2
                    | <-- conn resp  | raw
          announce  | -->            | repliable Datagram3
                    | <-- ann resp   | raw
                    | <-- error      | raw
          ----------+-----------------+-------------------

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `UDPTrackerClient.TrackerResponse` Represents a response from a UDP tracker. This class encapsulates the tracker's response including peer lists, interval information, and any error messages.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `EVENT_COMPLETED`
    `static int` | `EVENT_NONE`
    `static int` | `EVENT_STARTED`
    `static int` | `EVENT_STOPPED`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `UDPTrackerClient(I2PAppContext ctx, I2PSession session, I2PSnarkUtil util)`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `UDPTrackerClient.TrackerResponse` | `announce(byte[] ih, byte[] peerID, int max, long maxWait, String toHost, int toPort, long downloaded, long left, long uploaded, int event, boolean fast)` Announce and get peers for a torrent.
    `void` | `disconnected(I2PSession session)` Notify the client that the session has been terminated.
    `void` | `errorOccurred(I2PSession session, String message, Throwable error)` Notify the client that some error occurred.
    `void` | `messageAvailable(I2PSession session, int msgId, long size)` for non-muxed
    `void` | `messageAvailable(I2PSession session, int msgId, long size, int proto, int fromPort, int toPort)` Instruct the client that the given session has received a message
    `void` | `reportAbuse(I2PSession session, int severity)` Instruct the client that the session specified seems to be under attack and that the client may wish to move its destination to another router.
    `void` | `start()` Can't be restarted after stopping?
    `void` | `stop()` Stop everything.

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

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

- - ### Field Detail

    - #### EVENT_COMPLETED

          public static final int EVENT_COMPLETED

      See Also:
        Constant Field Values

    - #### EVENT_NONE

          public static final int EVENT_NONE

      See Also:
        Constant Field Values

    - #### EVENT_STARTED

          public static final int EVENT_STARTED

      See Also:
        Constant Field Values

    - #### EVENT_STOPPED

          public static final int EVENT_STOPPED

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### UDPTrackerClient

          public UDPTrackerClient(I2PAppContext ctx,
                                  I2PSession session,
                                  I2PSnarkUtil util)

  - ### Method Detail

    - #### announce

          public UDPTrackerClient.TrackerResponse announce(byte[] ih,
                                                           byte[] peerID,
                                                           int max,
                                                           long maxWait,
                                                           String toHost,
                                                           int toPort,
                                                           long downloaded,
                                                           long left,
                                                           long uploaded,
                                                           int event,
                                                           boolean fast)

      Announce and get peers for a torrent. Blocking! Caller should run in a thread.
      Parameters:
        `ih` - the Info Hash (torrent)
        `max` - maximum number of peers to return
        `maxWait` - the maximum time to wait (ms) must be > 0
        `fast` - if true, don't wait for dest, no retx, ...
      Returns:
        null on fail or if fast is true

    - #### disconnected

          public void disconnected(I2PSession session)

      Description copied from interface: `I2PSessionMuxedListener`
      Notify the client that the session has been terminated. All registered listeners will be called.
      Specified by:
        `disconnected` in interface `I2PSessionListener`
      Specified by:
        `disconnected` in interface `I2PSessionMuxedListener`

    - #### errorOccurred

          public void errorOccurred(I2PSession session,
                                    String message,
                                    Throwable error)

      Description copied from interface: `I2PSessionMuxedListener`
      Notify the client that some error occurred. All registered listeners will be called.
      Specified by:
        `errorOccurred` in interface `I2PSessionListener`
      Specified by:
        `errorOccurred` in interface `I2PSessionMuxedListener`
        `error` - can be null? or not?

    - #### messageAvailable

          public void messageAvailable(I2PSession session,
                                       int msgId,
                                       long size)

      for non-muxed
      Specified by:
        `messageAvailable` in interface `I2PSessionListener`
      Specified by:
        `messageAvailable` in interface `I2PSessionMuxedListener`
      Parameters:
        `session` - session to notify
        `msgId` - message number available
        `size` - size of the message - why it's a long and not an int is a mystery

    - #### messageAvailable

          public void messageAvailable(I2PSession session,
                                       int msgId,
                                       long size,
                                       int proto,
                                       int fromPort,
                                       int toPort)

      Instruct the client that the given session has received a message

      Will be called only if you register via addMuxedSessionListener(). Will be called only for the proto(s) and toPort(s) you register for.

      Specified by:
        `messageAvailable` in interface `I2PSessionMuxedListener`
      Parameters:
        `session` - session to notify
        `msgId` - message number available
        `size` - size of the message - why it's a long and not an int is a mystery
        `proto` - 1-254 or 0 for unspecified
        `fromPort` - 1-65535 or 0 for unspecified
        `toPort` - 1-65535 or 0 for unspecified

    - #### reportAbuse

          public void reportAbuse(I2PSession session,
                                  int severity)

      Description copied from interface: `I2PSessionMuxedListener`
      Instruct the client that the session specified seems to be under attack and that the client may wish to move its destination to another router. All registered listeners will be called. Unused. Not fully implemented.
      Specified by:
        `reportAbuse` in interface `I2PSessionListener`
      Specified by:
        `reportAbuse` in interface `I2PSessionMuxedListener`
      Parameters:
        `session` - session to report abuse to
        `severity` - how bad the abuse is

    - #### start

          public void start()

      Can't be restarted after stopping?

    - #### stop

          public void stop()

      Stop everything.