com.frostwire.jlibtorrent

Class SessionHandle

java.lang.Object

com.frostwire.jlibtorrent.SessionHandle

public class SessionHandle
extends java.lang.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, not expose a very high level interface like com.frostwire.jlibtorrent.Dht.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	SessionHandle.Options Flags to be passed in to removeTorrent(TorrentHandle, Options).
static class	SessionHandle.ProtocolType protocols used by addPortMapping(ProtocolType, int, int).
static class	SessionHandle.SaveStateFlags Flags that determines which aspects of the session should be saved when calling saveState(long)

Field Summary

Fields

Modifier and Type	Field and Description
protected session_handle	s

Constructor Summary

Constructors

Constructor and Description
SessionHandle(session_handle s)

Method Summary

Modifier and Type	Method and Description
void	addDHTNode(Pair<java.lang.String,java.lang.Integer> node) takes a host name and port pair.
void	addDHTRouter(Pair<java.lang.String,java.lang.Integer> node) adds the given endpoint to a list of DHT router nodes.
void	addExtension(Plugin plugin)
int	addPortMapping(SessionHandle.ProtocolType t, int externalPort, int localPort) add_port_mapping adds a port forwarding on UPnP and/or NAT-PMP, whichever is enabled.
TorrentHandle	addTorrent(AddTorrentParams params, ErrorCode ec) You add torrents through the addTorrent(AddTorrentParams, ErrorCode) 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, int 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 or not the session has successfully opened a listening port.
boolean	isPaused()
boolean	isValid()
void	loadState(byte[] data) Same as calling loadState(byte[], long) with all save state flags.
void	loadState(byte[] data, long flags) Loads all session settings, including DHT settings, encryption settings and proxy settings.
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 state_update_alert, containing the status of all torrents whose state changed since the last time this function was called.
void	postTorrentUpdates(TorrentHandle.StatusFlags flags) This functions instructs the session to post the state_update_alert, 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, SessionHandle.Options 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	resume() Resuming will restore the torrents to their previous paused state.
byte[]	saveState() Same as calling saveState(long) with all save state flags.
byte[]	saveState(long flags) Loads and saves all session settings, including dht settings, encryption settings and proxy settings.
SettingsPack	settings()
session_handle	swig()
java.util.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 Detail

s

protected final session_handle s

Constructor Detail

SessionHandle

public SessionHandle(session_handle s)

Parameters:

s -

Method Detail

swig

public session_handle swig()

Returns:

isValid

public boolean isValid()

saveState

public byte[] saveState(long flags)

Loads and saves all session settings, including dht settings, encryption settings and proxy settings. saveState(long) internally writes all keys to an entry that's passed in, which needs to either not be initialized, or initialized as a dictionary.

The flags argument passed in to this method can be used to filter which parts of the session state to save. By default, all state is saved (except for the individual torrents).

Returns:

See Also:

com.frostwire.jlibtorrent.swig.session_handle.save_state_flags_t}

saveState

public byte[] saveState()

Same as calling saveState(long) with all save state flags.

Returns:

See Also:

saveState(long)

loadState

public void loadState(byte[] data,
                      long flags)

Loads all session settings, including DHT settings, encryption settings and proxy settings.

loadState(byte[], long) expects a byte array that it is a bencoded buffer.

The flags argument passed in to this method can be used to filter which parts of the session state to load. By default, all state is restored (except for the individual torrents).

Parameters:

data -

See Also:

com.frostwire.jlibtorrent.swig.session_handle.save_state_flags_t}

loadState

public void loadState(byte[] data)

Same as calling loadState(byte[], long) with all save state flags.

See Also:

loadState(byte[], long)

postTorrentUpdates

public void postTorrentUpdates(TorrentHandle.StatusFlags flags)

This functions instructs the session to post the state_update_alert, 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 add_torrent_params. the ``flags`` argument is the same as for torrent_handle::status(). see torrent_handle::status_flags_t.

Parameters:

flags -

postTorrentUpdates

public void postTorrentUpdates()

This functions instructs the session to post the state_update_alert, 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 java.util.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 add_torrent_params.flags_t.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 -

ec -

Returns:

asyncAddTorrent

public void asyncAddTorrent(AddTorrentParams params)

removeTorrent

public void removeTorrent(TorrentHandle th,
                          SessionHandle.Options 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 -

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<java.lang.String,java.lang.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 -

addDHTRouter

public void addDHTRouter(Pair<java.lang.String,java.lang.Integer> node)

adds the given endpoint to a list of DHT router nodes. If a search is ever made while the routing table is empty, those nodes will be used as backups. Nodes in the router node list will also never be added to the regular routing table, which effectively means they are only used for bootstrapping, to keep the load off them.

An example routing node that you could typically add is ``router.bittorrent.com``.

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 -

settings

public SettingsPack settings()

Returns:

addPortMapping

public int addPortMapping(SessionHandle.ProtocolType t,
                          int externalPort,
                          int localPort)

add_port_mapping adds a port forwarding on UPnP and/or NAT-PMP, whichever is enabled. The return value is a handle referring to the port mapping that was just created. Pass it to delete_port_mapping() to remove it.

Parameters:

t -

externalPort -

localPort -

Returns:

deletePortMapping

public void deletePortMapping(int handle)

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,
                        int 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 or not 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:

addExtension

public void addExtension(Plugin plugin)