NetEvent

Engine/source/sim/netConnection.h

An event to be sent over the network.

More...

_Anonymous_ {
  GuaranteedOrdered = 0
  Guaranteed = 1
  Unguaranteed = 2
}

void

incRef()

void

decRef()

enum NetEvent::@174

mGuaranteeType 

NetConnectionId

mSourceId 

ConsoleObject

Parent 

NetEvent()

~NetEvent()

void

write(NetConnection * ps, BitStream * bstream)

void

pack(NetConnection * ps, BitStream * bstream)

void

unpack(NetConnection * ps, BitStream * bstream)

void

process(NetConnection * ps)

void

notifySent(NetConnection * ps)

void

notifyDelivered(NetConnection * ps, bool madeit)

DECLARE_ABSTRACT_CLASS(NetEvent , ConsoleObject )

DECLARE_INSCOPE(NetAPI )

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.

• 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.

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!"));

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.

@174

incRef()

decRef()

enum NetEvent::@174 mGuaranteeType 

NetConnectionId mSourceId 

typedef ConsoleObject Parent 

NetEvent()

~NetEvent()

write(NetConnection * ps, BitStream * bstream)

pack(NetConnection * ps, BitStream * bstream)

unpack(NetConnection * ps, BitStream * bstream)

process(NetConnection * ps)

notifySent(NetConnection * ps)

notifyDelivered(NetConnection * ps, bool madeit)

DECLARE_ABSTRACT_CLASS(NetEvent , ConsoleObject )

DECLARE_INSCOPE(NetAPI )