Deluge RPC

Message Formats

DelugeRPC is a protocol used for daemon/client communication. There are four types of messages involved in the protocol: RPC Request, RPC Response, RPC Error and Event. All messages are zlib compressed rencoded strings and their data formats are detailed below.

RPC Request

This message is created and sent by the client to the server requesting that a remote method be called. Multiple requests can be bundled in a list.

[[request_id, method, [args], {kwargs}], ...]

request_id (int)

An integer determined by the client that is used in replies from the server. This is used to ensure the client knows which request the data is in response to. Another alternative would be to respond in the same order the requests come in, but this could cause lag if an earlier request takes longer to process.

method (str)

The name of the remote method to call. This name can be in dotted format to call other objects or plugins methods.

args (list)

The arguments to call the method with.

kwargs (dict)

The keyword arguments to call the method with.

RPC Response

This message is created and sent in response to a RPC Request from a client. It will hold the return value of the requested method call. In the case of an error, a RPC Error message will be sent instead.

[message_type, request_id, [return_value]]

message_type (int)

This will be a RPC_RESPONSE type id. This is used on the client side to determine what kind of message is being received from the daemon.

request_id (int)

The request_id is the same as the one sent by the client in the initial request. It used on the client side to determine what message this is in response to.

return_value (list)

The return value of the method call.

RPC Error

This message is created in response to an error generated while processing a RPC Request and will serve as a replacement for a RPC Response message.

[message_type, request_id, exception_type, exception_msg, traceback]

message_type (int)

This will be a RPC_ERROR type id.

request_id (int)

The request_id is the same as the one sent by the client in the initial request.

exception_type (str)

The type of exception raised.

exception_msg (str)

The message as to why the exception was raised.

traceback (str)

The traceback of the generated exception.

Event

This message is created by the daemon and sent to the clients without being in response to a RPC Request. Events are generally sent for changes in the daemon’s state that the clients need to be made aware of.

[message_type, event_name, data]

message_type (int)

This will be a RPC_EVENT type id.

event_name (str)

This is the name of the event being emitted by the daemon.

data (list)

Additional data to be sent with the event. This is dependent upon the event being emitted.

Remote API

class deluge.__rpcapi.RpcApi

class core

Methods available in core

add_torrent_file(filename, filedump, options)

RPC Exported Function (Auth Level: 5)

Adds a torrent file to the session.

Parameters:

• filename (string) – the filename of the torrent
• filedump (string) – a base64 encoded string of the torrent file contents
• options (dict) – the options to apply to the torrent on add

Returns:

the torrent_id as a str or None

Return type:

string

add_torrent_magnet(uri, options)

RPC Exported Function (Auth Level: 5)

Adds a torrent from a magnet link.

Parameters:

• uri (string) – the magnet link
• options (dict) – the options to apply to the torrent on add

Returns:

the torrent_id

Return type:

string

add_torrent_url(url, options, headers=None)

RPC Exported Function (Auth Level: 5)

Adds a torrent from a url. Deluge will attempt to fetch the torrent from url prior to adding it to the session.

Parameters:

• url (string) – the url pointing to the torrent file
• options (dict) – the options to apply to the torrent on add
• headers (dict) – any optional headers to send

Returns:

a Deferred which returns the torrent_id as a str or None

connect_peer(torrent_id, ip, port)

RPC Exported Function (Auth Level: 5)

create_torrent(path, tracker, piece_length, comment, target, webseeds, private, created_by, trackers, add_to_session)

RPC Exported Function (Auth Level: 5)

disable_plugin(plugin)

RPC Exported Function (Auth Level: 5)

enable_plugin(plugin)

RPC Exported Function (Auth Level: 5)

force_reannounce(torrent_ids)

RPC Exported Function (Auth Level: 5)

force_recheck(torrent_ids)

RPC Exported Function (Auth Level: 5)

Forces a data recheck on torrent_ids

get_available_plugins()

RPC Exported Function (Auth Level: 5)

Returns a list of plugins available in the core

get_cache_status()

RPC Exported Function (Auth Level: 5)

Returns a dictionary of the session’s cache status.

Returns:the cache status Return type:dict

get_config()

RPC Exported Function (Auth Level: 5)

Get all the preferences as a dictionary

get_config_value(key)

RPC Exported Function (Auth Level: 5)

Get the config value for key

get_config_values(keys)

RPC Exported Function (Auth Level: 5)

Get the config values for the entered keys

get_dht_nodes()

RPC Exported Function (Auth Level: 5)

Returns the number of dht nodes

get_download_rate()

RPC Exported Function (Auth Level: 5)

Returns the payload download rate

get_enabled_plugins()

RPC Exported Function (Auth Level: 5)

Returns a list of enabled plugins in the core

get_filter_tree(show_zero_hits=True, hide_cat=None)

RPC Exported Function (Auth Level: 5)

returns {field: [(value,count)] } for use in sidebar(s)

get_free_space(path)

RPC Exported Function (Auth Level: 5)

Returns the number of free bytes at path

Parameter:path (string) – the path to check free space at Returns:the number of free bytes at path Return type:int Raises InvalidPathError:  if the path is invalid

get_health()

RPC Exported Function (Auth Level: 5)

Returns True if we have established incoming connections

get_listen_port()

RPC Exported Function (Auth Level: 5)

Returns the active listen port

get_num_connections()

RPC Exported Function (Auth Level: 5)

Returns the current number of connections

get_path_size(path)

RPC Exported Function (Auth Level: 5)

Returns the size of the file or folder ‘path’ and -1 if the path is

unaccessible (non-existent or insufficient privs)

get_session_state()

RPC Exported Function (Auth Level: 5)

Returns a list of torrent_ids in the session.

get_session_status(keys)

RPC Exported Function (Auth Level: 5)

Gets the session status values for ‘keys’, these keys are taking from libtorrent’s session status.

Parameter:keys (list) – the keys for which we want values Returns:a dictionary of {key: value, ...} Return type:dict

get_stats()

RPC Exported Function (Auth Level: 5)

Deprecated: please use get_session_status()

get_torrent_status(torrent_id, keys)

RPC Exported Function (Auth Level: 5)

get_torrents_status(filter_dict, keys)

RPC Exported Function (Auth Level: 5)

returns all torrents , optionally filtered by filter_dict.

get_upload_rate()

RPC Exported Function (Auth Level: 5)

Returns the payload upload rate

glob(path)

RPC Exported Function (Auth Level: 5)

move_storage(torrent_ids, dest)

RPC Exported Function (Auth Level: 5)

pause_all_torrents()

RPC Exported Function (Auth Level: 5)

Pause all torrents in the session

pause_torrent(torrent_ids)

RPC Exported Function (Auth Level: 5)

queue_bottom(torrent_ids)

RPC Exported Function (Auth Level: 5)

queue_down(torrent_ids)

RPC Exported Function (Auth Level: 5)

queue_top(torrent_ids)

RPC Exported Function (Auth Level: 5)

queue_up(torrent_ids)

RPC Exported Function (Auth Level: 5)

remove_torrent(torrent_id, remove_data)

RPC Exported Function (Auth Level: 5)

Removes a torrent from the session.

Parameters:

• torrent_id (string) – the torrent_id of the torrent to remove
• remove_data (boolean) – if True, remove the data associated with this torrent

Returns:

True if removed successfully

Return type:

bool

Raises InvalidTorrentError:  

if the torrent_id does not exist in the session

rename_files(torrent_id, filenames)

RPC Exported Function (Auth Level: 5)

Rename files in torrent_id. Since this is an asynchronous operation by libtorrent, watch for the TorrentFileRenamedEvent to know when the files have been renamed.

Parameters:

• torrent_id (string) – the torrent_id to rename files
• filenames (((index, filename), ...)) – a list of index, filename pairs

Raises InvalidTorrentError:  

if torrent_id is invalid

rename_folder(torrent_id, folder, new_folder)

RPC Exported Function (Auth Level: 5)

Renames the ‘folder’ to ‘new_folder’ in ‘torrent_id’. Watch for the TorrentFolderRenamedEvent which is emitted when the folder has been renamed successfully.

Parameters:

• torrent_id (string) – the torrent to rename folder in
• folder (string) – the folder to rename
• new_folder (string) – the new folder name

Raises InvalidTorrentError:  

if the torrent_id is invalid

rescan_plugins()

RPC Exported Function (Auth Level: 5)

Rescans the plugin folders for new plugins

resume_all_torrents()

RPC Exported Function (Auth Level: 5)

Resume all torrents in the session

resume_torrent(torrent_ids)

RPC Exported Function (Auth Level: 5)

set_config(config)

RPC Exported Function (Auth Level: 5)

Set the config with values from dictionary

set_torrent_auto_managed(torrent_id, value)

RPC Exported Function (Auth Level: 5)

Sets the auto managed flag for queueing purposes

set_torrent_file_priorities(torrent_id, priorities)

RPC Exported Function (Auth Level: 5)

Sets a torrents file priorities

set_torrent_max_connections(torrent_id, value)

RPC Exported Function (Auth Level: 5)

Sets a torrents max number of connections

set_torrent_max_download_speed(torrent_id, value)

RPC Exported Function (Auth Level: 5)

Sets a torrents max download speed

set_torrent_max_upload_slots(torrent_id, value)

RPC Exported Function (Auth Level: 5)

Sets a torrents max number of upload slots

set_torrent_max_upload_speed(torrent_id, value)

RPC Exported Function (Auth Level: 5)

Sets a torrents max upload speed

set_torrent_move_completed(torrent_id, value)

RPC Exported Function (Auth Level: 5)

Sets the torrent to be moved when completed

set_torrent_move_completed_path(torrent_id, value)

RPC Exported Function (Auth Level: 5)

Sets the path for the torrent to be moved when completed

set_torrent_options(torrent_ids, options)

RPC Exported Function (Auth Level: 5)

Sets the torrent options for torrent_ids

set_torrent_prioritize_first_last(torrent_id, value)

RPC Exported Function (Auth Level: 5)

Sets a higher priority to the first and last pieces

set_torrent_remove_at_ratio(torrent_id, value)

RPC Exported Function (Auth Level: 5)

Sets the torrent to be removed at ‘stop_ratio’

set_torrent_stop_at_ratio(torrent_id, value)

RPC Exported Function (Auth Level: 5)

Sets the torrent to stop at ‘stop_ratio’

set_torrent_stop_ratio(torrent_id, value)

RPC Exported Function (Auth Level: 5)

Sets the ratio when to stop a torrent if ‘stop_at_ratio’ is set

set_torrent_trackers(torrent_id, trackers)

RPC Exported Function (Auth Level: 5)

Sets a torrents tracker list. trackers will be [{“url”, “tier”}]

test_listen_port()

RPC Exported Function (Auth Level: 5)

Checks if the active port is open

Returns:True if the port is open, False if not Return type:bool

upload_plugin(filename, plugin_data)

RPC Exported Function (Auth Level: 5)

This method is used to upload new plugins to the daemon. It is used

when connecting to the daemon remotely and installing a new plugin on the client side. ‘plugin_data’ is a xmlrpc.Binary object of the file data, ie, plugin_file.read()

class RpcApi.daemon

Methods available in daemon

get_method_list()

RPC Exported Function (Auth Level: 5)

Returns a list of the exported methods.

info()

RPC Exported Function (Auth Level: 5)

Returns some info from the daemon.

Returns:str, the version number

shutdown(*args, **kwargs)

RPC Exported Function (Auth Level: 5)