Torque2D Reference

- Main Page
- Related Pages
- Modules
- Namespaces
- Classes

- Class List
- Class Index
- Class Hierarchy
- Class Members

List of all members
NetEvent Class Referenceabstract

`#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