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)

Adds a torrent file to the session.

Parameters:

• filename – str, the filename of the torrent
• filedump – str, 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

add_torrent_magnet(uri, options)

Adds a torrent from a magnet link.

Parameters:

• uri – str, the magnet link
• options – dict, the options to apply to the torrent on add

add_torrent_url(url, options, headers=None)

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

Parameters:

• url – str, 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:

the torrent_id as a str or None, if calling locally, then it will return a Deferred that fires once the torrent has been added

force_recheck(torrent_ids)

Forces a data recheck on torrent_ids

get_available_plugins()

Returns a list of plugins available in the core

get_cache_status()

Returns a dictionary of the session’s cache status.

Returns:a dict of the cache status

get_config()

Get all the preferences as a dictionary

get_config_value(key)

Get the config value for key

get_config_values(keys)

Get the config values for the entered keys

get_dht_nodes()

Returns the number of dht nodes

get_download_rate()

Returns the payload download rate

get_enabled_plugins()

Returns a list of enabled plugins in the core

get_filter_tree(show_zero_hits=True, hide_cat=None)

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

get_health()

Returns True if we have established incoming connections

get_listen_port()

Returns the active listen port

get_num_connections()

Returns the current number of connections

get_path_size(path)

Returns the size of the file or folder ‘path’ and -1 if the path is unaccessible (non-existent or insufficient privs)

get_session_state()

Returns a list of torrent_ids in the session.

get_session_status(keys)

Gets the session status values for ‘keys’

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

get_stats()

document me!!!

get_status_keys()

returns all possible keys for the keys argument in get_torrent(s)_status.

get_torrents_status(filter_dict, keys)

returns all torrents , optionally filtered by filter_dict.

get_upload_rate()

Returns the payload upload rate

pause_all_torrents()

Pause all torrents in the session

rename_files(torrent_id, filenames)

Renames files in ‘torrent_id’. The ‘filenames’ parameter should be a list of (index, filename) pairs.

rename_folder(torrent_id, folder, new_folder)

Renames the ‘folder’ to ‘new_folder’ in ‘torrent_id’.

rescan_plugins()

Rescans the plugin folders for new plugins

resume_all_torrents()

Resume all torrents in the session

set_config(config)

Set the config with values from dictionary

set_torrent_auto_managed(torrent_id, value)

Sets the auto managed flag for queueing purposes

set_torrent_file_priorities(torrent_id, priorities)

Sets a torrents file priorities

set_torrent_max_connections(torrent_id, value)

Sets a torrents max number of connections

set_torrent_max_download_speed(torrent_id, value)

Sets a torrents max download speed

set_torrent_max_upload_slots(torrent_id, value)

Sets a torrents max number of upload slots

set_torrent_max_upload_speed(torrent_id, value)

Sets a torrents max upload speed

set_torrent_move_completed(torrent_id, value)

Sets the torrent to be moved when completed

set_torrent_move_completed_path(torrent_id, value)

Sets the path for the torrent to be moved when completed

set_torrent_options(torrent_ids, options)

Sets the torrent options for torrent_ids

set_torrent_prioritize_first_last(torrent_id, value)

Sets a higher priority to the first and last pieces

set_torrent_remove_at_ratio(torrent_id, value)

Sets the torrent to be removed at ‘stop_ratio’

set_torrent_stop_at_ratio(torrent_id, value)

Sets the torrent to stop at ‘stop_ratio’

set_torrent_stop_ratio(torrent_id, value)

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

set_torrent_trackers(torrent_id, trackers)

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

test_listen_port()

Checks if active port is open

upload_plugin(filename, plugin_data)

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

Returns a list of the exported methods.

info()

Returns some info from the daemon.

Returns:str, the version number