Страницы справочника OS X

Эта страница руководства для  версии 10.9 Mac OS X

Читать страницы руководства

bee(n)                                           BitTorrent                                           bee(n)



____________________________________________________________________________________________________________

NAME
       bee - BitTorrent Serialization Format Encoder/Decoder

SYNOPSIS
       package require Tcl  8.4

       package require bee  ?0.1?

       ::bee::encodeString string

       ::bee::encodeNumber integer

       ::bee::encodeListArgs value...

       ::bee::encodeList list

       ::bee::encodeDictArgs key value...

       ::bee::encodeDict dict

       ::bee::decode string ?endvar? ?start?

       ::bee::decodeIndices string ?endvar? ?start?

       ::bee::decodeChannel chan -command cmdprefix ?-exact? ?-prefix data?

       cmdprefix eof token

       cmdprefix error token message

       cmdprefix value token value

       ::bee::decodeCancel token

       ::bee::decodePush token string

____________________________________________________________________________________________________________

DESCRIPTION
       The bee package provides de- and encoder commands for data in bencoding (speak 'bee'), the serializa-tion serialization
       tion format for data and messages used by the BitTorrent application.


PUBLIC API
   ENCODER
       The package provides one encoder command for each of the basic forms, and two commands per container,
       one taking a proper tcl data structure to encode in the container, the other taking the same informa-tion information
       tion as several arguments.


       ::bee::encodeString string
              Returns the bee-encoding of the string.

       ::bee::encodeNumber integer
              Returns the bee-encoding of the integer number.

       ::bee::encodeListArgs value...
              Takes zero or more bee-encoded values and returns the bee-encoding of their list.

       ::bee::encodeList list
              Takes a list of bee-encoded values and returns the bee-encoding of the list.

       ::bee::encodeDictArgs key value...
              Takes zero or more pairs of keys and values and returns the  bee-encoding  of  the  dictionary
              they  form. The values are expected to be already bee-encoded, but the keys must not be. Their
              encoding will be done by the command itself.

       ::bee::encodeDict dict
              Takes a dictionary list of string keys and bee-encoded values and returns the bee-encoding  of
              the  list.  Note that the keys in the input must not be bee-encoded already. This will be done
              by the command itself.



   DECODER
       The package provides two main decoder commands, one for decoding a string expected to contain a  com-plete complete
       plete data structure, the other for the incremental decoding of bee-values arriving on a channel. The
       latter command is asynchronous and provides the completed decoded values to the user through  a  com-mand command
       mand callback.


       ::bee::decode string ?endvar? ?start?
              Takes  the bee-encoding in the string and returns one decoded value. In the case of this being
              a container all contained values are decoded recursively as well and the result is a  properly
              nested tcl list and/or dictionary.

              If  the  optional  endvar  is  set then it is the name of a variable to store the index of the
              first character after the decoded value into. In other words, if the string contains more than
              one  value then endvar can be used to obtain the position of the bee-value after the bee-value
              currently decoded. together with start, see below, it is possible to iterate over  the  string
              to extract all contained values.

              The  optional  start index defaults to 0, i.e. the beginning of the string. It is the index of
              the first character of the bee-encoded value to extract.

       ::bee::decodeIndices string ?endvar? ?start?
              Takes the same arguments as ::bee::decode and returns the  same  information  in  endvar.  The
              result  however  is  different.  Instead of the tcl value contained in the string it returns a
              list describing the value with respect to type and location (indices for the  first  and  last
              character  of  the  bee-value).  In  case  of a container the structure also contains the same
              information for all the embedded values.

              Formally the results for the various types of bee-values are:

              string A list containing three elements:

                     •      The constant string string, denoting the type of the value.

                     •      An integer number greater than or equal to zero. This is the index of the  first
                            character of the bee-value in the input string.

                     •      An  integer  number greater than or equal to zero. This is the index of the last
                            character of the bee-value in the input string.

              Note that this information is present in the results for all four types  of  bee-values,  with
              only the first element changing according to the type of the value.

              integer
                     The  result  is  like  for  strings, except that the type element contains the constant
                     string integer.

              list   The result is like before, with two exceptions: One, the type element contains the con-stant constant
                     stant  string  list. And two, the result actually contains four elements. The last ele-ment element
                     ment is new, and contains the index data as described here for all elements of the bee-list. beelist.
                     list.

              dictionary
                     The  result  is  like  for  strings, except that the type element contains the constant
                     string dict. A fourth element is present as well, with a slightly  different  structure
                     than  for  lists. The element is a dictionary mapping from the strings keys of the bee-dictionary beedictionary
                     dictionary to a list containing two elements. The first of them is the  index  informa-tion information
                     tion for the key, and the second element is the index information for the value the key
                     maps to. This structure is the only which contains not only index data, but actual val-ues values
                     ues from the bee-string. While the index information of the keys is unique enough, i.e.
                     serviceable as keys, they are not easy to navigate when trying to find particular  ele-ment. element.
                     ment. Using the actual keys makes this much easier.


       ::bee::decodeChannel chan -command cmdprefix ?-exact? ?-prefix data?
              The  command  creates  a  decoder  for a series of bee-values arriving on the channel chan and
              returns its handle. This handle can be used to remove the decoder again.  Setting  up  another
              bee decoder on chan while a bee decoder is still active will fail with an error message.


              -command
                     The  command  prefix  cmdprefix  specified  by  the required option -command is used to
                     report extracted values and exceptional situations (error, and  EOF  on  the  channel).
                     The callback will be executed at the global level of the interpreter, with two or three
                     arguments. The exact call signatures are


                     cmdprefix eof token
                            The decoder has reached eof on the channel chan. No further invocations  of  the
                            callback  will  be  made  after this. The channel has already been closed at the
                            time of the call, and the token is not valid anymore as well.

                     cmdprefix error token message
                            The decoder encountered an error, which is not eof. For example a malformed bee-value. beevalue.
                            value. The message provides details about the error. The decoder token is in the
                            same state as for eof, i.e. invalid. The channel however is kept open.

                     cmdprefix value token value
                            The decoder received and successfully decoded a bee-value.  The  format  of  the
                            equivalent  tcl  value  is the same as returned by ::bee::decode. The channel is
                            still open and the decoder token is valid. This means that the callback is  able
                            to remove the decoder.


              -exact By  default  the decoder assumes that the remainder of the data in the channel consists
                     only of bee-values, and reads as much as possible per event, without regard for  bound-aries boundaries
                     aries  between bee-values. This means that if the the input contains non-bee data after
                     a series of bee-value the beginning of that data may be lost  because  it  was  already
                     read by the decoder, but not processed.

                     The  -exact  was  made for this situation. When specified the decoder will take care to
                     not read any characters behind the currently processed bee-value, so that  any  non-bee
                     data is kept in the channel for further processing after removal of the decoder.


              -prefix
                     If  this  option is specified its value is assumed to be the beginning of the bee-value
                     and used to initialize the internal decoder buffer. This feature  is  required  if  the
                     creator  of the decoder used data from the channel to determine if it should create the
                     decoder or not. Without the option this data would be lost to the decoding.


       ::bee::decodeCancel token
              This command cancels the decoder set up by ::bee::decodeChannel and represented by the  handle
              token.

       ::bee::decodePush token string
              This  command  appends the string to the internal decoder buffer. It is the runtime equivalent
              of the option -prefix of ::bee::decodeChannel. Use it to push data back into the decoder  when
              the  value  callback  used data from the channel to determine if it should decode another bee-value beevalue
              value or not.



FORMAT DEFINITION
       Data in the bee serialization format is constructed from two basic forms, and  two  container  forms.
       The basic forms are strings and integer numbers, and the containers are lists and dictionaries.


       String S
              A string S of length L is encoded by the string "L:S", where the length is written out in tex-tual textual
              tual form.

       Integer N
              An integer number N is encoded by the string "iNe".

       List v1 ... vn
              A list of the values v1 to vn is encoded by the string "lBV1...BVne" where "BVi" is  the  bee-encoding beeencoding
              encoding of the value "vi".

       Dict k1 -> v1 ...
              A  dictionary  mapping  the  string key ki to the value vi, for i in 1 ... n is encoded by the
              string "dBKiBVi...e" for i in 1 ... n, where "BKi" is the bee-encoding of the key string "ki".
              and "BVi" is the bee-encoding of the value "vi".

              Note:  The  bee-encoding  does  not retain the order of the keys in the input, but stores in a
              sorted order. The sorting is done for the "raw strings".


       Note that the type of each encoded item can be determined immediately from the first character of its
       representation:


       i      Integer.

       l      List.

       d      Dictionary.

       [0-9]  String.


       By  wrapping an integer number into i...e the format makes sure that they are different from strings,
       which all begin with a digit.

EXAMPLES
BUGS, IDEAS, FEEDBACK
       This document, and the package it describes,  will  undoubtedly  contain  bugs  and  other  problems.
       Please   report   such   in   the   category   bee   of   the   Tcllib  SF  Trackers  [http://source -
       forge.net/tracker/? group_id=12883].  Please also report any ideas for enhancements you may  have  for
       either package and/or documentation.

KEYWORDS
       BitTorrent, bee, bittorrent, serialization, torrent

CATEGORY
       Networking

COPYRIGHT
       Copyright (c) 2004 Andreas Kupries <andreas_kupries@users.sourceforge.net>




bee                                                  0.1                                              bee(n)