---

GNE::Connection Class Reference
[Mid-Level API]

#include <Connection.h>

Inheritance diagram for GNE::Connection:

List of all members.

Public Types
typedef SmartPtr< Connection >	sptr
typedef WeakPtr< Connection >	wptr
enum	State {   NeedsInitialization, ReadyToConnect, Connecting, Connected,   Disconnecting, Disconnected }
	Represents the states a Connection object can be in. More...
Public Member Functions
virtual	~Connection ()
	Destructor.
SmartPtr< ConnectionListener >	getListener () const
	Returns the currently registered event Listener.
void	setListener (const SmartPtr< ConnectionListener > &listener)
	Sets a new event listener.
int	getTimeout ()
	Returns the timeout for this connection.
void	setTimeout (int ms)
	Sets the timeout for this connection in milliseconds.
PacketStream &	stream ()
	Returns the PacketStream associated with this class.
ConnectionStats	getStats (int reliable) const
	If stats is enabled, returns Connection stats.
Address	getLocalAddress (bool reliable) const
	Returns the local address of this connection.
Address	getRemoteAddress (bool reliable) const
	Returns the remote address of this connection.
State	getState () const
	Returns the state this Connection is in.
bool	isConnected () const
	Returns true if this Connection is active and ready to send/recieve.
void	disconnect ()
	Immediately disconnects this socket.
void	disconnectSendAll (int waitTime=10000)
	A blocking call that disconnects nicely.
Static Public Member Functions
void	disconnectAll ()
	Disconnects all active connections in the GNE system.
Protected Member Functions
	Connection ()
	Intializes this class with a NULL listener, which must be set before any operations are performed on this instance.
void	setThisPointer (const wptr &weakThis)
	This method must be called and set to a weak pointer referencing this object before the end of the static create function of the child class.
void	addHeader (Buffer &raw)
	A utility function for ServerConnection and ClientConnection to add the standard header onto the connection packets.
void	addVersions (Buffer &raw)
	A utility function for ServerConnection and ClientConnection to add the version information to a packet.
void	checkHeader (Buffer &raw, ProtocolViolation::ViolationType t=ProtocolViolation::OtherViolation)
	A utility function for ServerConnection and ClientConnection to check to verify the GNE header of the connecting packets.
void	checkVersions (Buffer &raw)
	A utility function for ServerConnection and ClientConnection to check the GNE version, game name, and user versions in the Buffer.
void	onReceive ()
void	finishedInit ()
	The Connection has finished initializing and the state now can change to ReadyToConnect.
void	startConnecting ()
	Moves from ReadyToConnect to Connecting state.
void	startThreads ()
	Does the work needed to start up the PacketStream and EventThread thrads.
void	finishedConnecting ()
	The connecting has just finished and the state needs to be changed.
void	reg (bool reliable, bool unreliable)
	Register this Connection object's sockets with the ConnectionEventGenerator.
void	unreg (bool reliable, bool unreliable)
	Unregistered the sockets which are specified by passing true to the appropriate parameter.
Protected Attributes
wptr	this_
	A weak pointer to this own object.
SocketPair	sockets
	The pair of sockets.
PacketStream::sptr	ps
	The PacketStream associated with this Connection.
Friends
class	Listener
	Make Listener a friend so it can call our onRecieve(bool) event, which will properly parse the packets.
class	PacketStream
class	SyncConnection

---

Detailed Description

A class resembling any type of connection to a remote computer. A connection also manages flow control through its PacketStream.

When you create a new Connection, you will want to register a ConnectionListener for it so you can receive its events.

You should never create Connection objects directly. You want to create a ClientConnection (ServerConnection objects are created internally by the library).

See also:

ClientConnection::create

---

Member Enumeration Documentation

enum GNE::Connection::State

Represents the states a Connection object can be in. Enumeration values: NeedsInitialization  Connection was just created but needs initializing. ReadyToConnect  Connection is ready to connect. Connecting  Connection is in the middle of connecting. Connected  Connection is connected. Disconnecting  Connection is in the middle of disconnecting. Disconnected  Connection has finished and cannot be restarted.

---

Constructor & Destructor Documentation

GNE::Connection::Connection (   )  [protected]

Intializes this class with a NULL listener, which must be set before any operations are performed on this instance. THE CHILD CLASS IS RESPONSIBLE FOR SETTING THE THISPOINTER. This is because the EventThread needs a SmartPtr to this Connection, which is unknown during construction. See also: setThisPointer()

---

Member Function Documentation

void GNE::Connection::checkHeader (  Buffer &  raw, ProtocolViolation::ViolationType  t = ProtocolViolation::OtherViolation )  [protected]

A utility function for ServerConnection and ClientConnection to check to verify the GNE header of the connecting packets. The Buffer is read from so this function will move the reading position to the next element after the header. If it throws an exception, the read position is undefined. Parameters: t  the type of ProtocolViolation to throw if it throws one. Exceptions: ProtocolViolation  if the next bytes of the Buffer is not the proper GNE header.

void GNE::Connection::checkVersions (  Buffer &  raw  )  [protected]

A utility function for ServerConnection and ClientConnection to check the GNE version, game name, and user versions in the Buffer. This function behaves similarly to checkHeader. Exceptions: Error  with a code of Error::GNETheirVersionHigh or Error::GNETheirVersionLow if the GNE protocol versions do not match. WrongGame  if the game names don't match. UserVersionMismatch  if the user version numbers don't match.

void GNE::Connection::disconnect (   )

Immediately disconnects this socket. No more data will be recieved or sent on this socket. If you want to disconnect more nicely, use disconnectSendAll. It is okay to call this function even when this Connection is already disconnected. Note that even though the connection is disconnected immediately, it is still a graceful close such that an onExit event will be generated on the remote connection if possible, but any packets pending to be sent won't get sent. It is valid to call disconnect while the Connection object is still connecting -- this can be used to "abort" or cancel a connection attempt. NOTE: You may not reconnect this connection object after calling disconnect. See also: disconnectSendAll()

void GNE::Connection::disconnectSendAll (  int  waitTime = 10000  )

A blocking call that disconnects nicely. This has the same effect as disconnect, except that all data waiting to be sent will be sent if possible. If the connection is already disconnected, this function does nothing. Parameters: waitTime  the max amount of time in ms to wait for the outgoing packet queue to clear. See also: disconnect()

void GNE::Connection::finishedInit (   )  [protected]

The Connection has finished initializing and the state now can change to ReadyToConnect. Precondition: state is now NeedsInitialization

ConnectionListener::sptr GNE::Connection::getListener (   )  const

Returns the currently registered event Listener. After GNE 0.55 this method changed so that the return value of this method is either the listener you have set or an empty SmartPtr. It will return an empty SmartPtr if the Connection has been disconnected, but since this can happen at any moment, it can return an empty SmartPtr at any time. Deprecated: The semantics of method have changed to pretty much make it useless. It's probably dangerous to provide this, so I'm considering removing it. If you have a strong case to leave it in, please tell me.

Address GNE::Connection::getLocalAddress (  bool  reliable  )  const

Returns the local address of this connection. If the requested socket has not been opened, the returned Address will be invalid (!isValid()). An invalid address is also returned if the Connection was disconnected, which can happen at any time. Parameters: reliable  sometimes two sockets are used for reliable and unreliable data. Specify which low-level socket you want the address of. See also: GNE::Address

Address GNE::Connection::getRemoteAddress (  bool  reliable  )  const

Returns the remote address of this connection. If the requested socket is not connected, the returned Address will be invalid (!isValid()). An invalid address is also returned if the Connection was disconnected, which can happen at any time. Parameters: reliable  sometimes two sockets are used for reliable and unreliable data. Specify which low-level socket you want the address of. See also: GNE::Address

Connection::State GNE::Connection::getState (   )  const

Returns the state this Connection is in. Note that the state of the connection can change at any moment after this call by GNE if the state is Connecting or Connected. See also: State

ConnectionStats GNE::Connection::getStats (  int  reliable  )  const

If stats is enabled, returns Connection stats. Parameters: reliable  If greater than 0, returns reliable stats only. If 0, returns unreliable transfer stats only. If less than 0, returns cumulative stats for both. Returns: various connection stats. See also: ConnectionStats GNE::enableStats

int GNE::Connection::getTimeout (   )

Returns the timeout for this connection. See also: setTimeout

bool GNE::Connection::isConnected (   )  const

Returns true if this Connection is active and ready to send/recieve. A Connection may become disconnected at any time, as another thread or an event may cause a disconnect. This method returns true if the state is currently "Connected", false if any other state. See also: getState

void GNE::Connection::reg (  bool  reliable, bool  unreliable )  [protected]

Register this Connection object's sockets with the ConnectionEventGenerator. Pass true to register each socket type. Usually both will be registered, but in the future there may exist a new connection type that only uses one of the sockets. The internal class ConnectionListener will be used to trigger the proper onReceive(bool) event. The sockets will be unregistered automatically when the object is destroyed, but they may be unregistered explicitly at an earlier time through unreg(bool, bool). Registering a socket already registered will have no effect. See also: #onReceive(bool) unreg(bool, bool)

void GNE::Connection::setListener (  const SmartPtr< ConnectionListener > &  listener  )

Sets a new event listener. All new events will be sent to the new listener. This method has no effect on an event currently being processed and this method will not block to wait until the listener change has taken place. The next method generated will go to the newly set listener. If the passed listener is NULL, this will hold the event thread. This does NOT stop event generation -- generated events still will enter the queue but the actual event function will not be called until a proper listener is set. If you hold the event thread, a new listener should be set quickly as the connection is basically "frozen" during this time. You MUST have an event listener set because the event thread must call its required events before this object can be destroyed. If you care not to receive events because you are using SyncConnection, you will probably want to set ConnectionListener::getNullListener as the listener to discard all events before you wrap this Connection with a SyncConnection.

void GNE::Connection::setThisPointer (  const wptr &  weakThis  )  [protected]

This method must be called and set to a weak pointer referencing this object before the end of the static create function of the child class. This is needed since some things Connection registers with requires a SmartPtr to itself.

void GNE::Connection::setTimeout (  int  ms  )

Sets the timeout for this connection in milliseconds. A value of 0 signifies that no timeouts should occur. Values less than 0 are invalid. An onTimeout event occurs ms milliseconds after the last onReceive event, the last onTimeout event, or since setTimeout occured. Any of these events sets the "timeout counter" back to zero to say it another way. See also: GNE::ConnectionListener::onTimeout

void GNE::Connection::startThreads (   )  [protected]

Does the work needed to start up the PacketStream and EventThread thrads. Precondition: state must be Connecting.

PacketStream & GNE::Connection::stream (   )

Returns the PacketStream associated with this class. Writing and reading through this Connection is done through this PacketStream. You should not keep a reference to this PacketStream object any longer than you keep the reference to the Connection object.

void GNE::Connection::unreg (  bool  reliable, bool  unreliable )  [protected]

Unregistered the sockets which are specified by passing true to the appropriate parameter. This function call is optional -- when the object is destroyed, unregistering is automatic if socket was registered. Trying to unregister sockets that are already unregistered will result in no effect.

---

Member Data Documentation

PacketStream::sptr GNE::Connection::ps [protected]

The PacketStream associated with this Connection. This object also contains information about the in and out connection rates.

---

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

• Connection.h
• Connection.cpp

---