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.

Field Summary

Fields

Modifier and Type	Field and Description
static remove_flags_t	DELETE_FILES Delete the files belonging to the torrent from disk, including the part-file, if there is one.
static remove_flags_t	DELETE_PARTFILE Delete just the part-file associated with this torrent.
static int	DHT_ANNOUNCE_IMPLIED_PORT
static int	DHT_ANNOUNCE_SEED
static int	DHT_ANNOUNCE_SSL_TORRENT
static reopen_network_flags_t	REOPEN_MAP_PORTS This option indicates if the ports are mapped using natpmp and UPnP.
protected session_handle	s
static save_state_flags_t	SAVE_DHT_SETTINGS Saves DhtSettings.
static 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 save_state_flags_t	SAVE_SETTINGS Saves settings (i.e.

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	addExtension(Plugin plugin)
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 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[], save_state_flags_t) with all save state flags.
void	loadState(byte[] data, save_state_flags_t 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 StateUpdateAlert, containing the status of all torrents whose state changed since the last time this function was called.
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.
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, 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(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.
byte[]	saveState() Same as calling saveState(save_state_flags_t) with all save state flags.
byte[]	saveState(save_state_flags_t 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

SAVE_SETTINGS

public static final save_state_flags_t SAVE_SETTINGS

Saves settings (i.e. the SettingsPack).

SAVE_DHT_SETTINGS

public static final save_state_flags_t SAVE_DHT_SETTINGS

Saves DhtSettings.

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.

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.

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

DHT_ANNOUNCE_SEED

public static final int DHT_ANNOUNCE_SEED

See Also:

Constant Field Values

DHT_ANNOUNCE_IMPLIED_PORT

public static final int DHT_ANNOUNCE_IMPLIED_PORT

See Also:

Constant Field Values

DHT_ANNOUNCE_SSL_TORRENT

public static final int DHT_ANNOUNCE_SSL_TORRENT

See Also:

Constant Field Values

Constructor Detail

SessionHandle

public SessionHandle(session_handle s)

Parameters:

s - the native object

Method Detail

swig

public session_handle swig()

Returns:

the native object

isValid

public boolean isValid()

saveState

public byte[] saveState(save_state_flags_t flags)

Loads and saves all session settings, including dht settings, encryption settings and proxy settings. This method internally writes all keys to an entry that is returned as a bencoded byte array.

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:

the bencoded byte array

saveState

public byte[] saveState()

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

Returns:

the bencoded byte array

loadState

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

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

This method 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 - the bencoded byte array

loadState

public void loadState(byte[] data)

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

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

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,
                        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:

true if listening

addExtension

public void addExtension(Plugin plugin)