README
1NAME
2 Net::BitTorrent::PeerPacket - Parse/Build Peer Packets from BitTorrent
3
4SYNOPSIS
5 # import everything
6 use Net::BitTorrent::PeerPacket qw(:all);
7
8 # or be more selective
9 use Net::BitTorrent::PeerPacket qw(bt_build_packet :constants);
10
11 # Encode a packet
12 my $binary_packet = bt_build_packet($key1, $value1, $key2, $value2);
13
14 # Decode a packet
15 my $parsed_packet = bt_parse_packet($binary_data);
16
17DESCRIPTION
18 "Net::BitTorrent::PeerPacket" handles parsing and building binary data
19 shared between BitTorrent peers. The module optionally exports a single
20 subroutine for building packets and another for parsing packets, as well
21 as, a constant for each packet type defined by BitTorrent.
22
23CONSTANTS
24 There are ten primary types of packets that are shared between peers on
25 a BitTorrent network. The following constants are how the type of packet
26 being build/parsed are represented within this module.
27
28 BT_HANDSHAKE
29 Used to start communication between peers.
30
31 BT_CHOKE
32 Tell a peer that it is choked.
33
34 BT_UNCHOKE
35 Tell a peer that it is unchoked.
36
37 BT_INTERESTED
38 Used to tell a peer that it has a piece that you need.
39
40 BT_UNINTERESTED
41 Used to tell a peer that it has no pieces that you need.
42
43 BT_HAVE
44 Used to tell a peer that you now have a specific piece.
45
46 BT_BITFIELD
47 Used right after a handshake, this tells a peer all of the pieces
48 that you have and don't have in one message.
49
50 BT_REQUEST
51 Used to request a block of data from a piece that a peer has.
52
53 BT_PIECE
54 Used to return a block of data that was requested.
55
56 BT_CANCEL
57 Used to tell a peer that you no longer need the piece that you were
58 downloading from them.
59
60SUBROUTINES
61 bt_build_packet
62 This subroutine is responsible for building all types of BitTorrent
63 packets. The arguments are passed into the subroutine as a list of
64 key-value pairs. The resultant packet is sent back as a scalar.
65
66 Depending on the requested packet type, the required arguments vary. One
67 argument that is common to all calls is the "bt_code". The "bt_code"
68 maps to a "BT_" constant exported by this module and determines the type
69 of packet that will be built.
70
71 What follows is a list of the different BT codes and the details of
72 calling this subroutine with those codes.
73
74 BT_HANDSHAKE
75 Passing the "BT_HANDSHAKE" code causes a handshake packet to be
76 generated. This type of packet is sent as soon as peers are connected
77 and requires two additional keys:
78
79 * info_hash
80 The hash found in the ".torrent" file that represents the download.
81
82 * peer_id
83 The peer ID for the local peer. This should be the same as what is
84 reported to the tracker for the swarm.
85
86 BT_CHOKE
87 Passing the "BT_CHOKE" code causes a choke packet to be generated. This
88 type of packet requires no additional data and therefore no additional
89 arguments.
90
91 BT_UNCHOKE
92 Passing the "BT_UNCHOKE" code causes an unchoke packet to be generated.
93 This type of packet requires no additional data and therefore no
94 additional arguments.
95
96 BT_INTERESTED
97 Passing the "BT_INTERESTED" code causes an interested packet to be
98 generated. This type of packet requires no additional data and therefore
99 no additional arguments.
100
101 BT_UNINTERESTED
102 Passing the "BT_UNINTERESTED" code causes an uninterested packet to be
103 generated. This type of packet requires no additional data and therefore
104 no additional arguments.
105
106 BT_HAVE
107 Passing the "BT_HAVE" code causes a have packet to be generated. This
108 type of packet requires a piece index in addition to the BT code.
109
110 piece_index
111 The piece index is the zero-based numeric index of a piece within a
112 torrent.
113
114 BT_BITFIELD
115 Passing the "BT_BITFIELD" code causes a bit field packet to be
116 generated. This type of packet requires the bit field be specified in
117 addition to the BT code.
118
119 bitfield_ref
120 The bit field is passed in as a reference to a scalar. The scalar
121 contains binary data representing the pieces that are present and
122 missing.
123
124 BT_REQUEST
125 Passing the "BT_REQUEST" code causes a request packet to be generated.
126 This type of packet requires the piece index along with block offset and
127 size in addition to the BT code.
128
129 piece_index
130 The piece index is the zero-based numeric index of a piece within a
131 torrent.
132
133 block_offset
134 The block offset is the zero-based byte offset of the requested data
135 within the specified piece.
136
137 block_size
138 The block size is the size of the data requested. Be sure not to set
139 this value too large, as some clients will end your connection if
140 your request is too big.
141
142 BT_PIECE
143 Passing the "BT_PIECE" code causes a piece packet to be generated. This
144 type of packet requires the piece index along with block offset and the
145 data to be transferred in addition to the BT code.
146
147 piece_index
148 The piece index is the zero-based numeric index of a piece within a
149 torrent.
150
151 block_offset
152 The block offset is the zero-based byte offset of the requested data
153 within the specified piece.
154
155 data_ref
156 The data reference is a reference to a scalar containing the data at
157 the specified block offset within the specified piece.
158
159 BT_CANCEL
160 Passing the "BT_CANCEL" code causes a cancel packet to be generated.
161 This type of packet requires the piece index along with block offset and
162 size in addition to the BT code.
163
164 piece_index
165 The piece index is the zero-based numeric index of a piece within a
166 torrent.
167
168 block_offset
169 The block offset is the zero-based byte offset of the requested data
170 within the specified piece.
171
172 block_size
173 The block size is the size of the data requested. Be sure not to set
174 this value too large, as some clients will end your connection if
175 your request is too big.
176
177 bt_parse_packet
178 This subroutine is responsible for parsing all types of BitTorrent
179 packets. It accepts a single argument, which is a reference to a scalar
180 that contains the raw packet data. It returns a hash reference
181 containing the parsed data.
182
183 Depending on the packet type, the keys in the returned hash vary. One
184 key that is common to all packets is the bt_code. The bt_code maps to a
185 BT_ constant exported by this module and reveals the type of packet that
186 was parsed.
187
188 What follows is a list of the different BT codes that might be returned
189 and the additional keys that will be packaged with each code.
190
191 BT_CHOKE
192 The resultant hash from a choke packet will only contain the "bt_code"
193 key.
194
195 BT_UNCHOKE
196 The resultant hash from an unchoke packet will only contain the
197 "bt_code" key.
198
199 BT_INTERESTED
200 The resultant hash from an interested packet will only contain the
201 "bt_code" key.
202
203 BT_UNINTERESTED
204 The resultant hash from an uninterested packet will only contain the
205 "bt_code" key.
206
207 BT_HAVE
208 The resultant hash from a have packet will only contain the "bt_code"
209 key and the following additional keys.
210
211 piece_index
212 The piece index is the zero-based numeric index of a piece within a
213 torrent.
214
215 BT_BITFIELD
216 The resultant hash from a bit field packet will only contain the
217 "bt_code" key and the following additional keys.
218
219 bitfield_ref
220 The bit field is passed in as a reference to a scalar. The scalar
221 contains binary data representing the pieces that are present and
222 missing.
223
224 BT_REQUEST
225 The resultant hash from a request packet will only contain the "bt_code"
226 key and the following additional keys.
227
228 piece_index
229 The piece index is the zero-based numeric index of a piece within a
230 torrent.
231
232 block_offset
233 The block offset is the zero-based byte offset of the requested data
234 within the specified piece.
235
236 block_size
237 The block size is the size of the data requested. Be sure not to set
238 this value too large, as some clients will end your connection if
239 your request is too big.
240
241 BT_PIECE
242 The resultant hash from a piece packet will only contain the "bt_code"
243 key and the following additional keys.
244
245 piece_index
246 The piece index is the zero-based numeric index of a piece within a
247 torrent.
248
249 block_offset
250 The block offset is the zero-based byte offset of the requested data
251 within the specified piece.
252
253 data_ref
254 The data reference is a reference to a scalar containing the data at
255 the specified block offset within the specified piece.
256
257 BT_CANCEL
258 The resultant hash from a cancel packet will only contain the "bt_code"
259 key and the following additional keys.
260
261 piece_index
262 The piece index is the zero-based numeric index of a piece within a
263 torrent.
264
265 block_offset
266 The block offset is the zero-based byte offset of the requested data
267 within the specified piece.
268
269 block_size
270 The block size is the size of the data requested. Be sure not to set
271 this value too large, as some clients will end your connection if
272 your request is too big.
273
274INSTALL
275 perl Build.PL
276 ./Build
277 ./Build test
278 ./Build install
279
280AUTHOR
281 Josh McAdams <joshua dot mcadams at gmail dot com>
282
283