TNL::NetEvent class Reference

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.

TNL lets you pass NetEvent objects across EventConnection instances. There are three types of events:

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.

Of the 5 methods declared above; the constructor and destructor need only do whatever book-keeping is needed for the specific implementation, in addition to calling the NetEvent constructor with the direction and type information that the networking system needs to function. In this case, the SimpleMessageEvent simply allocates/deallocates the space for the string, and specifies the event as guaranteed ordered and bidirectional.

       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

enum TNL::NetEvent::EventDirection

Enumeration values:

DirUnset Default value - NetConnection will Assert if an event is posted without a valid direction set.

DirAny This event can be sent from the server or the client.

DirServerToClient This event can only be sent from the server to the client.

DirClientToServer This event can only be sent from the client to the server.

enum TNL::NetEvent::GuaranteeType

Enumeration values:

GuaranteedOrdered Event delivery is guaranteed and will be processed in the order it was sent relative to other ordered events.

Guaranteed Event delivery is guaranteed and will be processed in the order it was received.

Unguaranteed Event delivery is not guaranteed - however, the event will remain ordered relative to other unguaranteed events.

Constructor & Destructor Documentation

TNL::NetEvent::NetEvent ( GuaranteeType gType = GuaranteedOrdered,

EventDirection evDir = DirUnset

) [inline]

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

virtual void TNL::NetEvent::pack ( EventConnection * ps,

BitStream * bstream

) [pure virtual]

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.

virtual void TNL::NetEvent::unpack ( EventConnection * ps,

BitStream * bstream

) [pure virtual]

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.

virtual void TNL::NetEvent::process ( EventConnection * ps ) [pure virtual]

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.

virtual void TNL::NetEvent::notifyPosted ( EventConnection * ps ) [inline, virtual]

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

virtual void TNL::NetEvent::notifySent ( EventConnection * ps ) [inline, virtual]

notifySent is called on each event after all of the events for a packet have been written into the packet stream.

virtual void TNL::NetEvent::notifyDelivered ( EventConnection * ps,

bool madeIt

) [inline, virtual]

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.

EventDirection TNL::NetEvent::getEventDirection ( ) [inline]

getEventDirection returns the direction this event is allowed to travel in on a connection

virtual const char* TNL::NetEvent::getDebugName ( ) [inline, virtual]

getDebugName is used to construct event names for packet logging in debug mode.

Friends And Related Function Documentation

friend class EventConnection [friend]

Field Documentation

enum TNL::NetEvent::EventDirection TNL::NetEvent::mEventDirection

Direction this event is allowed to travel in the network.

enum TNL::NetEvent::GuaranteeType TNL::NetEvent::mGuaranteeType

Type of data guarantee this event supports.