server sip sync

qgis · Oct 1, 2016 · f4cb295 · f4cb295
1 parent a5adb66
commit f4cb295
Show file tree

Hide file tree

Showing 12 changed files with 244 additions and 58 deletions.
diff --git a/doc/api_break.dox b/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

diff --git a/python/server/qgsaccesscontrolfilter.sip b/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()
- *  * layerFilterSubsetString()
- *  * layerPermissions()
- *  * authorizedLayerAttributes()
- *  * allowToEdit()
+ *  * layerFilterExpression() - To get an additional expression filter (WMS/GetMap, WMS/GetFeatureInfo, WFS/GetFeature)
+ *  * layerFilterSQL() - To get an additional SQL filter (WMS/GetMap, WMS/GetFeatureInfo, WFS/GetFeature) for layer that support SQL
+ *  * 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()
  */
 
@@ -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;
 };
 

diff --git a/python/server/qgscapabilitiescache.sip b/python/server/qgscapabilitiescache.sip
@@ -15,21 +15,28 @@
  *                                                                         *
  ***************************************************************************/
 
-/**
-* \class QgsCapabilitiesCache
-* \brief A cache for capabilities xml documents (by configuration file path)
-*/
+/** \ingroup server
+ * A cache for capabilities xml documents (by configuration file path)
+ */
 class QgsCapabilitiesCache: QObject
 {
 %TypeHeaderCode
 #include "qgscapabilitiescache.h"
 %End
   public:
 
-    /** Returns cached capabilities document (or 0 if document for configuration file not in cache)*/
-    const QDomDocument* searchCapabilitiesDocument( const QString& configFilePath, const QString& version );
-    /** Inserts new capabilities document (creates a copy of the document, does not take ownership)*/
-    void insertCapabilitiesDocument( const QString& configFilePath, const QString& version, const QDomDocument* doc );
+    /** Returns cached capabilities document (or 0 if document for configuration file not in cache)
+     * @param configFilePath the progect file path
+     * @param key key used to separate different version in different cache
+     */
+    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

diff --git a/python/server/qgsmapserviceexception.sip b/python/server/qgsmapserviceexception.sip
@@ -16,7 +16,7 @@
  ***************************************************************************/
 
 
-/**
+/** \ingroup server
  * \class  QgsMapServiceException
  * \brief Exception class for WMS service exceptions.
  *

diff --git a/python/server/qgsrequesthandler.sip b/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;

diff --git a/python/server/qgsserverfilter.sip b/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:

diff --git a/python/server/qgsserverinterface.sip b/python/server/qgsserverinterface.sip
@@ -18,14 +18,17 @@
  ***************************************************************************/
 
 /**
- * \class QgsServerInterface
- * \brief Class defining the interface made available to server plugins.
+ * \ingroup server
+ * 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 filter with the given priority. The filter's requestReady()
-     * and responseReady() methods will be called from the loop*/
+
+    /**
+     * Register a QgsServerFilter
+     * @param filter the QgsServerFilter to add
+     * @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;
-    /** Returns the configFilePath as seen by the server, this value is only
-     * available after requestReady has been called.*/
+
+    /**
+     * Return the configuration file path
+     * @return QString containing the configuration file path
+     */
     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 */
-    virtual void removeProjectLayers( const QString& path ) = 0;
 
+    /**
+     * 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();
-
 };