---

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

#include <SyncConnection.h>

Inheritance diagram for GNE::SyncConnection:

List of all members.

Public Types
typedef SmartPtr< SyncConnection >	sptr
typedef WeakPtr< SyncConnection >	wptr
Public Member Functions
virtual	~SyncConnection ()
	Destructs this SyncConnection, calling release() if necessary.
SmartPtr< Connection >	getConnection () const
	Returns the underlying Connection.
void	open (const Address &dest, const ConnectionParams &params)
void	connect ()
void	disconnect ()
	Disconnects the underlying Connection.
void	release ()
	Releases this SyncConnection, returning the underlying Connection to its previous event handler.
bool	isReleased () const
	Returns true if release() has been called on this SyncConnection, and it is not a valid object to use anymore.
SyncConnection &	operator>> (Packet &packet)
SyncConnection &	operator<< (const Packet &packet)
	Writes a Packet to the connection by placing it in the outgoing queue.
Static Public Member Functions
sptr	create (const SmartPtr< Connection > &target)
	Creates a new SyncConnection.
Friends
class	ServerConnection
class	ClientConnection

---

Detailed Description

A class for performing syncronous connections. All methods of this class except writing block until completion. This is useful while connecting or performing trivial connections/communications. Many times if you want to perform non-game transfers, for example a server-query connection or another simple service it might be simpler to spawn a new thread and run the SyncConnection while the rest of the program runs.

SyncConnections throw an Error class on an error, so you must use try/catch blocks. Note that the Error class can't describe everything about an error, so sometimes more specific information is available in the debug logs (enable them with GNE::initDebug).

All transfers with SyncConnection are reliable (using TCP, SPX, or similar protocol).

If an error occurs, the connection was terminated. The underlying connection is disconnected, and this SyncConnection becomes released.

When you wrap a Connection with this class, the event listener for that Connection is suspended and SyncConnection "takes over" until it is release()d. So while in syncronous mode you will receive no events through your asyncronous event listener, with the exception of onDisconnect and onConnect. It is best only to use SyncConnection while connecting, because of possible side-effects when you wrap the Connection. If there was already data pending that you did not receive in asyncronous mode -- it was not lost, but you will get it from the next packet read. If you start out with a SyncConnection, then you can be certain no unexpected packets will be arriving.

See the example exsynchello for more help with the usage of this class.

---

Constructor & Destructor Documentation

GNE::SyncConnection::~SyncConnection (   )  [virtual]

Destructs this SyncConnection, calling release() if necessary. If releasing would throw an Error, it is ignored. If you wish to capture all errors, you should call release yourself. See also: release()

---

Member Function Documentation

void GNE::SyncConnection::connect (   )

Your event listener will receive the onConnect event resulting from this -- it is not repressed just like onDisconnect is not repressed. Many times though, when using this method you won't have a need for onConnect, but if you do create one, connect will wait until onConnect is finished. It is important that the wrapped Connection is a ClientConnection, otherwise undefined behavior (likely a crash) will result. Exceptions: Error  if the connection failed.

SyncConnection::sptr GNE::SyncConnection::create (  const SmartPtr< Connection > &  target  )  [static]

Creates a new SyncConnection. Pass in the Connection that you want to wrap. See the details above for more information.

void GNE::SyncConnection::disconnect (   )

Disconnects the underlying Connection. It is best to use this function instead of getConnection()->disconnect() because this will make sure any pending writes will have completed through a call to release(). Exceptions: Error  if release throws an error, or if the disconnection was unsuccessful.

void GNE::SyncConnection::open (  const Address &  dest, const ConnectionParams &  params )

If the open failed, an Error is thrown. It is important that the wrapped Connection is a ClientConnection, otherwise undefined behavior (likely a crash) will result. Exceptions: Error  if the connection could not be opened.

SyncConnection & GNE::SyncConnection::operator<< (  const Packet &  packet  )

Writes a Packet to the connection by placing it in the outgoing queue. This method actually doesn't block like every other SyncConnection method, but on a write there is no reason to block, since it will not effect the logic of the code. This allows for packet caching to improve network performance, and allows you to perform reads while the connection is still writing. All of this is transparent to your logic, though. release() will block until all writes are completed, and the destructor and disconnect() function call release() if needed. A SyncConnection should be released or destroyed before the start of GNE shutdown if you want to guarantee all packet sends were attempted. Exceptions: Error  if an error occured while writing, or an error occured since the last interaction with this object.

SyncConnection & GNE::SyncConnection::operator>> (  Packet &  packet  )

You should provide an already allocated packet whose Packet::readPacket function will be called. There will be type checking performed before this call to make sure the right packet is being read. If there is a mismatch, an error is thrown. The passed packet is untouched, and the connection remains connected; however, the data just received (the incorrect packet) is lost. The connection will remain connected in this case. Exceptions: PacketTypeMismatch  if the read packet was of the wrong type. Error  if an error occured while reading, or an error occured since the last interaction with this object.

void GNE::SyncConnection::release (   )

Releases this SyncConnection, returning the underlying Connection to its previous event handler. Once a SyncConnection has been released, then it is essentially in an invalid state and should not be used anymore (with the exception of the dtor, getConnection(), isReleased(), and this function). This function throws an Error if some underlying pending operations failed since the last call on this SyncConnection. If release is called when the SyncConnection is already released, no errors will be thrown. onReceive will be called in the original listener after release if necessary, and onDoneWriting will be called after release if any data since writing packets. Exceptions: Error  if an error has occured since the last operation on this SyncConnection instance.

---

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

• SyncConnection.h
• SyncConnection.cpp

---