#include <netConnection.h>

Inheritance diagram for NetEvent:

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)

Public Member Functions inherited from ConsoleObject
const AbstractClassRep::Field *	findField (StringTableEntry fieldName) const
	Get a reference to a field by name. More...

virtual AbstractClassRep *	getClassRep () const
	Gets the ClassRep. More...

bool	setField (const char fieldName, const char value)
	Set the value of a field. More...

virtual	~ConsoleObject ()

const AbstractClassRep::FieldList &	getFieldList () const
	Get a list of all the fields. This information cannot be modified. More...

AbstractClassRep::FieldList &	getModifiableFieldList ()

bool &	getDynamicGroupExpand ()

S32	getClassId (U32 netClassGroup) const

const char *	getClassName () const

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 ()

Additional Inherited Members
Static Public Member Functions inherited from ConsoleObject
static const char *	lookupClassName (const U32 in_classTag)
	Get the classname from a class tag. More...

static void	initPersistFields ()

static void	consoleInit ()

static ConsoleObject *	create (const char *in_pClassName)

static ConsoleObject *	create (const U32 groupId, const U32 typeId, const U32 in_classId)

static AbstractClassRep *	getStaticClassRep ()
	Get the abstract class information for this class. More...

static AbstractClassRep *	getParentStaticClassRep ()
	Get the abstract class information for this class's superclass. More...

Protected Member Functions inherited from ConsoleObject
	ConsoleObject ()

	ConsoleObject (const ConsoleObject &)

Static Protected Member Functions inherited from ConsoleObject
static void	addGroup (const char in_pGroupname, const char in_pGroupDocs=NULL)

static void	endGroup (const char *in_pGroupname)

static void	addField (const char in_pFieldname, const U32 in_fieldType, const dsize_t in_fieldOffset, const U32 in_elementCount=1, EnumTable in_table=NULL, const char *in_pFieldDocs=NULL)

static void	addField (const char in_pFieldname, const U32 in_fieldType, const dsize_t in_fieldOffset, AbstractClassRep::WriteDataNotify in_writeDataFn, const U32 in_elementCount=1, EnumTable in_table=NULL, const char *in_pFieldDocs=NULL)

static void	addField (const char in_pFieldname, const U32 in_fieldType, const dsize_t in_fieldOffset, const char in_pFieldDocs)

static void	addField (const char in_pFieldname, const U32 in_fieldType, const dsize_t in_fieldOffset, AbstractClassRep::WriteDataNotify in_writeDataFn, const char in_pFieldDocs)

static void	addFieldV (const char in_pFieldname, const U32 in_fieldType, const dsize_t in_fieldOffset, ConsoleTypeValidator v, const char *in_pFieldDocs=NULL)

static void	addProtectedField (const char in_pFieldname, const U32 in_fieldType, const dsize_t in_fieldOffset, AbstractClassRep::SetDataNotify in_setDataFn, AbstractClassRep::GetDataNotify in_getDataFn=&defaultProtectedGetFn, const U32 in_elementCount=1, EnumTable in_table=NULL, const char *in_pFieldDocs=NULL)

static void	addProtectedField (const char in_pFieldname, const U32 in_fieldType, const dsize_t in_fieldOffset, AbstractClassRep::SetDataNotify in_setDataFn, AbstractClassRep::GetDataNotify in_getDataFn=&defaultProtectedGetFn, AbstractClassRep::WriteDataNotify in_writeDataFn=&defaultProtectedWriteFn, const U32 in_elementCount=1, EnumTable in_table=NULL, const char *in_pFieldDocs=NULL)

static void	addProtectedField (const char in_pFieldname, const U32 in_fieldType, const dsize_t in_fieldOffset, AbstractClassRep::SetDataNotify in_setDataFn, AbstractClassRep::GetDataNotify in_getDataFn=&defaultProtectedGetFn, const char in_pFieldDocs=NULL)

static void	addProtectedField (const char in_pFieldname, const U32 in_fieldType, const dsize_t in_fieldOffset, AbstractClassRep::SetDataNotify in_setDataFn, AbstractClassRep::GetDataNotify in_getDataFn=&defaultProtectedGetFn, AbstractClassRep::WriteDataNotify in_writeDataFn=&defaultProtectedWriteFn, const char in_pFieldDocs=NULL)

static void	addDepricatedField (const char *fieldName)

static bool	removeField (const char *in_pFieldname)

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.

Member Typedef Documentation

typedef ConsoleObject Parent

Member Enumeration Documentation

anonymous enum

Enumerator
GuaranteedOrdered
Guaranteed
Unguaranteed

Constructor & Destructor Documentation

NetEvent ( )

inline

~NetEvent ( )

virtual

Member Function Documentation

void decRef ( )

inline

void incRef ( )

inline

void notifyDelivered	(	NetConnection *	ps,
		bool	madeit
	)

virtual

Reimplemented in FileChunkEvent, and NetStringEvent.

void notifySent ( NetConnection * ps )

virtual

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

pure virtual

Implemented in FileChunkEvent, RemoteCommandEvent, ConnectionMessageEvent, FileDownloadRequestEvent, GhostAlwaysObjectEvent, SimpleMessageEvent, and NetStringEvent.

virtual void process ( NetConnection * ps )

pure virtual

Implemented in FileChunkEvent, GhostAlwaysObjectEvent, RemoteCommandEvent, FileDownloadRequestEvent, ConnectionMessageEvent, NetStringEvent, and SimpleMessageEvent.

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

pure virtual

Implemented in FileChunkEvent, RemoteCommandEvent, GhostAlwaysObjectEvent, ConnectionMessageEvent, FileDownloadRequestEvent, NetStringEvent, and SimpleMessageEvent.

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

pure virtual

Implemented in FileChunkEvent, RemoteCommandEvent, ConnectionMessageEvent, GhostAlwaysObjectEvent, FileDownloadRequestEvent, SimpleMessageEvent, and NetStringEvent.

Member Data Documentation

enum { ... } mGuaranteeType

S32 mRefCount

NetConnectionId mSourceId

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

network/netConnection.h
network/netEvent.cc

Public Member Functions

Implementation Details

Additional Inherited Members

Detailed Description

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation