Adding shutdown() and serverPort() methods to QxtWeb's connectors

The shutdown() is to permit graceful termination of services and/or restarting
long-lived services to handle IP address changes. The serverPort() is simply
a convenience method to obtain a dynamically assigned port number. The class
documentation has been also been updated accordingly.

src/web/qxtabstracthttpconnector.cpp

@@ -255,16 +255,44 @@ void QxtAbstractHttpConnector::disconnected()
     sessionManager()->disconnected(device);
 }
 
+/*!
+ *  Returns the current local server port assigned during binding. This will
+ *  be 0 if the connector isn't currently bound.
+ *
+ * \sa listen()
+ */
+quint16 QxtAbstractHttpConnector::serverPort() const
+{
+    return 0;
+}
+
 /*!
  * \fn virtual bool QxtAbstractHttpConnector::listen(const QHostAddress& interface, quint16 port)
  * Invoked by the session manager to indicate that the connector should listen
  * for incoming connections on the specified \a interface and \a port.
  *
  * If the interface is QHostAddress::Any, the server will listen on all network interfaces.
+ * If the port is explicitly set to 0, the socket system will assign a port
+ * in the dynamic range. In this case, the resulting port number may be
+ * obtained using the serverPort() method.
  *
  * Returns true on success, or false if the server could not begin listening.
  *
- * \sa addConnection(QIODevice*)
+ * \sa addConnection(), shutdown()
+ */
+
+/*!
+ * \fn virtual bool QxtAbstractHttpConnector::shutdown()
+ * Invoked by the session manager to indicate that the connector should close
+ * it's listener port and stop accepting new connections. A shutdown may be
+ * followed by a new listen (to switch ports or handle a change in the
+ * machine's IP address). Note that if dynamic port assignment was used, it
+ * will be necessary to explictly set the port back to 0 or a subsequent
+ * listen will attempt to reuse the prior port number.
+ *
+ * Returns true on success, or false if the server wasn't listening.
+ *
+ * \sa listen()
  */
 
 /*!

src/web/qxtabstracthttpconnector.h

@@ -50,6 +50,8 @@ class QXT_WEB_EXPORT QxtAbstractHttpConnector : public QObject
 public:
     QxtAbstractHttpConnector(QObject* parent = 0);
     virtual bool listen(const QHostAddress& iface, quint16 port) = 0;
+    virtual bool shutdown() = 0;
+    virtual quint16 serverPort() const;
 
 protected:
     QxtHttpSessionManager* sessionManager() const;
@@ -76,6 +78,8 @@ class QXT_WEB_EXPORT QxtHttpServerConnector : public QxtAbstractHttpConnector
 public:
     QxtHttpServerConnector(QObject* parent = 0, QTcpServer* server = 0);
     virtual bool listen(const QHostAddress& iface, quint16 port = 80);
+    virtual bool shutdown();
+    virtual quint16 serverPort() const;
 
     QTcpServer* tcpServer() const;
 
@@ -114,6 +118,8 @@ class QXT_WEB_EXPORT QxtScgiServerConnector : public QxtAbstractHttpConnector
 public:
     QxtScgiServerConnector(QObject* parent = 0);
     virtual bool listen(const QHostAddress& iface, quint16 port);
+    virtual bool shutdown();
+    virtual quint16 serverPort() const;
 
 protected:
     virtual bool canParseRequest(const QByteArray& buffer);
@@ -134,6 +140,7 @@ Q_OBJECT
 public:
     QxtFcgiConnector(QObject* parent = 0);
     virtual bool listen(const QHostAddress& iface, quint16 port);
+    virtual bool shutdown();
 
 private:
     QXT_DECLARE_PRIVATE(QxtFcgiConnector)

src/web/qxtabstractwebsessionmanager.cpp

@@ -183,6 +183,20 @@ void QxtAbstractWebSessionManager::sessionDestroyed(int)
  * Session managers should not create sessions before start() is invoked.
  * Subclasses are encouraged to refrain from accepting connections until the
  * session manager is started.
+ *
+ * Returns true if the session was successfully started and false otherwise.
+ */
+
+/*!
+ * \fn virtual bool QxtAbstractWebSessionManager::shutdown()
+ * Stops the session manager.
+ *
+ * This method stops listening for new connections. Any active connections
+ * remain viable. It is permissible to start() the session again after a
+ * successful shutdown (to change ports for example).
+ *
+ * Returns true if the session was active (successfully shut down) and false
+ * otherwise.
  */
 
 /*!

src/web/qxtabstractwebsessionmanager.h

@@ -47,6 +47,7 @@ public:
     QxtAbstractWebSessionManager(QObject* parent = 0);
 
     virtual bool start() = 0;
+    virtual bool shutdown() = 0;
     virtual void postEvent(QxtWebEvent* event) = 0;
     void setServiceFactory(ServiceFactory* factory);
     ServiceFactory* serviceFactory() const;

src/web/qxthttpserverconnector.cpp

@@ -111,6 +111,26 @@ bool QxtHttpServerConnector::listen(const QHostAddress& iface, quint16 port)
     return qxt_d().server->listen(iface, port);
 }
 
+/*!
+ * \reimp
+ */
+bool QxtHttpServerConnector::shutdown()
+{
+    if(qxt_d().server->isListening()){
+	qxt_d().server->close();
+	return true;
+    }
+    return false;
+}
+
+/*!
+ * \reimp
+ */
+quint16 QxtHttpServerConnector::serverPort() const
+{
+    return qxt_d().server->serverPort();
+}
+
 /*!
  * Returns the QTcpServer used by this QxtHttpServerConnector. Use this pointer
  * to adjust the maxPendingConnections or QNetworkProxy properties of the

src/web/qxthttpsessionmanager.cpp

@@ -129,12 +129,12 @@ QxtHttpSessionManager::QxtHttpSessionManager(QObject* parent) : QxtAbstractWebSe
 
 /*!
  * Returns the interface on which the session manager will listen for incoming connections.
- * \sa setInterface
+ * \sa setListenInterface()
  */
 QHostAddress QxtHttpSessionManager::listenInterface() const
-    {
-        return qxt_d().iface;
-    }
+{
+    return qxt_d().iface;
+}
 
 /*!
  * Sets the interface \a iface on which the session manager will listen for incoming
@@ -143,7 +143,7 @@ QHostAddress QxtHttpSessionManager::listenInterface() const
  * The default value is QHostAddress::Any, which will cause the session manager
  * to listen on all network interfaces.
  *
- * \sa QxtAbstractHttpConnector::listen
+ * \sa QxtAbstractHttpConnector::listen()
  */
 void QxtHttpSessionManager::setListenInterface(const QHostAddress& iface)
 {
@@ -151,8 +151,11 @@ void QxtHttpSessionManager::setListenInterface(const QHostAddress& iface)
 }
 
 /*!
- * Returns the port on which the session manager will listen for incoming connections.
- * \sa setInterface
+ * Returns the port on which the session manager is expected to listen for
+ * incoming connections. This is always whatever value was supplied in the
+ * last \ref setPort() and not neccessarily the port number actually being
+ * used.
+ * \sa setPort(), serverPort()
  */
 quint16 QxtHttpSessionManager::port() const
 {
@@ -160,19 +163,39 @@ quint16 QxtHttpSessionManager::port() const
 }
 
 /*!
- * Sets the \a port on which the session manager will listen for incoming connections.
+ * Sets the \a port on which the session manager should listen for incoming
+ * connections.
  *
  * The default value is to listen on port 80. This is an acceptable value when
  * using QxtHttpServerConnector, but it is not likely to be desirable for other
- * connectors.
+ * connectors. You may also use 0 to allow the network layer to dynamically
+ * assign a port number. In this case, the \ref serverPort() method will
+ * return the actual port assigned once the session has been successfully
+ * started.
  *
- * \sa port
+ * \note Setting the port number after the session has been started will
+ * have no effect unless it is shutdown and started again.
+ *
+ * \sa port(), serverPort()
  */
 void QxtHttpSessionManager::setPort(quint16 port)
 {
     qxt_d().port = port;
 }
 
+/*!
+ * Returns the port on which the session manager is listening for incoming
+ * connections. This will be 0 if the session manager has not been started
+ * or was shutdown.
+ * \sa setInterface(), setPort()
+ */
+quint16 QxtHttpSessionManager::serverPort() const
+{
+    if(qxt_d().connector)
+	return connector()->serverPort();
+    return 0;
+}
+
 /*!
  * \reimp
  */
@@ -182,6 +205,15 @@ bool QxtHttpSessionManager::start()
     return connector()->listen(listenInterface(), port());
 }
 
+/*!
+ * \reimp
+ */
+bool QxtHttpSessionManager::shutdown()
+{
+    Q_ASSERT(qxt_d().connector);
+    return connector()->shutdown();
+}
+
 /*!
  * Returns the name of the HTTP cookie used to track sessions in the web browser.
  * \sa setSessionCookieName
@@ -192,7 +224,8 @@ QByteArray QxtHttpSessionManager::sessionCookieName() const
 }
 
 /*!
- * Sets the \a name of the HTTP cookie used to track sessions in the web browser.
+ * Sets the \a name of the HTTP cookie used to track sessions in the web
+ * browser.
  *
  * The default value is "sessionID".
  *

src/web/qxthttpsessionmanager.h

@@ -44,6 +44,11 @@ class QXT_WEB_EXPORT QxtHttpSessionManager : public QxtAbstractWebSessionManager
 {
     friend class QxtAbstractHttpConnector;
     Q_OBJECT
+    Q_PROPERTY(QHostAddress listenInterface READ listenInterface WRITE setListenInterface)
+    Q_PROPERTY(QByteArray sessionCookieName READ sessionCookieName WRITE setSessionCookieName)
+    Q_PROPERTY(quint16 port READ port WRITE setPort)
+    Q_PROPERTY(quint16 serverPort READ serverPort)
+    Q_PROPERTY(bool autoCreateSession READ autoCreateSession WRITE setAutoCreateSession)
 public:
     enum Connector { HttpServer, Scgi, Fcgi };
 
@@ -57,6 +62,8 @@ public:
     quint16 port() const;
     void setPort(quint16 port);
 
+    quint16 serverPort() const;
+
     QByteArray sessionCookieName() const;
     void setSessionCookieName(const QByteArray& name);
 
@@ -71,6 +78,7 @@ public:
     QxtAbstractHttpConnector* connector() const;
 
     virtual bool start();
+    virtual bool shutdown();
 
 protected:
     virtual void sessionDestroyed(int sessionID);

src/web/qxtscgiserverconnector.cpp

@@ -76,6 +76,26 @@ bool QxtScgiServerConnector::listen(const QHostAddress& iface, quint16 port)
     return qxt_d().server->listen(iface, port);
 }
 
+/*!
+ * \reimp
+ */
+bool QxtScgiServerConnector::shutdown()
+{
+    if(qxt_d().server->isListening()){
+	qxt_d().server->close();
+	return true;
+    }
+    return false;
+}
+
+/*!
+ * \reimp
+ */
+quint16 QxtScgiServerConnector::serverPort() const
+{
+    return qxt_d().server->serverPort();
+}
+
 /*!
  * \internal
  */