BearHopsFlow - BEAR4v1
         +---------------+
 bytes   +       0       +
         +---------------+
 value   +    maxHops    +
         +---------------+

A Hops flow message is sent from leaf to ultrapeer, with maxHops indicating
the maximum number of hops for messages we wish to see.  This is used
primarily as a leaf <-> UP flow control mechanism.




BearHorizonPing - BEAR5v1
         +---------------+
 bytes   +       0       +
         +---------------+
 value   +      ttl      +
         +---------------+

A Horizon Ping message is sent to all neighbor peers or ultrapeers initially
upon connection, and once every 120 seconds thereafter.  The TTL indicates the
maximum node distance from you that you wish to receive info about.  This
should generally be the same as your current broadcast query TTL.  This should 
never be sent to a leaf, and will not be processed or responded to if sent to
one.




BearHorizonPong - BEAR6v1|=========================REPEAT ttl TIMES=======================~~
         +---------------+-------------------------------+-------------------------------+~~
 bytes   +       0       +       1       |       4       +       5       |       8       +~~
         +---------------+-------------------------------+-------------------------------+~~
 value   +      ttl      +           nSharing            +           nFreePeers          +~~
         +---------------+-------------------------------+-------------------------------+~~
             ~~========REPEAT ttl TIMES========|
             ~~+-------------------------------+
             ~~+       9       |      12       +
             ~~+-------------------------------+
             ~~+        nAuthenticated         +
             ~~+-------------------------------+

A Horizon pong is sent to a peer or leaf in response to received Horizon Ping
message, or can be sent unsolicited by UltraPeers.  This message contains the
number of *directly* counted sharing nodes, BearShare nodes, and BearShare
nodes with Authentication.  This does *not* include results received from other
Horizon Pongs.  When displaying this value to the user, however, all available
values are added, and the max between this sum and the counted nodes is
actually displayed.  It is very important to not add values before sending them
in Horizon Pongs, though, or the count will be wildly inaccurate.

The nSharing field will be the useful field for other vendors.  A planned
future enhancement will make this message more vendor-independent.

Data is packed into this message in the order of hops=0, hops=1, ..., hops=(ttl
from horizon ping)




BearConnectBack - BEAR7v1
         +-------------------------------+
 bytes   +       0       |       1       +
         +-------------------------------+
 value   +          listenPort           +
         +-------------------------------+

The ConnectBack message is sent to determine the ability of our node to receive
incoming connections.  It includes the listening port to attempt to connect
to.  Upon receipt of this message, a node will immediately try to open a
connection to our IP, using the listenPort specified.  BearShare will use this
once per hour to re-test firewalled status if it has not received an incoming
connection on listenPort within that hour.




BearUltraPing - BEAR9v1
         +---------------+---------------+-------------------------------+~~
 bytes   +       0       +       1       +       2       |       5       +~~
         +---------------+---------------+-------------------------------+~~
 value   +    maxAddr    +    minHops    +         anyFlagsMask          +~~
         +---------------+---------------+-------------------------------+~~
             ~~+-------------------------------+
             ~~+       6       |       9       +
             ~~+-------------------------------+
             ~~+         allFlagsMask          +
             ~~+-------------------------------+

UltraPing messages are sent when we want to receive a set of IP addresses which
meet certain criteria.  We will receive up to maxAddr addresses, all at least
minHops away from the node we sent the UltraPing to.  For a node to be returned
to us, it must meet at least one of the anyFlagsMask criteria and all of the
allFlagsMask criteria. 

BearShare will only send and respond to UltraPings and UltraPongs from other
Authenticated BearShares.




BearUltraPong - BEAR8v1  |=======================================REPEAT nITEMS TIMES======~~
         +---------------+-------------------------------+-------------------------------+~~
 bytes   +       0       +       1       |       4       +       5       |       6       +~~
         +---------------+-------------------------------+-------------------------------+~~
 value   +    nItems     +               IP              +             port              +~~
         +---------------+-------------------------------+-------------------------------+~~
             ~~=============REPEAT nITEMS TIMES================|
             ~~+---------------+-------------------------------+
             ~~+       7       +       8       |       11      +
             ~~+---------------+-------------------------------+
             ~~+     hops      +             Flags             +
             ~~+---------------+-------------------------------+

UltraPong messages are sent in response to a received UltraPing message, or are
sent unsolicited at regular intervals to leaves.  They contain information on
nItems distinct nodes.  Each entry will contain the IP and port, as well as the
hops count from the source node, and the Flags representing the connect/accept
status of that node.


BearUltraPing/BearUltraPong Flags

The bitfield 'Flags' can be any combination (bitwise OR) of these values:
FlagNone         0x00
FlagFreePeerSlot 0x01
FlagFreeLeafSlot 0x02
FlagBearShare    0x04
FlagUltraPeer    0x08
FlagAll          0xFF




BearChat - BEAR10v1
         +-------------------------------+-------------------------------~~
 bytes   +       0       |       1       +       2       |       5       ~~
         +-------------------------------+-------------------------------~~
 value   +            command            +           srcUserID           ~~
         +-------------------------------+-------------------------------~~
             ~~+-------------------------------+-------------------------------+~~
             ~~+       6       |       9       +       10      |        13     +~~
             ~~+-------------------------------+-------------------------------+~~
             ~~+          destUserID           +           lenGGEP1            +~~
             ~~+-------------------------------+-------------------------------+~~
                 ~~+-------------------------------+-------------------------------+~~
                 ~~+       14      |        17     +        18     |        21     +~~
                 ~~+-------------------------------+-------------------------------+~~
                 ~~+           lenGGEP2            +            Reserved           +~~
                 ~~+-------------------------------+-------------------------------+~~
                     ~~+-------------------------------+--------------------------------------+
                     ~~+       22      |  22+lenGGEP1  +  23+lenGGEP1  | 23+lenGGEP1+lenGGEP2 +
                     ~~+-------------------------------+--------------------------------------+
                     ~~+   GGEP Block 1:CLIENT block   +       GGEP Block 2:SERVER block      +
                     ~~+-------------------------------+--------------------------------------+

Chat messages are divided into 2 separate GGEP blocks; Client block and Server
block.  Each block is GGEPed with one or more 'Key/Value' pairs.

BearChat Commands
  NAME           VALUE    USAGE
--------         -----    -----
cmdConnect         1      Connect client to server
cmdDisconnect      2      Disconnect client if sent to server, remove user srcUserID if sent to client
cmdInsertUser      3      Sent to client to add a user to userlist
cmdInsertYou       4      Sent to client to add themselves to userlist
cmdMsg             5      Contains text to send
cmdNick            6      Unused/reserved
cmdIdle            7      Set or Clear Idle flag for srcUserID
cmdInfo            8      Request user/server info
cmdKick            9      Remove user that is sent this message from chat server



BearChat GGEP Client Block Data

  NAME                     KEY    VALUE      USAGE
--------                  -----   -----      -----
C_UNUSED                  "CU"    NULL       Must be present in an otherwise empty GGEP Client block
C_NICK                    "CN"    Text       Desired UserName, used on connect
C_MSG                     "CM"    Text       Text to send to other chatters, destUserID set to whisper
C_IDLE                    "CI"    NULL       During cmdIdle, set/clear idle flag if field is/isn't present
C_INFO                    "C?"    NULL       Must be present in cmdIdle command, set destUserID to 
                                               desired UserID or 0 for chat server info 
C_INFO_AIM                "CIA"   Text       Used on connect, contains AIM username
C_INFO_YIM                "CIY"   Text       Used on connect, contains Yahoo IM username
C_INFO_MSN                "CIM"   Text       Used on connect, contains MSN IM username
C_INFO_ICQ                "CII"   Text       Used on connect, contains ICQ IM number
C_INFO_EMAIL              "CIE"   Text       Used on connect, contains user's email address
C_INFO_GUID               "CIG"   Binary     Used on connect, contains GUID for pushes
C_INFO_IP                 "CIP"   Long Int   Used on connect, contains user's IP address
C_INFO_PORT               "CIL"   Long Int   Used on connect, contains user's listening port
C_INFO_FIREWALLED         "CIF"   NULL       Used on connect, user is firewalled if field present
C_INFO_FILES_SHARED       "CIS"   Long Int   Used on connect, contains number of shared files
C_INFO_FILES_BYTES_DOUBLE "CID"   Double     Used on connect, contains number of bytes shared



BearChat GGEP Server Block Data

  NAME                     KEY    VALUE      USAGE
--------                  -----   -----      -----
S_UNUSED                  "SU"    NULL       Must be present in an otherwise empty GGEP Server block
S_NICK                    "SN"    Text       Username granted to user by server
S_PREV_NICK               "SP"    Text       Username rejected by server
S_MSG                     "SM"    Text       Text to be displayed, from srcUserID.  Whispered privately 
                                               to destUserID if destUserID is nonzero
S_IDLE                    "SI"    NULL       During cmdIdle, set/clear idle flag if field is/isn't present
S_INFO                    "S?"    NULL       Unused - reserved
S_INFO_USERS_ACTIVE       "SIA"   Long Int   Contains number of active, non-idle users
S_INFO_USERS_IDLE         "SII"   Long Int   Contains number of idle, non-active users
S_INFO_RECENT_MSGS        "SIM"   Long Int   Contains number of messages sent via chat, up to 3 million
S_INFO_RECENT_UPTIME      "SIU"   Long Int   Contains number of seconds since chat server started


All LongInt values are in Network byte order when GGEPed.
