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.
