---

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

#include <ServerConnectionListener.h>

List of all members.

Public Types
typedef SmartPtr< ServerConnectionListener >	sptr
typedef WeakPtr< ServerConnectionListener >	wptr
Public Member Functions
virtual	~ServerConnectionListener ()
	Destructor.
bool	open (int port)
	Opens a socket ready for listening, but not yet listening.
void	close ()
	Closes the listening connection.
bool	listen ()
	Starts this socket listening.
bool	isListening () const
	Returns true if this ServerConnectionListener is active.
Address	getLocalAddress () const
	Returns the address of the listening socket.
Static Public Member Functions
void	closeAllListeners ()
	For all active listeners, calls close on them.
Protected Member Functions
	ServerConnectionListener ()
	Initalizes this class.
void	setThisPointer (const sptr &thisPointer)
	You must call this from your create function BEFORE exiting it.
virtual void	onListenFailure (const Error &error, const Address &from, const SmartPtr< ConnectionListener > &listener)=0
	There was a failure when trying to listen on this socket.
virtual void	onListenSuccess (const SmartPtr< ConnectionListener > &listener)
	This is an optional event to catch which is called after ConnectionListener::onNewConn.
virtual void	getNewConnectionParams (ConnectionParams &params)=0
	A new connection is starting, and now we want the parameters for this new connection.
Friends
class	ServerConnection
class	ServerListener

---

Detailed Description

A connection that listens for other connections. Inherit from this class, overriding the functions from Connection and ClientConnection based on the events you wish to respond to.

You need to create a static "create" method like other classes in GNE since ServerConnectionListener is managed by a SmartPtr. There exists a master list of ServerConnectionListener objects that are actively listening. Therefore you don't need to keep the reference around to keep the object from getting prematurely deleted.

When GNE closes, all active listeners will be shutdown, so the close operation is optional. You can close early by calling the close method. The static method closeAllListeners is also available to you.

All of the methods in this class are safe to call from multiple threads at the same time unless otherwise noted.

---

Constructor & Destructor Documentation

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

Destructor. Closes the listening connection if it is open.

---

Member Function Documentation

void GNE::ServerConnectionListener::close (   )

Closes the listening connection. It is OK to call close at any time, even if already closed or never opened. You can start the listener again by calling open and listen. The close operation is optional. GNE will shut down active listeners when it is shut down. Note that a listener can be closed while an event is being processed. This behaviour was chosen because it matches the behaviour of the previous GNE 0.55 API, and because it avoids using mutexes, which keep the events from running in parallel even if they are capable. This should not affect the events except that the getLocalAddress method may return an invalid address.

void GNE::ServerConnectionListener::closeAllListeners (   )  [static]

For all active listeners, calls close on them. This method is implicitly called when GNE shuts down.

Address GNE::ServerConnectionListener::getLocalAddress (   )  const

Returns the address of the listening socket. If the listener has not been opened or is not listening, an invalid address is returned. Most notably, a listener can be closed while an event is being processed. See also: close

virtual void GNE::ServerConnectionListener::getNewConnectionParams (  ConnectionParams &  params  )  [protected, pure virtual]

A new connection is starting, and now we want the parameters for this new connection. The parameters passed should be modified to give the new connection's flow control parameters and listener. This function can be called from multiple threads at the same time.

bool GNE::ServerConnectionListener::listen (   )

Starts this socket listening. onNewConn will be called when a new connection has been negotiated and error checked. This method also registers the listener into the master list, so you after this method is called you no longer need to keep the reference. If already listening, this method has no effect and returns false. While a listener is listening, it is added to a master list so that it won't be destroyed prematurely. It is removed from the list when the listener is closed (this includes when all listeners are shutdown when GNE is shut down). Precondition: listener has been opened with open. See also: onListenFailure onListenSuccess open Returns: true, if there was an error starting the listen

virtual void GNE::ServerConnectionListener::onListenFailure (  const Error &  error, const Address &  from, const SmartPtr< ConnectionListener > &  listener )  [protected, pure virtual]

There was a failure when trying to listen on this socket. This is not called when the actual low-level listen fails (that error is returned from listen), but instead high-level errors while connecting such as a version mismatch are sent here. Only errors that occur before or during the ConnectionListener::onNewConn event are sent here. This function may be called from multiple threads at the same time, and may block if it wishes; it does not have the "non-blocking" restriction most GNE events have. Depending on when and under what circumstances the failure happened, in any case, from might be an invalid address, and listener may be NULL. Parameters: error  the type of error from  the remote address the failed attempt came from listener  the unused ConnectionListener that was obtained from getNewConnectionParams. If it is NULL, then getNewConnectionParams was never called.

virtual void GNE::ServerConnectionListener::onListenSuccess (  const SmartPtr< ConnectionListener > &  listener  )  [protected, virtual]

This is an optional event to catch which is called after ConnectionListener::onNewConn. The default behavior for this event is to do nothing, but you may overload it to catch it. This method may block, but until it completes the connection will be marked as connecting and not as connected, and listener will not start to receive any events (besides the onNewConn it just got) until this function completes. See the expong example of a case where the onListenSuccess event can be useful, where the same implementation using only onNewConn would be harder to program and understand. This function can be called from multiple threads at the same time. Parameters: listener  The listener than you returned from getNewConnectionParams.

bool GNE::ServerConnectionListener::open (  int  port  )

Opens a socket ready for listening, but not yet listening. If the socket has already been opened, this method has no effect and returns false. This fact may be an issue, since if you call open with one port, calling open again won't change the port unless you close. Unless you restrict your usage of the open function to a single thread or use an external mutex, it is impossible to safely change port. This is usually not a problem as most users will initialize the listener from only a single thread. Parameters: port  the port to listen on. Returns: true if could not open a socket on the port.

---

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

• ServerConnectionListener.h
• ServerConnectionListener.cpp

---