---

TNL::NetEvent Class Reference

An event to be sent over the network. More...

#include <tnlNetEvent.h>

Inheritance diagram for TNL::NetEvent:

List of all members.

Public Types
enum	EventDirection { DirUnset, DirAny, DirServerToClient, DirClientToServer }
enum	GuaranteeType { GuaranteedOrdered = 0, Guaranteed = 1, Unguaranteed = 2 }
Public Methods
	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.
Public Attributes
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.

---

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.

Definition at line 197 of file tnlNetEvent.h.

---

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. Definition at line 201 of file tnlNetEvent.h. Referenced by getEventDirection(), and NetEvent().

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. Definition at line 208 of file tnlNetEvent.h. Referenced by NetEvent().

---

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. Definition at line 222 of file tnlNetEvent.h. References DirUnset, EventDirection, GuaranteedOrdered, GuaranteeType, mEventDirection, and mGuaranteeType.

---

Member Function Documentation

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. Definition at line 256 of file tnlNetEvent.h.

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 Definition at line 245 of file tnlNetEvent.h. Referenced by TNL::EventConnection::postNetEvent().

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. Referenced by TNL::EventConnection::processEvent().

---

The documentation for this class was generated from the following file:

• /home/rdbrown/doxygen/cse125g1/src/modules/tnl/tnlNetEvent.h

---