#include <SyncConnection.h>
Inheritance diagram for GNE::SyncConnection:
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 ¶ms) |
| 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 | |
| static sptr | create (const SmartPtr< Connection > &target) |
| Creates a new SyncConnection. | |
Friends | |
| class | ServerConnection |
| class | ClientConnection |
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 synchronous mode you will receive no events through your asynchronous 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 asynchronous 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.
| 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.
| 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.
| 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().
| 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.
| 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.
| Error | if an error occurred while writing, or an error occurred 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.
| PacketTypeMismatch | if the read packet was of the wrong type. | |
| Error | if an error occurred while reading, or an error occurred 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.
| Error | if an error has occurred since the last operation on this SyncConnection instance. |
1.4.7