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 Details

    • DELETE_FILES

      public static final 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 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 save_state_flags_t SAVE_EXTENSION_STATE
      Load or save state from plugins.

    • SAVE_IP_FILTER

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

    • SAVE_DHT_STATE

      public static final 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 save_state_flags_t SAVE_SETTINGS
      Saves settings (i.e. the SettingsPack).

    • REOPEN_MAP_PORTS

      public static final 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 session_flags_t PAUSED
      When set, the session will start paused. Call SessionHandle::resume() to start.

    • TCP

      public static final portmap_protocol TCP

    • UDP

      public static final portmap_protocol UDP

    • s

      protected final session_handle s

  • Constructor Details

    • SessionHandle

      public SessionHandle(session_handle s)
      Parameters:
      s - the native object

  • Method Details

    • swig

      public session_handle swig()
      Returns:
      the native object

    • isValid

      public boolean isValid()

    • sessionState

      public SessionParams sessionState(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 sessionState(save_state_flags_t) with all the flags bits active.
      Returns:
      the session params

    • postTorrentUpdates

      public void postTorrentUpdates(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 AddTorrentParams. 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 TorrentHandle 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 addTorrent(AddTorrentParams, ErrorCode) 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 TorrentHandle. In order to add torrents more efficiently, consider using asyncAddTorrent(AddTorrentParams) which returns immediately, without waiting for the torrent to add. Notification of the torrent being added is sent as AddTorrentAlert.

      The TorrentHandle 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, 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 deletePortMapping(int) 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(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 DhtImmutableItemAlert.
      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 DhtMutableItemAlert 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