Developers.HowShareazaWorks

How Shareaza Works

This part of the wiki is for documenting how Shareaza works. Right now, comments in the code are sparse and little documentation for developers exists. It's difficult to jump into the Shareaza project and find your way around. Working together, we can change that. Shareaza is already the best program of its kind in many areas. It connects to all the major open networks, took Gnutella to the next level of performance, and even looks great. Let's also make it the best written, best organized, best commented, and best documented open source code base for peer-to-peer computing.

As far as I can tell, the most complete and official specification for Gnutella is RFC-Gnutella 0.6 by The Gnutella Developer Forum. Gnutella2 is documented at g2.trillinux.org. I haven't started looking for official specifications for eDonkey or BitTorrent yet, but a page a hydranode.com looks promising.

Source Code Files

There are 335 .cpp files that make up the Shareaza source code. I started out just opening each one, figuring out what the code inside basically does, and wrote it all down. Then, I sorted them into general categories that could become folders in Visual Studio or C++ namespaces in the code. Developers.CodeFiles

Focuses in on the files that contain peer-to-peer networking code. Developers.NetFiles

Tries to show how the networking objects reference one another, but they didn't fall together into a single heirarchy as well as I had hoped they would. Developers.NetCalls

CConnection and CNeighbour

Now, I'm going to jump into the actual code, commenting lines and documeting methods. I'm starting with the Connection and Neighbour objects. Developers.Code.CConnection Developers.Code.CNeighbour

Here are some notes about how this part of Shareaza seems to be designed, along with some ideas for how it could be changed and improved. Developers.Refactor.Connection Developers.Refactor.Host

First, I did a really high-level view of the code: Developers.CodeFiles. Then, I dropped down and totally understood Developers.Code.CConnection and Developers.Code.CNeighbour. The first was too macro, the second too micro. There are a lot of classes that have the name Neighbour in them. I know somewhere in here are peer-to-peer jobs like the handshake and packets. I'm going to attack thing thing at a medium height, and map out the key classes of the core of the networking code. Also, developer ten9 worked on isolating the code for the different networks, and created these class diagrams. Developers.NetMap

The Handshake

These three classes deal with the handshake. I will comment and document them now. CHandshake looks at the first 7 bytes a remote computer tells us, and figures out what network its on. It also does Gnutella and Gnutella2-style push operations by receiving and sending GIV and PUSH packets. Developers.Code.CHandshake

When Shareaza is running, it makes a CHandshake object for each computer we're connected to. There is only one CHandshakes object, though, and it's created right when the program runs. It keeps a list of all the CHandshake objects. It also has one socket, which it sets up as a listening socket. When a new remote computer calls this socket, it accepts the connection by making a new CHandshake object for it, and placing it in the list. This class also uses a thread. It waits on the listening socket to accept new connections as they come in. It also loops down the list of CHandshake objects, pushing data through each of them in both directions. Developers.Code.CHandshakes

When Shareaza has a new a TCP socket connection to a remote computer, the first bytes exchanged are called the handshake. Developers.GnutellaHandshake Developers.GnutellaHandshakeHeaders Shareaza creates a CShakeNeighbour object for a remote computer while negotiating the handshake. This class inherits from CNeighbour and CConnection, from where it gets the socket. Once the handshake is over, code converts the CShakeNeighbour object into a CG1Neighbour or CG2Neighbour object. Developers.Code.CShakeNeighbour Developers.Code.CShakeNeighbour.Running

CBuffer and CZLib

Shareaza has a class called CBuffer that keeps a block of memory. There are a lot of useful methods to add memory and manipulate it, and the class takes care of allocating more space and freeing itself automatically. Shareaza includes the ZLib compression library, and uses it to compress and decompress data. Developers.Code.CBuffer Developers.Refactor.Buffer Developers.Code.CZLib Developers.Refactor.Compress

Peer-to-peer networks use GUIDs to uniquely identify computers and packets without having to coordinate at all. Developers.GUIDs

Gnutella Packets

Once the handshake is over, Shareaza exchanges packets with the remote computer. Packets are small amounts of memory, and Shareaza needs to be able to work with them very quickly. To make them fast and easy to work with, Shareaza has several classes devoted to organizing groups of them.

• Developers.ThePacketPool
• Developers.Code.CG1PacketBuffer

Shareaza connects to Gnutella, Gnutella2, and eDonkey2000. I'm looking at the Gnutella code first. A Gnutella packet is represented by a CG1Packet object. This class inherits from CPacket. The classes hold the memory of the packet, and provide methods to read and write parts of it.

• Developers.Code.CPacket
• Developers.Code.CG1Packet

Once the handshake has determined that the remote computer is running Gnutella, Shareaza converts the CShakeNeighbour object into a CG1Neighbour one. Both classes inherit from CNeighbour and CConnection. The methods in CG1Neighbour sort and process Gnutella packets, handing off work to other areas of the code. The CG1Neighbour class also finally starts to make use of the many member variables CNeighbour defined.

• Developers.Code.CG1Neighbour

---

At this point, it seems useful to write a document about the classes I understand, and how I've discovered Shareaza works so far. Also, I'm putting together a guide that tells where in the code peer-to-peer jobs are done. And, it's a good time to collect notes for how this part of the code could be refactored.

• Developers.HowItWorksSoFar
• Developers.SingleGlobalObjects
• Developers.WhereEachJobIsDone
• Developers.Refactor

And, keep notes as I start into the next section, the huge CNeighbours inheritance column.

• Developers.FiguringOutCNeighbours
• Developers.FiguringOutUltrapeers

Here are all the classes that lead to CNeighbours.

• Developers.Code.CNeighboursBase
• Developers.Code.CNeighboursWithG1
• Developers.Code.CNeighboursWithG2
• Developers.Code.CNeighboursWithED2K
• Developers.Code.CNeighboursWithRouting
• Developers.Code.CNeighboursWithConnect
• Developers.Code.CNeighbours

---

There are a handful of different kinds of Gnutella packets, and they each have a specific structure and purpose. In addition to documenting the code method-by-method, I'm writing these pages about each packet. The Shareaza code isn't organized so everything about one packet is in one place yet, but these documents will be.

• Developers.Gnutella.Packet.Header
• Developers.Gnutella.Packet.TimeToLiveAndHops
• Developers.Gnutella.Packet.PingAndPong
• Developers.Gnutella.Packet.Push
• Developers.Gnutella.Packet.Query
• Developers.Gnutella.Packet.Hit
• Developers.Gnutella.Packet.Bye
• Developers.Gnutella.Packet.CommonQueryHash
• Developers.Gnutella.Packet.VendorSpecificPackets
• Developers.Gnutella.Packet.ClusterAdvisor