NAME
      Net::BitTorrent::PeerPacket - Parse/Build Peer Packets from BitTorrent

SYNOPSIS
      # Encode a packet
      my $binary_packet = bt_build_packet($hash_reference);

      # Decode a packet
      my $parsed_packet = bt_parse_packet($binary_data);

DESCRIPTION
    "Net::BitTorrent::PeerPacket" handles parsing and building binary data
    shared between BitTorrent peers. The module optinally exports a single
    subroutine for building packets and another for parsing packets, as well
    as, a constant for each packet type defined by BitTorrent.

CONSTANTS
    There are nine primary types of packets that are shared between peers on
    a BitTorrent network. The following constants are how the type of packet
    being build/parsed are represented within this module.

    BT_CHOKE
    BT_UNCHOKE
    BT_INTERESTED
    BT_UNINTERESTED
    BT_HAVE
    BT_BITFIELD
    BT_REQUEST
    BT_PIECE
    BT_CANCEL

SUBROUTINES
  bt_build_packet
    This subroutine is responsible for building all types of BitTorrent
    packets. The arguments are passed into the subroutine as a list of
    key-value pairs. The resultant packet is sent back as a scalar.

    Depending on the requested packet type, the required arguments vary. One
    argument that is common to all calls is the bt_code. The bt_code maps to
    a BT_ constant exported by this module and determines the type of packet
    that will be built.

    What follows is a list of the different BT codes and the details of
    calling this subroutine with those codes.

   BT_CHOKE
    Passing the BT_CHOKE code causes a choke packet to be generated. This
    type of packet requires no additional data and therefore no additional
    arguments.

   BT_UNCHOKE
    Passing the BT_UNCHOKE code causes an unchoke packet to be generated.
    This type of packet requires no additional data and therefore no
    additional arguments.

   BT_INTERESTED
    Passing the BT_INTERESTED code causes an interested packet to be
    generated. This type of packet requires no additional data and therefore
    no additional arguments.

   BT_UNINTERESTED
    Passing the BT_UNINTERESTED code causes an uninterested packet to be
    generated. This type of packet requires no additional data and therefore
    no additional arguments.

   BT_HAVE
    Passing the BT_HAVE code causes a have packet to be generated. This type
    of packet requires a piece index in addition to the BT code.

    piece_index
        The piece index is the zero-based numeric index of a piece within a
        torrent.

   BT_BITFIELD
    Passing the BT_BITFIELD code causes a bit field packet to be generated.
    This type of packet requires the bit field be specified in addition to
    the BT code.

    bitfield_ref
        The bit field is passed in as a reference to a scalar. The scalar
        contains binary data representing the pieces that are present and
        missing.

   BT_REQUEST
    Passing the BT_REQUEST code causes a request packet to be generated.
    This type of packet requires the piece index along with block offset and
    size in addition to the BT code.

    piece_index
        The piece index is the zero-based numeric index of a piece within a
        torrent.

    block_offset
        The block offset is the zero-based byte offset of the requested data
        within the specified piece.

    block_size
        The block size is the size of the data requested. Be sure not to set
        this value too large, as some clients will end your connection if
        your request is too big.

   BT_PIECE
    Passing the BT_PIECE code causes a piece packet to be generated. This
    type of packet requires the piece index along with block offset and the
    data to be transfered in addition to the BT code.

    piece_index
        The piece index is the zero-based numeric index of a piece within a
        torrent.

    block_offset
        The block offset is the zero-based byte offset of the requested data
        within the specified piece.

    data_ref
        The data reference is a reference to a scalar containing the data at
        the specified block offset within the specified piece.

   BT_CANCEL
    Passing the BT_CANCEL code causes a cancel packet to be generated. This
    type of packet requires the piece index along with block offset and size
    in addition to the BT code.

    piece_index
        The piece index is the zero-based numeric index of a piece within a
        torrent.

    block_offset
        The block offset is the zero-based byte offset of the requested data
        within the specified piece.

    block_size
        The block size is the size of the data requested. Be sure not to set
        this value too large, as some clients will end your connection if
        your request is too big.

  bt_parse_packet
    This subroutine is responsible for parsing all types of BitTorrent
    packets. It accepts a single argument, which is a reference to a scalar
    that contains the raw packet data. It returns a hash reference
    containing the parsed data.

    Depending on the packet type, the keys in the returned hash vary. One
    key that is common to all packets is the bt_code. The bt_code maps to a
    BT_ constant exported by this module and reveals the type of packet that
    was parsed.

    What follows is a list of the different BT codes that might be returned
    and the additional keys that will be packaged with each code.

   BT_CHOKE
    The resultant hash from a choke packet will only contain the 'bt_code'
    key.

   BT_UNCHOKE
    The resultant hash from an unchoke packet will only contain the
    'bt_code' key.

   BT_INTERESTED
    The resultant hash from an interested packet will only contain the
    'bt_code' key.

   BT_UNINTERESTED
    The resultant hash from an uninterested packet will only contain the
    'bt_code' key.

   BT_HAVE
    The resultant hash from a have packet will only contain the 'bt_code'
    key and the following additional keys.

    piece_index
        The piece index is the zero-based numeric index of a piece within a
        torrent.

   BT_BITFIELD
    The resultant hash from a bit field packet will only contain the
    'bt_code' key and the following additional keys.

    bitfield_ref
        The bit field is passed in as a reference to a scalar. The scalar
        contains binary data representing the pieces that are present and
        missing.

   BT_REQUEST
    The resultant hash from a request packet will only contain the 'bt_code'
    key and the following additional keys.

    piece_index
        The piece index is the zero-based numeric index of a piece within a
        torrent.

    block_offset
        The block offset is the zero-based byte offset of the requested data
        within the specified piece.

    block_size
        The block size is the size of the data requested. Be sure not to set
        this value too large, as some clients will end your connection if
        your request is too big.

   BT_PIECE
    The resultant hash from a piece packet will only contain the 'bt_code'
    key and the following additional keys.

    piece_index
        The piece index is the zero-based numeric index of a piece within a
        torrent.

    block_offset
        The block offset is the zero-based byte offset of the requested data
        within the specified piece.

    data_ref
        The data reference is a reference to a scalar containing the data at
        the specified block offset within the specified piece.

   BT_CANCEL
    The resultant hash from a cancel packet will only contain the 'bt_code'
    key and the following additional keys.

    piece_index
        The piece index is the zero-based numeric index of a piece within a
        torrent.

    block_offset
        The block offset is the zero-based byte offset of the requested data
        within the specified piece.

    block_size
        The block size is the size of the data requested. Be sure not to set
        this value too large, as some clients will end your connection if
        your request is too big.

INSTALL
      perl Build.PL
      ./Build
      ./Build test
      ./Build install

AUTHOR
    Josh McAdams <joshua dot mcadams at gmail dot com>