docs/gnutella.txt

   1 (*
   2
   3 AS PRESENTED BY GNUCLEUS (BUT WE ARE IMPLEMENTING LIMEWIRE CURRENTLY !!!)
   4
   5 Gnutella Protocol : Connections
   6
   7    Connection is what make the gnutella network work. All data through
   8    the network flow through these connections. As a developer you strive
   9    to have a connection process that holds on to nodes for a long period
  10    of time and hence creating a stronger gnutella network as a whole.
  11
  12    Connecting Version 0.4
  13    This is the most typical way connections are made over gnutella. It is
  14    how all the clients have been connecting since the initial release of
  15    the 0.56 client by Nullsoft. Who ever initiates the connection sends
  16    this.
  17                           GNUTELLA CONNECT/0.4\n\n
  18    In response if the host accepts the connection it sends this. Right
  19    after the statement normal gnutella packet flow begins.
  20                           GNUTELLA OK\n\n
  21
  22    Connecting Version 0.6
  23    The new connect process is supported by most clients now and is
  24    backwards compatible with the old version 0.4 style. The main reason
  25    for this was to get more information out of the connect string, for
  26    debugging purposes and adding new features to the protocol. The client
  27    that initiates the connection sends this.
  28    GNUTELLA CONNECT/0.6\r\n
  29    User-Agent: Gnucleus 1.4.5.0\r\n
  30    \r\n
  31        In response, if the host accepts the connection it sends this.
  32    GNUTELLA/0.6 200 OK\r\n
  33    User-Agent: Gnucleus 1.4.5.2\r\n
  34    \r\n
  35    At this point the host that initiated the connection determines if it
  36    also accepts the connection based on the header information from the
  37    server. If all is a go it sends this and normal packet flow begins.
  38    GNUTELLA/0.6 200 OK\r\n
  39    \r\n
  40
  41
  42
  43
  44                         Gnutella Protocol : Packets
  45
  46    There are only five packet types that run over the network. Every
  47    packet has a header and payload, the last four bytes of the header
  48    describes the size of the payload in bytes.
  49    Network Byte Order (NBO) means for some reason the bytes are reversed.
  50    So before you use them in a variable reverse the order of the bytes.
  51    Same when you are building a packet, make sure the bytes are switched
  52    into NBO.
  53
  54    Packet Type
  55    Byte Description Value
  56
  57                                    Header
  58
  59                                   Payload
  60
  61    Size: Total packet size (bytes)
  62    Flow: Direction to send packet
  63
  64                Ping - Used to discover other hosts on network
  65                Byte    Description   Value
  66                0 - 15  GUID          Random 16 bytes
  67                16      Function      0x00 (hex), 0 (dec)
  68                17      TTL           7
  69                18      Hops          0
  70                19 - 22 Payload (NBO) 0
  71                Total Size: 23 bytes
  72                Flow: Broadcasted
  73
  74       Pong - Reply to a ping, contains info on host
  75       Byte    Description      Value
  76       0 - 15  GUID             GUID of the Ping being replied to
  77       16      Function         0x01 (hex), 1 (dec)
  78       17      TTL              Hops value of the Ping being replied to
  79       18      Hops             0
  80       19 - 22 Payload (NBO)    14
  81       23 - 24 Port             Port Client is listening on
  82       25 - 28 Host             Four byte IP address of Client
  83       29 - 32 File Count (NBO) Total number of files shared
  84       33 - 36 File Size (NBO)  Total size of files shared (kilobytes)
  85       Total Size: 37 bytes
  86       Flow: Routed
  87
  88
  89    Query - A file search
  90    Byte Description Value
  91    0 - 15 GUID Random 16 bytes
  92    16 Function 0x80 (hex), 128 (dec)
  93    17 TTL 7
  94    18 Hops 0
  95    19 - 22 Payload (NBO) Greater than 2 and less than 256
  96    23 - 24 Minimum Speed Minimum Speed Client must be to respond
  97    (kilobits)
  98    25 + Query Keywords being Searched for
  99    Total Size: 23 bytes + Payload
 100    Flow: Broadcasted
 101
 102    Query Hit - Reply to a file search, contains set of results
 103    Byte Description Value
 104    0 - 15 GUID GUID of the Query being replied to
 105    16 Function 0x81 (hex), 129 (dec)
 106    17 TTL Hops value of the Query being replied to
 107    18 Hops 0
 108    19 - 22 Payload (NBO) Greater than 26 and less than 65536
 109    23 Total Hits Number or results listed in packet
 110    24 - 25 Port Port Client is listening on
 111    26 - 29 Host Four byte IP address of Client
 112    30 - 33 Speed (NBO) Speed of client (kilobits)
 113    34 + Results Results one after the other, number of results should
 114    match the value of Total Hits
 115    Result
 116    Byte Description Value
 117    0 - 3 Index (NBO) Index of the file in the client
 118    4 - 7 Size (NBO) Size of the file (bytes)
 119    8 + Filename Name of the file, terminated by a NULL
 120    NULL - NULL Extended Data Results always end with two NULLs, sometimes
 121    there is extra data between them
 122    After Results QHD Query Hit Descriptor - Extended Client information
 123    QHD
 124    Byte Description Value
 125    0 - 3 Vendor Identifier A unique four character code identifying the
 126    vendor
 127    4 Public Sector Length 2 - Length of Public Sector (bytes)
 128    5, bit 0 Push Behind a firewall, dont bother connecting
 129    5, bit 1 Flag Bad A screw up, always set to 1
 130    5, bit 2 Flag Busy Value tells if busy bit is set
 131    5, bit 3 Flag Stable Value tells if stable bit is set
 132    5, bit 4 Flag Speed Value tells if speed bit is set
 133    5, bit 5 - 7 Unused Just set to all zeros
 134    6, bit 0 Flag Push Value tells if push bit is set
 135    6, bit 1 Bad A screw up, always set to 0
 136    6, bit 2 Busy Client is currently busy
 137    6, bit 3 Stable Client has successfully transmitted at least one
 138    upload
 139    6, bit 4 Speed Speed byte is set to maximum achieved speed during an
 140    upload
 141    6, bit 5 - 7 Unused Just set to all zeros
 142    variable Private Sector Used on a per vendor basis to send proprietary
 143    info
 144    last 16 Client GUID A Static random 16 bytes unique to each Gnutella
 145    Client
 146    Total Size: 23 bytes + Payload
 147    Flow: Routed
 148
 149    Push - Reply to a Query Hit from a client behind a firewall
 150    Byte Description Value
 151    0 - 15 GUID Random 16 bytes
 152    16 Function 0x40 (hex), 64 (dec)
 153    17 TTL Hops value of the Query Hit being replied to
 154    18 Hops 0
 155    19 - 22 Payload (NBO) 26
 156    23 - 38 Client GUID Client GUID from Query Hit packet
 157    39 - 42 Index (NBO) Index of file from Query Hit packet
 158    43 - 46 Host Four byte IP address of Client
 159    47 - 48 Port Port Client is listening on
 160    Total Size: 49 bytes
 161    Flow: Routed
 162
 163
 164                         Gnutella Protocol : Transfer
 165
 166    File transfers over Gnutella happen over a direct connection between
 167    two nodes. The syntax of the code is similar to HTTP, but is not
 168    actually to the standard. It has been modified slightly. Use the
 169    examples on this page as a guide.
 170    Gnutella also has a file transfer mechanism called 'push' to assist
 171    nodes behind firewalls share files. If you are unable to connect to a
 172    node to get a file, you can request the node to 'push' the file to you
 173    be connecting to you instead. Push does not work if both nodes are
 174    behind a firewall.
 175
 176    File Request
 177    On connect to the host you want to download from, you send the file
 178    request header. The first line is the GET statement, the number
 179    between the slashes is the index of the file from the query hit
 180    packet. Following that is the name of the file. The next line
 181    describes what client is requesting the file. The range statement
 182    tells the host what position in the file to start sending from in case
 183    the client is resuming the download. A new download starts at the
 184    postion of zero. Each line is terminated with a '\r\n' or in ASCII a
 185    '13,10' pair.
 186    GET /get/2975/How Towels Work.txt HTTP/1.0\r\n
 187    User-Agent: LimeWire 1.8\r\n
 188    Range: bytes=0-\r\n
 189    \r\n
 190
 191    Server Reply
 192    After the server receives the File Request it returns a HTTP 200 OK to
 193    the client unless it is busy or the file isnt found. In that case use
 194    HTTP specs to return the correct HTTP error code. To make things easy
 195    always send files with a content type of application/binary. Following
 196    that is the total length of the file in bytes. After sending the last
 197    '\r\n' proceed in sending the actual file.
 198    HTTP 200 OK\r\n
 199    Server: Gnucleus 1.4.5.2\r\n
 200    Content-type:application/binary\r\n
 201    Content-length: 2894894\r\n
 202    \r\n
 203    Resuming
 204    If a client sends a GET request with a byte range other than zero that
 205    means the client is resuming the transfer. In that case the reply is
 206    modified a bit. Instead of the Content-length: statement,
 207    Accept-Ranges: and Content-range is used. Accept-Ranges: is always
 208    bytes. Content-range: is followed by byte= and then the postion the
 209    transfer is resuming from. After the dash is the positoin of the last
 210    byte in the file, and after the slash is the total bytes in the file.
 211    HTTP 200 OK\r\n
 212    Server: Gnucleus 1.5.0.0\r\n
 213    Content-type:application/binary\r\n
 214    Accept-Ranges: bytes\r\n
 215    Content-range: bytes=565768-1947689/1947690\r\n
 216    \r\n
 217
 218    Pushing
 219    Instead of connecting to a host to send a GET request you send a push
 220    packet out over the gnutella network. The reason you do this is
 221    because the host you want the file from has an unreachable IP address
 222    such as 192.168.0.67. The push packet tells the host to connect to you
 223    instead (you having a reachable IP address). On connect of the host to
 224    you, that host sends you a GIV request. The GIV request is three
 225    parts, the file index, the GUID of the server and the name of the
 226    file. Take note the give request ends with \n\n and not \r\n.
 227        GIV 446:72814A49E69D0F43FF288B3E6AAAB400/Paint Drying.mpg\n\n
 228    After the GIV, the client and server act normally as before and send
 229    each other the proper headers in order the get the file transfer
 230    moving.
 231    GET /get/446/Paint Drying.mpg HTTP/1.0\r\n
 232    User-Agent: Bearshare 2.3.0\r\n
 233    Range: bytes=0-\r\n
 234    \r\n
 235    HTTP 200 OK\r\n
 236    Server: Gnucleus 1.3.3.1\r\n
 237    Content-type:application/binary\r\n
 238    Content-length: 56763485\r\n
 239    \r\n
 240
 241
 242 PROTOCOL
 243
 244     public static final byte F_PING=(byte)0x0;
 245     public static final byte F_PING_REPLY=(byte)0x1;
 246     public static final byte F_PUSH=(byte)0x40;
 247     public static final byte F_QUERY=(byte)0x80;
 248     public static final byte F_QUERY_REPLY=(byte)0x81;
 249     public static final byte F_ROUTE_TABLE_UPDATE=(byte)0x30;
 250
 251   The GnutellaNet protocol
 252 Last update: 2001 Nov 28
 253 Original version was by gene@wego.com.
 254 This verson is updated to correct the endian-ness errors, and clarify
 255 and update the situation with the network size and TTL values.
 256 Notes
 257 Everything is in network byte order unless otherwise noted. Byte order
 258 of the GUID is not important.
 259 Apparently, there is some confusion as to what "\r" and "\n" are.
 260 Well, \r is carriage return, or 0x0d, and \n is newline, or 0x0a. This
 261 is standard ASCII, but there it is, from "man ascii".
 262 Keep in mind that every message you send can be replied by multiple servers.
 263 Hence, PING is used to discover servers, as the PONG (Ping reply) contains
 264 server information.
 265 Throughout this document, the term server and client is interchangeable.
 266 Gnutella clients are Gnutella servers.
 267 Thanks to capnbry for his efforts in decoding the protocol and posting it.
 268 How GnutellaNet works
 269 General description
 270 GnutellaNet works by "viral propagation". I send a message to you, and
 271 you send it to all clients connected to you. That way, I only need to
 272 know about you to know about the entire rest of the network.
 273 A simple glance at this message delivery mechanism will tell you that
 274 it generates inordinate amounts of traffic. Take for example the
 275 defaults for Gnutella 0.54. It defaults to maintaining 25 active
 276 connections with a TTL (TTL means Time To Live, or the number of times
 277 a message can be passed on before it "dies"). In the worst of worlds,
 278 this means 25×24^6, or 4,777,574,400 messages resulting from just
 279 one message!
 280 Well, okay. In truth it isn't that bad. In reality, there are usually
 281 only a few thousand Gnutella clients on the GnutellaNet at any one
 282 time (and there have never been more than about 30,000). That means
 283 that long before the TTL expires on our hypothetical message, every
 284 client on the GnutellaNet will have seen our message.
 285 During 2000, many Gnutella clients used smaller defaults for the TTL
 286 and the number of active connections. Some went so far as to lower
 287 both to 4. However, this is much too low. Even if the network were
 288 "connected" in the most perfect manner, 4 links per node and a TTL of
 289 4 is only enough to connect 96 clients. Another popular combination is
 290 4 links per node and a TTL of 7, which can connect 1155 clients, but
 291 again only if the network is "wired" perfectly. If all the nodes hd 4
 292 links per node and the network connections changed purely at random,
 293 the TTL would have to be about 12 to 15 in order for most messages to
 294 be able to reach all nodes.
 295 However, some network structure has evolved. Smarter clients and
 296 higher-bandwidth clients have formed a "backbone", with older clients
 297 and low- bandwidth users pushed off to the edges. If the backbone
 298 clients maintain a higher number of connections, the GnutellaNet can
 299 work even with a TTL of 7 to 10 even when most of the clients only
 300 maintain 4 connections.
 301 GUIDs
 302 Obviously, once a client sees a message, it's unnecessary for it to
 303 process the message again. The original Gnutella designers, in
 304 recognition of this, engineered each message to contain a GUID
 305 (Globally Unique Identifier) which allows Gnutella clients to uniquely
 306 identify each message on the network.
 307 So how do Gnutella clients take advantage of the GUID? Each Gnutella
 308 client maintains a short memory of the GUIDs it has seen. For example,
 309 I will remember each message I have received. I forward each message I
 310 receive as appropriate, unless I have already seen the message. If I
 311 have seen the message, that means I have already forwarded it, so
 312 everyone I forwarded it to has already seen it, and so on. So I just
 313 forget about the duplicate and save everyone the trouble.
 314 Topology
 315 The GnutellaNet has no hierarchy. Every server is equal. Every server
 316 is also a client.
 317 Each Gnutella server only knows about the servers that it is directly
 318 connected to. All other servers are invisible, unless they announce
 319 themselves by answering to a PING or by replying to a QUERY. This
 320 provides amazing anonymity.
 321 Unfortunately, the combination of having no hierarchy and the lack of
 322 a definitive source for a server list means that the network is not
 323 easily described. It is not a tree (since there is no hierarchy) and
 324 it is cyclic. Being cyclic means that every message a client sends out will
 325 arrive back multiple times unless all (or at least most) of the
 326 clients are careful to use the GUIDs to drop the duplicates.
 327 Connecting to a server
 328 After making the initial connection to the server, you must handshake.
 329 Currently, the handshake is very simple.  The connecting client says:
 330 GNUTELLA CONNECT/0.4\n\n The accepting server responds:
 331 GNUTELLA OK\n\n After that, it's all data.
 332 Header
 333 bytes
 334 summary
 335 description
 336 0-15
 337 Message identifier
 338 16 bytes that will identify this
 339 message and distinguish it from all others sent on the network.
 340 Windows clients use a Windows GUID (which is 16 bytes). Other
 341 clients should generate 16 bytes based on something that will make it unique
 342 (like your local IP address, the current time, and some random numbers)
 343 16
 344 Payload descriptor
 345 (function identifier)
 346 Value Function
 347
 348
 349 0x00 PING
 350
 351
 352 0x01 PONG (Ping reply)
 353
 354
 355 0x40 PUSH request
 356
 357
 358 0x80 QUERY
 359
 360
 361 0x81 HITS (Query reply)
 362 17
 363 TTL
 364 Time to live.  Each time a message is forwarded its TTL is
 365 decremented by one.  If a message is received with TTL
 366 less than one (1), it should not be forwarded.
 367 18
 368 Hops
 369 Number of times this message has been forwarded.
 370 19- 22
 371 Payload length
 372 The length of the ensuing payload.
 373 Payload: PING (function 0x00)
 374 No payload
 375 Routing instructions for PING
 376 Forward PING packets to all connected clients. Most other documents
 377 state that you should not forward packets to their originators. I
 378 think that's a good optimization, but not a real requirement. A server
 379 should be smart enough to know not to forward a packet that it
 380 originated.
 381 A cursory analysis of GnutellaNet traffic shows that PING comprises
 382 roughly 50% of the network traffic. Clearly, this needs to be
 383 optimized. One of the problems with clients today is that they seem to
 384 PING the network periodically. That is indeed necessary, but the
 385 frequency of these "update" PINGs can be drastically reduced. Simply
 386 watching the PONG messages that your client routes is enough to
 387 capture lots of server addresses.
 388 One possible way to really reduce the number of PINGs is to alter the
 389 protocol to support PING messages which includes PONG data. That way
 390 you need only wait for servers to announce themselves, rather than
 391 discovering them yourself.
 392 Payload: PONG (query reply) (function 0x01)
 393 bytes
 394 summary
 395 description
 396 0-1
 397 Port
 398 IPv4 port number, using little-endian byte order:
 399 The low byte comes first. For example, if the port number is 6346, the
 400 first byte is 202 and the second byte is 24 (because 24×256+202=6346)
 401 2
 402 IP address
 403 IPv4 address, first byte
 404 3
 405 IP address
 406 IPv4 address, second byte
 407 4
 408 IP address
 409 IPv4 address, third byte
 410 5
 411 IP address
 412 IPv4 address, last byte. Please note
 413 this byte ordering not little-endian. For example, if the
 414 IP address is 10.23.45.67, byte 2 will be 10, byte 3 will be 23, etc.
 415 6-9
 416 Number of files
 417 Number of files the server is sharing.
 418 10- 13
 419 Number of kilobytes
 420 Number of kilobytes the server is sharing.
 421 Routing instructions for PONG
 422 Like all replies, PONG packets are "routed". In other words, you need
 423 to forward this packet only back down the path its PING came from. If
 424 you didn't see its PING, then you have an interesting situation that
 425 should never arise. Why? If you didn't see the PING that corresponds
 426 with this PONG, then the server sending this PONG routed it
 427 incorrectly.
 428 Payload: QUERY (function 0x80)
 429 bytes
 430 summary
 431 description
 432 0-1
 433 Minimum speed
 434 The minimum speed, in kilobytes/sec, of servers which should reply to
 435 this request.
 436 2+
 437 Search criteria
 438 Search keywords or other criteria.  NULL terminated.
 439 Routing instructions for QUERY
 440 Forward QUERY messages to all connected servers.
 441 Payload: HITS (query reply) (function 0x81)
 442 bytes
 443 summary
 444 description
 445 0
 446 Number of hits (N)
 447 The number of hits in this set.
 448 See "Result set" below.
 449 1-2
 450 Port
 451 IPv4 port number.
 452 3-6
 453 IP address
 454 IPv4 address. Same byte ordering as in PONG
 455 payload description above
 456 7-10
 457 Speed
 458 Speed, in kilobits/sec, of the responding server.
 459 11+
 460 Result set
 461 There are N of these (see "Number of hits" above).
 462
 463
 464 bytes summary, description
 465
 466
 467 0-3 Index: Index number of file.
 468
 469
 470 4-7 Size: Size of file in bytes.
 471
 472
 473  8+  File name: Name of file. Terminated by double-NULL.
 474 N bytes
 475 EQHD
 476 Extended QueryHit Descriptor (not always present).
 477 To determine if this data is present and to measure its size, you must
 478 count from the beginning through all the result sets to find the end
 479 of the last result set, and then compare that to the total payload length minus 16 (for the GUID). Any extra data between the last result
 480 and the GUID is EQHD.
 481 Last
 482 16 bytes
 483 Client identifier
 484 GUID of the responding server. Used in PUSH.
 485 Routing instructions for HITS
 486 HITS are routed, the same way PONGs are -- send these messages back on
 487 their inbound path. That means, send them only to the connection from which you recieved the corresponding QUERY. The corresponding QUERY is
 488 the one with the same message identifier (GUID) in its header as this reply.
 489 Extended QueryHit Descriptor
 490 This field is not always present. To determine if it is
 491 present and to measure its size, you must
 492 count from the beginning through all the result sets to find the end
 493 of the last result set, and then compare that to the total payload
 494 length minus 16 (for the GUID). Any extra data between the last result
 495 and the GUID is EQHD.
 496 A valie EQHD must contain at least 5 bytes of data:
 497 bytes
 498 summary
 499 description
 500 0-3
 501 Vendor Code
 502 A 4-byte code (probably 4 ASCII characters) representing
 503 the name of the program that originated this QueryHit. See table below.
 504 4
 505 Open Data Size
 506 Number of bytes of open-protocol (publicly
 507 documented) data. In practice, this is usually 2.
 508 N bytes
 509 Open Data
 510 Publicly-documented data. This is usually 2 bytes long,
 511 see below for description of format.
 512 M bytes
 513 Private Data
 514 Any additional data in the EQHD is of a
 515 format defined privately by the vendor. Use Vendor Code to determine
 516 whether this data is in a format you can understand (some vendors,
 517 notably Cultiv8r, have publicly-documented private data formats)
 518 Here is a table of known vendor codes. More are added from time to
 519 time as new clients are written.
 520
 521 Code
 522 Who or what
 523
 524 BEAR
 525 BearShare
 526
 527 LIME
 528 LimeWire
 529
 530 CULT
 531 Cultiv8r
 532
 533 GNOT
 534 Gnotella
 535
 536 GNUC
 537 Gnucleus
 538
 539 GNUT
 540 gnut
 541
 542 GTKG
 543 Gtk-Gnutella
 544
 545 HSLG
 546 Hagelslag
 547
 548 MACT
 549 Mactella
 550
 551 NAPS
 552 NapShare
 553
 554 OCFG
 555 OpenCola
 556
 557 TOAD
 558 ToadNode
 559 The OpenData usually contains two bytes:
 560 bits:
 561 7
 562 6
 563 5
 564       4
 565       3
 566      2
 567 1
 568      0
 569 1st byte:
 570 r
 571 r
 572 r
 573 validUploadSpeed
 574 validHaveUploaded
 575 validBusy
 576 r
 577 flagPush
 578
 579
 580
 581
 582
 583
 584
 585
 586 bits:
 587 7
 588 6
 589 5
 590       4
 591       3
 592      2
 593 1
 594      0
 595 2nd byte:
 596 r
 597 r
 598 r
 599 flagUploadSpeed
 600 flagHaveUploaded
 601 flagBusy
 602 r
 603 validPush
 604 r = reserved for future use.
 605 flagUploadSpeed = 1 if and only if the Speed field of this
 606    QueryHit descriptor contains the highest average transfer rate (in
 607    kbps) of the last 10 uploads.
 608 validUploadSpeed = 1 if and only if the flagUploadSpeed bit is
 609    meaningful.
 610 flagHaveUploaded = 1 if and only if the servent has successfully
 611    uploaded at least one file.
 612 validHaveUploaded = 1 if and only if the flagHaveUploaded bit is
 613    meaningful.
 614 flagBusy = 1 if and only if all of the servent's upload slots are
 615    full (at the time this QueryHit was generated)
 616 validBusy = 1 if and only if the flagBusy bit is meaningful.
 617 flagPush = 1 if and only if the servent is firewalled or has not yet
 618    accepted an incoming connection.
 619 validPush = 1 if and only if the flagPush bit is meaningful.
 620 PLEASE NOTE: the first byte contains 3 valid bits and one flag
 621 bit, and vice-versa for the second byte. That is deliberate, it's
 622 actually implemented that way in BearShare. (The description in the
 623 Cultiv8r version of this document is wrong regarding the placement of
 624 flagPush and validPush.)
 625 Payload: PUSH request (function 0x40)
 626 bytes
 627 summary
 628 description
 629 0-15
 630 Client identifier
 631 GUID of the server which should push.
 632 16-19
 633 Index
 634 Index number of file (given in query hit).
 635 20-23
 636 IP address
 637 IPv4 address to push to.
 638 24-25
 639 Port
 640 IPv4 port number to push to.
 641 Routing instructions for PUSH
 642 Forward PUSH messages only along the path on which the query hit was
 643 delivered. If you missed the query hit then drop the packet, since you
 644 are not instrumental in the delivery of the PUSH request.
 645 Downloading from a server
 646 Downloading files from a server is extremely easy. It's HTTP. The
 647 downloading client makes a new connection (a TCP connection)
 648 directly to the IP address of the server with the file to be
 649 downloaded. It then requests the file by sending an HTTP header:
 650 GET /get/1234/strawberry-rhubarb-pies.rcp HTTP/1.0\r\n
 651 Connection: Keep-Alive\r\n
 652 Range: bytes=0-\r\n
 653 \r\n As you can see, Gnutella supports the range parameter for resuming
 654 partial downloads. The 1234 is the file index (from HITS packet
 655 described above), and "strawberry-rhubarb-pies.rcp" is the filename.
 656 The server will respond with normal HTTP headers.  For example:
 657 HTTP 200 OK\r\n
 658 Server: Gnutella\r\n
 659 Content-type:application/binary\r\n
 660 Content-length: 948\r\n
 661 \r\n
 662 ds*GKh:RkFk@)gjGLgK\Gh@+$L__^KVU-`D@:`/:#%KfTYJ^Y(BWDFL$#:rltyh... The important bit is the "Content-Length" header. That tells you how
 663 much data to expect. After you get your fill, close the socket. Also
 664 note the double \r\n before the beginning of the data. No special
 665 encoding is used -- if the file is bonary, the data will be binary.
 666 PUSH Downloads
 667 A PUSH download is initiated by a server that has received a PUSH
 668 request packet as described above. The server connects to the
 669 requesting server, that is, the server that sent the PUSH request (the
 670 requester's address is in the PUSH request packet) and writes a line
 671 of the following format:
 672 GIV 1234:1F340601AE6B60911956D022ECA8A045/strawberry-rhubarb-pies.rcp This line tells the requesting server that it is recieving a PUSH
 673 connection to download the file it wants. The format is:
 674   "GIV"
 675   " " (a blank space)
 676   "1234": The file index
 677   ":"
 678   "1F3406..." the 16-byte GUID from the PUSH request as 32 hexadecimal digits
 679   "/"
 680   "strawberry..." the filename or pathname The requesting server will respond by sending back a GET header in the
 681 same format as described above, and from there on the transfer
 682 proceeds the same way it would have if the requester had established
 683 the connection.
 684
 685
 686 The gnut pages are hosted by
 687 gnutelliums.com and
 688 gnutelanews.com
 689 Permission is granted to copy, distribute and/or modify this text
 690 under the terms of the
 691 GNU Free Documentation License, Version 1.1
 692 or any later version published by the Free Software Foundation; with
 693 no Invariant Sections, with no Front-Cover Texts and with no
 694 Back-Cover Texts.
 695 Use of the gnut source code is subject to the terms and conditions
 696 of the
 697 GNU General Public License.
 698 gnut is provided in the hope that it will be useful, but WITHOUT ANY
 699 WARRANTY; without even the implied warranty of MERCHANTABILITY or
 700 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
 701 for more details.
 702 gnut is currently maintained by Robert Munafo, mrob at mrob com
 703 Back to main gnut page
 704
 705 QUERY:
 706
 707
 708 (17)(119)(46)(2)(0)(156)(202)(71)(255)(123)(244)(89)(248)(200)(172)(0)          UID
 709 (128)                                                                           RECHERCHE
 710 (7)                                                                             TTL
 711 (0)                                                                             HOPS
 712 (168)(0)(0)(0)                                                                  PAYLOAD
 713 (0)(0)
 714 f a r m e r   m y l e n e  (0) < ? x m l   v e r s i o n = " 1 . 0 " ? > < a u d i o s   x s i : n o N a m e s p a c e S c h e m a L o c a t i o n = " h t t p : / / w w w . l i m e w i r e . c o m / s c h e m a s / a u d i o . x s d " > < a u d i o   a r t i s t = " f a r m e r   m y l e n e " > < / a u d i o > < / a u d i o s >(0)
 715
 716
 717   QUERY REPLY:
 718
 719 (17)(119)(46)(2)(0)(156)(202)(71)(255)(123)(244)(89)(248)(200)(172)(0)
 720 (129)
 721 (0)
 722 (7)
 723 (199)(1)(0)(0)
 724 (2)(202)(24)(192)(168)(0)(3)(64)(5)(0)(0)(154)(1)(0)(0)(124)(26)(60)(0)
 725 M y l e n e   F a r m e r   -   M a m a n   a   T o 1 . m p 3
 726 (0)(0)(155)(1)(0)(0)(206)(181)(114)(0)
 727 M y l e n e   F a r m e r   -   M a m a n   A   T o r . m p 3
 728 (0)(0)
 729 L I M E
 730 (4)(28)(25)(80)(1)(0)
 731 { p l a i n t e x t } < ? x m l   v e r s i o n = " 1 . 0 " ? > < a u d i o s   n o N a m e s p a c e S c h e m a L o c a t i o n = " h t t
 732  p : / / w w w . l i m e w i r e . c o m / s c h e m a s / a u d i o . x s d " > < a u d i o       b i t r a t e = " 1 2 8 "   s e c o n d
 733 s = " 2 4 6 "   i n d e x = " 0 "   / > < a u d i o       t i t l e = " M a m a n   A   T o r t "   a r t i s t = " M y l e n e   F a r m e
 734 r "   a l b u m = " D a n c e   R e m i x e s   2 "   g e n r e = " P o p "   y e a r = " 2 0 0 0 "   c o m m e n t s = " ,   A G #   8 5 1
 735 E A 3 B 7 "   b i t r a t e = " 1 6 0 "   s e c o n d s = " 3 7 5 " i n d e x = " 1 "   / > < / a u d i o s >
 736 (0)
 737 (122)(93)(63)(134)(108)(83)(239)(129)(255)(75)(235)(24)(150)(226)(201)(0)
 738 (54)(77)(175)(208)(60)(71)(78)(116)(255)(162)(94)(196)(115)(169)(160)(0)(1)(3)(4)(14)(0)(0)(0)]
 739
 740
 741     private QueryReply(byte[] guid, byte ttl,
 742              int port, byte[] ip, long speed, Response[] responses,
 743              byte[] clientGUID, byte[] xmlBytes,
 744              boolean includeQHD, boolean needsPush, boolean isBusy,
 745              boolean finishedUpload, boolean measuredSpeed,
 746              boolean supportsChat) {
 747         super(guid, Message.F_QUERY_REPLY, ttl, (byte)0,
 748               11 +                             // 11 bytes of header
 749               rLength(responses) +             // file records size
 750               qhdLength(includeQHD, xmlBytes) +
 751                                                // conditional xml-style QHD len
 752               16);                             // 16-byte footer
 753         // you aren't going to send this.  it will throw an exception above in
 754         // the appropriate constructor....
 755         if (xmlBytes.length > XML_MAX_SIZE)
 756             return;
 757
 758         Assert.that((port&0xFFFF0000)==0);
 759         Assert.that(ip.length==4);
 760         Assert.that((speed&0xFFFFFFFF00000000l)==0);
 761         final int n=responses.length;
 762         Assert.that(n<256);
 763
 764         payload=new byte[getLength()];
 765         //Write beginning of payload.
 766         //Downcasts are ok, even if they go negative
 767         payload[0]=(byte)n;
 768         ByteOrder.short2leb((short)port,payload,1);
 769         payload[3]=ip[0];
 770         payload[4]=ip[1];
 771         payload[5]=ip[2];
 772         payload[6]=ip[3];
 773         ByteOrder.int2leb((int)speed,payload,7);
 774
 775         //Write each response at index i
 776         int i=11;
 777         for (int left=n; left>0; left--) {
 778             Response r=responses[n-left];
 779             ByteOrder.int2leb((int)r.getIndex(),payload,i);
 780             ByteOrder.int2leb((int)r.getSize(),payload,i+4);
 781             i+=8;
 782             byte[] nameBytes = r.getNameBytes();
 783             System.arraycopy(nameBytes, 0, payload, i, nameBytes.length);
 784             i+=nameBytes.length;
 785             //Write first null terminator.
 786             payload[i++]=(byte)0;
 787             //add the second null terminator
 788             payload[i++]=(byte)0;
 789         }
 790
 791         //Write QHD if desired
 792         if (includeQHD) {
 793             //a) vendor code.  This is hardcoded here for simplicity,
 794             //efficiency, and to prevent character decoding problems.
 795             payload[i++]=(byte)76; //'L'
 796             payload[i++]=(byte)73; //'I'
 797             payload[i++]=(byte)77; //'M'
 798             payload[i++]=(byte)69; //'E'
 799
 800             //b) payload length
 801             payload[i++]=(byte)COMMON_PAYLOAD_LEN;
 802
 803             //c) PART 1: common area flags and controls.  See format in
 804             //parseResults2.
 805             payload[i++]=(byte)((needsPush ? PUSH_MASK : 0)
 806                 | BUSY_MASK
 807                 | UPLOADED_MASK
 808                 | SPEED_MASK);
 809             payload[i++]=(byte)(PUSH_MASK
 810                 | (isBusy ? BUSY_MASK : 0)
 811                 | (finishedUpload ? UPLOADED_MASK : 0)
 812                 | (measuredSpeed ? SPEED_MASK : 0));
 813
 814             //d) PART 2: size of xmlBytes + 1.
 815             int xmlSize = xmlBytes.length + 1;
 816             if (xmlSize > XML_MAX_SIZE)
 817                 xmlSize = XML_MAX_SIZE;  // yes, truncate!
 818             ByteOrder.short2leb(((short) xmlSize), payload, i);
 819             i += 2;
 820
 821             //e) private area: one flag that says whether we support chat
 822             payload[i++]=(byte)(supportsChat ? 0x1 : 0);
 823
 824             //f) actual xml.
 825             System.arraycopy(xmlBytes, 0,
 826                              payload, i, xmlSize-1);
 827             // adjust i...
 828             i += xmlSize-1;
 829             // write null after xml, as specified
 830             payload[i++] = (byte)0;
 831         }
 832
 833         //Write footer at payload[i...i+16-1]
 834         for (int j=0; j<16; j++) {
 835             payload[i+j]=clientGUID[j];
 836         }
 837     }
 838
 839
 840         //2. Extract BearShare-style metainformation, if any.  Any exceptions
 841         //are silently caught.  The definitive reference for this format is at
 842         //http://www.clip2.com/GnutellaProtocol04.pdf.  Briefly, the format is
 843         //      vendor code           (4 bytes, case insensitive)
 844         //      common payload length (4 byte, unsigned, always>0)
 845         //      common payload        (length given above.  See below.)
 846         //      vendor payload        (length until clientGUID)
 847         //The normal 16 byte clientGUID follows, of course.
 848         //
 849         //The first byte of the common payload has a one in its 0'th bit* if we
 850         //should try a push.  However, if there is a second byte, and if the
 851         //0'th bit of this byte is zero, the 0'th bit of the first byte should
 852         //actually be interpreted as MAYBE.  Unfortunately LimeWire 1.4 failed
 853         //to set this bit in the second byte, so it should be ignored when
 854         //parsing, though set on writing.
 855         //
 856         //The remaining bits of the first byte of the common payload area tell
 857         //whether the corresponding bits in the optional second byte is defined.
 858         //The idea behind having two bits per flag is to distinguish between
 859         //YES, NO, and MAYBE.  These bits are as followed:
 860         //      bit 1*  undefined, for historical reasons
 861         //      bit 2   1 iff server is busy
 862         //      bit 3   1 iff server has successfully completed an upload
 863         //      bit 4   1 iff server's reported speed was actually measured, not
 864         //              simply set by the user.
 865         //
 866         //*Here, we use 0-(N-1) numbering.  So "0'th bit" refers to the least
 867         //significant bit.
 868         /* ----------------------------------------------------------------
 869          * QHD UPDATE 8/17/01
 870          * Here is an updated QHD spec.
 871          *
 872          * Byte 0-3 : Vendor Code
 873          * Byte 4   : Public area size (COMMON_PAYLOAD_LEN)
 874          * Byte 5-6 : Public area (as described above)
 875          * Byte 7-8 : Size of XML + 1 (for a null), you need to count backward
 876          * from the client GUID.
 877          * Byte 9-beginning of xml : (new) private area
 878          * Byte (payload.length - 16 - xmlSize (above)) -
 879                 (payload.length - 16 - 1) : XML!!
 880          * Byte (payload.length - 16 - 1) : NULL
 881          * Last 16 Bytes: client GUID.
 882          */
 883
 884
 885
 886 *)