sessions

Description

sessions is the main package used for accessing sessions and torrents through the Lua API. It exports two functions, get and list that gets a session by name or lists all sessions, respectively.

Function `get(string)`

Gets a session by name. If no session is found, it will return nil.

local sessions = require("sessions")
local default  = sessions.get("default")

Function `list()`

Returns an iterator to be able to iterate all sessions.

local sessions = require("sessions")

for session in sessions.list() do
    print(session.name)
end

Types

`Session`

The Session type represents one session in Porla. Its APIs is similar to the libtorrent::session APIs which it wraps.

Function `apply_settings(SettingsPack)`

Applies a SettingsPack to the session.

local settings = session:settings()
settings.active_limit = 99
session:apply_settings(settings)

Function `find_torrent(InfoHash)`

Gets a TorrentHandle from a session, or nil of not found.

Function `settings()`

Returns a SettingsPack object that wraps a libtorrent::settings_pack.

local settings = session:settings()
-- print a setting
print(settings.active_limit)

Function `torrents()`

Returns an iterator that can be used to iterate all torrents in a session. Each torrent is a TorrentHandle.

for torrent in session:torrents() do
    print("info hash", torrent:info_hash().v1)
end

`TorrentClientData`

A Porla specific object that contains category, tags, etc.

Property `category`

The category this torrent belongs to. You can get and set this category and it will be persisted across restarts.

local userdata = torrent:userdata()
userdata.category = "movies"
print(userdata.category)

Property `session`

Gets the name of the session that this torrent belongs to.

Property `tags`

A list of tags. You can get and set the list of tags and they will be persisted across restarts.

local userdata = torrent:userdata()

-- replacing all tags
userdata.tags = {"foo", "bar"}

-- add a single tag
userdata.tags:add("baz")

-- remove a single tag
userdata.tags:erase("baz")

-- print tags
for _, tag in pairs(userdata.tags) do
    print(tag)
end

if userdata.tags.foo then
    print("torrent is tagged with 'foo'")
end

`TorrentInfo`

A TorrentInfo objects represents a torrent file. It closely wraps the libtorrent::torrent_info type.

Function `static from_buffer(string data)`

Parses a TorrentInfo object from a buffer. The function is static, meaning that it does not take a self parameter and should be called directly on the type.

It returns a tuple with the first item being the parsed TorrentInfo object, and the second being an error. If an error occurs, the TorrentInfo is null.

local buffer = io.open("/path/to/file.torrent"):read("*all")
local ti, err = TorrentInfo.from_buffer(buffer)

if err then
    print(err)
else
    print(ti:comment())
end

Function `static from_file(string path)`

Same as from_buffer but takes a file path instead of a buffer.

Function `comment()`

The comment associated with the torrent. If there's no comment, it will return an empty string.

Function `creator()`

The creator string in the torrent. If there is no creator string it will return an empty string.

Function `info_hash()`

The info hash of the torrent.

Function `name()`

The name of the torrent

Function `num_files()`

Function `num_pieces()`

The total number of pieces.

Function `priv()`

True if this torrent is private. i.e., the client should not advertise itself on the trackerless network (the Kademlia DHT) for this torrent

Function `trackers()`

Function `total_size()`

The total number of bytes the torrent-file represents. Note that this is the number of pieces times the piece size (modulo the last piece possibly being smaller). With pad files, the total size will be larger than the sum of all (regular) file sizes.

`TorrentHandle`

A TorrentHandle represents a single torrent in a session. It closely wraps the libtorrent::torrent_handle type.

Function `clear_error()`

If the torrent is in an error state (i.e. torrent_status::error is non-empty), this will clear the error and start the torrent again.

Function `clear_peers()`

This will disconnect all peers and clear the peer list for this torrent. New peers will have to be acquired before resuming, from trackers, DHT or local service discovery, for example.

Function `download_limit()`

Returns the current download bandwidth limit.

Function `flags()`

Returns the flags of this torrent as a table. The key is the name of the flag and the value is a boolean which is true or false depending on if the flag is set or not.

Function `flush_cache()`

Function `force_reannounce()`

Function `force_recheck()`

Function `info_hash()`

Function `is_valid()`

Function `max_connections()`

Function `max_uploads()`

Function `move_storage(string path)`

Function `pause()`

Function `peer_info()`

Function `pause()`

Function `post_download_queue()`

Function `post_file_progress()`

Function `post_peer_info()`

Function `post_piece_availability()`

Function `post_status()`

Function `post_trackers()`

Function `queue_position()`

Function `queue_position_bottom()`

Function `queue_position_down()`

Function `queue_position_top()`

Function `queue_position_up()`

Function `resume()`

Function `set_download_limit(int limit)`

Function `set_flags(table flags)`

Function `set_max_connections(int limit)`

Function `set_max_uploads(int limit)`

Function `set_upload_limit(int limit)`

Function `status()`

Returns a TorrentStatus object with all the status information for this torrent.

local status = torrent:status()

Function `trackers()`

Function `torrent_file()`

Function `upload_limit()`

Function `userdata()`

Returns a TorrentClientData object with Porla specific information like category and tags.

local userdata = torrent:userdata()
print(userdata.category)

`TorrentStatus`

Represents the libtorrent::torrent_status type.

Property `active_duration`

Property `all_time_download`

Property `all_time_upload`

Property `announcing_to_dht`

Property `announcing_to_lsd`

Property `announcing_to_trackers`

Property `block_size`

Property `connect_candidates`

Property `connections_limit`

Property `current_tracker`

Property `distributed_copies`

Property `down_bandwidth_queue`

Property `download_payload_rate`

Property `download_rate`

Property `finished_duration`

Property `flags`

Property `info_hash`

Property `is_finished`

Property `is_seeding`

Property `handle`

Property `has_incoming`

True if there has ever been an incoming connection attempt to this torrent.

Property `has_metadata`

Property `list_peers`

Property `list_seeds`

Property `moving_storage`

Property `name`

Property `need_save_resume`

Property `num_complete`

Property `num_connections`

Property `num_incomplete`

Property `num_peers`

Property `num_pieces`

Property `num_seeds`

Property `num_uploads`

Property `progress`

The current progress of the torrent.

Description​

Function get(string)​

Function list()​

Types​

Session​

Function apply_settings(SettingsPack)​

Function find_torrent(InfoHash)​

Function settings()​

Function torrents()​

TorrentClientData​

Property category​

Property session​

Property tags​

TorrentInfo​

Function static from_buffer(string data)​

Function static from_file(string path)​

Function comment()​

Function creator()​

Function info_hash()​

Function name()​

Function num_files()​

Function num_pieces()​

Function priv()​

Function trackers()​

Function total_size()​

TorrentHandle​

Function clear_error()​

Function clear_peers()​

Function download_limit()​

Function flags()​

Function flush_cache()​

Function force_reannounce()​

Function force_recheck()​

Function info_hash()​

Function is_valid()​

Function max_connections()​

Function max_uploads()​

Function move_storage(string path)​

Function pause()​

Function peer_info()​

Function pause()​

Function post_download_queue()​

Function post_file_progress()​

Function post_peer_info()​

Function post_piece_availability()​

Function post_status()​

Function post_trackers()​

Function queue_position()​

Function queue_position_bottom()​

Function queue_position_down()​

Function queue_position_top()​

Function queue_position_up()​

Function resume()​

Function set_download_limit(int limit)​

Function set_flags(table flags)​

Function set_max_connections(int limit)​

Function set_max_uploads(int limit)​

Function set_upload_limit(int limit)​

Function status()​

Function trackers()​

Function torrent_file()​

Function upload_limit()​

Function userdata()​

TorrentStatus​

Property active_duration​

Property all_time_download​

Property all_time_upload​

Property announcing_to_dht​

Property announcing_to_lsd​

Property announcing_to_trackers​

Property block_size​

Property connect_candidates​

Property connections_limit​

Property current_tracker​

Property distributed_copies​

Property down_bandwidth_queue​

Property download_payload_rate​

Property download_rate​

Property finished_duration​

Property flags​

Description

Function `get(string)`

Function `list()`

Types

`Session`

Function `apply_settings(SettingsPack)`

Function `find_torrent(InfoHash)`

Function `settings()`

Function `torrents()`

`TorrentClientData`

Property `category`

Property `session`

Property `tags`

`TorrentInfo`

Function `static from_buffer(string data)`

Function `static from_file(string path)`

Function `comment()`

Function `creator()`

Function `info_hash()`

Function `name()`

Function `num_files()`

Function `num_pieces()`

Function `priv()`

Function `trackers()`

Function `total_size()`

`TorrentHandle`

Function `clear_error()`

Function `clear_peers()`

Function `download_limit()`

Function `flags()`

Function `flush_cache()`

Function `force_reannounce()`

Function `force_recheck()`

Function `info_hash()`

Function `is_valid()`

Function `max_connections()`

Function `max_uploads()`

Function `move_storage(string path)`

Function `pause()`

Function `peer_info()`

Function `pause()`

Function `post_download_queue()`

Function `post_file_progress()`

Function `post_peer_info()`

Function `post_piece_availability()`

Function `post_status()`

Function `post_trackers()`

Function `queue_position()`

Function `queue_position_bottom()`

Function `queue_position_down()`

Function `queue_position_top()`

Function `queue_position_up()`

Function `resume()`

Function `set_download_limit(int limit)`

Function `set_flags(table flags)`

Function `set_max_connections(int limit)`

Function `set_max_uploads(int limit)`

Function `set_upload_limit(int limit)`

Function `status()`

Function `trackers()`

Function `torrent_file()`

Function `upload_limit()`

Function `userdata()`

`TorrentStatus`

Property `active_duration`

Property `all_time_download`

Property `all_time_upload`

Property `announcing_to_dht`

Property `announcing_to_lsd`

Property `announcing_to_trackers`

Property `block_size`

Property `connect_candidates`

Property `connections_limit`

Property `current_tracker`

Property `distributed_copies`

Property `down_bandwidth_queue`

Property `download_payload_rate`

Property `download_rate`

Property `finished_duration`

Property `flags`