Class SessionHandle

java.lang.Object
com.frostwire.jlibtorrent.SessionHandle
public class SessionHandle extends Object
The session holds all state that spans multiple torrents. Among other things it runs the network loop and manages all torrents. Once it's created, the session object will spawn the main thread that will do all the work. The main thread will be idle as long it doesn't have any torrents to participate in.

This class belongs to a middle logical layer of abstraction. It's a wrapper of the underlying swig session object (from libtorrent), but it does not expose all the raw features.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final com.frostwire.jlibtorrent.swig.remove_flags_t
    DELETE_FILES
    Delete the files belonging to the torrent from disk, including the part-file, if there is one.
    static final com.frostwire.jlibtorrent.swig.remove_flags_t
    DELETE_PARTFILE
    Delete just the part-file associated with this torrent.
    static final int
    DHT_ANNOUNCE_IMPLIED_PORT
     
    static final int
    DHT_ANNOUNCE_SEED
     
    static final int
    DHT_ANNOUNCE_SSL_TORRENT
     
    static final com.frostwire.jlibtorrent.swig.session_flags_t
    PAUSED
    When set, the session will start paused.
    static final com.frostwire.jlibtorrent.swig.reopen_network_flags_t
    REOPEN_MAP_PORTS
    This option indicates if the ports are mapped using natpmp and UPnP.
    protected final com.frostwire.jlibtorrent.swig.session_handle
    s
     
    static final com.frostwire.jlibtorrent.swig.save_state_flags_t
    SAVE_DHT_STATE
    Saves dht state such as nodes and node-id, possibly accelerating joining the DHT if provided at next session startup.
    static final com.frostwire.jlibtorrent.swig.save_state_flags_t
    SAVE_EXTENSION_STATE
    Load or save state from plugins.
    static final com.frostwire.jlibtorrent.swig.save_state_flags_t
    SAVE_IP_FILTER
    Load or save state of IP filter set in the session.
    static final com.frostwire.jlibtorrent.swig.save_state_flags_t
    SAVE_SETTINGS
    Saves settings (i.e.
    static final com.frostwire.jlibtorrent.swig.portmap_protocol
    TCP
     
    static final com.frostwire.jlibtorrent.swig.portmap_protocol
    UDP
     

  • Constructor Summary

    Constructors
    Constructor
    Description
    SessionHandle(com.frostwire.jlibtorrent.swig.session_handle s)
     

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    addDhtNode(Pair<String,Integer> node)
    takes a host name and port pair.
    int[]
    addPortMapping(PortmapProtocol t, int externalPort, int localPort)
    Adds a port forwarding on UPnP and/or NAT-PMP, using PCP if supported, whichever is enabled.
    TorrentHandle
    addTorrent(AddTorrentParams params, ErrorCode ec)
    You add torrents through the function where you give an object with all the parameters.
    void
    applySettings(SettingsPack sp)
    Applies the settings specified by the settings pack sp.
    void
    asyncAddTorrent(AddTorrentParams params)
     
    void
    deletePortMapping(int handle)
     
    void
    dhtAnnounce(Sha1Hash infoHash)
     
    void
    dhtAnnounce(Sha1Hash infoHash, int port, byte flags)
     
    void
    dhtDirectRequest(UdpEndpoint endp, Entry entry)
     
    void
    dhtDirectRequest(UdpEndpoint endp, Entry entry, long userdata)
     
    void
    dhtGetItem(byte[] key, byte[] salt)
    Query the DHT for a mutable item under the public key key.
    void
    dhtGetItem(Sha1Hash target)
    Query the DHT for an immutable item at the target hash.
    void
    dhtGetPeers(Sha1Hash infoHash)
     
    void
    dhtPutItem(byte[] publicKey, byte[] privateKey, Entry entry, byte[] salt)
     
    Sha1Hash
    dhtPutItem(Entry entry)
    Store the given bencoded data as an immutable item in the DHT.
    TorrentHandle
    findTorrent(Sha1Hash infoHash)
    Looks for a torrent with the given info-hash.
    int
    getListenPort()
    returns the port we ended up listening on.
    int
    getSslListenPort()
     
    boolean
    isDhtRunning()
     
    boolean
    isListening()
    will tell you whether the session has successfully opened a listening port.
    boolean
    isPaused()
     
    boolean
    isValid()
     
    void
    pause()
    Pausing the session has the same effect as pausing every torrent in it, except that torrents will not be resumed by the auto-manage mechanism.
    void
    postDhtStats()
    This will cause a dht_stats_alert to be posted.
    void
    postSessionStats()
    This function will post a SessionStatsAlert object, containing a snapshot of the performance counters from the internals of libtorrent.
    void
    postTorrentUpdates()
    This functions instructs the session to post the StateUpdateAlert, containing the status of all torrents whose state changed since the last time this function was called.
    void
    postTorrentUpdates(com.frostwire.jlibtorrent.swig.status_flags_t flags)
    This functions instructs the session to post the StateUpdateAlert, containing the status of all torrents whose state changed since the last time this function was called.
    void
    removeTorrent(TorrentHandle th)
    This method will close all peer connections associated with the torrent and tell the tracker that we've stopped participating in the swarm.
    void
    removeTorrent(TorrentHandle th, com.frostwire.jlibtorrent.swig.remove_flags_t options)
    This method will close all peer connections associated with the torrent and tell the tracker that we've stopped participating in the swarm.
    void
    reopenNetworkSockets()
    Instructs the session to reopen all listen and outgoing sockets.
    void
    reopenNetworkSockets(com.frostwire.jlibtorrent.swig.reopen_network_flags_t options)
    Instructs the session to reopen all listen and outgoing sockets.
    void
    resume()
    Resuming will restore the torrents to their previous paused state.
    SessionParams
    sessionState()
    Same as with all the flags bits active.
    SessionParams
    sessionState(com.frostwire.jlibtorrent.swig.save_state_flags_t flags)
    Returns the current session state.
    SettingsPack
    settings()
     
    com.frostwire.jlibtorrent.swig.session_handle
    swig()
     
    List<TorrentHandle>
    torrents()
    Returns a list of torrent handles to all the torrents currently in the session.

    Methods inherited from class java.lang.Object

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

  • Field Details

    • DELETE_FILES

      public static final com.frostwire.jlibtorrent.swig.remove_flags_t DELETE_FILES
      Delete the files belonging to the torrent from disk, including the part-file, if there is one.

    • DELETE_PARTFILE

      public static final com.frostwire.jlibtorrent.swig.remove_flags_t DELETE_PARTFILE
      Delete just the part-file associated with this torrent.

    • DHT_ANNOUNCE_SEED

      public static final int DHT_ANNOUNCE_SEED
      See Also:

    • DHT_ANNOUNCE_IMPLIED_PORT

      public static final int DHT_ANNOUNCE_IMPLIED_PORT
      See Also:

    • DHT_ANNOUNCE_SSL_TORRENT

      public static final int DHT_ANNOUNCE_SSL_TORRENT
      See Also:

    • SAVE_EXTENSION_STATE

      public static final com.frostwire.jlibtorrent.swig.save_state_flags_t SAVE_EXTENSION_STATE
      Load or save state from plugins.

    • SAVE_IP_FILTER

      public static final com.frostwire.jlibtorrent.swig.save_state_flags_t SAVE_IP_FILTER
      Load or save state of IP filter set in the session.

    • SAVE_DHT_STATE

      public static final com.frostwire.jlibtorrent.swig.save_state_flags_t SAVE_DHT_STATE
      Saves dht state such as nodes and node-id, possibly accelerating joining the DHT if provided at next session startup.

    • SAVE_SETTINGS

      public static final com.frostwire.jlibtorrent.swig.save_state_flags_t SAVE_SETTINGS
      Saves settings (i.e. the ).

    • REOPEN_MAP_PORTS

      public static final com.frostwire.jlibtorrent.swig.reopen_network_flags_t REOPEN_MAP_PORTS
      This option indicates if the ports are mapped using natpmp and UPnP. If mapping was already made, they are deleted and added again. This only works if natpmp and/or upnp are configured to be enabled.

    • PAUSED

      public static final com.frostwire.jlibtorrent.swig.session_flags_t PAUSED
      When set, the session will start paused. Call SessionHandle::resume() to start.

    • TCP

      public static final com.frostwire.jlibtorrent.swig.portmap_protocol TCP

    • UDP

      public static final com.frostwire.jlibtorrent.swig.portmap_protocol UDP

    • s

      protected final com.frostwire.jlibtorrent.swig.session_handle s

  • Constructor Details

    • SessionHandle

      public SessionHandle(com.frostwire.jlibtorrent.swig.session_handle s)
      Parameters:
      s - the native object

  • Method Details

    • swig

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

    • isValid

      public boolean isValid()

    • sessionState

      public SessionParams sessionState(com.frostwire.jlibtorrent.swig.save_state_flags_t flags)
      Returns the current session state. This can be passed to write_session_params() to save the state to disk and restored using read_session_params() when constructing a new session. The kind of state that's included is all settings, the DHT routing table, possibly plugin-specific state. The flags parameter can be used to only save certain parts of the session state.
      Parameters:
      flags - specifies to safe certain parts
      Returns:
      the session params

    • sessionState

      public SessionParams sessionState()
      Same as with all the flags bits active.
      Returns:
      the session params

    • postTorrentUpdates

      public void postTorrentUpdates(com.frostwire.jlibtorrent.swig.status_flags_t flags)
      This functions instructs the session to post the StateUpdateAlert, containing the status of all torrents whose state changed since the last time this function was called.

      Only torrents who has the state subscription flag set will be included. This flag is on by default. See . the flags argument is the same as for torrent_handle::status().

      Parameters:
      flags - or-combination of native values

    • postTorrentUpdates

      public void postTorrentUpdates()
      This functions instructs the session to post the StateUpdateAlert, containing the status of all torrents whose state changed since the last time this function was called.

      Only torrents who has the state subscription flag set will be included.

    • postSessionStats

      public void postSessionStats()
      This function will post a SessionStatsAlert object, containing a snapshot of the performance counters from the internals of libtorrent. To interpret these counters, query the session via session_stats_metrics().

    • postDhtStats

      public void postDhtStats()
      This will cause a dht_stats_alert to be posted.

    • findTorrent

      public TorrentHandle findTorrent(Sha1Hash infoHash)
      Looks for a torrent with the given info-hash. In case there is such a torrent in the session, a to that torrent is returned.

      In case the torrent cannot be found, a null is returned.

      Parameters:
      infoHash -
      Returns:

    • torrents

      public List<TorrentHandle> torrents()
      Returns a list of torrent handles to all the torrents currently in the session.
      Returns:

    • addTorrent

      public TorrentHandle addTorrent(AddTorrentParams params, ErrorCode ec)
      You add torrents through the function where you give an object with all the parameters. The addTorrent overloads will block until the torrent has been added (or failed to be added) and returns an error code and a . In order to add torrents more efficiently, consider using which returns immediately, without waiting for the torrent to add. Notification of the torrent being added is sent as AddTorrentAlert.

      The returned by this method can be used to retrieve information about the torrent's progress, its peers etc. It is also used to abort a torrent.

      If the torrent you are trying to add already exists in the session (is either queued for checking, being checked or downloading) the error code will be set to libtorrent_errors.duplicate_torrent unless flag_duplicate_is_error is set to false. In that case, addTorrent will return the handle to the existing torrent.

      All torrent handles must be destructed before the session is destructed!

      Parameters:
      params - the parameters to create the torrent download
      ec - the error code if no torrent handle was created
      Returns:
      the torrent handle, could be invalid

    • asyncAddTorrent

      public void asyncAddTorrent(AddTorrentParams params)

    • removeTorrent

      public void removeTorrent(TorrentHandle th, com.frostwire.jlibtorrent.swig.remove_flags_t options)
      This method will close all peer connections associated with the torrent and tell the tracker that we've stopped participating in the swarm. This operation cannot fail. When it completes, you will receive a torrent_removed_alert.

      The optional second argument options can be used to delete all the files downloaded by this torrent. To do so, pass in the value session::delete_files. The removal of the torrent is asynchronous, there is no guarantee that adding the same torrent immediately after it was removed will not throw a libtorrent_exception exception. Once the torrent is deleted, a torrent_deleted_alert is posted.

      Parameters:
      th - the handle

    • removeTorrent

      public void removeTorrent(TorrentHandle th)
      This method will close all peer connections associated with the torrent and tell the tracker that we've stopped participating in the swarm. This operation cannot fail. When it completes, you will receive a torrent_removed_alert.
      Parameters:
      th -

    • pause

      public void pause()
      Pausing the session has the same effect as pausing every torrent in it, except that torrents will not be resumed by the auto-manage mechanism.

    • resume

      public void resume()
      Resuming will restore the torrents to their previous paused state. i.e. the session pause state is separate from the torrent pause state. A torrent is inactive if it is paused or if the session is paused.

    • isPaused

      public boolean isPaused()

    • isDhtRunning

      public boolean isDhtRunning()

    • addDhtNode

      public void addDhtNode(Pair<String,Integer> node)
      takes a host name and port pair. That endpoint will be pinged, and if a valid DHT reply is received, the node will be added to the routing table.
      Parameters:
      node -

    • applySettings

      public void applySettings(SettingsPack sp)
      Applies the settings specified by the settings pack sp. This is an asynchronous operation that will return immediately and actually apply the settings to the main thread of libtorrent some time later.
      Parameters:
      sp - the settings

    • settings

      public SettingsPack settings()
      Returns:
      a copy of the internal settings

    • addPortMapping

      public int[] addPortMapping(PortmapProtocol t, int externalPort, int localPort)
      Adds a port forwarding on UPnP and/or NAT-PMP, using PCP if supported, whichever is enabled. The return value is a handle referring to the port mapping that was just created. Pass it to to remove it.
      Parameters:
      t - the mapping protocol
      externalPort - the external port
      localPort - the local port
      Returns:
      the array of port mapping ids

    • deletePortMapping

      public void deletePortMapping(int handle)

    • reopenNetworkSockets

      public void reopenNetworkSockets(com.frostwire.jlibtorrent.swig.reopen_network_flags_t options)
      Instructs the session to reopen all listen and outgoing sockets.

      It's useful in the case your platform doesn't support the built in IP notifier mechanism, or if you have a better more reliable way to detect changes in the IP routing table.

      Parameters:
      options - the options

    • reopenNetworkSockets

      public void reopenNetworkSockets()
      Instructs the session to reopen all listen and outgoing sockets.

      It's useful in the case your platform doesn't support the built in IP notifier mechanism, or if you have a better more reliable way to detect changes in the IP routing table.

    • dhtGetItem

      public void dhtGetItem(Sha1Hash target)
      Query the DHT for an immutable item at the target hash. the result is posted as a .
      Parameters:
      target -

    • dhtGetItem

      public void dhtGetItem(byte[] key, byte[] salt)
      Query the DHT for a mutable item under the public key key. this is an ed25519 key. The salt argument is optional and may be left as an empty string if no salt is to be used.

      if the item is found in the DHT, a is posted.

      Parameters:
      key -
      salt -

    • dhtPutItem

      public Sha1Hash dhtPutItem(Entry entry)
      Store the given bencoded data as an immutable item in the DHT. the returned hash is the key that is to be used to look the item up again. It's just the sha-1 hash of the bencoded form of the structure.
      Parameters:
      entry -
      Returns:

    • dhtPutItem

      public void dhtPutItem(byte[] publicKey, byte[] privateKey, Entry entry, byte[] salt)

    • dhtGetPeers

      public void dhtGetPeers(Sha1Hash infoHash)
      Parameters:
      infoHash -

    • dhtAnnounce

      public void dhtAnnounce(Sha1Hash infoHash, int port, byte flags)
      Parameters:
      infoHash -
      port -
      flags -

    • dhtAnnounce

      public void dhtAnnounce(Sha1Hash infoHash)
      Parameters:
      infoHash -

    • dhtDirectRequest

      public void dhtDirectRequest(UdpEndpoint endp, Entry entry, long userdata)
      Parameters:
      endp -
      entry -
      userdata -

    • dhtDirectRequest

      public void dhtDirectRequest(UdpEndpoint endp, Entry entry)
      Parameters:
      endp -
      entry -

    • getListenPort

      public int getListenPort()
      returns the port we ended up listening on. Since you just pass a port-range to the constructor and to ``listen_on()``, to know which port it ended up using, you have to ask the session using this function.
      Returns:

    • getSslListenPort

      public int getSslListenPort()

    • isListening

      public boolean isListening()
      will tell you whether the session has successfully opened a listening port. If it hasn't, this function will return false, and then you can use ``listen_on()`` to make another attempt.
      Returns:
      true if listening