BitTorrent.com » BitTorrent DNA » Resources » DNA Integration Guide »

DNA Integration Guide

Integration Downloads

(III) DNA Control API

The Control API is a programmatic way to monitor and control downloads performed by the DNA client. The interface is a REST-style RPC communication with a local HTTP server.
The first step in using the Control API is to acquire the DNA port (see DNA Proxy API section above).

The format of data returned from the Control API depends on the HTTP Accept header in the request. If it contains "text/xml" the returned data will always be XML formatted; if it contains "application/jsonrequest" it will be returned as JSON.

As a demonstration, we'll use a browser, although wget or any other http client library will work. For the following examples, we'll direct the browser to the conventional localhost IP address 127.0.0.1 and in each case we’ll assume DNA is listening on­ port 64348. While a torrent is downloading, we’ll open a separate browser tab and load the URL into the address bar.

Control API instructions can address content by URL (url=), infohash (id=), torrent display name (caption=) or path (info_file=).

To check status for an active torrent use ctrl/torrent:

http://127.0.0.1:64348/ctrl/torrent?url=http%3A%2F%2Fdownload.bittorrent.com%2Fpublic%2FSeedMe%2FBolivia%2FBT_640x360.flv

Once the swarming begins the following info is returned (contains sample data):

<torrent>
	<avail_factor>1114058</avail_factor>
	<begin_prio_window_piece>883</begin_prio_window_piece>
	<buffer_secs>30</buffer_secs>
	<caption>C206C1E9F5FE42BA1099C4DE256D29318E9E2CFE</caption>
	<conn_peer>22</conn_peer>
	<conn_seed>14</conn_seed>
	<cursor>437</cursor>
	<dl_bytes_remaining>7602176</dl_bytes_remaining>
	<dl_rate>1706294</dl_rate>
	<download_state>1</download_state>
	<downloaded>14467072</downloaded>
	<duration>299</duration>
	<end_prio_window_piece>1082</end_prio_window_piece>
	<eta>9</eta>
	<eye_ms>25407</eye_ms>
	<ghost_ms>27948</ghost_ms>
	<hash>C206C1E9F5FE42BA1099C4DE256D29318E9E2CFE</hash>
	<hole>883</hole>
	<http_pending_limit>4</http_pending_limit>
	<list_peer>141</list_peer>
	<list_seed>15</list_seed>
	<offload>741</offload>
	<p_downloaded>24122823</p_downloaded>
<path>C%3a%5cDocuments%20and%20Settings%5csmorris.SF00316%5cLocal%20Settings
%5cApplication%20Data%5cDNA%5cCache%5cC206C1E9F5FE42BA1099C4DE25
6D29318E9E2CFE</path>
	<pct_complete>810</pct_complete>
	<peer_id>444E41303230303030A2A1010101359DA0930290</peer_id>
	<qos_rate>133720</qos_rate>
	<ratio>0</ratio>
	<receive_piece>520</receive_piece>
	<scrambled>1</scrambled>
	<service>STREAMING</service>
	<status>137</status>
	<total_dl>32249287</total_dl>
	<total_ul>0</total_ul>
	<ui_label></ui_label>
	<ul_rate>31277</ul_rate>
	<use_bt_throttling>1</use_bt_throttling>
	<use_utp>0</use_utp>
	<w_downloaded>8337134</w_downloaded>
	<waste_bytes>0</waste_bytes>
</torrent>

Field Definitions:

  • avail_factor: availability factor. Most significant 16 bits is the number of copies of the rarest piece. The least significant 16 bits is meant to be used as a fraction. It is the fraction of pieces with a number of copies greater than the number of copies of the rarest piece.
  • begin_prio_window_piece: first piece in the priority window. Priority window begins at the “hole” (see below) and extends to a number of pieces beyond the receive_piece (see below).
  • buffer_secs: maximum buffer required by the encoded video. In MPEG parlance, this is called the Video Buffer Verifier). Is specified in seconds or MM:SS format.
  • caption: in case of multiple files in the same torrent this is the name of the directory into which the multiple files are placed, defaults to the value of the torrent infohash.
  • conn_peer: number of non-seed peers for which we have opened connections.
  • conn_seed: number of seeds for which we have opened connections.
  • cursor: the highest piece number completely forwarded to the application.
  • dl_bytes_remaining: number of bytes remaining.
  • dl_rate: total download rate for this torrent, i.e., sum across all peers in torrent.
  • download_state: the current state of the download: 0 = downloading but not yet joined the swarm, 1 = downloading from the swarm, 2 = seeding but no longer downloading (completed or paused)
  • downloaded: the number of contiguous pieces downloaded up until now.
  • duration: duration of the stream in seconds or MM:SS format.
  • end_prio_window_piece: one piece above the largest piece in the priority window.
  • eta: estimated time (in seconds) until download completes. Once download has completed this becomes the estimated time until the desired seeding ratio is met.
  • eye_ms: estimated playback point.
  • ghost_ms: estimated playback point multiplied by a safety factor.
  • hash: hex-encoded SHA-1 hash of the info block in the torrent's .torrent file, a.k.a infohash.
  • hole: the lowest piece number that DNA has not yet received.
  • http_pending_limit: is the number of http requests that are pipelined to web servers. i.e. how many that are kept in-flight while waiting for a response on the first one.
  • list_peer: number of non-banned, non-seed peers this peer knows including those with opened connections.
  • list_seed: number of non-banned seeds this peer knows including those with opened connections.
  • offload: integer between 0 and 1000 denoting % offload * 10
  • p_downloaded: total number of non-wasted bytes received for this torrent via peers
  • path: the disk location where the file is stored
  • pct_complete: percentage of bytes downloaded * 10, e.g., 932 = 93.2%.
  • peer_id: unique session ID for DNA from the last time it was started up;
  • qos_rate: for STREAMING this is the encoded bitrate (the size of the file divided by the duration). For MIN_RATE_DATA this the rate above which the HTTP sources can be throttled.
  • ratio: uploaded / downloaded * 1000, e.g. 500 = twice as much downloaded as uploaded.
  • receive_piece: the piece that should be received right now to satisfy the ghost safety factor and buffer_secs. The priority window extends in front of the receive_piece.
  • scrambled: whether or not the content is obscured in the cache – used in conjunction with NSIS installer in cases where a download should be able to be installed directly from the cache.
  • service: STREAMING (= http streaming a.k.a. progressive download service) or MIN_RATE_DATA (= download service)
  • status: byte used as bit array. STARTED = 1, CHECKING = 2, START_AFTER_CHECK = 4, CHECKED = 8, ERROR = 16, PAUSED = 32, AUTO = 64, LOADED = 128
  • total_dl: total number of bytes downloaded from this torrent, i.e., sum of downloaded from every peer in torrent.
  • total_ul: total number of bytes uploaded from this torrent, i.e., sum of uploaded from every peer in torrent.
  • ui_label: the value of the label attached to the torrent, visible through consumer UI (defaults to “”)
  • ul_rate: total upload rate for this torrent, i.e., sum across all peers in torrent.
  • use_bt_throttling: (for internal BitTorrent use only) – marker of whether or not bt_throttling parameter is set
  • use_utp: (for internal BitTorrent use only) – marker of whether or not use_utp parameter is set
  • w_downloaded: total number of non-wasted bytes received for this torrent via a web server or web servers
  • waste_bytes: number of bytes that have been downloaded that duplicate bytes that have already been received

The values marked with the arrow bullet symbol as follows:

  •  

...are returned only if the service is STREAMING.

To gets stats about peers, use ctrl/peerstats:

http://127.0.0.1:64348/ctrl/peerstats?url=http%3A%2F%2Fdownload.bittorrent.com%2Fpublic%2FSeedMe%2FBolivia%2FBT_640x360.flv

It returns a dict containing two keys "BitTorrent" which contains stats for BitTorrent peers, and "HTTP" which contains stats for HTTP seeds. The value for each of these keys is a list of dicts. Each dict in each of these lists represent a host (peer or http seed):

  • ip = IP address
  • dl = number of bytes downloaded
  • ul = number of bytes uploaded
  • dl_rate = download rate in bytes per second.
  • ul_rate = upload rate in bytes per second.
  • seed = 0: not seed, 1: seed

An example of results is shown below:

<peerstats>
	 <BitTorrent>
			 <item>
					 <dl>16384</dl>
					 <dl_rate>2614</dl_rate>
					 <ip>62.45.197.106</ip>
					 <seed>1</seed>
					 <tick>131321031</tick>
					 <ul>0</ul>
					 <ul_rate>86</ul_rate>
			 </item>
			 <item>
					 <dl>245760</dl>
					 <dl_rate>29783</dl_rate>
					 <ip>12.216.200.202</ip>
					 <seed>0</seed>
					 <tick>131321031</tick>
					 <ul>0</ul>
					 <ul_rate>292</ul_rate>
			 </item>
	 </BitTorrent>
	 <HTTP>
			 <item>
					 <dl>4325376</dl>
					 <dl_rate>154425</dl_rate>
					 <ip>208.72.193.71</ip>
					 <seed>1</seed>
					 <tick>131321031</tick>
					 <ul>0</ul>
					 <ul_rate>973</ul_rate>
			 </item>
	 </HTTP>
</peerstats>

To get information about pieces, use ctrl/pieces:

http://127.0.0.1:64348/ctrl/pieces?url=http%3A%2F%2Fdownload.bittorrent.com%2Fpublic%2FSeedMe%2FBolivia%2FBT_640x360.flv

It returns a dict containing keys "Piece#", where # is replaced by the number of the piece, for all pieces in the torrent. If we have the piece, the value is 1, otherwise it is 0.

A example of results (truncated) is shown below:

<pieces>
	 <Piece1>1</Piece1>
	 <Piece10>1</Piece10>
	 <Piece100>0</Piece100>
		...
		...
		...
	 <Piece997>1</Piece997>
	 <Piece998>0</Piece998>
	 <Piece999>1</Piece999>
</pieces>

To pass instructions to DNA in order to optimize player function use ctrl/update :

http://127.0.0.1:64348/ctrl/update?url=http%3A%2F%2Fdownload.bittorrent.com%2F public%2FSeedMe%2FBolivia%2FBT_640x360.flv

                               &qos=____

                               OR

                               &duration=____ 

                               OR 

                               &buffer_secs=____

This returns no body.

It allows the caller to set parameters or update the video playback position.

The qos value is in bytes per second.

The duration and buffer_secs are in seconds or MM:SS format.

To remove a torrent and the associated cached content use ctrl/remove :

http://127.0.0.1:64348/ctrl/remove?options=0&url=http%3A%2F%2Fdownload.bittorrent.com%2Fpublic%2FSeedMe%2FBolivia%2FBT_640x360.flv

This returns no body. ?options= is a parameter to specify whether DNA should remove the torrent and content asynchronously or synchronously (i.e. whether DNA should wait for completion of the instruction): 0 is the option for issuing the instruction asynchronously, 8 issues the instruction synchronously.

© 2001-2009 BitTorrent, Inc. All rights reserved. BitTorrent, the BitTorrent Logo, and Torrent are trademarks of BitTorrent, Inc.