server sip sync

doc/api_break.dox

@@ -172,6 +172,7 @@ This page tries to maintain a list with incompatible changes that happened in pr
 <tr><td>QgsVectorLayer<td>rendererV2<td>renderer
 <tr><td>QgsVectorLayerEditUtils<td>deleteVertexV2<td>deleteVertex
 <tr><td>QgsComposerSymbolItem<td>symbolV2<td>symbol
+<tr><td>QgsServerInterface<td>capabiblitiesCache<td>capabilitiesCache
 </table>
 
 \subsection qgis_api_break_3_0_removed_classes Removed Classes

python/server/qgsaccesscontrolfilter.sip

@@ -18,15 +18,16 @@
  ***************************************************************************/
 
 /**
+ * \ingroup server
  * \class QgsAccessControlFilter
- * \brief Class defining access control interface for QGIS Server.
+ * \brief Class defining access control interface for QGIS Server plugins.
  *
  * Security can define any (or none) of the following method:
- *  * layerFilterExpression()
+ *  * layerFilterExpression() - To get an additional expression filter (WMS/GetMap, WMS/GetFeatureInfo, WFS/GetFeature)
- *  * layerFilterSubsetString()
+ *  * layerFilterSQL() - To get an additional SQL filter (WMS/GetMap, WMS/GetFeatureInfo, WFS/GetFeature) for layer that support SQL
- *  * layerPermissions()
+ *  * layerPermissions() - To give the general layer permissins (read / update / insert / delete)
- *  * authorizedLayerAttributes()
+ *  * authorizedLayerAttributes() - Tho filter the attributes (WMS/GetFeatureInfo, WFS/GetFeature)
- *  * allowToEdit()
+ *  * allowToEdit() - (all WFS-T requests)
  *  * cacheKey()
  */
 
@@ -39,7 +40,7 @@ class QgsAccessControlFilter
   public:
     /** Constructor
      * QgsServerInterface passed to plugins constructors
-     * and must be passed to QgsAccessControlPlugin instances.
+     * and must be passed to QgsAccessControlFilter instances.
      */
     QgsAccessControlFilter( const QgsServerInterface* serverInterface );
     /** Destructor */
@@ -56,18 +57,42 @@ class QgsAccessControlFilter
 
     /** Return the QgsServerInterface instance*/
     const QgsServerInterface* serverInterface() const;
-    /** Return an additional expression filter */
+
+    /** Return an additional expression filter
+     * @param layer the layer to control
+     * @return the filter expression
+     */
     virtual QString layerFilterExpression( const QgsVectorLayer* layer ) const;
-    /** Return an additional the subset string (typically SQL) filter.
+
-        Faster than the layerFilterExpression but not supported on all the type of layer */
+    /** Return an additional subset string (typically SQL) filter
+     * @param layer the layer to control
+     * @return the subset string
+     */
     virtual QString layerFilterSubsetString( const QgsVectorLayer* layer ) const;
-    /** Return the layer permissions */
+
+    /** Return the layer permissions
+     * @param layer the layer to control
+     * @return the permission to use on the layer
+     */
     virtual LayerPermissions layerPermissions( const QgsMapLayer* layer ) const;
-    /** Return the authorized layer attributes */
+
+    /** Return the authorized layer attributes
+     * @param layer the layer to control
+     * @param attributes the current list of visible attribute
+     * @return the new list of visible attributes
+     */
     virtual QStringList authorizedLayerAttributes( const QgsVectorLayer* layer, const QStringList& attributes ) const;
-    /** Are we authorize to modify the following geometry */
+
+    /** Are we authorized to modify the following geometry
+     * @param layer the layer to control
+     * @param feature the concerned feature
+     * @return true if we are allowed to edit
+     */
     virtual bool allowToEdit( const QgsVectorLayer* layer, const QgsFeature& feature ) const;
-    /** Cache key to used to create the capabilities cache, "" for no cache, shouldn't any contains "-", default to "" */
+
+    /** Cache key to used to create the capabilities cache
+     * @return the cache key, "" for no cache
+     */
     virtual QString cacheKey() const;
 };
 

python/server/qgscapabilitiescache.sip

@@ -15,10 +15,9 @@
  *                                                                         *
  ***************************************************************************/
 
-/**
+/** \ingroup server
-* \class QgsCapabilitiesCache
+ * A cache for capabilities xml documents (by configuration file path)
-* \brief A cache for capabilities xml documents (by configuration file path)
+ */
-*/
 class QgsCapabilitiesCache: QObject
 {
 %TypeHeaderCode
@@ -26,10 +25,18 @@ class QgsCapabilitiesCache: QObject
 %End
   public:
 
-    /** Returns cached capabilities document (or 0 if document for configuration file not in cache)*/
+    /** Returns cached capabilities document (or 0 if document for configuration file not in cache)
-    const QDomDocument* searchCapabilitiesDocument( const QString& configFilePath, const QString& version );
+     * @param configFilePath the progect file path
-    /** Inserts new capabilities document (creates a copy of the document, does not take ownership)*/
+     * @param key key used to separate different version in different cache
-    void insertCapabilitiesDocument( const QString& configFilePath, const QString& version, const QDomDocument* doc );
+     */
+    const QDomDocument* searchCapabilitiesDocument( const QString& configFilePath, const QString& key );
+
+    /** Inserts new capabilities document (creates a copy of the document, does not take ownership)
+     * @param configFilePath the project file path
+     * @param key key used to separate different version in different cache
+     * @param doc the DOM document
+     */
+    void insertCapabilitiesDocument( const QString& configFilePath, const QString& key, const QDomDocument* doc );
 
     /** Remove capabilities document
      * @param path the project file path

python/server/qgsmapserviceexception.sip

@@ -16,7 +16,7 @@
  ***************************************************************************/
 
 
-/**
+/** \ingroup server
  * \class  QgsMapServiceException
  * \brief Exception class for WMS service exceptions.
  *

python/server/qgsrequesthandler.sip

@@ -26,46 +26,106 @@ class QgsRequestHandler
 
   public:
 
+    /** Parses the input and creates a request neutral Parameter/Value map
+     * @note not available in Python bindings
+     */
+    // virtual void parseInput() = 0;
+
+    /** Sends the map image back to the client
+     * @note not available in Python bindings
+     */
+    // virtual void setGetMapResponse( const QString& service, QImage* img, int imageQuality ) = 0;
+
+    //! @note not available in Python bindings
+    // virtual void setGetCapabilitiesResponse( const QDomDocument& doc ) = 0;
+
+    //! @note not available in Python bindings
+    // virtual void setGetFeatureInfoResponse( const QDomDocument& infoDoc, const QString& infoFormat ) = 0;
+
     /** Allow plugins to return a QgsMapServiceException*/
     virtual void setServiceException( QgsMapServiceException ex /Transfer/ ) = 0;
+
+    //! @note not available in Python bindings
+    // virtual void setXmlResponse( const QDomDocument& doc ) = 0;
+
+    //! @note not available in Python bindings
+    // virtual void setXmlResponse( const QDomDocument& doc, const QString& mimeType ) = 0;
+
+    //! @note not available in Python bindings
+    // virtual void setGetPrintResponse( QByteArray* b ) = 0;
+
+    //! @note not available in Python bindings
+    // virtual bool startGetFeatureResponse( QByteArray* ba, const QString& infoFormat ) = 0;
+
+    //! @note not available in Python bindings
+    // virtual void setGetFeatureResponse( QByteArray* ba ) = 0;
+
+    //! @note not available in Python bindings
+    virtual void endGetFeatureResponse( QByteArray* ba ) = 0;
+
+    //! @note not available in Python bindings
+    virtual void setGetCoverageResponse( QByteArray* ba ) = 0;
+
     virtual void setDefaultHeaders();
+
     /** 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;
+
     /** Append the bytestream to response body*/
     virtual void appendBody( const QByteArray &body ) = 0;
+
     /** Clears the response body*/
     virtual void clearBody() = 0;
+
     /** Return the response body*/
     virtual QByteArray body();
+
     /** Set the info format string such as "text/xml"*/
     virtual void setInfoFormat( const QString &format ) = 0;
+
     /** Check whether there is any header set or the body is not empty*/
     virtual bool responseReady() const = 0;
+
     /** Send out HTTP headers and flush output buffer*/
     virtual void sendResponse() = 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 requested format string*/
     QString format() const;
+
     /** Return the mime type for the response*/
     QString infoFormat() const;
+
     /** Return true if the HTTP headers were already sent to the client*/
     bool headersSent();
+
+
+    //! @note not available in Python bindings
+    // virtual QPair<QByteArray, QByteArray> getResponse() = 0;
+
 private:
     /** Parses the input and creates a request neutral Parameter/Value map*/
     virtual void parseInput() = 0;

python/server/qgsserverfilter.sip

@@ -1,6 +1,6 @@
 /***************************************************************************
                           qgsserverfilter.h
- Server I/O filters class for Qgis Mapserver for use by plugins
+ Server I/O filters class for QGIS Server for use by plugins
                           -------------------
   begin                : 2014-09-10
   copyright            : (C) 2014 by Alessandro Pasotti
@@ -17,8 +17,9 @@
  ***************************************************************************/
 
 /**
+ * \ingroup server
  * \class QgsServerFilter
- * \brief Class defining I/O filters for Qgis Mapserver and
+ * \brief Class defining I/O filters for QGIS Server and
  * implemented in plugins.
  *
  * Filters can define any (or none) of the following hooks:

python/server/qgsserverinterface.sip

@@ -18,14 +18,17 @@
  ***************************************************************************/
 
 /**
- * \class QgsServerInterface
+ * \ingroup server
- * \brief Class defining the interface made available to server plugins.
+ * QgsServerInterface
+ * Class defining interfaces exposed by QGIS Server and
+ * made available to 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.
+ *
  */
 
 
@@ -40,39 +43,89 @@ class QgsServerInterface
 %End
 
   public:
-    /** Returns the current request handler*/
+    /**
+     * Set the request handler
+     * @param requestHandler request handler
+     * @note not available in Python bindings
+     */
+    // virtual void setRequestHandler( QgsRequestHandler* requestHandler ) = 0;
+
+    /**
+     * Clear the request handler
+     *
+     * @note not available in python bindings
+     */
+    // virtual void clearRequestHandler() = 0;
+
+    /**
+     * Get pointer to the capabiblities cache
+     * @return QgsCapabilitiesCache
+     */
+    virtual QgsCapabilitiesCache* capabilitiesCache() = 0 /KeepReference/;
+
+    /**
+     * Get pointer to the request handler
+     * @return QgsRequestHandler
+     */
     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 QgsServerFilter
-    /** Register a filter with the given priority. The filter's requestReady()
+     * @param filter the QgsServerFilter to add
-     * and responseReady() methods will be called from the loop*/
+     * @param priority an optional priority for the filter order
+     */
     virtual void registerFilter( QgsServerFilter* filter /Transfer/, int priority = 0 ) = 0;
-    /** Set the filters map */
+
+    /**
+     * Set the filters map
+     * @param filters the QgsServerFiltersMap
+     */
     virtual void setFilters( QgsServerFiltersMap* filters /Transfer/) = 0;
-    /** Register a security module with the given priority.*/
+
+    /**
+     * Return the list of current QgsServerFilter
+     * @return QgsServerFiltersMap list of QgsServerFilter
+     */
+    virtual QgsServerFiltersMap filters() = 0;
+
+    /** Register an access control filter
+     * @param accessControl the access control to register
+     * @param priority the priority used to order them
+     */
     virtual void registerAccessControl( QgsAccessControlFilter* accessControl /Transfer/, int priority = 0 ) = 0;
+
     /** Gets the registred access control filters */
     virtual const QgsAccessControl* accessControls() const = 0;
-    /** Return an environment variable set by FCGI*/
+
+    //! Return an enrironment variable, used to pass  environment variables to python
     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
+    /**
-    virtual QgsServerFiltersMap filters() = 0;
+     * Return the configuration file path
-    /** Returns the configFilePath as seen by the server, this value is only
+     * @return QString containing the configuration file path
-     * available after requestReady has been called.*/
+     */
     virtual QString configFilePath() = 0;
-    /** Set the config file path */
+
+    /**
+     * Set the configuration file path
+     * @param configFilePath QString with the configuration file path
+     */
     virtual void setConfigFilePath( const QString& configFilePath) = 0;
-    /** Remove entry from config cache */
+
+    /**
+     * Remove entry from config cache
+     * @param path the path of the file to remove
+     */
     virtual void removeConfigCacheEntry( const QString& path ) = 0;
-    /** Remove entry from layer cache */
+
+    /**
+     * Remove entries from layer cache
+     * @param path the path of the project which own the layers to be removed
+     */
     virtual void removeProjectLayers( const QString& path ) = 0;
 
-
+  private:
-private:
     /** Constructor */
     QgsServerInterface();
-
 };
 

src/server/qgsaccesscontrolfilter.h

@@ -1,6 +1,8 @@
 /***************************************************************************
                           qgsaccesscontrolfilter.h
                           ------------------------
+ Access control interface for Qgis Server plugins
+
   begin                : 2015-05-19
   copyright            : (C) 2015 by Stéphane Brunner
   email                : stephane dot brunner at camptocamp dot org
@@ -40,6 +42,7 @@ class QgsFeature;
  *  * layerPermissions() - To give the general layer permissins (read / update / insert / delete)
  *  * authorizedLayerAttributes() - Tho filter the attributes (WMS/GetFeatureInfo, WFS/GetFeature)
  *  * allowToEdit() - (all WFS-T requests)
+ *  * cacheKey()
  */
 class SERVER_EXPORT QgsAccessControlFilter
 {

src/server/qgscapabilitiescache.h

@@ -24,7 +24,8 @@
 #include <QObject>
 
 /** \ingroup server
- * A cache for capabilities xml documents (by configuration file path)*/
+ * A cache for capabilities xml documents (by configuration file path)
+ */
 class SERVER_EXPORT QgsCapabilitiesCache : public QObject
 {
     Q_OBJECT

src/server/qgsrequesthandler.h

@@ -59,69 +59,98 @@ class QgsRequestHandler
      * @note not available in Python bindings
      */
     virtual void parseInput() = 0;
+
     /** Sends the map image back to the client
      * @note not available in Python bindings
      */
     virtual void setGetMapResponse( const QString& service, QImage* img, int imageQuality ) = 0;
+
     //! @note not available in Python bindings
     virtual void setGetCapabilitiesResponse( const QDomDocument& doc ) = 0;
-    //! @note not availabe in Python bindings
+
+    //! @note not available in Python bindings
     virtual void setGetFeatureInfoResponse( const QDomDocument& infoDoc, const QString& infoFormat ) = 0;
+
     /** Allow plugins to return a QgsMapServiceException*/
     virtual void setServiceException( QgsMapServiceException ex ) = 0;
+
     //! @note not available in Python bindings
     virtual void setXmlResponse( const QDomDocument& doc ) = 0;
+
     //! @note not available in Python bindings
     virtual void setXmlResponse( const QDomDocument& doc, const QString& mimeType ) = 0;
+
     //! @note not available in Python bindings
     virtual void setGetPrintResponse( QByteArray* b ) = 0;
+
     //! @note not available in Python bindings
     virtual bool startGetFeatureResponse( QByteArray* ba, const QString& infoFormat ) = 0;
+
     //! @note not available in Python bindings
     virtual void setGetFeatureResponse( QByteArray* ba ) = 0;
 
     //! @note not available in Python bindings
     virtual void endGetFeatureResponse( QByteArray* ba ) = 0;
+
     //! @note not available in Python bindings
     virtual void setGetCoverageResponse( QByteArray* ba ) = 0;
+
     virtual void setDefaultHeaders() {}
+
     /** 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;
+
     /** Append the bytestream to response body*/
     virtual void appendBody( const QByteArray &body ) = 0;
+
     /** Clears the response body*/
     virtual void clearBody() = 0;
+
     /** Return the response body*/
     virtual QByteArray body() { return mBody; }
+
     /** Set the info format string such as "text/xml"*/
     virtual void setInfoFormat( const QString &format ) = 0;
+
     /** Check whether there is any header set or the body is not empty*/
     virtual bool responseReady() const = 0;
+
     /** Send out HTTP headers and flush output buffer*/
     virtual void sendResponse() = 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() { return mParameterMap; }
+
     /** 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 requested format string*/
     QString format() const { return mFormat; }
+
     /** Return the mime type for the response*/
     QString infoFormat() const { return mInfoFormat; }
+
     /** Return true if the HTTP headers were already sent to the client*/
     bool headersSent() { return mHeadersSent; }
+
 #ifdef HAVE_SERVER_PYTHON_PLUGINS
     /** Allow core services to call plugin hooks through sendResponse()
      * @note not available in Python bindings
@@ -129,7 +158,7 @@ class QgsRequestHandler
     virtual void setPluginFilters( QgsServerFiltersMap pluginFilters ) = 0;
 #endif
 
-    //! @note not availabe in Python bindings
+    //! @note not available in Python bindings
     virtual QPair<QByteArray, QByteArray> getResponse() = 0;
 
   protected:

src/server/qgsserverinterface.h

@@ -1,7 +1,8 @@
 /***************************************************************************
-                          qgsseerversinterface.h
+                          qgsserverinterface.h
- Interface class for exposing functions in QGIS Server for use by plugins
+
-                             -------------------
+  Class defining the interface made available to QGIS Server plugins.
+  -------------------
   begin                : 2014-09-10
   copyright            : (C) 2014 by Alessandro Pasotti
   email                : a dot pasotti at itopen dot it
@@ -32,6 +33,12 @@
  * Class defining interfaces exposed by QGIS Server and
  * made available to 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.
+ *
  */
 class SERVER_EXPORT QgsServerInterface
 {
@@ -62,7 +69,7 @@ class SERVER_EXPORT QgsServerInterface
      * Get pointer to the capabiblities cache
      * @return QgsCapabilitiesCache
      */
-    virtual QgsCapabilitiesCache* capabiblitiesCache() = 0;
+    virtual QgsCapabilitiesCache* capabilitiesCache() = 0;
 
     /**
      * Get pointer to the request handler
@@ -88,11 +95,13 @@ class SERVER_EXPORT QgsServerInterface
      * @return QgsServerFiltersMap list of QgsServerFilter
      */
     virtual QgsServerFiltersMap filters() = 0;
+
     /** Register an access control filter
      * @param accessControl the access control to register
      * @param priority the priority used to order them
      */
     virtual void registerAccessControl( QgsAccessControlFilter* accessControl, int priority = 0 ) = 0;
+
     /** Gets the registred access control filters */
     virtual const QgsAccessControl* accessControls() const = 0;
 
@@ -123,9 +132,6 @@ class SERVER_EXPORT QgsServerInterface
      */
     virtual void removeProjectLayers( const QString& path ) = 0;
 
-
-
-
   private:
     QString mConfigFilePath;
 };

src/server/qgsserverinterfaceimpl.h

@@ -46,7 +46,7 @@ class QgsServerInterfaceImpl : public QgsServerInterface
 
     void setRequestHandler( QgsRequestHandler* requestHandler ) override;
     void clearRequestHandler() override;
-    QgsCapabilitiesCache* capabiblitiesCache() override { return mCapabilitiesCache; }
+    QgsCapabilitiesCache* capabilitiesCache() override { return mCapabilitiesCache; }
     //! Return the QgsRequestHandler, to be used only in server plugins
     QgsRequestHandler*  requestHandler() override { return mRequestHandler; }
     void registerFilter( QgsServerFilter *filter, int priority = 0 ) override;