ReadyEvent Class Reference
[ReadyEvent]

#include <ReadyEvent.h>

Inheritance diagram for ReadyEvent:

PluginInterface

List of all members.

Public Member Functions

 ReadyEvent ()
 Constructor.
virtual ~ReadyEvent ()
 Destructor.
bool SetEvent (int eventId, bool isReady)
bool DeleteEvent (int eventId)
bool IsEventSet (int eventId)
bool IsEventCompletionProcessing (int eventId) const
bool IsEventCompleted (int eventId) const
bool HasEvent (int eventId)
unsigned GetEventListSize (void) const
int GetEventAtIndex (unsigned index) const
bool AddToWaitList (int eventId, SystemAddress address)
bool RemoveFromWaitList (int eventId, SystemAddress address)
bool IsInWaitList (int eventId, SystemAddress address)
unsigned GetRemoteWaitListSize (int eventId) const
SystemAddress GetFromWaitListAtIndex (int eventId, unsigned index) const
ReadyEventSystemStatus GetReadyStatus (int eventId, SystemAddress address)
void SetSendChannel (unsigned char newChannel)

Protected Member Functions

void OnAttach (RakPeerInterface *peer)
virtual PluginReceiveResult OnReceive (RakPeerInterface *peer, Packet *packet)
virtual void OnCloseConnection (RakPeerInterface *peer, SystemAddress systemAddress)
virtual void OnShutdown (RakPeerInterface *peer)


Detailed Description

Ready event plugin Used to signal event completion when a set of systems all set a signal flag to true. This is usually used for lobby systems, or peer to peer turn based environments. The user will get ID_READY_EVENT_SET and ID_READY_EVENT_UNSET as the signal flag is set or unset The user will get ID_READY_EVENT_ALL_SET when all systems are done waiting for all other systems, in which case the event is considered complete, and no longer tracked.

Member Function Documentation

bool ReadyEvent::SetEvent ( int  eventId,
bool  isReady 
)

Sets or updates the initial ready state for our local system. If eventId is an unknown event the event is created. If eventId was previously used and you want to reuse it, call DeleteEvent first, or else you will keep the same event signals from before Systems previously or later added through AddToWaitList() with the same eventId when isReady=true will get ID_READY_EVENT_SET Systems previously added through AddToWaitList with the same eventId will get ID_READY_EVENT_UNSET For both ID_READY_EVENT_SET and ID_READY_EVENT_UNSET, eventId is encoded in bytes 1 through 1+sizeof(int)

Note:
Setting isReady to false will fail during the finalization sequence, where any system our the wait list has returned ID_READY_EVENT_ALL_SET
Parameters:
[in] eventId A user-defined identifier to wait on. This can be a sequence counter, an event identifier, or anything else you want.
[in] isReady True to signal we are ready to proceed with this event, false to unsignal
Returns:
True on success. False (failure) on unknown eventId, or during the finalization process

bool ReadyEvent::DeleteEvent ( int  eventId  ) 

Deletes an event. We will no longer wait for this event, and any systems that we know have set the event will be forgotten. Call this to clear memory when events are completed and you know you will never need them again.

Parameters:
[in] eventId A user-defined identifier
Returns:
True on success. False (failure) on unknown eventId

bool ReadyEvent::IsEventSet ( int  eventId  ) 

Returns what was passed to SetEvent()

Returns:
The value of isReady passed to SetEvent(). Also returns false on unknown event.

bool ReadyEvent::IsEventCompletionProcessing ( int  eventId  )  const

Returns if the event is about to be ready and we are negotiating the final packets. This will usually only be true for a very short time, after which IsEventCompleted should return true. While this is true you cannot add to the wait list, or SetEvent() isReady to false anymore.

Parameters:
[in] eventId A user-defined identifier
Returns:
True if any other system has completed processing. Will always be true if IsEventCompleted() is true

bool ReadyEvent::IsEventCompleted ( int  eventId  )  const

Returns if the wait list is a subset of the completion list. Call this after all systems you want to wait for have been added with AddToWaitList

Parameters:
[in] eventId A user-defined identifier
Returns:
True on completion. False (failure) on unknown eventId, or the set is not completed.

bool ReadyEvent::HasEvent ( int  eventId  ) 

Returns if this is a known event. Events may be known even if we never ourselves referenced them with SetEvent, because other systems created them via ID_READY_EVENT_SET.

Parameters:
[in] eventId A user-defined identifier
Returns:
true if we have this event, false otherwise

unsigned ReadyEvent::GetEventListSize ( void   )  const

Returns the total number of events stored in the system.

Returns:
The total number of events stored in the system.

int ReadyEvent::GetEventAtIndex ( unsigned  index  )  const

Returns the event ID stored at a particular index. EventIDs are stored sorted from least to greatest.

Parameters:
[in] index Index into the array, from 0 to GetEventListSize()
Returns:
The event ID stored at a particular index

bool ReadyEvent::AddToWaitList ( int  eventId,
SystemAddress  address 
)

Adds a system to wait for to signal an event before considering the event complete and returning ID_READY_EVENT_ALL_SET. As we add systems, if this event was previously set to true with SetEvent, these systems will get ID_READY_EVENT_SET. As these systems disconnect (directly or indirectly through the router) they are removed.

Note:
If the event completion process has already started, you cannot add more systems, as this would cause the completion process to fail
Parameters:
[in] eventId A user-defined number previously passed to SetEvent that has not yet completed
[in] addressArray An address to wait for event replies from. Pass UNASSIGNED_SYSTEM_ADDRESS for all currently connected systems. Until all systems in this list have called SetEvent with this ID and true, and have this system in the list, we won't get ID_READY_EVENT_COMPLETE
Returns:
True on success, false on unknown eventId (this should be considered an error), or if the completion process has already started.

bool ReadyEvent::RemoveFromWaitList ( int  eventId,
SystemAddress  address 
)

Removes systems from the wait list, which should have been previously added with AddToWaitList

Note:
Systems that directly or indirectly disconnect from us are automatically removed from the wait list
Parameters:
[in] address The system to remove from the wait list. Pass UNASSIGNED_SYSTEM_ADDRESS for all currently connected systems.
Returns:
True on success, false on unknown eventId (this should be considered an error)

bool ReadyEvent::IsInWaitList ( int  eventId,
SystemAddress  address 
)

Returns if a particular system is waiting on a particular event.

Parameters:
[in] eventId A user-defined identifier
[in] The address of the system we are checking up on
Returns:
True if this system is waiting on this event, false otherwise.

unsigned ReadyEvent::GetRemoteWaitListSize ( int  eventId  )  const

Returns the total number of systems we are waiting on for this event. Does not include yourself

Parameters:
[in] eventId A user-defined identifier
Returns:
The total number of systems we are waiting on for this event.

SystemAddress ReadyEvent::GetFromWaitListAtIndex ( int  eventId,
unsigned  index 
) const

Returns the system address of a system at a particular index, for this event.

Parameters:
[in] eventId A user-defined identifier
[in] index Index into the array, from 0 to GetWaitListSize()
Returns:
The system address of a system at a particular index, for this event.

ReadyEventSystemStatus ReadyEvent::GetReadyStatus ( int  eventId,
SystemAddress  address 
)

For a remote system, find out what their ready status is (waiting, signaled, complete).

Parameters:
[in] eventId A user-defined identifier
[in] address Which system we are checking up on
Returns:
The status of this system, for this particular event.
See also:
ReadyEventSystemStatus

void ReadyEvent::SetSendChannel ( unsigned char  newChannel  ) 

This channel will be used for all RakPeer::Send calls

Parameters:
[in] newChannel The channel to use for internal RakPeer::Send calls from this system. Defaults to 0.

void ReadyEvent::OnAttach ( RakPeerInterface peer  )  [protected, virtual]

Called when the interface is attached

Parameters:
[in] peer the instance of RakPeer that is calling Receive

Reimplemented from PluginInterface.

PluginReceiveResult ReadyEvent::OnReceive ( RakPeerInterface peer,
Packet packet 
) [protected, virtual]

OnReceive is called for every packet.

Parameters:
[in] peer the instance of RakPeer that is calling Receive
[in] packet the packet that is being returned to the user
Returns:
True to allow the game and other plugins to get this message, false to absorb it

Reimplemented from PluginInterface.

void ReadyEvent::OnCloseConnection ( RakPeerInterface peer,
SystemAddress  systemAddress 
) [protected, virtual]

Called when a connection is dropped because the user called RakPeer::CloseConnection() for a particular system

Parameters:
[in] peer the instance of RakPeer that is calling Receive
[in] systemAddress The system whose connection was closed

Reimplemented from PluginInterface.

void ReadyEvent::OnShutdown ( RakPeerInterface peer  )  [protected, virtual]

Called when RakPeer is shutdown

Parameters:
[in] peer the instance of RakPeer that is calling Receive

Reimplemented from PluginInterface.


The documentation for this class was generated from the following files:
Generated on Mon Mar 31 21:15:53 2008 for RakNet by  doxygen 1.5.4