Torque Game Engine Documentation
TGE Version 1.5.2

NetEvent Class Reference

#include <netConnection.h>

Inheritance diagram for NetEvent:

[legend]

Detailed Description

An event to be sent over the network.

Note:: Torque implements two methods of network data passing; this is one of them. See NetConnection for details of the other, which is referred to as ghosting.

Torque's network layer lets you pass events to/from the server. 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 position updates or voice communication.
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.
GuaranteedOrdered events are events which are guaranteed not only to be delivered, but to be delivered in order. This is good for information which is not only important, but also order-critical, like chat messages.

There are 6 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.
 // This is based on the code in netTest.cc
 class SimpleMessageEvent : public NetEvent
 {
    typedef NetEvent Parent;
    char *msg;
 public:
    SimpleMessageEvent(const char *message = NULL);
    ~SimpleMessageEvent();

    virtual void pack   (NetConnection *conn, BitStream *bstream);
    virtual void write  (NetConnection *conn, BitStream *bstream);
    virtual void unpack (NetConnection *conn, BitStream *bstream);
    virtual void process(NetConnection *conn);

    DECLARE_CONOBJECT(SimpleMessageEvent);
 };

 IMPLEMENT_CO_NETEVENT_V1(SimpleMessageEvent);

Notice the two macros which we call. The first, DECLARE_CONOBJECT() is there because we're a ConsoleObject. The second, IMPLEMENT_CO_NETEVENT_V1(), is there to register this event type with Torque's networking layer, so that it can be properly transmitted over the wire. There are three macros which you might use:

IMPLEMENT_CO_NETEVENT_V1, which indicates an event which may be sent in either direction, from the client to the server, or from the server to the client.
IMPLEMENT_CO_CLIENTEVENT_V1, which indicates an event which may only be sent to the client.
IMPLEMENT_CO_SERVEREVENT_V1, which indicates an event which may only be sent to the server.

Choosing the right macro is a good way to make your game more resistant to hacking; for instance, PathManager events are marked as CLIENTEVENTs, because they would cause the server to crash if a client sent them.

Note:: Torque allows you to call NetConnection::setLastError() on the NetConnection passed to your NetEvent. You can cause the connection to abort if invalid data is received, specifying a reason to the user.

Now, the 6 methods which we have above; the constructor and destructor need only do whatever book-keeping is needed for your specific implementation. In our case, we just need to allocate/deallocate the space for our string:

    SimpleMessageEvent::SimpleMessageEvent(const char *message = NULL)
    {
       // If we wanted to make this not be a GuaranteedOrdered event, we'd
       // put a line like this in the constructor:
       // mGuaranteeType = Guaranteed;
       // (or whatever type you wanted.)
       if(message)
          msg = dStrdup(message);
       else
          msg = NULL;
    }

    SimpleMessageEvent::~SimpleMessageEvent()
    {
      dFree(msg);
    }

Simple as that! Now, onto pack(), write(), unpack(), process().

pack() is responsible for packing the event over the wire:

 void SimpleMessageEvent::pack(NetConnection* 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(NetConnection *conn, BitStream *bstream)
 {
   char buf[256];
   bstream->readString(buf);
   msg = dStrdup(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 also been dealt with.

 // This just prints the event in the console. You might
 // want to do something more clever here -- BJG
 void SimpleMessageEvent::process(NetConnection *conn)
 {
   Con::printf("RMSG %d  %s", mSourceId, msg);
 }

write() is called if a demo recording is started, and the event has not yet been processed, but it has been unpacked. It should be identical in its output to the bitstream compared to pack(), but since it is called after unpack() some lookups may not need to be performed. In normal demo recording, whole network packets are recorded, meaning that most of the time write() will not be called.

In our case, it's entirely identical to pack():

 virtual void write(NetConnection*, BitStream *bstream)
 {
   bstream->writeString(msg);
 }

The NetEvent is sent over the wire in a straightforward way (assuming you have a handle to a NetConnection):

 NetConnection *conn; // We assume you have filled this in.

 con->postNetEvent(new SimpleMessageEvent("This is a test!"));

See also:: GhostAlwaysObjectEvent for an example of dissimilar write()/pack() methods.

Finally, for more advanced applications, notifySent() is called whenever the event is sent over the wire, in NetConnection::eventWritePacket(). notifyDelivered() is called when the packet is finally received or (in the case of Unguaranteed packets) dropped.

Note:: IMPLEMENT_CO_NETEVENT_V1 and co. have sibling macros which allow you to specify a groupMask; see ConsoleObject for a further discussion of this.

Implementation Details

These are internal fields which you won't need to manipulate, except for mGuaranteeType.

typedef ConsoleObject Parent

S32 mRefCount

enum NetEvent::{
  GuaranteedOrdered = 0,
  Guaranteed = 1,
  Unguaranteed = 2
} mGuaranteeType

NetConnectionId mSourceId

void incRef ()

void decRef ()

Public Member Functions

Things To Subclass

NetEvent ()

virtual ~NetEvent ()

virtual void write (NetConnection *ps, BitStream *bstream)=0

virtual void pack (NetConnection *ps, BitStream *bstream)=0

virtual void unpack (NetConnection *ps, BitStream *bstream)=0

virtual void process (NetConnection *ps)=0

virtual void notifySent (NetConnection *ps)

virtual void notifyDelivered (NetConnection *ps, bool madeit)

Member Typedef Documentation

typedef ConsoleObject NetEvent::Parent

Reimplemented in WeatherLightningStrikeEvent.

Member Enumeration Documentation

anonymous enum

Enumerator:

GuaranteedOrdered
Guaranteed
Unguaranteed

Constructor & Destructor Documentation

NetEvent::NetEvent ( ) [inline]

virtual NetEvent::~NetEvent ( ) [virtual]

Member Function Documentation

void NetEvent::incRef ( ) [inline]

void NetEvent::decRef ( ) [inline]

virtual void NetEvent::write	(	NetConnection *	ps,
		BitStream *	bstream
	)			`[pure virtual]`

Implemented in WeatherLightningStrikeEvent, SimDataBlockEvent, Sim2DAudioEvent, Sim3DAudioEvent, and SetMissionCRCEvent.

virtual void NetEvent::pack	(	NetConnection *	ps,
		BitStream *	bstream
	)			`[pure virtual]`

Implemented in WeatherLightningStrikeEvent, SimDataBlockEvent, Sim2DAudioEvent, Sim3DAudioEvent, and SetMissionCRCEvent.

virtual void NetEvent::unpack	(	NetConnection *	ps,
		BitStream *	bstream
	)			`[pure virtual]`

Implemented in WeatherLightningStrikeEvent, SimDataBlockEvent, Sim2DAudioEvent, Sim3DAudioEvent, and SetMissionCRCEvent.

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

Implemented in WeatherLightningStrikeEvent, SimDataBlockEvent, Sim2DAudioEvent, Sim3DAudioEvent, and SetMissionCRCEvent.

virtual void NetEvent::notifySent ( NetConnection * ps ) [virtual]

virtual void NetEvent::notifyDelivered	(	NetConnection *	ps,
		bool	madeit
	)			`[virtual]`

Reimplemented in SimDataBlockEvent.

Field Documentation

S32 NetEvent::mRefCount

enum { ... } NetEvent::mGuaranteeType

NetConnectionId NetEvent::mSourceId