| Both sides previous revisionPrevious revisionNext revision | Previous revision |
| inside_bitcomet [2010/05/10 02:32] – lucy | inside_bitcomet [2022/06/20 15:11] (current) – [BC Link Format (obsoleted as of v.1.17)] wxhere |
|---|
| ==== Torrent File Format ==== | ==== Torrent File Format ==== |
| |
| **1. Torrent File Format** -- as applied in v0.59 or later, contains <html><span style=color:red>important notice</span></html> with regards to encoding. | **1. Torrent File Format** -- as applied in v0.59 or later, contains <html><span style=color:red;font-weight:bold>important notice</span></html> with regards to encoding. |
| |
| The torrent file format below is used in BitComet v0.59 and later. | The torrent file format below is used in BitComet v0.59 and later. |
| * **"path"**: a list containing one or more string elements that, together, represent the path and filename. Each element in the list corresponds to either a directory name or (in the case of the final element) the filename. For example, a the file "dir1/dir2/file.ext" would consist of three string elements: "dir1", "dir2", and "file.ext". This is encoded as a bencoded list of strings such as l4:dir14:dir28:file.exte Important Notice: BitComet also includes empty directory when creating torrent, that is the file name here may be zero-length string. | * **"path"**: a list containing one or more string elements that, together, represent the path and filename. Each element in the list corresponds to either a directory name or (in the case of the final element) the filename. For example, a the file "dir1/dir2/file.ext" would consist of three string elements: "dir1", "dir2", and "file.ext". This is encoded as a bencoded list of strings such as l4:dir14:dir28:file.exte Important Notice: BitComet also includes empty directory when creating torrent, that is the file name here may be zero-length string. |
| |
| //Info keys common to **both** single-file and multi-file modes:// | //Info// <html><span id="privateflag", style=font-style:italic>keys</span></html> //common to **both** single-file and multi-file modes:// |
| |
| * **"piece length"**: number of bytes in each piece (integer) | * **"ed2k"**: (optional) 128 bit eMule hash for each file of the torrent; |
| * **"pieces"**: string consisting of the chaining together of all 20-byte SHA1 hash values, one per piece (byte string) | * **"filehash"**: (optional) 160 bit LT-Seeding hash for each file of the torrent; |
| * **"private"**: (optional) if the torrent is a Private Torrent (SecureTorrent), it must only announce itself to the private tracker or to a single tracker at any time, if there are several trackers in the announce-list (integer, 0 or 1);(([[http://bittorrent.org/beps/bep_0027.html|Private Torrents]])) | * **"piece length"**: number of bytes in each piece (integer); |
| * **"publisher"**: (optional) the name of the torrent creator, if do not allow to be changed (string) | * **"pieces"**: string consisting of the chaining together of all 20-byte SHA1 hash values, one per piece (byte string); |
| * **"publisher-url"**: (optional) the URL of the torrent creator if do not allow to be changed (string) | * **"private"**: (optional) if the torrent is a Private Torrent (SecureTorrent), BitComet must only announce itself to the private tracker or to a single tracker at any time, if there are several trackers in the announce-list (integer, 0 or 1)(([[http://bittorrent.org/beps/bep_0027.html|Private Torrents]])); |
| | * **"publisher"**: (optional) the name of the torrent creator, if do not allow to be changed (string); |
| | * **"publisher-url"**: (optional) the URL of the torrent creator if do not allow to be changed (string); |
| |
| **2) "encoding"**: the string encoding (string), in v0.59 or above is always "UTF-8"\\ | **2) "encoding"**: the string encoding (string), in v0.59 or above is always "UTF-8";\\ |
| **3) "creation date"**: the creation time of the torrent, in standard Unix epoch format (integer seconds since 1-Jan-1970 00:00:00 UTC)\\ | **3) "creation date"**: the creation time of the torrent, in standard Unix epoch format (integer seconds since 1-Jan-1970 00:00:00 UTC);\\ |
| **4) "created by"**: name and version of the program used to create the .torrent (string), like this: "BitComet/0.59";\\ | **4) "created by"**: name and version of the program used to create the .torrent (string), like this: "BitComet/0.59";\\ |
| **5) "announce"**: (optional) The announce URL of the tracker (string);\\ | **5) "announce"**: (optional) The announce URL of the tracker (string);\\ |
| **8) "publisher"**: (optional) the name of the torrent creator (string);\\ | **8) "publisher"**: (optional) the name of the torrent creator (string);\\ |
| **9) "publisher-url"**: (optional) the url of the torrent creator (string);\\ | **9) "publisher-url"**: (optional) the url of the torrent creator (string);\\ |
| **10) "comment"**: (optional) free-form textual comments by the author (string); | **10) "comment"**: (optional) free-form textual comments by the author (string);\\ |
| | **11) "url-list"**: (optional) a list containing one or more URLs of the mirror server(s) used as webseeding download sources.(([[http://www.getright.com/seedtorrent.html|GetRight webseeding specifications]]))(([[http://bittorrent.org/beps/bep_0019.html|HTTP/FTP webseeding - GetRight style]])). |
| |
| <html><span style=color:red>Important Notice:</span></html> | <html><span style=color:red;font-weight:bold>Important Notice:</span></html> |
| |
| * In BitComet v0.58 or prior, the string was encoded using MSCB (user's code page), and a ".utf-8" key was added for UTF-8 encoded string. | * In BitComet v0.58 or prior, the string was encoded using MSCB (user's code page), and a ".utf-8" key was added for UTF-8 encoded string. |
| * **key**: Optional. An additional identification that is not shared with any users. It is intended to allow a client to prove their identity, should their IP address change. | * **key**: Optional. An additional identification that is not shared with any users. It is intended to allow a client to prove their identity, should their IP address change. |
| |
| **2) Tracker -> Client**. The tracker responds with a "text/plain" document, consisting of a bencoded dictionary with the following keys: | **2) Tracker -> Client**. The <html><span id="private">tracker</span></html> responds with a "text/plain" document, consisting of a bencoded dictionary with the following keys: |
| |
| * **failure reason**: Optional. If present, then no other keys may be present. The value is a human-readable error message as to why the request failed (string). | * **failure reason**: Optional. If present, then no other keys may be present. The value is a human-readable error message as to why the request failed (string). |
| - **port**: peer's port number (integer) | - **port**: peer's port number (integer) |
| * **tracker_alias_url**: Optional. a string list of alias trackers. If the other tracker is in the same server, server domain may be omitted | * **tracker_alias_url**: Optional. a string list of alias trackers. If the other tracker is in the same server, server domain may be omitted |
| * <html><span style=color:deeppink>private:</span></html> Optional. If specified, can be 0 or 1 to indicate if the tracker is a private tracker. When a torrent is made under Disable Public DHT Network - Use Tracker Server - (that is to say that there is no nodes key in the torrent, and every tracker in the list announces that it is private tracker explicitly, by sending "private" = 1), BitComet will not add DHT Network as a Backup Tracker, even if all the trackers cannot be connected later, and will also disable Peer Exchange between peers.\\ <html><br /></html> | * <html><span style=color:deeppink;font-weight:bold>private:</span></html> Optional. If specified, can be 0 or 1 to indicate if the tracker is a private tracker. When a torrent is made under Disable Public DHT Network - Use Tracker Server - (that is to say that there is no nodes key in the torrent, and every tracker in the list announces that it is private tracker explicitly, by sending "private" = 1), BitComet will not add DHT Network as a Backup Tracker, even if all the trackers cannot be connected later, and will also disable Peer Exchange between peers.\\ <html><br /></html> |
| |
| **II. Tracker HTTP Protocol before v0.59** -- old spec before v0.59 | **II. Tracker HTTP Protocol before v0.59** -- old spec before v0.59 |
| ==== Multitracker Policy ==== | ==== Multitracker Policy ==== |
| |
| As the multi-tracker spec((http://www.bittorrent.org/beps/bep_0012.html|Multitracker Metadata Extension)) says, we define that the tracker group is comprised of several servers sharing peer information. BitComet will only connect to one of the group's members, but will try connecting to different tracker groups simultaneously. Detailed description on their syntax can be found in [[making_torrents_with_bitcomet|Torrent Maker]]. | As the multi-tracker spec(([[http://www.bittorrent.org/beps/bep_0012.html|Multitracker Metadata Extension]])) says, we define that the tracker group is comprised of several servers sharing peer information. BitComet will only connect to one of the group's members, but will try connecting to different tracker groups simultaneously. Detailed description on their syntax can be found in [[making_torrents_with_bitcomet|Torrent Maker]]. |
| |
| ---- | ---- |
| ==== BC Link Format (obsoleted as of v.1.17) ==== | ==== BC Link Format (obsoleted as of v.1.17) ==== |
| |
| A BC Link contains information for creating a BT task, HTTP task or FTP task. | A //BC Link// contains information for creating a BT task, HTTP task or FTP task. |
| The basic plain format is as following: | The basic plain format is as following: |
| |
| In additional, more parameters can be added: | In additional, more parameters can be added: |
| |
| bc://bt2/${TaskName}/${FileSize}/${InfoHash}/?torrent=${torrent_url} | bc://bt2/${TaskName}/${FileSize}/${InfoHash}/?torrent=${torrent_url}&infohash_v2=${InfoHashv2} |
| bc://http2/${TaskName}/?url=${url}&usr=${username}&psd=${password}&refer=${url_referer}&cookie=${url_cookie} | bc://http2/${TaskName}/?url=${url}&usr=${username}&psd=${password}&refer=${url_referer}&cookie=${url_cookie}&user_agent=${user_agent}&mirror=${mirror_url}&custom_headers_for_mirrors=true |
| bc://ftp2/${TaskName}/?url=${url}&usr=${username}&psd=${password} | bc://ftp2/${TaskName}/?url=${url}&usr=${username}&psd=${password} |
| | |
| Finally, with the advantage of hiding details from end-user, the BASE64 encoded format is recommended to distribute for public: | Finally, with the advantage of hiding details from end-user, the BASE64 encoded format is recommended to distribute for public: |
| |
| |
| <html><span style=color:Teal>Note:</span></html> To support various languages besides English, all parameters should be UTF8 + URL_Escape encoded before Base64 encoding. | <html><span style=color:Teal>Note:</span></html> To support various languages besides English, all parameters should be UTF8 + URL_Escape encoded before Base64 encoding. |
| | |
| | <html><span style=color:Teal>Note:</span></html> If multiple HTTP mirrors available for a HTTP task, multiple "mirror" parameters can be added. |
| | |
| | <html><span style=color:Teal>Note:</span></html> If "custom_headers_for_mirrors" parameter is true, the "referer", "cookie" and "user_agent" will also be sent to mirror addresses. |
| | |
| | <html><span style=color:Teal>Note:</span></html> Starting with BitComet v.1.17 //BC Links// have been replaced by //Magnet Links// (see below). |
| |
| ---- | ---- |
| |
| A [[peers_seeds_torrent_tracker_dht_peer_exchange_pex_magnet_links#magnet_links|Magnet URI]] contains information for locating a P2P resource. BitComet can use it to start a BT download. | A [[peers_seeds_torrent_tracker_dht_peer_exchange_pex_magnet_links#magnet_links|Magnet URI]] contains information for locating a P2P resource. BitComet can use it to start a BT download. |
| The format is as following: | The basic v1 format is as following: |
| |
| magnet:?xt=urn:btih:<info-hash>&dn=<name>&tr=<tracker-url>&xl=<task-size> | magnet:?xt=urn:btih:<info-hash-v1> |
| | |
| | The basic v2 format with a 32 bytes info hash of SHA256: |
| | |
| | magnet:?xt=urn:btmh:1220<info-hash-v2> |
| | |
| | The hybrid format with info hash v1 and v2: |
| | |
| | magnet:?xt=urn:btih:<info-hash-v1>&xt=urn:btmh:1220<info-hash-v2> |
| | |
| | In additional, more parameters can be added: |
| | |
| | magnet:?xt=urn:btih:<info-hash-v1>&dn=<name>&xl=<task-size>&tr=<tracker-url>&ws=<escaped_web_seed_url>&xs=<escaped_torrent_file_url> |
| |
| ---- | ---- |
| === Mandatory parameter === | === Mandatory parameter === |
| |
| **xt**=urn:btih:<info-hash> is a mandatory parameter for BitTorrent magnetic links. | **xt**=urn:btih:<info-hash-v1> is a mandatory parameter for BitTorrent v1 magnetic links. |
| | |
| | **<info-hash-v1>** is the torrent info-hash-v1 hex encoded, for a total of 40 characters. The 32 character [[http://www.ietf.org/rfc/rfc3548.txt|base32]] encoded info-hash-v1 is also accepted. |
| | |
| | **xt**=urn:btmh:1220<info-hash-v2> is a mandatory parameter for BitTorrent v2 magnetic links. |
| |
| **<info-hash>** is the torrent info-hash hex encoded, for a total of 40 characters. The 32 character [[http://www.ietf.org/rfc/rfc3548.txt|base32]] encoded info-hash is also accepted. | **<info-hash-v2>** is the torrent info-hash-v2 hex encoded, for a total of 64 characters. |
| |
| ---- | ---- |
| |
| **dn** is the user-friendly display name (which may be displayed while waiting for metadata); it should be UTF8 + URL_Escape encoded for non-English characters.\\ | **dn** is the user-friendly display name (which may be displayed while waiting for metadata); it should be UTF8 + URL_Escape encoded for non-English characters.\\ |
| **tr** is a tracker URL, if there is one; for multiple trackers multiple "tr" parameters may be added.\\ | |
| **xl** is the task size.\\ | **xl** is the task size.\\ |
| | **tr** is a tracker URL, if there is one; for multiple trackers multiple "tr" parameters may be added.\\ |
| | **ws** is the escaped web seed URL.\\ |
| | **xs** is the escaped HTTP URL of torrent file.\\ |
| | |
| For a technical introduction to Magnet URIs please refer to [[wp>Magnet URI scheme]]. | For a technical introduction to Magnet URIs please refer to [[wp>Magnet URI scheme]]. |
| |
| * **For a torrent maker:** | * **For a torrent maker:** |
| |
| Make the torrent file with the "Private torrent" (or "Only accept peers from tracker" in older versions) option enabled (no DHT or Peer Exchange allowed for that torrent and also no Torrent Exchange/Share, LT-Seeding or eDonkey connectivity enabled in BitComet). | Make the torrent file with the "//Private torrent//" (or "//Only accept peers from tracker//" in older versions) option enabled (no DHT or Peer Exchange allowed for that torrent and also no Torrent Exchange/Share, LT-Seeding or eDonkey connectivity enabled in BitComet). |
| Read [[Making Torrents with BitComet]] for more information on how to enable this option upon making a torrent. This option will add a private tag in the torrent file, and has the same meaning as [[http://wiki.vuze.com/w/SecureTorrents|SecureTorrent in Azureus]]. | Read [[Making Torrents with BitComet]] for more information on how to enable this option upon making a torrent. This option will add a "//[[inside_bitcomet#privateflag|private]]//" tag in the torrent file, and has the same meaning as [[http://wiki.vuze.com/w/SecureTorrents|SecureTorrent in Azureus]]. |
| |
| * **For a tracker admin:** | * **For a tracker admin:** |
| |
| Add a //[[inside_bitcomet#tracker_http_protocol|private]]// keyword in the tracker HTTP response. Read [[inside_bitcomet#tracker_http_protocol|Tracker HTTP Protocol]] in this section for more information on all parameters used in client -> tracker communication and the keys contained in the tracker -> client response. | Add a //[[inside_bitcomet#private|private]]// keyword in the tracker HTTP response. Read [[inside_bitcomet#tracker_http_protocol|Tracker HTTP Protocol]] in this section for more information on all parameters used in client -> tracker communication and the keys contained in the tracker -> client response. |
| |
| Note: The Private Torrent (SecureTorrent) flag does not work properly in v.0.60 because | Note: The Private Torrent (SecureTorrent) flag does not work properly in v.0.60 because |
| User Account Control (UAC) is a technology and security infrastructure introduced along with Microsoft's **Windows Vista** and **Windows Server 2008** operating system and also present in the subsequent versions such as **Windows 7**. It aims to improve the security of Microsoft Windows by limiting the access rights of the software applications running in Windows to standard user privileges, by default, until an administrator authorizes an elevation. | User Account Control (UAC) is a technology and security infrastructure introduced along with Microsoft's **Windows Vista** and **Windows Server 2008** operating system and also present in the subsequent versions such as **Windows 7**. It aims to improve the security of Microsoft Windows by limiting the access rights of the software applications running in Windows to standard user privileges, by default, until an administrator authorizes an elevation. |
| |
| Because running the BitComet installation package needs administrator privileges, in certain cases, unsuitable combinations between certain UAC settings and the user account type, may lead to installation failure. | Because running the BitComet installation package needs administrator privileges, in certain cases, //unsuitable combinations between certain UAC settings and the user account type, may lead to installation failure.// |
| |
| As a basic guideline you should keep in mind that if you disabled UAC then you should run | As a basic guideline you should keep in mind that if you disabled UAC then you should run |
| - When a task finished downloading, a Hash Checking will be performed to prepare for eMule plugin uploading, if the torrent is not private and the eMule plugin is not disabled, but it was not supported by the torrent maker. | - When a task finished downloading, a Hash Checking will be performed to prepare for eMule plugin uploading, if the torrent is not private and the eMule plugin is not disabled, but it was not supported by the torrent maker. |
| - When a task finished downloading, a Hash Checking will be performed if the "//bittorrent.hash_check_on_finished//" option on the //Advanced Options// page is set to TRUE. | - When a task finished downloading, a Hash Checking will be performed if the "//bittorrent.hash_check_on_finished//" option on the //Advanced Options// page is set to TRUE. |
| | |
| | ---- |
| | |
| | ==== AJAX interface for Remote Download ==== |
| | |
| | see details in [[AJAX interface for Remote Download|this page]] |
| |
| ---- | ---- |
| -[[bitcomet_command_line|Previous Page]]\\ | -[[bitcomet_command_line|Previous Page]]\\ |
| -[[start|Main Index]] | -[[start|Main Index]] |
