/// @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:
/// - <b>Unguaranteed events</b> 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.
/// - <b>Guaranteed events</b> 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.
/// - <b>GuaranteedOrdered events</b> 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.
/// @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 net_event objects across event_connection instances. There are three types of events:
/// - <b>unguaranteed events</b> 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.
/// - <b>guaranteed events</b> 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.
/// - <b>guaranteed_ordered events</b> 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 net_event subclass, and 2 macros you need to call.
///
/// @code
/// // A simple NetEvent to transmit a string over the network.
/// class SimpleMessageEvent : public NetEvent
/// // A simple net_event to transmit a string over the network.
/// The first macro called, TORQUE_DECLARE_CLASS() registers the static class functions and ClassRep object that will assign
/// this class a network ID and allow instances to be constructed by ID.
///
/// The second, TNL_IMPLEMENT_NETEVENT(), instantiates the ClassRep 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:
/// - <b>NetEvent::GuaranteedOrdered</b>, for guaranteed, ordered events
/// - <b>NetEvent::Guaranteed</b>, for guaranteed events
/// - <b>NetEvent::Unguaranteed</b>, 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:
/// - <b>NetEvent::DirAny</b>, this event can be sent from server to client
/// or from client to server
/// - <b>NetEvent::DirServerToClient</b>, 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.
/// - <b>NetEvent::DirClientToServer</b>, 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.
/// The first macro called, TORQUE_DECLARE_CLASS() registers the static class functions and ClassRep object that will assign this class a network ID and allow instances to be constructed by ID.
///
/// The second, TNL_IMPLEMENT_NETEVENT(), instantiates the ClassRep and tells it that the instances are net_event 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 net_event class. The guarantee type can be one of:
/// - <b>net_event::guaranteed_ordered</b>, for guaranteed, ordered events
/// - <b>net_event::guaranteed</b>, for guaranteed events
/// - <b>net_event::unguaranteed</b>, 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:
/// - <b>net_event::DirAny</b>, this event can be sent from server to client or from client to server
/// - <b>net_event::DirServerToClient</b>, 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.
/// - <b>net_event::DirClientToServer</b>, 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 event_connection passed to the net_event. 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 net_event 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.
/// <b>process()</b> 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.
/// <b>process()</b> is called when the network layer is finished with things. A typical case is that a guaranteed_ordered event is unpacked and stored, but not processed until the events preceding it in the sequence have been process()'d.
///
/// @code
/// // This just prints the event in the log. You might
/// logprintf("Received a SimpleMessageEvent: %s", msg);
///
@@ -142,97 +105,77 @@
/// Posting an event to the remote host on a connection is simple:
///
/// @code
/// EventConnection *conn; // We assume you have filled this in.
/// event_connection *conn; // We assume you have filled this in.
///
/// conn->postNetEvent(new SimpleMessageEvent("This is a test!"));
/// @endcode
///
/// 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.
/// Finally, for more advanced applications, notify_posted() is called when the event is posted into the send queue, notify_sent() is called whenever the event is sent over the wire, in event_connection::eventWritePacket(). notify_delivered() 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.
classNetEvent:publicObject
/// @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.
classnet_event:publicref_object
{
friendclassEventConnection;
friendclassevent_connection;
public:
enumEventDirection{
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
}mEventDirection;///< Direction this event is allowed to travel in the network
enumevent_direction{
bidirectional,///< This event can be sent from either the initiator or the host of the connection.
downstream,///< This event can only be sent from the host to the initiator
upstream,///< This event can only be sent from the initiator to the host
}_event_direction;///< Direction this event is allowed to travel in the network
enumGuaranteeType{
GuaranteedOrdered=0,///< Event delivery is guaranteed and will be processed in the order it
/// was sent relative to other ordered events.
Guaranteed=1,///< Event delivery is guaranteed and will be processed in the order it
/// was received.
Unguaranteed=2///< Event delivery is not guaranteed - however, the event will remain
/// ordered relative to other unguaranteed events.
}mGuaranteeType;///< Type of data guarantee this event supports
enumguarantee_type{
guaranteed_ordered=0,///< Event delivery is guaranteed and will be processed in the order it was sent relative to other ordered events.
guaranteed=1,///< Event delivery is guaranteed and will be processed in the order it was received.
unguaranteed=2///< Event delivery is not guaranteed - however, the event will remain ordered relative to other unguaranteed events.
}_guarantee_type;///< Type of data guarantee this event supports
/// 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.
/// Subclasses MUST pass in an event direction and guarantee type, or else the network system will error on the event. Events are by default guaranteed_ordered, however, the default direction is unset which will result in asserts.
/// 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.
virtualvoidprocess(EventConnection*ps)=0;
/// 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.
virtualvoidprocess(event_connection*ps)=0;
/// 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
virtualvoidnotifyPosted(EventConnection*ps){}
/// notify_posted is called on an event when it is posted to a particular event_connection, 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
virtualvoidnotify_posted(event_connection*ps){}
/// notifySent is called on each event after all of the events for a packet have
/// been written into the packet stream.
virtualvoidnotifySent(EventConnection*ps){}
/// notify_sent is called on each event after all of the events for a packet have been written into the packet stream.
virtualvoidnotify_sent(event_connection*ps){}
/// notifyDelivered is called on the source event after it has been received
/// and processed by the other side of the connection.
/// notify_delivered 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
