TNL::NetEvent Class Reference
#include <tnlNetEvent.h>
Inheritance diagram for TNL::NetEvent:
Detailed Description
An event to be sent over the network.
- Note:
- TNL implements two methods of network data passing; this is one of them. See GhostConnection for details of the other, which is referred to as ghosting.
- Unguaranteed events are events which are sent once. If they don't make it through the link, they are not resent. This is good for quick, frequent status updates which are of transient interest, like voice communication fragments.
- Guaranteed events are events which are guaranteed to be delivered. If they don't make it through the link, they are sent as needed. This is good for important, one-time information, like which team a user wants to play on, or the current weather. Guaranteed events are processed when they are received, so they may be processed in a different order than they were sent in.
- GuaranteedOrdered events are events which are guaranteed to be delivered, and whose process methods will be executed in the order the events were sent. This is good for information which is not only important, but also order-critical, like chat messages or file transfers.
There are 3 methods that you need to implement if you want to make a basic NetEvent subclass, and 2 macros you need to call.
// A simple NetEvent to transmit a string over the network. class SimpleMessageEvent : public NetEvent { typedef NetEvent Parent; char *msg; public: SimpleMessageEvent(const char *message = NULL); ~SimpleMessageEvent(); virtual void pack (EventConnection *conn, BitStream *bstream) virtual void unpack (EventConnection *conn, BitStream *bstream); virtual void process(EventConnection *conn); TNL_DECLARE_CLASS(SimpleMessageEvent); }; TNL_IMPLEMENT_NETEVENT(SimpleMessageEvent, NetClassGroupGameMask,0);
The first macro called, TNL_DECLARE_CLASS() registers the static class functions and NetClassRep object that will assign this class a network ID and allow instances to be constructed by ID.
The second, TNL_IMPLEMENT_NETEVENT(), instantiates the NetClassRep and tells it that the instances are NetEvent objects in the Game group. The final parameter to the TNL_IMPLEMENT_NETEVENT macro is the version number of the event class. Versioning allows a server to offer new event services without forcing older clients to be updated.
In the constructor for the event the guarantee type of the event and the direction it will be allowed to travel over the connection, must be specified by way of the constructor for the base NetEvent class. The guarantee type can be one of:
- NetEvent::GuaranteedOrdered, for guaranteed, ordered events
- NetEvent::Guaranteed, for guaranteed events
- NetEvent::Unguaranteed, for unguaranteed events
It is also a good idea to clearly specify which direction the event is allowed to travel. If the program has a certain set of message events that are only sent from server to client, then the network system can enforce that error checking automatically, in order to prevent hacks that may otherwise crash or compromise the program. The valid event directions are:
- NetEvent::DirAny, this event can be sent from server to client or from client to server
- NetEvent::DirServerToClient, this event can only be sent from server to client. If the server receives an event of this type, it will signal an error on the connection.
- NetEvent::DirClientToServer, this event can only be sent from client to server. If the client receives an event of this type, it will signal an error on the connection.
- Note:
- TNL allows you to call NetConnection::setLastError() on the EventConnection passed to the NetEvent. This will cause the connection to abort if invalid data is received, specifying a reason to the user.
SimpleMessageEvent::SimpleMessageEvent(const char *message = NULL) : NetEvent(NetEvent::GuaranteedOrdered, NetEvent::DirAny) { // we marked this event as GuaranteedOrdered, and it can be sent in any direction if(message) msg = strdup(message); else msg = NULL; } SimpleMessageEvent::~SimpleMessageEvent() { free(msg); }
The 3 other functions that must be overridden for evern NetEvent are pack(), unpack() and process().
pack() is responsible for packing the event over the wire:
void SimpleMessageEvent::pack(EventConnection* conn, BitStream *bstream) { bstream->writeString(msg); }
unpack() is responsible for unpacking the event on the other end:
// The networking layer takes care of instantiating a new // SimpleMessageEvent, which saves us a bit of effort. void SimpleMessageEvent::unpack(EventConnection *conn, BitStream *bstream) { char buf[256]; bstream->readString(buf); msg = strdup(buf); }
process() is called when the network layer is finished with things. A typical case is that a GuaranteedOrdered event is unpacked and stored, but not processed until the events preceding it in the sequence have been process()'d.
// This just prints the event in the log. You might // want to do something more clever here. void SimpleMessageEvent::process(EventConnection *conn) { logprintf("Received a SimpleMessageEvent: %s", msg); // An example of something more clever - kick people who say bad words. // if(isBadWord(msg)) conn->setLastError("No swearing, naughtypants!"); }
Posting an event to the remote host on a connection is simple:
EventConnection *conn; // We assume you have filled this in. conn->postNetEvent(new SimpleMessageEvent("This is a test!"));
Finally, for more advanced applications, notifyPosted() is called when the event is posted into the send queue, notifySent() is called whenever the event is sent over the wire, in EventConnection::eventWritePacket(). notifyDelivered() is called when the packet is finally received or (in the case of Unguaranteed packets) dropped.
- Note:
- the TNL_IMPLEMENT_NETEVENT groupMask specifies which "group" of EventConnections the event can be sent over. See TNL::Object for a further discussion of this.
Public Types | |
| enum | EventDirection { DirUnset, DirAny, DirServerToClient, DirClientToServer } |
| enum | GuaranteeType { GuaranteedOrdered = 0, Guaranteed = 1, Unguaranteed = 2 } |
Public Member Functions | |
| NetEvent (GuaranteeType gType=GuaranteedOrdered, EventDirection evDir=DirUnset) | |
| Constructor - should always be called by subclasses. | |
| virtual void | pack (EventConnection *ps, BitStream *bstream)=0 |
| Pack is called on the origin side of the connection to write an event's data into a packet. | |
| virtual void | unpack (EventConnection *ps, BitStream *bstream)=0 |
| Unpack is called on the destination side of the connection to read an event's data out of a packet. | |
| virtual void | process (EventConnection *ps)=0 |
| Process is called to process the event data when it has been unpacked. | |
| virtual void | notifyPosted (EventConnection *ps) |
| notifyPosted is called on an event when it is posted to a particular EventConnection, before it is added to the send queue. | |
| virtual void | notifySent (EventConnection *ps) |
| notifySent is called on each event after all of the events for a packet have been written into the packet stream. | |
| virtual void | notifyDelivered (EventConnection *ps, bool madeIt) |
| notifyDelivered is called on the source event after it has been received and processed by the other side of the connection. | |
| EventDirection | getEventDirection () |
| getEventDirection returns the direction this event is allowed to travel in on a connection | |
| virtual const char * | getDebugName () |
| getDebugName is used to construct event names for packet logging in debug mode. | |
Data Fields | |
| enum TNL::NetEvent::EventDirection | mEventDirection |
| Direction this event is allowed to travel in the network. | |
| enum TNL::NetEvent::GuaranteeType | mGuaranteeType |
| Type of data guarantee this event supports. | |
Friends | |
| class | EventConnection |
Member Enumeration Documentation
|
|
|
|
Constructor & Destructor Documentation
|
||||||||||||
|
Constructor - should always be called by subclasses. Subclasses MUST pass in an event direction and guarantee type, or else the network system will error on the event. Events are by default GuaranteedOrdered, however, the default direction is unset which will result in asserts. |
Member Function Documentation
|
||||||||||||
|
Pack is called on the origin side of the connection to write an event's data into a packet.
Implemented in TNL::NetObjectRPCEvent, and TNL::RPCEvent. |
|
||||||||||||
|
Unpack is called on the destination side of the connection to read an event's data out of a packet.
Implemented in TNL::NetObjectRPCEvent, and TNL::RPCEvent. |
|
|
Process is called to process the event data when it has been unpacked. For a guaranteed, ordered event, process is called only once all prior events have been received and processed. For unguaranteed events, process is called immediately after unpack. Implemented in TNL::NetObjectRPCEvent, and TNL::RPCEvent. |
|
|
notifyPosted is called on an event when it is posted to a particular EventConnection, before it is added to the send queue. This allows events to post additional events to the connection that will be send _before_ this event |
|
|
notifySent is called on each event after all of the events for a packet have been written into the packet stream.
|
|
||||||||||||
|
notifyDelivered is called on the source event after it has been received and processed by the other side of the connection. If the packet delivery fails on an unguaranteed event, madeIt will be false, otherwise it will be true. |
|
|
getEventDirection returns the direction this event is allowed to travel in on a connection
|
|
|
getDebugName is used to construct event names for packet logging in debug mode.
|
Friends And Related Function Documentation
|
|
|
Field Documentation
|
|
Direction this event is allowed to travel in the network.
|
|
|
Type of data guarantee this event supports.
|