CW Cyrix's Git Repository Mirror
Browse code

Import from the old rivettracker git repository at sourceforge (amisaph/amisapphire branch)

Clarissa Walker (ami-sapphire) authored on 2014/01/24 14:02:23
Showing 1 changed files
docs/BEncode-API.txt
History View file @ 1c8ad06
1 1 
new file mode 100644
... ... 
@@ -0,0 +1,83 @@
1 
+API Interfaces
2 
+
3 
+
4 
+BDecode($string)
5 
+---------------
6 
+
7 
+Takes input as a single string. This string should be the whole
8 
+.torrent file or whatever encoded stream you want to decode.
9 
+
10 
+Returns the array of the original encoded data. For example, to
11 
+get the URL of the tracker used by a .torrent, use
12 
+
13 
+	$fd = fopen("myfile.torrent", "rb");
14 
+	$stream = fread($fd, filesize("myfile.torrent"));
15 
+	fclose($fd);
16 
+
17 
+	$array = BDecode($stream);
18 
+
19 
+	echo "Url: ".$array["announce"]."\n";
20 
+
21 
+
22 
+
23 
+
24 
+BEncode($array)
25 
+---------------
26 
+
27 
+Pretty much the opposite of the decoder. It takes an array and
28 
+outputs the encoded data as one large string. Assuming there
29 
+are no bugs in the code, BEncode(BDecode($stream) should give
30 
+the exact same string back.
31 
+
32 
+
33 
+
34 
+
35 
+
36 
+$array
37 
+------
38 
+
39 
+My first impression of the whole BEncode system is that Python
40 
+makes a distinction between lists and dictionaries. I'm sure that's
41 
+a good thing for the Python programmers but we have a different
42 
+problem.
43 
+
44 
+PHP doesn't really make a difference between lists and
45 
+dictionaries. They're all arrays. As such, the difference
46 
+between a dictionary and an array is simple: lists are numerically
47 
+indexed only. If (isset($array[0])) is true, you may assume the
48 
+array is a "list" and treat it as such. Iterate until !isset($array[$i]);
49 
+
50 
+In the event of a list that has zero entries ("le"), it will be represented
51 
+as array() (is_array() && empty()). Dictionaries ("de") will be represented
52 
+as the boolean type true, not an array.
53 
+
54 
+This should hold as long as Bram doesn't do something cruel in the
55 
+near future. :)
56 
+
57 
+
58 
+Notes
59 
+-----
60 
+
61 
+The return value will always be an array if the response is one of the
62 
+normal responses of BitTorrent, which are always dictionaries. But it will
63 
+also accept non-dictionaries as input.
64 
+
65 
+For exmaple, BDecode("i15e") === (int) 15
66 
+
67 
+Finally, the decoder is a little more tolerant of bencoding errors than
68 
+the Python becode library. Things like sorted dictionaries when decoding
69 
+are not enforced.
70 
+
71 
+
72 
+
73 
+Dictionaries
74 
+------------
75 
+One last thing about dictionaries. If you were to do something like this:
76 
+
77 
+foreach ($array as $left => $right) { .. }
78 
+ or similarly
79 
+$array[$left] = $right;
80 
+
81 
+Then beware: $left has had addslashes applied to it. This is to work
82 
+around a small quirk in PHP. Null bytes ("\0") would cause the value
83 
+of $left to be truncated at the null byte.
0 84 
\ No newline at end of file