1bee(n)                            BitTorrent                            bee(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       bee - BitTorrent Serialization Format Encoder/Decoder
9

SYNOPSIS

11       package require Tcl  8.4
12
13       package require bee  ?0.1?
14
15       ::bee::encodeString string
16
17       ::bee::encodeNumber integer
18
19       ::bee::encodeListArgs value...
20
21       ::bee::encodeList list
22
23       ::bee::encodeDictArgs key value...
24
25       ::bee::encodeDict dict
26
27       ::bee::decode string ?endvar? ?start?
28
29       ::bee::decodeIndices string ?endvar? ?start?
30
31       ::bee::decodeChannel chan -command cmdprefix ?-exact? ?-prefix data?
32
33       cmdprefix eof token
34
35       cmdprefix error token message
36
37       cmdprefix value token value
38
39       ::bee::decodeCancel token
40
41       ::bee::decodePush token string
42
43_________________________________________________________________
44

DESCRIPTION

46       The bee package provides de- and encoder commands for data in bencoding
47       (speak 'bee'), the serialization format for data and messages  used  by
48       the BitTorrent application.
49

PUBLIC API

51   ENCODER
52       The  package  provides one encoder command for each of the basic forms,
53       and two commands per container, one taking a proper tcl data  structure
54       to  encode  in  the container, the other taking the same information as
55       several arguments.
56
57       ::bee::encodeString string
58              Returns the bee-encoding of the string.
59
60       ::bee::encodeNumber integer
61              Returns the bee-encoding of the integer number.
62
63       ::bee::encodeListArgs value...
64              Takes zero or more bee-encoded values and returns the bee-encod‐
65              ing of their list.
66
67       ::bee::encodeList list
68              Takes  a list of bee-encoded values and returns the bee-encoding
69              of the list.
70
71       ::bee::encodeDictArgs key value...
72              Takes zero or more pairs of keys and values and returns the bee-
73              encoding of the dictionary they form. The values are expected to
74              be already bee-encoded, but the keys must not be. Their encoding
75              will be done by the command itself.
76
77       ::bee::encodeDict dict
78              Takes  a  dictionary  list of string keys and bee-encoded values
79              and returns the bee-encoding of the list. Note that the keys  in
80              the  input must not be bee-encoded already. This will be done by
81              the command itself.
82
83   DECODER
84       The package provides two main decoder  commands,  one  for  decoding  a
85       string expected to contain a complete data structure, the other for the
86       incremental decoding of bee-values arriving on a  channel.  The  latter
87       command  is  asynchronous  and provides the completed decoded values to
88       the user through a command callback.
89
90       ::bee::decode string ?endvar? ?start?
91              Takes the bee-encoding in the string  and  returns  one  decoded
92              value.  In the case of this being a container all contained val‐
93              ues are decoded recursively as well and the result is a properly
94              nested tcl list and/or dictionary.
95
96              If  the optional endvar is set then it is the name of a variable
97              to store the index of the  first  character  after  the  decoded
98              value into. In other words, if the string contains more than one
99              value then endvar can be used to obtain the position of the bee-
100              value  after  the  bee-value  currently  decoded.  together with
101              start, see below, it is possible to iterate over the  string  to
102              extract all contained values.
103
104              The  optional  start  index defaults to 0, i.e. the beginning of
105              the string. It is the index of the first character of  the  bee-
106              encoded value to extract.
107
108       ::bee::decodeIndices string ?endvar? ?start?
109              Takes  the  same arguments as ::bee::decode and returns the same
110              information in endvar. The result however is different.  Instead
111              of  the  tcl  value  contained  in  the string it returns a list
112              describing the value with respect to type and location  (indices
113              for the first and last character of the bee-value). In case of a
114              container the structure also contains the same  information  for
115              all the embedded values.
116
117              Formally the results for the various types of bee-values are:
118
119              string A list containing three elements:
120
121                     ·      The  constant  string string, denoting the type of
122                            the value.
123
124                     ·      An integer number greater than or equal  to  zero.
125                            This  is  the  index of the first character of the
126                            bee-value in the input string.
127
128                     ·      An integer number greater than or equal  to  zero.
129                            This  is  the  index  of the last character of the
130                            bee-value in the input string.
131
132              Note that this information is present in  the  results  for  all
133              four  types  of bee-values, with only the first element changing
134              according to the type of the value.
135
136              integer
137                     The result is like for strings, except that the type ele‐
138                     ment contains the constant string integer.
139
140              list   The  result is like before, with two exceptions: One, the
141                     type element contains the constant string list. And  two,
142                     the result actually contains four elements. The last ele‐
143                     ment is new, and contains the  index  data  as  described
144                     here for all elements of the bee-list.
145
146              dictionary
147                     The result is like for strings, except that the type ele‐
148                     ment contains the constant string dict. A fourth  element
149                     is  present  as well, with a slightly different structure
150                     than for lists. The element is a dictionary mapping  from
151                     the strings keys of the bee-dictionary to a list contain‐
152                     ing two elements. The first of them is the index informa‐
153                     tion  for  the  key,  and the second element is the index
154                     information for the value the key maps to. This structure
155                     is  the  only  which  contains  not  only index data, but
156                     actual values from the bee-string. While the index infor‐
157                     mation  of the keys is unique enough, i.e. serviceable as
158                     keys, they are not easy to navigate when trying  to  find
159                     particular element. Using the actual keys makes this much
160                     easier.
161
162
163       ::bee::decodeChannel chan -command cmdprefix ?-exact? ?-prefix data?
164              The command creates a decoder for a series of bee-values  arriv‐
165              ing  on the channel chan and returns its handle. This handle can
166              be used to remove the decoder again.   Setting  up  another  bee
167              decoder  on  chan  while a bee decoder is still active will fail
168              with an error message.
169
170
171              -command
172                     The command prefix cmdprefix specified  by  the  required
173                     option  -command  is  used to report extracted values and
174                     exceptional situations (error, and EOF on  the  channel).
175                     The  callback will be executed at the global level of the
176                     interpreter, with two or three arguments. The exact  call
177                     signatures are
178
179
180                     cmdprefix eof token
181                            The  decoder  has reached eof on the channel chan.
182                            No further invocations of  the  callback  will  be
183                            made  after  this.  The  channel  has already been
184                            closed at the time of the call, and the  token  is
185                            not valid anymore as well.
186
187                     cmdprefix error token message
188                            The  decoder  encountered  an  error, which is not
189                            eof. For example a malformed bee-value.  The  mes‐
190                            sage provides details about the error. The decoder
191                            token is in  the  same  state  as  for  eof,  i.e.
192                            invalid. The channel however is kept open.
193
194                     cmdprefix value token value
195                            The  decoder  received  and successfully decoded a
196                            bee-value.  The format of the equivalent tcl value
197                            is  the  same  as  returned  by ::bee::decode. The
198                            channel is still open and  the  decoder  token  is
199                            valid.  This  means  that  the callback is able to
200                            remove the decoder.
201
202
203              -exact By default the decoder assumes that the remainder of  the
204                     data  in  the  channel  consists  only of bee-values, and
205                     reads as much as possible per event, without  regard  for
206                     boundaries between bee-values. This means that if the the
207                     input contains non-bee data after a series  of  bee-value
208                     the  beginning  of  that  data may be lost because it was
209                     already read by the decoder, but not processed.
210
211                     The -exact was made for this  situation.  When  specified
212                     the  decoder  will  take  care to not read any characters
213                     behind the currently processed  bee-value,  so  that  any
214                     non-bee  data is kept in the channel for further process‐
215                     ing after removal of the decoder.
216
217
218              -prefix
219                     If this option is specified its value is  assumed  to  be
220                     the beginning of the bee-value and used to initialize the
221                     internal decoder buffer. This feature is required if  the
222                     creator  of  the  decoder  used  data from the channel to
223                     determine if it should create the decoder or not. Without
224                     the option this data would be lost to the decoding.
225
226
227       ::bee::decodeCancel token
228              This  command cancels the decoder set up by ::bee::decodeChannel
229              and represented by the handle token.
230
231       ::bee::decodePush token string
232              This command appends the string to the internal decoder  buffer.
233              It   is   the  runtime  equivalent  of  the  option  -prefix  of
234              ::bee::decodeChannel. Use it to push data back into the  decoder
235              when  the value callback used data from the channel to determine
236              if it should decode another bee-value or not.
237

FORMAT DEFINITION

239       Data in the bee serialization format  is  constructed  from  two  basic
240       forms, and two container forms. The basic forms are strings and integer
241       numbers, and the containers are lists and dictionaries.
242
243       String S
244              A string S of length L is encoded by the string "L:S", where the
245              length is written out in textual form.
246
247       Integer N
248              An integer number N is encoded by the string "iNe".
249
250       List v1 ... vn
251              A  list  of  the  values  v1  to  vn  is  encoded  by the string
252              "lBV1...BVne" where "BVi" is the bee-encoding of the value "vi".
253
254       Dict k1 -> v1 ...
255              A dictionary mapping the string key ki to the value vi, for i in
256              1 ... n is encoded by the string "dBKiBVi...e" for i in 1 ... n,
257              where "BKi" is the bee-encoding of the  key  string  "ki".   and
258              "BVi" is the bee-encoding of the value "vi".
259
260              Note:  The bee-encoding does not retain the order of the keys in
261              the input, but stores in a sorted order. The sorting is done for
262              the "raw strings".
263
264       Note  that  the type of each encoded item can be determined immediately
265       from the first character of its representation:
266
267       i      Integer.
268
269       l      List.
270
271       d      Dictionary.
272
273       [0-9]  String.
274
275       By wrapping an integer number into i...e the  format  makes  sure  that
276       they are different from strings, which all begin with a digit.
277

EXAMPLES

BUGS, IDEAS, FEEDBACK

280       This  document,  and the package it describes, will undoubtedly contain
281       bugs and other problems.  Please report such in the category bee of the
282       Tcllib  SF  Trackers  [http://sourceforge.net/tracker/?group_id=12883].
283       Please also report any ideas for enhancements you may have  for  either
284       package and/or documentation.
285

KEYWORDS

287       BitTorrent, bee, bittorrent, serialization, torrent
288
290       Copyright (c) 2004 Andreas Kupries <andreas_kupries@users.sourceforge.net>
291
292
293
294
295bee                                   0.1                               bee(n)
Impressum