Added comments for bindings.

Author: elpaso

python/server/qgscapabilitiescache.sip

@@ -1,12 +1,29 @@
+/***************************************************************************
+                          qgscapabilitiescache.sip
 
-/**A cache for capabilities xml documents (by configuration file path)*/
+  A cache for capabilities xml documents (by configuration file path)
+  -------------------
+  begin                : 2014-09-10
+  copyright            : (C) 2014 by Alessandro Pasotti
+  email                : a dot pasotti at itopen dot it
+ ***************************************************************************/
+
+/***************************************************************************
+ *                                                                         *
+ *   This program is free software; you can redistribute it and/or modify  *
+ *   it under the terms of the GNU General Public License as published by  *
+ *   the Free Software Foundation; either version 2 of the License, or     *
+ *   (at your option) any later version.                                   *
+ *                                                                         *
+ ***************************************************************************/
+
+/**
+* \class QgsCapabilitiesCache
+* \brief A cache for capabilities xml documents (by configuration file path)
+*/
 class QgsCapabilitiesCache: public QObject
 {
 %TypeHeaderCode
-#include <QDomDocument>
-#include <QFileSystemWatcher>
-#include <QHash>
-#include <QObject>
 #include "qgscapabilitiescache.h"
 %End
   public:

python/server/qgsmapserviceexception.sip

@@ -1,9 +1,32 @@
+/***************************************************************************
+                          qgsmapserviceexception.sip
+  QGIS Server exception
+                             -------------------
+  begin                : 2014-09-10
+  copyright            : (C) 2014 by Alessandro Pasotti
+  email                : a dot pasotti at itopen dot it
+ ***************************************************************************/
 
-/**Exception class for WMS service exceptions. The most important codes are:
-"InvalidFormat"
-"Invalid CRS"
-"LayerNotDefined" / "StyleNotDefined"
-"OperationNotSupported"*/
+/***************************************************************************
+ *                                                                         *
+ *   This program is free software; you can redistribute it and/or modify  *
+ *   it under the terms of the GNU General Public License as published by  *
+ *   the Free Software Foundation; either version 2 of the License, or     *
+ *   (at your option) any later version.                                   *
+ *                                                                         *
+ ***************************************************************************/
+
+
+/**
+ * \class  QgsMapServiceException
+ * \brief Exception class for WMS service exceptions.
+ *
+ * The most important codes are:
+ *  * "InvalidFormat"
+ *  * "Invalid CRS"
+ *  * "LayerNotDefined" / "StyleNotDefined"
+ *  * "OperationNotSupported"
+ */
 
 class QgsMapServiceException
 {

python/server/qgsrequesthandler.sip

@@ -1,5 +1,24 @@
-/**This class is an interface hiding the details of reading input and writing output from/to a wms request mechanism.
-Examples of possible mechanisms are cgi Get, cgi Post, SOAP or the usage as a standalone command line executable*/
+/***************************************************************************
+                          qgsrequesthandler.sip
+
+  This class is an interface hiding the details of reading input and
+  writing output from/to a wms request mechanism
+  -------------------
+  begin                : 2014-09-10
+  copyright            : (C) 2014 by Alessandro Pasotti
+  email                : a dot pasotti at itopen dot it
+ ***************************************************************************/
+
+
+/**
+ * \class  QgsRequestHandler
+ * \brief This class is an interface hiding the details of reading input and
+ * writing output from/to a wms request mechanism.
+ *
+ * Examples of possible mechanisms are cgi Get, cgi Post, SOAP or the usage
+ * as a standalone command line executable
+ */
+
 class QgsRequestHandler
 {
 %TypeHeaderCode
@@ -10,46 +29,61 @@ class QgsRequestHandler
 
   public:
 
-    virtual void parseInput() = 0;
-    virtual void setGetMapResponse( const QString& service, QImage* img, int imageQuality ) = 0;
-    virtual void setGetCapabilitiesResponse( const QDomDocument& doc ) = 0;
-    virtual void setGetFeatureInfoResponse( const QDomDocument& infoDoc, const QString& infoFormat ) = 0;
-    virtual void setServiceException( QgsMapServiceException ex ) = 0;
-    virtual void setGetStyleResponse( const QDomDocument& doc ) = 0;
-    virtual void setGetPrintResponse( QByteArray* ba ) = 0;
-    virtual bool startGetFeatureResponse( QByteArray* ba, const QString& infoFormat ) = 0;
-    virtual void setGetFeatureResponse( QByteArray* ba ) = 0;
-    virtual void endGetFeatureResponse( QByteArray* ba ) = 0;
-    virtual void setGetCoverageResponse( QByteArray* ba ) = 0;
-
     /**Set an HTTP header*/
     virtual void setHeader( const QString &name, const QString &value ) = 0;
     /**Remove an HTTP header*/
     virtual int removeHeader( const QString &name ) = 0;
     /**Delete all HTTP headers*/
     virtual void clearHeaders( ) = 0;
+    /**Returns the response body*/
+    virtual QByteArray* body();
     /**Append the bytestream to response body*/
     virtual void appendBody( const QByteArray &body) = 0;
     /**Clears the response body*/
     virtual void clearBody( ) = 0;
+    /**Set the info format string such as "text/xml"*/
     virtual void setInfoFormat( const QString &format ) = 0;
-    virtual void sendResponse( ) const = 0;
+    /**Check wether there is any header set or the body is not empty*/
     virtual bool responseReady() const = 0;
     /**Pointer to last raised exception*/
     virtual bool exceptionRaised() const = 0;
+    /**Return a copy of the parsed parameters as a key-value pair, to modify
+     * a parameter setParameter( const QString &key, const QString &value)
+     * and removeParameter(const QString &key) must be used
+     */
     QMap<QString, QString> parameterMap( );
     /**Set a request parameter*/
     virtual void setParameter(const QString &key, const QString &value) = 0;
     /**Remove a request parameter*/
     virtual int removeParameter(const QString &key) = 0;
     /**Return a request parameter*/
     virtual QString parameter(const QString &key) const = 0;
+    /**Return the image format*/
     QString format() const;
+    /**Return the format string as requested by the client*/
+    QString infoFormat() const;
+
+private:
 
-protected:
+    /* Not yet part of the API */
 
     virtual void sendHeaders( ) const = 0;
     virtual void sendBody( ) const = 0;
 
+    /**Send out the response writing to FCGI stdout*/
+    virtual void sendResponse( ) const = 0;
+
+    virtual void parseInput() = 0;
+    virtual void setGetMapResponse( const QString& service, QImage* img, int imageQuality ) = 0;
+    virtual void setGetCapabilitiesResponse( const QDomDocument& doc ) = 0;
+    virtual void setGetFeatureInfoResponse( const QDomDocument& infoDoc, const QString& infoFormat ) = 0;
+    virtual void setServiceException( QgsMapServiceException ex ) = 0;
+    virtual void setGetStyleResponse( const QDomDocument& doc ) = 0;
+    virtual void setGetPrintResponse( QByteArray* ba ) = 0;
+    virtual bool startGetFeatureResponse( QByteArray* ba, const QString& infoFormat ) = 0;
+    virtual void setGetFeatureResponse( QByteArray* ba ) = 0;
+    virtual void endGetFeatureResponse( QByteArray* ba ) = 0;
+    virtual void setGetCoverageResponse( QByteArray* ba ) = 0;
+
 
 };

python/server/qgsserverfilter.sip

@@ -17,10 +17,13 @@
  ***************************************************************************/
 
 /**
- * QgsServerFilter
- * Class defining I/O filters for Qgis Mapserver and
- * implemented in plugins
+ * \class QgsServerFilter
+ * \brief Class defining I/O filters for Qgis Mapserver and
+ * implemented in plugins.
  *
+ * Filters can define any (or none) of the following hooks:
+ *  * requestReady() - called when request is ready
+ *  * responseReady() - called when the response is ready
  */
 
 class QgsServerFilter
@@ -32,12 +35,21 @@ class QgsServerFilter
 
 public:
 
-   /** Constructor */
+   /** Constructor
+    * QgsServerInterface passed to plugins constructors
+    * and must be passed to QgsServerFilter instances.
+    */
    QgsServerFilter( QgsServerInterface* serverInterface /Transfer/);
    /** Destructor */
    virtual ~QgsServerFilter();
+   /** Return the QgsServerInterface instance*/
    QgsServerInterface* serverInterface( );
+   /** Method called when the QgsRequestHandler is ready and populated with
+    * parameters, just before entering the main switch for core services.*/
    virtual void requestReady();
+   /** Method called when the QgsRequestHandler processing has done and
+    * the response is ready, just after the main switch for core services.
+    */
    virtual void responseReady();
 
 };

python/server/qgsserverinterface.sip

@@ -1,9 +1,31 @@
+/***************************************************************************
+                          qgsserverinterface.sip
+
+  Class defining the interface made available to server plugins.
+  -------------------
+  begin                : 2014-09-10
+  copyright            : (C) 2014 by Alessandro Pasotti
+  email                : a dot pasotti at itopen dot it
+ ***************************************************************************/
+
+/***************************************************************************
+ *                                                                         *
+ *   This program is free software; you can redistribute it and/or modify  *
+ *   it under the terms of the GNU General Public License as published by  *
+ *   the Free Software Foundation; either version 2 of the License, or     *
+ *   (at your option) any later version.                                   *
+ *                                                                         *
+ ***************************************************************************/
+
 /**
  * \class QgsServerInterface
- * \brief Class defining interfaces
- * made available to server plugins.
+ * \brief Class defining the interface made available to server plugins.
  *
- * Only functionality exposed by QgisServerInterface can be used in server plugins.
+ * This class provides methods to access the request handler and
+ * the capabilties cache. A method to read the environment
+ * variables set in the main FCGI loop is also available.
+ * Plugins can add listeners (instances of QgsServerFilter) with
+ * a certain priority through the registerFilter( QgsServerFilter* , int) method.
  */
 
 
@@ -16,10 +38,15 @@ class QgsServerInterface
 %End
 
   public:
-    virtual QgsCapabilitiesCache* capabiblitiesCache() = 0 /KeepReference/;
+    /**Returns the current request handler*/
     virtual QgsRequestHandler* requestHandler( ) = 0 /KeepReference/;
+    /**Returns the capabilities cache*/
+    virtual QgsCapabilitiesCache* capabiblitiesCache() = 0 /KeepReference/;
     // Tansfer ownership to avoid garbage collector to call dtor
+    /** Register a filter with the given priority. The filter's requestReady()
+     * and responseReady() methods will be called from the loop*/
     virtual void registerFilter( QgsServerFilter* filter /Transfer/, int priority = 0 ) = 0;
+    /**Return an environment variable set by FCGI*/
     virtual QString getEnv(const QString& name ) const = 0;
     // Commented because of problems with typedef QgsServerFiltersMap, provided
     // methods to alter the filters map into QgsRequestHandler API

python/server/qgsserverlogger.sip

@@ -10,7 +10,6 @@
 %Import core/core.sip
 
 %Include qgsserverfilter.sip
-%Include qgsserverlogger.sip
 %Include qgsmapserviceexception.sip
 %Include qgscapabilitiescache.sip
 %Include qgsrequesthandler.sip