`LtTorrentHandle`

A handle to a torrent.

Methods

`add_url_seed(url: string): void`

v1.0

Adds a URL to the list of URL seeds for this torrent.

`clear_error(): void`

v1.0

If the torrent is in an error state (i.e the status of the torrent has errc set), calling this will clear the error and start the torrent.

`clear_peers(): void`

v1.0

This will disconnect all peers and clear the peer list for this torrent.

`clear_piece_deadlines(): void`

v1.0

Removes deadlines on all pieces in the torrent.

`download_limit(): number`

v1.0

The current download limit.

`file_status(): LtOpenFileState[]`

v1.0

Returns a list with status about files that are open for this torrent.

`flags(): LtTorrentFlags`

v1.0

Returns the current set of flags for this torrent.

`flush_cache(): void`

v1.0

Flush the disk cache and close all file handles. This is done async and you can listen for the torrent.cache_flushed event to be notified when it is done.

`force_dht_announce(): void`

v1.0

Announce the torrent to the DHT.

`force_lsd_announce(): void`

v1.0

Announce the torrent on LSD.

`force_reannounce(seconds?: number, index?: number, flags?: table): void`

v1.0

Forces a reannounce for this torrent.

seconds - how many seconds from now to issue the announce. 0 or nil is immediate.
index - which tracker to re-announce. -1 or nil is all.
flags - { ignore_min_interval = boolean, high_priority = boolean }, both are false by default.

Example

Forces an immediate re-announce to all trackers in this torrent.

th:force_reannounce(0, -1, { ignore_min_interval = true })

`force_recheck(): void`

v1.0

Puts the torrent in a state where it assumes to have no resume data. All peers will be disconnected, announcing will stop, and its pieces will be checked.

`get_file_priorities(): number[]`

v1.0

Returns a table of all the file priorities.

Example

info

Lua arrays are 1-based.

local file_priorities = torrent:get_file_priorities()

for i, v in pairs(file_priorities) do
    print("file {}: {}", i, v)
end

`get_peer_info(): LtPeerInfo[]`

v1.0

Gets a list of information about the peers for this torrent.

`get_renamed_files(): LtRenamedFiles`

v1.0

`have_piece(index: number): boolean`

v1.0

Returns true if the piece with the given index has been completely downloaded and written to disk.

`in_session(): boolean`

v1.0

Returns true if the torrent is in the session.

`info_hash(): LtInfoHash`

v1.0

Returns the info hash for this torrent.

`is_valid(): boolean`

v1.0

Returns true if the handle refers to a valid torrent that is both in the session and not removed.

`max_connections(): number`

v1.0

Returns the maximum number of connections this torrent will open.

`max_uploads(): number`

v1.0

Returns the maximum number of peers that can be unchoked at the same time for this torrent.

`move_storage(path: string, options?: table): void`

v1.0

Moves the file(s) that this torrent is currently seeding/downloading. This is done async and the torrent.storage_moved or torrent.storage_moved_failed will be emitted when done (or failed).

Use options to set extra flags on the move operation. Available flags are,

always_replace_files
fail_if_exist
dont_replace
reset_save_path
reset_save_path_unchecked

Example

th:move_storage("/tmp", { flags = "dont_replace" })

`pause(): void`

v1.0

Pauses the torrent and disconnect all peers. If the torrent is auto managed it may be automatically resumed again.

`post_download_queue(): void`

v1.0

Triggers a torrent.download_queue event to be emitted.

`post_file_priorities(): void`

v1.0

Triggers a torrent.file_priorities event to be emitted.

`post_file_progress(): void`

v1.0

Triggers a torrent.file_progress event to be emitted.

`post_file_status(): void`

v1.0

Triggers a torrent.file_status event to be emitted.

`post_peer_info(): void`

v1.0

Triggers a torrent.peer_info event to be emitted.

`post_piece_availability(): void`

v1.0

Triggers a torrent.piece_availability event to be emitted.

`post_status(): void`

v1.0

Triggers a torrent.state_update event to be emitted`.

`post_trackers(): void`

v1.0

Triggers a torrent.tracker_list event to be emitted.

`prioritize_files(priorities: number[]): void`

v1.0

Prioritizes files in the torrent. File priorities are from 0 to 7 (inclusive).

Priority	Meaning
0	dont_download
1	low_priority
4	default_priority
7	top_priority

Example

info

File indices are based on array position. Porla does the translation from 1-based Lua arrays to the 0-based arrays in C++.

-- set the priority of the first file (index 0) to 0 (dont_download).
torrent:prioritize_files({ 0 })

`queue_position(): number`

v1.0

Returns the queue position for this torrent. Torrents that are being seeded has a queue position of -1.

`queue_position_bottom(): void`

v1.0

Moves the torrent to the bottom of the queue.

`queue_position_down(): void`

v1.0

Moves the torrent one step down in the queue.

`queue_position_set(position: number): void`

v1.0

Updates the queue position for this torrent.

`queue_position_top(): void`

v1.0

Moves the torrent to the top of the queue.

`queue_position_up(): void`

v1.0

Moves the torrent one step up in the queue.

`read_piece(index: number): void`

v1.0

Starts an async read of the piece specified by the index. Triggers the event torrent.read_piece to be emitted.

`remove_url_seed(url: string): void`

v1.0

Removes the given URL from the list of URL seeds, if it exists.

`rename_file(index: number, name: string): void`

v1.0

Begins an async rename of the file specified by the index. Triggers the event torrent.file_renamed or torrent.file_rename_failed to be emitted.

`resume(): void`

v1.0

Resumes peer connections for this torrent.

`save_resume_data(): void`

v1.0

Begins an async save resume data operation for this torrent.

`set_download_limit(val: number): void`

v1.0

Set the download bandwidth limit for this torrent.

`set_flags(flags: LtTorrentFlags, mask?: LtTorrentFlags): void`

v1.0

Sets flags on the torrent. Use the mask override to both set and clear in a single call. Not all flags can be set - some one have an effect when adding a torrent, for example seed_mode.

Example

This example shows how the mask can be used to unset a flag. All flags from mask will be set, so if a flag is missing in flags but set in mask, it will be unset.

In the example, paused will be set and auto_managed will be unset. Stopping the torrent.

local flags = LtTorrentFlags()
flags:set("paused")

local mask = LtTorrentFlags()
mask:set("auto_managed")
mask:set("paused")

th:set_flags(flags, mask)

`set_max_connections(val: number): void`

v1.0

Sets the max number of connections this torrent will open.

`set_max_uploads(val: number): void`

v1.0

Sets the max number of peers that can be unchoked at the same time for this torrent.

`set_ssl_certificate(certificate: string, private_key: string, dh_params: string, passphrase: string)`

v1.0

`set_ssl_certificate_buffer(buffer: string, private_key: string, dh_params: string, passphrase_stirng)`

v1.0

`set_upload_limit(val: number): void`

v1.0

Sets the upload bandwidth limit for this torrent.

`status(): LtTorrentStatus`

v1.0

`torrent_file(): LtTorrentFile | nil`

v1.0

`trackers(): LtAnnounceEntry[]`

v1.0

Returns the list of trackers for this torrent.

`unset_flags(flags: LtTorrentFlags): void`

Unsets the flags passed in flags.

`upload_limit(): number`

v1.0

Returns the upload bandwidth limit for this torrent.

`url_seeds(): string[]`

v1.0

Returns a list of the URL seeds for this torrent.

`userdata(): PoTorrentData`

v1.0

Returns a PoTorrentData object that lets you manage category, tags and also get the PoSessionHandle.

Methods

Methods​

add_url_seed(url: string): void​

clear_error(): void​

clear_peers(): void​

clear_piece_deadlines(): void​

download_limit(): number​

file_status(): LtOpenFileState[]​

flags(): LtTorrentFlags​

flush_cache(): void​

force_dht_announce(): void​

force_lsd_announce(): void​

force_reannounce(seconds?: number, index?: number, flags?: table): void​

Example​

force_recheck(): void​

get_file_priorities(): number[]​

Example​

get_peer_info(): LtPeerInfo[]​

get_renamed_files(): LtRenamedFiles​

have_piece(index: number): boolean​

in_session(): boolean​

info_hash(): LtInfoHash​

is_valid(): boolean​

max_connections(): number​

max_uploads(): number​

move_storage(path: string, options?: table): void​

Example​

pause(): void​

post_download_queue(): void​

post_file_priorities(): void​

post_file_progress(): void​

post_file_status(): void​

post_peer_info(): void​

post_piece_availability(): void​

post_status(): void​

post_trackers(): void​

prioritize_files(priorities: number[]): void​

Example​

queue_position(): number​

queue_position_bottom(): void​

queue_position_down(): void​

queue_position_set(position: number): void​

queue_position_top(): void​

queue_position_up(): void​

read_piece(index: number): void​

remove_url_seed(url: string): void​

rename_file(index: number, name: string): void​

resume(): void​

save_resume_data(): void​

set_download_limit(val: number): void​

set_flags(flags: LtTorrentFlags, mask?: LtTorrentFlags): void​

Example​

set_max_connections(val: number): void​

set_max_uploads(val: number): void​

set_ssl_certificate(certificate: string, private_key: string, dh_params: string, passphrase: string)​

set_ssl_certificate_buffer(buffer: string, private_key: string, dh_params: string, passphrase_stirng)​

set_upload_limit(val: number): void​

status(): LtTorrentStatus​

torrent_file(): LtTorrentFile | nil​

trackers(): LtAnnounceEntry[]​

unset_flags(flags: LtTorrentFlags): void​

upload_limit(): number​

url_seeds(): string[]​

userdata(): PoTorrentData​

Methods

`add_url_seed(url: string): void`

`clear_error(): void`

`clear_peers(): void`

`clear_piece_deadlines(): void`

`download_limit(): number`

`file_status(): LtOpenFileState[]`

`flags(): LtTorrentFlags`

`flush_cache(): void`

`force_dht_announce(): void`

`force_lsd_announce(): void`

`force_reannounce(seconds?: number, index?: number, flags?: table): void`

Example

`force_recheck(): void`

`get_file_priorities(): number[]`

Example

`get_peer_info(): LtPeerInfo[]`

`get_renamed_files(): LtRenamedFiles`

`have_piece(index: number): boolean`

`in_session(): boolean`

`info_hash(): LtInfoHash`

`is_valid(): boolean`

`max_connections(): number`

`max_uploads(): number`

`move_storage(path: string, options?: table): void`

Example

`pause(): void`

`post_download_queue(): void`

`post_file_priorities(): void`

`post_file_progress(): void`

`post_file_status(): void`

`post_peer_info(): void`

`post_piece_availability(): void`

`post_status(): void`

`post_trackers(): void`

`prioritize_files(priorities: number[]): void`

Example

`queue_position(): number`

`queue_position_bottom(): void`

`queue_position_down(): void`

`queue_position_set(position: number): void`

`queue_position_top(): void`

`queue_position_up(): void`

`read_piece(index: number): void`

`remove_url_seed(url: string): void`

`rename_file(index: number, name: string): void`

`resume(): void`

`save_resume_data(): void`

`set_download_limit(val: number): void`

`set_flags(flags: LtTorrentFlags, mask?: LtTorrentFlags): void`

Example

`set_max_connections(val: number): void`

`set_max_uploads(val: number): void`

`set_ssl_certificate(certificate: string, private_key: string, dh_params: string, passphrase: string)`

`set_ssl_certificate_buffer(buffer: string, private_key: string, dh_params: string, passphrase_stirng)`

`set_upload_limit(val: number): void`

`status(): LtTorrentStatus`

`torrent_file(): LtTorrentFile | nil`

`trackers(): LtAnnounceEntry[]`

`unset_flags(flags: LtTorrentFlags): void`

`upload_limit(): number`

`url_seeds(): string[]`

`userdata(): PoTorrentData`