[Release] NetHandler - Networking Made Easy

[kklouzal]

Download NetHandler At GitHub

NetHandler is a networking library built with ENet at it's core and uses Cereal's Portable Binary Archive for Endian Safe packet data serialization.

NetHandler includes Lua Bindings to allow network communication from a scripting environment. Bindings are optionally compiled from the main library with a separate included project.

Portable to Windows, Mac, and Linux. NetHandler is perfect for any project requiring networking, not just Irrlicht applications.

Premake scripts are included to quickly compile from source and have integration into your project in little to no time at all.

Future plans to use LZ4 for packet compression and support for automatic threading.

[kklouzal]

This is a guide on compiling NetHandler. This is geared towards windows and visual studio with hints on how to do it on other operating systems.

1. Obtain a copy of NetHandler source code from GitHub: https://github.com/kklouzal/NetHandler

2. If you downloaded it as a zip archive extract it to some location or if you cloned it, navigate to the location your cloned the repository. For this tutorial I downloaded it as a zip archive and extracted it to the top level of my C drive.

3. Open the projects folder, here you will find "Build.bat" for windows and "Build.sh" for Linux/Mac.


4. Execute the corresponding file for your system to create the project files. A console window will appear and your project folder will be created.


5. Open the newly created folder and go into the folder that corresponds to your IDE. There you will find the main project file, mine is "NetHandler.sln"


6. I'm using Visual Studio 2013 Express which asks me to upgrade the projects, go ahead and click OK if you get this window and the solution will be upgraded.


7. Select the appropriate build configuration, right click "NetHandler" in the Solution Explorer and press "Build"


8. If you want to use Lua Bindings you must add your lua library and include folders to the project, the same goes for the LuaClient and LuaServer examples.


9. The newly compiled library files will be located in a new folder called "lib" at the top level of the NetHandler folder.

The actual library files will be a few more folders deep depending on your OS and IDE.


At this point the library has been compiled and is ready for use in your project. Go back and compile the Lua Bindings if needed and/or the Example projects.

[kklouzal]

This is a basic overview of NetHandlers features/usage.
Please refer to the example projects included with the library for more complete usage examples.

To use NetHandler in any of your projects you must do two simple things, Include it's main header file and link to the correct libraries.

Code: Select all

#include <NetHandler\NetHandler.h>
#ifdef _MSC_VER
    #pragma comment(lib, "ws2_32")
    #pragma comment(lib, "winmm")
    #ifdef NDEBUG
        #pragma comment(lib, "NetHandler.lib")
    #else
        #pragma comment(lib, "NetHandler_Debug.lib")
    #endif
#endif

The preprocessor macros above let you easily switch between release/debug project configurations.

Creating A Server
Servers require 5 arguments and return a pointer to a NetPoint Object.
HostName - This can either be an IP address or a Domain Name. Domain names will automatically be translated into IP Addresses.
Port - What port to allow incoming connections on.
MaxConnections - How many clients maximum can connect.
NumChannels - How many channels do you want to allow packts to use.
iClientFactory - Pointer to your own implementation of 'NetClientFactory'

Code: Select all

NetPoint* CreateServer(const char* HostName, enet_uint16 Port, size_t MaxConnections, size_t NumChannels, NetClientFactory* iClientFactory);

You may specify your own implementation of 'NetClientFactory' so the NetHandler will create and use your own client objects. Custom Client Objects must inherit from 'NetClient'

Code: Select all

class MyClient : public NetClient
{
public:
    MyClient() {}
    ~MyClient() {}
};
 
class MyClientFactory : public NetClientFactory
{
public:
    
    NetClient* CreateClient()
    {
        return new MyClient;
    }
};

When a new client connects it will call MyClientFactory::CreateClient which will return a new MyClient object. When a client disconnects NetHandler will automatically delete the MyClient object.

Creating A Client
Clients require 1 argument and return a pointer to a NetPoint object.
NumChannels - How many channels do you want to allow packets to use.

To connect a client to a server simply call its Connect method which requires two arguments.
HostName - This can either be an IP address or a Domain Name. Domain names will automatically be translated into IP Addresses.
Port - What port to allow incoming connections on.
The Connect method will return true on success and false if an error occurred.

You can correspondingly disconnect a client using its Disconnect method and check if it is currently connected with the IsConnected method.

Clients and servers require you to periodically call their Updated method to check for new packets and/or new connections.

You have three callback functions at your disposal and you are able to set different functions for different NetPoint's
The callback functions are as follows:

Code: Select all

std::function<void(NetClient* Client)> Callback_ClientConnect;
    std::function<void(NetClient* Client)> Callback_ClientDisconnect;
    std::function<void(const NetPacket& Packet, NetClient* Client)> Callback_NewMessage;

And are used as follows:

Code: Select all

void NetCallback_ClientConnected(NetClient* ThisNetClient)
{
}
 
void NetCallback_ClientDisconnected(NetClient* ThisNetClient)
{
}
 
void NetCallback_NewMessage(const NetPacket& Packet, NetClient* ThisNetClient)
{
}
 
//    Called when a client connects
Server_NetPoint->SetCallback_ClientConnect(NetCallback_ClientConnected);
//    Called when a client disconnects
Server_NetPoint->SetCallback_ClientDisconnect(NetCallback_ClientDisconnected);
//    Called when a new packet is received
Server_NetPoint->SetCallback_NewMessage(NetCallback_NewMessage);
 
//    Called when the client successfully connects to a server
Server_NetPoint->SetCallback_ClientConnect(NetCallback_ClientConnected);
//    Called when the client successfully disconnects from a server
Server_NetPoint->SetCallback_ClientDisconnect(NetCallback_ClientDisconnected);
//    Called when the client receives a new packet
Server_NetPoint->SetCallback_NewMessage(NetCallback_NewMessage);

Packet Usage:
To create a packet, simply call:
NetHandler::CreatePacket
Create Packet requires two arguments and returns a unique_ptr thus the object will be automatically cleaned up when it is no longer needed.
HostPoint - Which NetPoint will be used to send the packet?
MessageID - Assign the packet a message id.

Code: Select all

std::unique_ptr<NetPacket> CreatePacket(NetPoint* HostPoint, const unsigned int MessageID);

Adding Data:
To add data to a packet call the NetPacket::WriteData function. WriteData is a templatized function and is used as follows:

Code: Select all

NewPacket->WriteData<int>(10);
NewPacket->WriteData<std::string>("Some String");
NewPacket->WriteData<unsigned long long>(1234567890);

Reading Data:
Reading data is as simple as writing data, simply call the templatized ReadData function. Data must be read in the same order it is written

Code: Select all

int SomeInt = NewPacket->ReadData<int>();
std::string SomeString = NewPacket->ReadData<std::string>();
unsigned long long SomeHugeAssNumber = NewPacket->ReadData<unsigned long long>();

Sending A packet:
Finally you want to send packets with the NetPacket::Send function
The Send function has two variants:

Code: Select all

void Send(const bool Reliable, const enet_uint8 Channel);
void Send(NetClient* Client, const bool Reliable, const enet_uint8 Channel);

The first is used to send packets to a server, the second is used to send packets to a specific client.
Pass a Boolean if you want to guarantee delivery of this packet, and an integer for which channel to send on.

Thank you for bearing with me through this guide, I know it was a lot of information. I tried to structure it as best as I could. I'll try to clean it up a bit in the future. For now at least you have something to refer to. Remember to check the Examples that are included with the library to see how it is actually used.

[Peppercorn142]

Freaking awesome man! haha can't wait to implement this

[kklouzal]

I just pushed a new commit to GitHub. Received packets are now handled in a dedicated thread. Each created NetPoint gets assigned their own dedicated thread to handle receiving of packets. The next thing I'll do is most likely make sending of packets handled in a dedicated thread.

[hendu]

What are the differences compared to Grapple?

[kklouzal]

I'm not sure about differences but I can list all the features of the current release.
Create multiple servers and multiple clients in a single application.
Each unique client and server can have their own set of callback functions.
Client objects are handled automatically.
You have the ability to provide your own implementation of client objects by subclassing NetClient and NetClientFactory.
Each unique server can have their own unique NetClientFactory.
Each unique client and server gets their own dedicated receive thread.
Packet serialization using Cereal ensures endian safe binary serialization.
UDP only packets with the ability to specify a packet as reliable to ensure delivery.
Passing domain names for hostnames will translate into IP addresses.
LUA Bindings are included as a separate optional project which can be built and linked to extend the libraries functionality.
NetHandler is built around speed and efficiency using the least amount of bandwidth possible.
Simple read and write functions to read and write data to and from packets.

There are probably more but I can't think of them at the moment :P

[hendu]

Well, it seems you've duplicated a part of Grapple, I don't see anything unique except the Lua binding.

[kklouzal]

I may have duplicated some of it's functionality but the inner workings are very different.

[thanhle]

Goodjob.
Can't wait to see this growing further.
Will you provide support for sending structure or object? Sample code would be useful.
It would be good to also adding encryption and decryption to the packet.

Regards
thanh

[kklouzal]

Sending user defined objects from classes/structs is already possible. You just need to open up 'NetPacket.cpp' at near the top define all the types you want to be able to send/receive. You may need to consult Cereal if your custom defined types there won't compile into the library. They will most likely need to be polymorphic types.

I'll look into encryption. I'm almost finished with database handling then I think I'm going to implement CURL.