feature:2982 API: add high-level type check

introduces some constants fro bool, int, float, positive and notnull parameters
types are tested in PwgServer::invoke and no in each method
+ some optimizations + update methods descriptions

git-svn-id: http://piwigo.org/svn/trunk@25077 68402e56-0260-453c-a942-63ccdbb3a9ee

4 files changed, 544 insertions, 432 deletions

diff --git a/include/ws_core.inc.php b/include/ws_core.inc.php
index 933b2ba57..3bb69a828 100644
--- a/include/ws_core.inc.php
+++ b/include/ws_core.inc.php
@@ -35,6 +35,13 @@ define( 'WS_PARAM_ACCEPT_ARRAY',  0x010000 );
 define( 'WS_PARAM_FORCE_ARRAY',   0x030000 );
 define( 'WS_PARAM_OPTIONAL',      0x040000 );
 
+define( 'WS_TYPE_BOOL',           0x01 );
+define( 'WS_TYPE_INT',            0x02 );
+define( 'WS_TYPE_FLOAT',          0x04 );
+define( 'WS_TYPE_POSITIVE',       0x10 );
+define( 'WS_TYPE_NOTNULL',        0x20 );
+define( 'WS_TYPE_ID', WS_TYPE_INT | WS_TYPE_POSITIVE | WS_TYPE_NOTNULL);
+
 define( 'WS_ERR_INVALID_METHOD',  501 );
 define( 'WS_ERR_MISSING_PARAM',   1002 );
 define( 'WS_ERR_INVALID_PARAM',   1003 );
@@ -273,12 +280,16 @@ Request format: ".@$this->_requestFormat." Response format: ".@$this->_responseF
       return;
     }
 
-    $this->addMethod('reflection.getMethodList',
-        array('PwgServer', 'ws_getMethodList'),
-        null, '' );
-    $this->addMethod('reflection.getMethodDetails',
+    // add reflection methods
+    $this->addMethod(
+        'reflection.getMethodList',
+        array('PwgServer', 'ws_getMethodList')
+        );
+    $this->addMethod(
+        'reflection.getMethodDetails',
         array('PwgServer', 'ws_getMethodDetails'),
-        array('methodName'),'');
+        array('methodName')
+        );
 
     trigger_action('ws_add_methods', array(&$this) );
     uksort( $this->_methods, 'strnatcmp' );
@@ -302,19 +313,20 @@ Request format: ".@$this->_requestFormat." Response format: ".@$this->_responseF
    * Registers a web service method.
    * @param methodName string - the name of the method as seen externally
    * @param callback mixed - php method to be invoked internally
-   * @param params array - map of allowed parameter names with optional default
-   *   values and parameter flags. Example of $params:
-   *     array( 'param1' => array('default'=>523, 'flags'=>WS_PARAM_FORCE_ARRAY) ).
-   *   Possible parameter flags are:
-   *     WS_PARAM_ALLOW_ARRAY - this parameter can be an array
-   *     WS_PARAM_FORCE_ARRAY - if this parameter is scalar, force it to an array
-   *       before invoking the method
+   * @param params array - map of allowed parameter names with options
+   *    @option mixed default (optional)
+   *    @option int flags (optional)
+   *      possible values: WS_PARAM_ALLOW_ARRAY, WS_PARAM_FORCE_ARRAY, WS_PARAM_OPTIONAL
+   *    @option int type (optional)
+   *      possible values: WS_TYPE_BOOL, WS_TYPE_INT, WS_TYPE_FLOAT, WS_TYPE_ID
+   *                       WS_TYPE_POSITIVE, WS_TYPE_NOTNULL
+   *    @option int|float maxValue (optional)
    * @param description string - a description of the method.
    * @param include_file string - a file to be included befaore the callback is executed
-   * @param options array - Available options are:
-   *   hidden - if true, this method won't be visible by reflection.getMethodList
+   * @param options array
+   *    @option bool hidden (hidden) - if true, this method won't be visible by reflection.getMethodList
    */
-  function addMethod($methodName, $callback, $params=array(), $description, $include_file='', $options=array())
+  function addMethod($methodName, $callback, $params=array(), $description='', $include_file='', $options=array())
   {
     if (!is_array($params))
     {
@@ -330,16 +342,22 @@ Request format: ".@$this->_requestFormat." Response format: ".@$this->_responseF
     {
       if ( !is_array($data) )
       {
-        $params[$param] = array('flags'=>0);
+        $params[$param] = array('flags'=>0,'type'=>0);
       }
       else
       {
-        $flags = isset($data['flags']) ? $data['flags'] : 0;
+        if ( !isset($data['flags']) )
+        {
+          $data['flags'] = 0;
+        }
         if ( array_key_exists('default', $data) )
         {
-          $flags |= WS_PARAM_OPTIONAL;
+          $data['flags'] |= WS_PARAM_OPTIONAL;
+        }
+        if ( !isset($data['type']) )
+        {
+          $data['type'] = 0;
         }
-        $data['flags'] = $flags;
         $params[$param] = $data;
       }
     }
@@ -375,7 +393,7 @@ Request format: ".@$this->_requestFormat." Response format: ".@$this->_responseF
     return isset($HTTP_RAW_POST_DATA) or !empty($_POST);
   }
 
-  /*static*/ function makeArrayParam(&$param)
+  static function makeArrayParam(&$param)
   {
     if ( $param==null )
     {
@@ -383,12 +401,100 @@ Request format: ".@$this->_requestFormat." Response format: ".@$this->_responseF
     }
     else
     {
-      if (! is_array($param) )
+      if ( !is_array($param) )
       {
         $param = array($param);
       }
     }
   }
+  
+  static function checkType(&$param, $type, $name)
+  {
+    $opts = array();
+    $msg = '';
+    if ( self::hasFlag($type, WS_TYPE_POSITIVE | WS_TYPE_NOTNULL) )
+    {
+      $opts['options']['min_range'] = 1;
+      $msg = ' positive and not null';
+    }
+    else if ( self::hasFlag($type, WS_TYPE_POSITIVE) )
+    {
+      $opts['options']['min_range'] = 0;
+      $msg = ' positive';
+    }
+    
+    if ( is_array($param) )
+    {
+      if ( self::hasFlag($type, WS_TYPE_BOOL) )
+      {
+        foreach ($param as &$value)
+        {
+          if ( ($value = filter_var($value, FILTER_VALIDATE_BOOLEAN, FILTER_NULL_ON_FAILURE)) === null )
+          {
+            return new PwgError(WS_ERR_INVALID_PARAM, $name.' must only contain booleans' );
+          }
+        }
+        unset($value);
+      }
+      else if ( self::hasFlag($type, WS_TYPE_INT) )
+      {
+        foreach ($param as &$value)
+        {
+          if ( ($value = filter_var($value, FILTER_VALIDATE_INT, $opts)) === false )
+          {
+            return new PwgError(WS_ERR_INVALID_PARAM, $name.' must only contain'.$msg.' integers' );
+          }
+        }
+        unset($value);
+      }
+      else if ( self::hasFlag($type, WS_TYPE_FLOAT) )
+      {
+        foreach ($param as &$value)
+        {
+          if (
+            ($value = filter_var($value, FILTER_VALIDATE_FLOAT)) === false
+            or ( isset($opts['options']['min_range']) and $value < $opts['options']['min_range'] )
+          ) {
+            return new PwgError(WS_ERR_INVALID_PARAM, $name.' must only contain'.$msg.' floats' );
+          }
+        }
+        unset($value);
+      }
+    }
+    else if ( $param !== '' )
+    {
+      if ( self::hasFlag($type, WS_TYPE_BOOL) )
+      {
+        if ( ($param = filter_var($param, FILTER_VALIDATE_BOOLEAN, FILTER_NULL_ON_FAILURE)) === null )
+        {
+          return new PwgError(WS_ERR_INVALID_PARAM, $name.' must be a boolean' );
+        }
+      }
+      else if ( self::hasFlag($type, WS_TYPE_INT) )
+      {
+        if ( ($param = filter_var($param, FILTER_VALIDATE_INT, $opts)) === false )
+        {
+          return new PwgError(WS_ERR_INVALID_PARAM, $name.' must be an'.$msg.' integer' );
+        }
+      }
+      else if ( self::hasFlag($type, WS_TYPE_FLOAT) )
+      {
+        if (
+          ($param = filter_var($param, FILTER_VALIDATE_FLOAT)) === false
+          or ( isset($opts['options']['min_range']) and $param < $opts['options']['min_range'] )
+        ) {
+          return new PwgError(WS_ERR_INVALID_PARAM, $name.' must be a'.$msg.' float' );
+        }
+      }
+    }
+    
+    return null;
+  }
+  
+  static function hasFlag($val, $flag)
+  {
+    return ($val & $flag) == $flag;
+  }
 
   /**
    *  Invokes a registered method. Returns the return of the method (or
@@ -400,54 +506,77 @@ Request format: ".@$this->_requestFormat." Response format: ".@$this->_responseF
   {
     $method = @$this->_methods[$methodName];
 
-    if ( $method==null )
+    if ( $method == null )
     {
       return new PwgError(WS_ERR_INVALID_METHOD, 'Method name is not valid');
     }
 
-    // parameter check and data coercion !
+    // parameter check and data correction
     $signature = $method['signature'];
     $missing_params = array();
-    foreach($signature as $name=>$options)
+    
+    foreach ($signature as $name => $options)
     {
       $flags = $options['flags'];
+      
+      // parameter not provided in the request
       if ( !array_key_exists($name, $params) )
-      {// parameter not provided in the request
-        if ( !($flags&WS_PARAM_OPTIONAL) )
+      {
+        if ( !self::hasFlag($flags, WS_PARAM_OPTIONAL) )
         {
           $missing_params[] = $name;
         }
-        else if ( array_key_exists('default',$options) )
+        else if ( array_key_exists('default', $options) )
         {
           $params[$name] = $options['default'];
-          if ( ($flags&WS_PARAM_FORCE_ARRAY)==WS_PARAM_FORCE_ARRAY )
+          if ( self::hasFlag($flags, WS_PARAM_FORCE_ARRAY) )
           {
-            $this->makeArrayParam( $params[$name] );
+            self::makeArrayParam($params[$name]);
           }
         }
       }
+      // parameter provided but empty
+      else if ( $params[$name]==='' and !self::hasFlag($flags, WS_PARAM_OPTIONAL) )
+      {
+        $missing_params[] = $name;
+      }
+      // parameter provided - do some basic checks
       else
-      {// parameter provided - do some basic checks
+      {
         $the_param = $params[$name];
-        if ( is_array($the_param) and ($flags&WS_PARAM_ACCEPT_ARRAY)==0 )
+        
+        if ( is_array($the_param) and !self::hasFlag($flags, WS_PARAM_ACCEPT_ARRAY) )
         {
           return new PwgError(WS_ERR_INVALID_PARAM, $name.' must be scalar' );
         }
-        if ( ($flags&WS_PARAM_FORCE_ARRAY)==WS_PARAM_FORCE_ARRAY )
+        
+        if ( self::hasFlag($flags, WS_PARAM_FORCE_ARRAY) )
+        {
+          self::makeArrayParam($the_param);
+        }
+        
+        if ( $options['type'] > 0 )
         {
-          $this->makeArrayParam( $the_param );
+          if ( ($ret = self::checkType($the_param, $options['type'], $name)) !== null )
+          {
+            return $ret;
+          }
         }
+        
         if ( isset($options['maxValue']) and $the_param>$options['maxValue'])
         {
           $the_param = $options['maxValue'];
         }
+        
         $params[$name] = $the_param;
       }
     }
+    
     if (count($missing_params))
     {
       return new PwgError(WS_ERR_MISSING_PARAM, 'Missing parameters: '.implode(',',$missing_params));
     }
+    
     $result = trigger_event('ws_invoke_allowed', true, $methodName, $params);
     if ( strtolower( @get_class($result) )!='pwgerror')
     {
@@ -457,6 +586,7 @@ Request format: ".@$this->_requestFormat." Response format: ".@$this->_responseF
       }
       $result = call_user_func_array($method['callback'], array($params, &$this) );
     }
+    
     return $result;
   }
 
@@ -476,24 +606,27 @@ Request format: ".@$this->_requestFormat." Response format: ".@$this->_responseF
   static function ws_getMethodDetails($params, &$service)
   {
     $methodName = $params['methodName'];
+    
     if (!$service->hasMethod($methodName))
     {
-      return new PwgError(WS_ERR_INVALID_PARAM,
-            'Requested method does not exist');
+      return new PwgError(WS_ERR_INVALID_PARAM, 'Requested method does not exist');
     }
+    
     $res = array(
       'name' => $methodName,
       'description' => $service->getMethodDescription($methodName),
       'params' => array(),
     );
-    $signature = $service->getMethodSignature($methodName);
-    foreach ($signature as $name => $options)
+    
+    foreach ($service->getMethodSignature($methodName) as $name => $options)
     {
       $param_data = array(
         'name' => $name,
-        'optional' => ($options['flags']&WS_PARAM_OPTIONAL)?true:false,
-        'acceptArray' => ($options['flags']&WS_PARAM_ACCEPT_ARRAY)?true:false,
+        'optional' => self::hasFlag($options['flags'], WS_PARAM_OPTIONAL),
+        'acceptArray' => self::hasFlag($options['flags'], WS_PARAM_ACCEPT_ARRAY),
+        'type' => 'mixed',
         );
+      
       if (isset($options['default']))
       {
         $param_data['defaultValue'] = $options['default'];
@@ -502,6 +635,28 @@ Request format: ".@$this->_requestFormat." Response format: ".@$this->_responseF
       {
         $param_data['info'] = $options['info'];
       }
+      
+      if ( self::hasFlag($options['type'], WS_TYPE_BOOL) )
+      {
+        $param_data['type'] = 'bool';
+      }
+      else if ( self::hasFlag($options['type'], WS_TYPE_INT) )
+      {
+        $param_data['type'] = 'int';
+      }
+      else if ( self::hasFlag($options['type'], WS_TYPE_FLOAT) )
+      {
+        $param_data['type'] = 'float';
+      }
+      if ( self::hasFlag($options['type'], WS_TYPE_POSITIVE) )
+      {
+        $param_data['type'].= ' positive';
+      }
+      if ( self::hasFlag($options['type'], WS_TYPE_NOTNULL) )
+      {
+        $param_data['type'].= ' notnull';
+      }
+      
       $res['params'][] = $param_data;
     }
     return $res;
diff --git a/include/ws_functions.inc.php b/include/ws_functions.inc.php
index eb0399f2d..d2a920772 100644
--- a/include/ws_functions.inc.php
+++ b/include/ws_functions.inc.php
@@ -226,11 +226,7 @@ function ws_getMissingDerivatives($params, $service)
     }
   }
 
-  if ( ($max_urls = intval($params['max_urls'])) <= 0)
-  {
-    return new PwgError(WS_ERR_INVALID_PARAM, "Invalid max_urls");
-  }
-
+  $max_urls = $params['max_urls'];
   list($max_id, $image_count) = pwg_db_fetch_row( pwg_query('SELECT MAX(id)+1, COUNT(*) FROM '.IMAGES_TABLE) );
 
   if (0 == $image_count)
@@ -308,10 +304,14 @@ function ws_getMissingDerivatives($params, $service)
 function ws_getVersion($params, $service)
 {
   global $conf;
-  if ($conf['show_version'] or is_admin() )
+  if ( $conf['show_version'] or is_admin() )
+  {
     return PHPWG_VERSION;
+  }
   else
+  {
     return new PwgError(403, 'Forbidden');
+  }
 }
 
 /**
@@ -387,11 +387,6 @@ function ws_caddie_add($params, $service)
   {
     return new PwgError(401, 'Access denied');
   }
-  $params['image_id'] = array_map( 'intval',$params['image_id'] );
-  if ( empty($params['image_id']) )
-  {
-    return new PwgError(WS_ERR_INVALID_PARAM, "Invalid image_id");
-  }
   global $user;
   $query = '
 SELECT id
@@ -427,9 +422,6 @@ function ws_categories_getImages($params, $service)
   $where_clauses = array();
   foreach($params['cat_id'] as $cat_id)
   {
-    $cat_id = (int)$cat_id;
-    if ($cat_id<=0)
-      continue;
     if ($params['recursive'])
     {
       $where_clauses[] = 'uppercats '.DB_REGEX_OPERATOR.' \'(^|,)'.$cat_id.'(,|$)\'';
@@ -960,7 +952,7 @@ function ws_images_addComment($params, $service)
   {
     return new PwgError(405, "This method requires HTTP POST");
   }
-  $params['image_id'] = (int)$params['image_id'];
+
   $query = '
 SELECT DISTINCT image_id
   FROM '.IMAGE_CATEGORY_TABLE.' INNER JOIN '.CATEGORIES_TABLE.' ON category_id=id
@@ -1014,11 +1006,6 @@ SELECT DISTINCT image_id
 function ws_images_getInfo($params, $service)
 {
   global $user, $conf;
-  $params['image_id'] = (int)$params['image_id'];
-  if ( $params['image_id']<=0 )
-  {
-    return new PwgError(WS_ERR_INVALID_PARAM, "Invalid image_id");
-  }
 
   $query='
 SELECT * FROM '.IMAGES_TABLE.'
@@ -1028,12 +1015,14 @@ SELECT * FROM '.IMAGES_TABLE.'
       ' AND'
     ).'
 LIMIT 1';
-
-  $image_row = pwg_db_fetch_assoc(pwg_query($query));
-  if ($image_row==null)
+  $result = pwg_query($query);
+  
+  if (pwg_db_num_rows($resul) == 0)
   {
     return new PwgError(404, "image_id not found");
   }
+  
+  $image_row = pwg_db_fetch_assoc($result);
   $image_row = array_merge( $image_row, ws_std_get_urls($image_row) );
 
   //-------------------------------------------------------- related categories
@@ -1202,11 +1191,10 @@ SELECT id, date, author, content
  */
 function ws_images_Rate($params, $service)
 {
-  $image_id = (int)$params['image_id'];
   $query = '
 SELECT DISTINCT id FROM '.IMAGES_TABLE.'
   INNER JOIN '.IMAGE_CATEGORY_TABLE.' ON id=image_id
-  WHERE id='.$image_id
+  WHERE id='.$params['image_id']
   .get_sql_condition_FandF(
     array(
         'forbidden_categories' => 'category_id',
@@ -1221,7 +1209,7 @@ SELECT DISTINCT id FROM '.IMAGES_TABLE.'
   }
   $rate = (int)$params['rate'];
   include_once(PHPWG_ROOT_PATH.'include/functions_rate.inc.php');
-  $res = rate_picture( $image_id, $rate );
+  $res = rate_picture( $params['image_id'], $rate );
   if ($res==false)
   {
     global $conf;
@@ -1256,9 +1244,6 @@ function ws_images_search($params, $service)
       implode(' AND ', $where_clauses)
     );
 
-  $params['per_page'] = (int)$params['per_page'];
-  $params['page'] = (int)$params['page'];
-
   $image_ids = array_slice(
       $search_result['items'],
       $params['page']*$params['per_page'],
@@ -1317,13 +1302,8 @@ function ws_images_setPrivacyLevel($params, $service)
   {
     return new PwgError(405, "This method requires HTTP POST");
   }
-  $params['image_id'] = array_map( 'intval',$params['image_id'] );
-  if ( empty($params['image_id']) )
-  {
-    return new PwgError(WS_ERR_INVALID_PARAM, "Invalid image_id");
-  }
   global $conf;
-  if ( !in_array( (int)$params['level'], $conf['available_permission_levels']) )
+  if ( !in_array($params['level'], $conf['available_permission_levels']) )
   {
     return new PwgError(WS_ERR_INVALID_PARAM, "Invalid level");
   }
@@ -1354,53 +1334,28 @@ function ws_images_setRank($params, $service)
     return new PwgError(405, "This method requires HTTP POST");
   }
 
-  // is the image_id valid?
-  $params['image_id'] = (int)$params['image_id'];
-  if ($params['image_id'] <= 0)
-  {
-    return new PwgError(WS_ERR_INVALID_PARAM, "Invalid image_id");
-  }
-
-  // is the category valid?
-  $params['category_id'] = (int)$params['category_id'];
-  if ($params['category_id'] <= 0)
-  {
-    return new PwgError(WS_ERR_INVALID_PARAM, "Invalid category_id");
-  }
-
-  // is the rank valid?
-  $params['rank'] = (int)$params['rank'];
-  if ($params['rank'] <= 0)
-  {
-    return new PwgError(WS_ERR_INVALID_PARAM, "Invalid rank");
-  }
-
   // does the image really exist?
   $query='
-SELECT
-    *
+SELECT COUNT(*)
   FROM '.IMAGES_TABLE.'
   WHERE id = '.$params['image_id'].'
 ;';
 
-  $image_row = pwg_db_fetch_assoc(pwg_query($query));
-  if ($image_row == null)
+  list($count) = pwg_db_fetch_row(pwg_query($query));
+  if ($count == 0)
   {
     return new PwgError(404, "image_id not found");
   }
 
   // is the image associated to this category?
   $query = '
-SELECT
-    image_id,
-    category_id,
-    rank
+SELECT COUNT(*)
   FROM '.IMAGE_CATEGORY_TABLE.'
   WHERE image_id = '.$params['image_id'].'
     AND category_id = '.$params['category_id'].'
 ;';
-  $category_row = pwg_db_fetch_assoc(pwg_query($query));
-  if ($category_row == null)
+  list($count) = pwg_db_fetch_row(pwg_query($query));
+  if ($count == 0)
   {
     return new PwgError(404, "This image is not associated to this category");
   }
@@ -1626,12 +1581,6 @@ function ws_images_addFile($params, $service)
     return new PwgError(401, 'Access denied');
   }
 
-  $params['image_id'] = (int)$params['image_id'];
-  if ($params['image_id'] <= 0)
-  {
-    return new PwgError(WS_ERR_INVALID_PARAM, "Invalid image_id");
-  }
-
   //
   // what is the path and other infos about the photo?
   //
@@ -1646,12 +1595,14 @@ SELECT
   FROM '.IMAGES_TABLE.'
   WHERE id = '.$params['image_id'].'
 ;';
-  $image = pwg_db_fetch_assoc(pwg_query($query));
+  $result = pwg_query($query);
 
-  if ($image == null)
+  if (pwg_db_num_rows($result) == 0)
   {
     return new PwgError(404, "image_id not found");
   }
+  
+  $image = pwg_db_fetch_assoc($result);
 
   // since Piwigo 2.4 and derivatives, we do not take the imported "thumb"
   // into account
@@ -1726,17 +1677,16 @@ function ws_images_add($params, $service)
       );
   }
 
-  $params['image_id'] = (int)$params['image_id'];
   if ($params['image_id'] > 0)
   {
     $query='
-SELECT *
+SELECT COUNT(*)
   FROM '.IMAGES_TABLE.'
   WHERE id = '.$params['image_id'].'
 ;';
 
-    $image_row = pwg_db_fetch_assoc(pwg_query($query));
-    if ($image_row == null)
+    list($count) = pwg_db_fetch_row(pwg_query($query));
+    if ($count == 0)
     {
       return new PwgError(404, "image_id not found");
     }
@@ -1755,8 +1705,7 @@ SELECT *
     }
 
     $query = '
-SELECT
-    COUNT(*) AS counter
+SELECT COUNT(*)
   FROM '.IMAGES_TABLE.'
   WHERE '.$where_clause.'
 ;';
@@ -1879,38 +1828,30 @@ function ws_images_addSimple($params, $service)
 
   if (!isset($_FILES['image']))
   {
-    return new PwgError(405, "The image (file) parameter is missing");
+    return new PwgError(405, "The image (file) is missing");
   }
 
-  $params['image_id'] = (int)$params['image_id'];
   if ($params['image_id'] > 0)
   {
     $query='
-SELECT *
+SELECT COUNT(*)
   FROM '.IMAGES_TABLE.'
   WHERE id = '.$params['image_id'].'
 ;';
 
-    $image_row = pwg_db_fetch_assoc(pwg_query($query));
-    if ($image_row == null)
+    list($count) = pwg_db_fetch_row(pwg_query($query));
+    if ($count == 0)
     {
       return new PwgError(404, "image_id not found");
     }
   }
 
-  // category
-  $params['category'] = (int)$params['category'];
-  if ($params['category'] <= 0 and $params['image_id'] <= 0)
-  {
-    return new PwgError(WS_ERR_INVALID_PARAM, "Invalid category_id");
-  }
-
   include_once(PHPWG_ROOT_PATH.'admin/include/functions_upload.inc.php');
 
   $image_id = add_uploaded_file(
     $_FILES['image']['tmp_name'],
     $_FILES['image']['name'],
-    $params['category'] > 0 ? array($params['category']) : null,
+    $params['category'],
     8,
     $params['image_id'] > 0 ? $params['image_id'] : null
     );
@@ -1931,14 +1872,14 @@ SELECT *
     }
   }
 
-  if (count(array_keys($update)) > 0)
+  if (count($update) > 0)
   {
     $update['id'] = $image_id;
     
     single_update(
       IMAGES_TABLE,
       $update,
-      array('id', $update['id'])
+      array('id' => $update['id'])
       );
   }
 
@@ -1969,12 +1910,12 @@ SELECT *
 
   $url_params = array('image_id' => $image_id);
 
-  if ($params['category'] > 0)
+  if (!empty($params['category']))
   {
     $query = '
 SELECT id, name, permalink
   FROM '.CATEGORIES_TABLE.'
-  WHERE id = '.$params['category'].'
+  WHERE id = '.$params['category'][0].'
 ;';
     $result = pwg_query($query);
     $category = pwg_db_fetch_assoc($result);
@@ -2009,15 +1950,9 @@ function ws_rates_delete($params, $service)
     return new PwgError(401, 'Access denied');
   }
 
-  $user_id = (int)$params['user_id'];
-  if ($user_id<=0)
-  {
-    return new PwgError(WS_ERR_INVALID_PARAM, 'Invalid user_id');
-  }
-
   $query = '
 DELETE FROM '.RATE_TABLE.'
-  WHERE user_id='.$user_id;
+  WHERE user_id='.$params['user_id'];
 
   if (!empty($params['anonymous_id']))
   {
@@ -2144,7 +2079,6 @@ function ws_tags_getImages($params, $service)
   global $conf;
 
   // first build all the tag_ids we are interested in
-  $params['tag_id'] = array_map( 'intval',$params['tag_id'] );
   $tags = find_tags($params['tag_id'], $params['tag_url_name'], $params['tag_name']);
   $tags_by_id = array();
   foreach( $tags as $tag )
@@ -2168,8 +2102,6 @@ function ws_tags_getImages($params, $service)
     ws_std_image_sql_order($params) );
 
   $count_set = count($image_ids);
-  $params['per_page'] = (int)$params['per_page'];
-  $params['page'] = (int)$params['page'];
   $image_ids = array_slice($image_ids, $params['per_page']*$params['page'], $params['per_page'] );
 
   $image_tag_map = array();
@@ -2272,16 +2204,6 @@ function ws_categories_add($params, $service)
     $options['status'] = $params['status'];
   }
   
-  if (!empty($params['visible']) and in_array($params['visible'], array('true','false')))
-  {
-    $options['visible'] = get_boolean($params['visible']);
-  }
-  
-  if (!empty($params['commentable']) and in_array($params['commentable'], array('true','false')) )
-  {
-    $options['commentable'] = get_boolean($params['commentable']);
-  }
-  
   if (!empty($params['comment']))
   {
     $options['comment'] = $params['comment'];
@@ -2367,8 +2289,7 @@ SELECT
       }
     }
   }
-
-  if ('filename' == $conf['uniqueness_mode'])
+  else if ('filename' == $conf['uniqueness_mode'])
   {
     // search among photos the list of photos already added, based on
     // filename list
@@ -2419,12 +2340,6 @@ function ws_images_checkFiles($params, $service)
   // file_sum
   // high_sum
 
-  $params['image_id'] = (int)$params['image_id'];
-  if ($params['image_id'] <= 0)
-  {
-    return new PwgError(WS_ERR_INVALID_PARAM, "Invalid image_id");
-  }
-
   $query = '
 SELECT
     path
@@ -2489,12 +2404,6 @@ function ws_images_setInfo($params, $service)
     return new PwgError(405, "This method requires HTTP POST");
   }
 
-  $params['image_id'] = (int)$params['image_id'];
-  if ($params['image_id'] <= 0)
-  {
-    return new PwgError(WS_ERR_INVALID_PARAM, "Invalid image_id");
-  }
-
   include_once(PHPWG_ROOT_PATH.'admin/include/functions.php');
 
   $query='
@@ -2502,12 +2411,14 @@ SELECT *
   FROM '.IMAGES_TABLE.'
   WHERE id = '.$params['image_id'].'
 ;';
-
-  $image_row = pwg_db_fetch_assoc(pwg_query($query));
-  if ($image_row == null)
+  $result = pwg_query($query);
+  
+  if (pwg_db_num_rows($result) == 0)
   {
     return new PwgError(404, "image_id not found");
   }
+  
+  $image_row = pwg_db_fetch_assoc($result);
 
   // database registration
   $update = array();
@@ -2564,7 +2475,7 @@ SELECT *
     single_update(
       IMAGES_TABLE,
       $update,
-      array('id', $update['id'])
+      array('id' => $update['id'])
       );
   }
 
@@ -2633,17 +2544,20 @@ function ws_images_delete($params, $service)
     return new PwgError(405, "This method requires HTTP POST");
   }
 
-  if (empty($params['pwg_token']) or get_pwg_token() != $params['pwg_token'])
+  if (get_pwg_token() != $params['pwg_token'])
   {
     return new PwgError(403, 'Invalid security token');
   }
 
-  $params['image_id'] = preg_split(
-    '/[\s,;\|]/',
-    $params['image_id'],
-    -1,
-    PREG_SPLIT_NO_EMPTY
-    );
+  if (!is_array($params['image_id']))
+  {
+    $params['image_id'] = preg_split(
+      '/[\s,;\|]/',
+      $params['image_id'],
+      -1,
+      PREG_SPLIT_NO_EMPTY
+      );
+  }
   $params['image_id'] = array_map('intval', $params['image_id']);
 
   $image_ids = array();
@@ -2826,12 +2740,6 @@ function ws_categories_setInfo($params, $service)
   // name
   // comment
 
-  $params['category_id'] = (int)$params['category_id'];
-  if ($params['category_id'] <= 0)
-  {
-    return new PwgError(WS_ERR_INVALID_PARAM, "Invalid category_id");
-  }
-
   // database registration
   $update = array(
     'id' => $params['category_id'],
@@ -2857,7 +2765,7 @@ function ws_categories_setInfo($params, $service)
     single_update(
       CATEGORIES_TABLE,
       $update,
-      array('id', $update['id'])
+      array('id' => $update['id'])
       );
   }
 }
@@ -2879,41 +2787,27 @@ function ws_categories_setRepresentative($params, $service)
   // category_id
   // image_id
 
-  $params['category_id'] = (int)$params['category_id'];
-  if ($params['category_id'] <= 0)
-  {
-    return new PwgError(WS_ERR_INVALID_PARAM, "Invalid category_id");
-  }
-
   // does the category really exist?
   $query='
-SELECT
-    *
+SELECT COUNT(*)
   FROM '.CATEGORIES_TABLE.'
   WHERE id = '.$params['category_id'].'
 ;';
-  $row = pwg_db_fetch_assoc(pwg_query($query));
-  if ($row == null)
+  list($count) = pwg_db_fetch_row(pwg_query($query));
+  if ($count == 0)
   {
     return new PwgError(404, "category_id not found");
   }
 
-  $params['image_id'] = (int)$params['image_id'];
-  if ($params['image_id'] <= 0)
-  {
-    return new PwgError(WS_ERR_INVALID_PARAM, "Invalid image_id");
-  }
-
   // does the image really exist?
   $query='
-SELECT
-    *
+SELECT COUNT(*)
   FROM '.IMAGES_TABLE.'
   WHERE id = '.$params['image_id'].'
 ;';
 
-  $row = pwg_db_fetch_assoc(pwg_query($query));
-  if ($row == null)
+  list($count) = pwg_db_fetch_row(pwg_query($query));
+  if ($count == 0)
   {
     return new PwgError(404, "image_id not found");
   }
@@ -2947,7 +2841,7 @@ function ws_categories_delete($params, $service)
     return new PwgError(405, "This method requires HTTP POST");
   }
 
-  if (empty($params['pwg_token']) or get_pwg_token() != $params['pwg_token'])
+  if (get_pwg_token() != $params['pwg_token'])
   {
     return new PwgError(403, 'Invalid security token');
   }
@@ -2963,12 +2857,15 @@ function ws_categories_delete($params, $service)
       );
   }
 
-  $params['category_id'] = preg_split(
-    '/[\s,;\|]/',
-    $params['category_id'],
-    -1,
-    PREG_SPLIT_NO_EMPTY
-    );
+  if (!is_array($params['category_id']))
+  {
+    $params['category_id'] = preg_split(
+      '/[\s,;\|]/',
+      $params['category_id'],
+      -1,
+      PREG_SPLIT_NO_EMPTY
+      );
+  }
   $params['category_id'] = array_map('intval', $params['category_id']);
 
   $category_ids = array();
@@ -3016,17 +2913,20 @@ function ws_categories_move($params, $service)
     return new PwgError(405, "This method requires HTTP POST");
   }
 
-  if (empty($params['pwg_token']) or get_pwg_token() != $params['pwg_token'])
+  if (get_pwg_token() != $params['pwg_token'])
   {
     return new PwgError(403, 'Invalid security token');
   }
 
-  $params['category_id'] = preg_split(
-    '/[\s,;\|]/',
-    $params['category_id'],
-    -1,
-    PREG_SPLIT_NO_EMPTY
-    );
+  if (!is_array($params['category_id']))
+  {
+    $params['category_id'] = preg_split(
+      '/[\s,;\|]/',
+      $params['category_id'],
+      -1,
+      PREG_SPLIT_NO_EMPTY
+      );
+  }
   $params['category_id'] = array_map('intval', $params['category_id']);
 
   $category_ids = array();
@@ -3095,15 +2995,8 @@ SELECT
 
   // does this parent exists? This check should be made in the
   // move_categories function, not here
-  //
   // 0 as parent means "move categories at gallery root"
-  if (!is_numeric($params['parent']))
-  {
-    return new PwgError(403, 'Invalid parent input parameter');
-  }
-
   if (0 != $params['parent']) {
-    $params['parent'] = intval($params['parent']);
     $subcat_ids = get_subcat_ids(array($params['parent']));
     if (count($subcat_ids) == 0)
     {
@@ -3206,7 +3099,7 @@ function ws_plugins_performAction($params, &$service)
     return new PwgError(401, 'Access denied');
   }
 
-  if (empty($params['pwg_token']) or get_pwg_token() != $params['pwg_token'])
+  if (get_pwg_token() != $params['pwg_token'])
   {
     return new PwgError(403, 'Invalid security token');
   }
@@ -3240,7 +3133,7 @@ function ws_themes_performAction($params, $service)
     return new PwgError(401, 'Access denied');
   }
 
-  if (empty($params['pwg_token']) or get_pwg_token() != $params['pwg_token'])
+  if (get_pwg_token() != $params['pwg_token'])
   {
     return new PwgError(403, 'Invalid security token');
   }
@@ -3271,21 +3164,16 @@ function ws_extensions_update($params, $service)
     return new PwgError(401, l10n('Webmaster status is required.'));
   }
 
-  if (empty($params['pwg_token']) or get_pwg_token() != $params['pwg_token'])
+  if (get_pwg_token() != $params['pwg_token'])
   {
     return new PwgError(403, 'Invalid security token');
   }
 
-  if (empty($params['type']) or !in_array($params['type'], array('plugins', 'themes', 'languages')))
+  if (!in_array($params['type'], array('plugins', 'themes', 'languages')))
   {
     return new PwgError(403, "invalid extension type");
   }
 
-  if (empty($params['id']) or empty($params['revision']))
-  {
-    return new PwgError(null, 'Wrong parameters');
-  }
-
   include_once(PHPWG_ROOT_PATH.'admin/include/functions.php');
   include_once(PHPWG_ROOT_PATH.'admin/include/'.$params['type'].'.class.php');
 
@@ -3366,7 +3254,7 @@ function ws_extensions_ignoreupdate($params, $service)
     return new PwgError(401, 'Access denied');
   }
 
-  if (empty($params['pwg_token']) or get_pwg_token() != $params['pwg_token'])
+  if (get_pwg_token() != $params['pwg_token'])
   {
     return new PwgError(403, 'Invalid security token');
   }
diff --git a/tools/ws.htm b/tools/ws.htm
index ba285c0d0..de23c3e67 100644
--- a/tools/ws.htm
+++ b/tools/ws.htm
@@ -53,9 +53,9 @@
   #the_methods {width:250px;float:left;border-style:solid;border-color:#cdcdcd;border-width:1px 1px 0 0;
     background-image:url(data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAMAAAADCAIAAADZSiLoAAAAH0lEQVQImSXHMQEAMAwCMOrfK0jIjuVL2gLBzyHJtgd7wBdU3Vt/7AAAAABJRU5ErkJggg==);
   }
-  #the_methods ul {font-size:1.1em;margin:5px 0 10px 10px;list-style:none;}
-  #the_methods li:before {content:"\203A\00A0";font-weight:bold;color:#EB9C39;font-size:1.1em;}
-  #the_methods li:hover:before {content:"\00A0\203A";}
+  #methodsList {font-size:1.1em;margin:5px 0 10px 10px;list-style:none;}
+  #methodsList li:before {content:"\203A\00A0";font-weight:bold;color:#EB9C39;font-size:1.1em;}
+  #methodsList li:hover:before {content:"\00A0\203A";}
 
   #the_page {margin-left:252px;border-style:solid;border-color:#cdcdcd;border-width:1px 0 0 1px;}
   #the_content {padding:10px;}
@@ -70,6 +70,8 @@
   #methodParams td.input {text-align:center;}
   #methodParams td.input input[type="text"] {width:97%;font-size:0.9em;background:#f7f7f7;border:1px solid #ccc;border-radius:2px;}
   #methodParams td.input input[type="text"]:hover, #methodParams td.input input[type="text"]:focus {border-color:#C7E2F1;border-top-color:#96BCD7;background:#fff;}
+  #methodParams .type {display:inline-block;width:16px;height:16px;font-size:12px;line-height:16px;background:#ddd;border-radius:8px;font-weight:bold;text-align:center;color:#222;}
+  #methodParams .subtype {vertical-align:super;}
 
   #testForm {display:inline-block;margin-left:15px;}
   #testForm td {padding:2px 0;}
@@ -87,6 +89,7 @@
   
   .methodInfo {float:right;display:inline-block;width:16px;height:16px;font-size:12px;line-height:16px;background:#555;border-radius:8px;font-family:"Times New Roman",sans-serif;font-style:italic;font-weight:bold;text-align:center;color:#fff;}
   .methodInfo:hover {border:none;text-shadow:none;background:#888;cursor:pointer;color:#fff;}
+  #tiptip_content { font-size:12px; }
   
   #iframeWrapper {width:100%;height:300px;padding:3px 3px 20px 3px;background:#F9F9F9;border:1px solid #cdcdcd;overflow:hidden;position:relative;}
   iframe {width:100%;height:100%;background:#fff;}
@@ -155,6 +158,7 @@
             <tr>
               <td style="width:150px;">Name</td>
               <td class="mini">Extra</td>
+              <td class="mini">Type</td>
               <td style="width:300px;">Value</td>
               <td class="mini">Send</td>
             </tr>
@@ -165,7 +169,10 @@
           
           <tfoot>
             <tr>
-              <td colspan="4"><b>*</b>: required parameter, <b>?</b>: optional parameter, <b>[]</b>: parameter can be an array (use a pipe | to split values)</td>
+              <td colspan="5">
+                <b>*</b>: required, <b>?</b>: optional, <b>[]</b>: can be an array (use a pipe | to split values)<br>
+                <b>B</b>: boolean, <b>I</b>: integer, <b>F</b>: float, <b>+</b>: positive, <b>&oslash;</b>: not null
+              </td>
             </tr>
           </tfoot>
         </table>
@@ -305,11 +312,11 @@ function displayError(error) {
 
 // display ws_url form
 function askForUrl() {
+  displayError("can't contact web-services, please give absolute url to 'ws.php'");
   if ($("#urlForm input[name='ws_url']").val() == "") {
     $("#urlForm input[name='ws_url']").val(ws_url);
   }
   $("#urlForm").show();
-  displayError("can't contact web-services, please give absolute url to 'ws.php'");
 }
 
 // parse Piwigo JSON
@@ -404,10 +411,18 @@ function fillNewMethod(methodName) {
   var methodParams = '';
   if (method.params && method.params.length>0) {
     for (var i=0; i<method.params.length; i++) {
-      var isOptional = method.params[i].optional;
-      var acceptArray = method.params[i].acceptArray;
-      var defaultValue = method.params[i].defaultValue == null ? '' : method.params[i].defaultValue;
-      var info = method.params[i].info == null ? '' : '<a class="methodInfo" title="'+ method.params[i].info + '">i</a>';
+      var param = method.params[i],
+          isOptional = param.optional,
+          acceptArray = param.acceptArray,
+          defaultValue = param.defaultValue == null ? '' : param.defaultValue,
+          info = param.info == null ? '' : '<a class="methodInfo" title="'+ param.info.replace(/"/g, '&quot;') + '">i</a>',
+          type = '';
+      
+      if (param.type.match(/bool/)) type+= '<span class=type>B</span>';
+      if (param.type.match(/int/)) type+= '<span class=type>I</span>';
+      if (param.type.match(/float/)) type+= '<span class=type>F</span>';
+      if (param.type.match(/positive/)) type+= '<span class=subtype>+</span>';
+      if (param.type.match(/notnull/)) type+= '<span class=subtype>&oslash;</span>';
       
       // if an array is direclty printed, the delimiter is a comma where we use a pipe
       if (typeof defaultValue == 'object') {
@@ -415,8 +430,9 @@ function fillNewMethod(methodName) {
       }
 
       methodParams+= '<tr>'+
-        '<td>'+ method.params[i].name + info +'</td>'+
+        '<td>'+ param.name + info +'</td>'+
         '<td class="mini">'+ (isOptional ? '?':'*') + (acceptArray ? ' []':'') +'</td>'+
+        '<td class="mini">'+ type +'</td>'+
         '<td class="input"><input type="text" class="methodParameterValue" data-id="'+ i +'" value="'+ defaultValue +'"></td>'+
         '<td class="mini"><input type="checkbox" class="methodParameterSend" data-id="'+ i +'" '+ (isOptional ? '':'checked="checked"') +'></td>'+
       '</tr>';
@@ -438,10 +454,8 @@ function fillNewMethod(methodName) {
   
   // tiptip
   $(".methodInfo").tipTip({
-    activation:"click",
     maxWidth:"300px",
     defaultPosition:"right",
-    keepAlive:true,
     delay:0
   });
 }
diff --git a/ws.php b/ws.php
index 82da5aa03..318ddd16a 100644
--- a/ws.php
+++ b/ws.php
@@ -103,147 +103,159 @@ function ws_addDefaultMethods( $arr )
   
   include_once(PHPWG_ROOT_PATH.'include/ws_functions.inc.php');
   
+  $f_params = array(
+    'f_min_rate' => array('default'=>null,
+                          'type'=>WS_TYPE_FLOAT),
+    'f_max_rate' => array('default'=>null,
+                          'type'=>WS_TYPE_FLOAT),
+    'f_min_hit' =>  array('default'=>null,
+                          'type'=>WS_TYPE_INT|WS_TYPE_POSITIVE),
+    'f_max_hit' =>  array('default'=>null,
+                          'type'=>WS_TYPE_INT|WS_TYPE_POSITIVE),
+    'f_min_ratio' => array('default'=>null,
+                           'type'=>WS_TYPE_FLOAT|WS_TYPE_POSITIVE),
+    'f_max_ratio' => array('default'=>null,
+                           'type'=>WS_TYPE_FLOAT|WS_TYPE_POSITIVE),
+    'f_max_level' => array('default'=>null,
+                           'type'=>WS_TYPE_INT|WS_TYPE_POSITIVE),
+    'f_min_date_available' => array('default'=>null),
+    'f_max_date_available' => array('default'=>null),
+    'f_min_date_created' =>   array('default'=>null),
+    'f_max_date_created' =>   array('default'=>null),
+    );
+  
   $service->addMethod(
       'pwg.getVersion',
       'ws_getVersion',
       null,
-      'retrieves the PWG version'
+      'Returns the Piwigo version.'
     );
 	  
   $service->addMethod(
       'pwg.getInfos',
       'ws_getInfos',
       null,
-      'retrieves general informations'
+      '<b>Admin only.</b> Returns general informations.'
     );
 
   $service->addMethod(
       'pwg.caddie.add',
       'ws_caddie_add',
       array(
-        'image_id'=> array('flags'=>WS_PARAM_FORCE_ARRAY),
+        'image_id'=> array('flags'=>WS_PARAM_FORCE_ARRAY,
+                           'type'=>WS_TYPE_ID),
         ),
-      'adds the elements to the caddie'
+      '<b>Admin only.</b> Adds elements to the caddie. Returns the number of elements added.'
     );
 
   $service->addMethod(
       'pwg.categories.getImages',
       'ws_categories_getImages',
-      array(
-        'cat_id' =>     array('default'=>0, 
-                              'flags'=>WS_PARAM_FORCE_ARRAY),
-        'recursive' =>  array('default'=>false ),
-        'per_page' =>   array('default'=>100, 
-                              'maxValue'=>$conf['ws_max_images_per_page']),
-        'page' =>       array('default'=>0),
-        'order' =>      array('default'=>null),
-        'f_min_rate' => array('default'=>null),
-        'f_max_rate' => array('default'=>null),
-        'f_min_hit' =>  array('default'=>null),
-        'f_max_hit' =>  array('default'=>null),
-        'f_min_date_available' => array('default'=>null),
-        'f_max_date_available' => array('default'=>null),
-        'f_min_date_created' =>   array('default'=>null),
-        'f_max_date_created' =>   array('default'=>null),
-        'f_min_ratio' => array('default'=>null),
-        'f_max_ratio' => array('default'=>null),
-        'f_max_level' => array('default'=>null),
-        ),
+      array_merge(array(
+        'cat_id' =>     array('default'=>null, 
+                              'flags'=>WS_PARAM_FORCE_ARRAY,
+                              'type'=>WS_TYPE_INT|WS_TYPE_POSITIVE),
+        'recursive' =>  array('default'=>false,
+                              'type'=>WS_TYPE_BOOL),
+        'per_page' =>   array('default'=>100,
+                              'maxValue'=>$conf['ws_max_images_per_page'],
+                              'type'=>WS_TYPE_INT|WS_TYPE_POSITIVE),
+        'page' =>       array('default'=>0,
+                              'type'=>WS_TYPE_INT|WS_TYPE_POSITIVE),
+        'order' =>      array('default'=>null,
+                              'info'=>'id, file, name, hit, rating_score, date_creation, date_available, random'),
+        ), $f_params),
       'Returns elements for the corresponding categories.
-<br><b>cat_id</b> can be empty if <b>recursive</b> is true. Can be sent as an array.
-<br><b>order</b> comma separated fields for sorting (file,id, rating_score,...)'
+<br><b>cat_id</b> can be empty if <b>recursive</b> is true.
+<br><b>order</b> comma separated fields for sorting'
     );
 
   $service->addMethod(
       'pwg.categories.getList',
       'ws_categories_getList',
       array(
-        'cat_id' =>       array('default'=>0),
-        'recursive' =>    array('default'=>false),
-        'public' =>       array('default'=>false),
-        'tree_output' =>  array('default'=>false),
-        'fullname' =>     array('default'=>false),
+        'cat_id' =>       array('default'=>null,
+                                'type'=>WS_TYPE_INT|WS_TYPE_POSITIVE,
+                                'info'=>'Parent category. "0" or empty for root.'),
+        'recursive' =>    array('default'=>false,
+                                'type'=>WS_TYPE_BOOL),
+        'public' =>       array('default'=>false,
+                                'type'=>WS_TYPE_BOOL),
+        'tree_output' =>  array('default'=>false,
+                                'type'=>WS_TYPE_BOOL),
+        'fullname' =>     array('default'=>false,
+                                'type'=>WS_TYPE_BOOL),
         ),
-      'retrieves a list of categories (tree_output option only compatible with json/php output format'
+      'Returns a list of categories.'
     );
 
   $service->addMethod(
       'pwg.getMissingDerivatives',
       'ws_getMissingDerivatives',
-      array(
-        'types' =>      array('default'=>array(),
-                              'flags'=>WS_PARAM_FORCE_ARRAY),
-        'ids' =>        array('default'=>array(),
-                              'flags'=>WS_PARAM_FORCE_ARRAY),
-        'max_urls' =>   array('default'=>200),
-        'prev_page' =>  array('default'=>null),
-        'f_min_rate' => array('default'=>null),
-        'f_max_rate' => array('default'=>null),
-        'f_min_hit' =>  array('default'=>null),
-        'f_max_hit' =>  array('default'=>null),
-        'f_min_date_available' => array('default'=>null),
-        'f_max_date_available' => array('default'=>null),
-        'f_min_date_created' =>   array('default'=>null),
-        'f_max_date_created' =>   array('default'=>null),
-        'f_min_ratio' => array('default'=>null),
-        'f_max_ratio' => array('default'=>null),
-        'f_max_level' => array('default'=>null),
-        ),
-      'retrieves a list of derivatives to build'
+      array_merge(array(
+        'types' =>        array('default'=>null,
+                                'flags'=>WS_PARAM_FORCE_ARRAY,
+                                'info'=>'square, thumb, 2small, xsmall, small, medium, large, xlarge, xxlarge'),
+        'ids' =>          array('default'=>null,
+                                'flags'=>WS_PARAM_FORCE_ARRAY,
+                                'type'=>WS_TYPE_ID),
+        'max_urls' =>     array('default'=>200,
+                                'type'=>WS_TYPE_INT|WS_TYPE_POSITIVE),
+        'prev_page' =>    array('default'=>null,
+                                'type'=>WS_TYPE_INT|WS_TYPE_POSITIVE),
+        ), $f_params),
+      '<b>Admin only.</b> Returns a list of derivatives to build.'
     );
 
   $service->addMethod(
       'pwg.images.addComment',
       'ws_images_addComment',
       array(
-        'image_id' => array(),
+        'image_id' => array('type'=>WS_TYPE_ID),
         'author' =>   array('default'=>is_a_guest()?'guest':$user['username']),
         'content' =>  array(),
         'key' =>      array(),
         ),
-      'add a comment to an image'
+      '<b>POST only.</b> Adds a comment to an image.'
     );
 
   $service->addMethod(
       'pwg.images.getInfo',
       'ws_images_getInfo',
       array(
-        'image_id' =>           array(),
-        'comments_page' =>      array('default'=>0 ),
-        'comments_per_page' =>  array('default' =>  $conf['nb_comment_page'],
-                                      'maxValue' => 2*$conf['nb_comment_page']),
+        'image_id' =>           array('type'=>WS_TYPE_ID),
+        'comments_page' =>      array('default'=>0,
+                                      'type'=>WS_TYPE_INT|WS_TYPE_POSITIVE),
+        'comments_per_page' =>  array('default'=>$conf['nb_comment_page'],
+                                      'maxValue'=>2*$conf['nb_comment_page'],
+                                      'type'=>WS_TYPE_INT|WS_TYPE_POSITIVE),
         ),
-      'retrieves information about the given photo'
+      'Returns information about an image.'
     );
 
   $service->addMethod(
       'pwg.images.rate',
       'ws_images_rate',
-      array('image_id', 'rate'),
-      'rate the image'
+      array(
+        'image_id' => array('type'=>WS_TYPE_ID),
+        'rate' =>     array('type'=>WS_TYPE_FLOAT),
+      ),
+      'Rates an image.'
     );
 
   $service->addMethod(
       'pwg.images.search',
       'ws_images_search',
-      array(
-        'query' =>      array(),
-        'per_page' =>   array('default'=>100, 
-                              'maxValue'=>$conf['ws_max_images_per_page']),
-        'page' =>       array('default'=>0),
-        'order' =>      array('default'=>null),
-        'f_min_rate' => array('default'=>null),
-        'f_max_rate' => array('default'=>null),
-        'f_min_hit' =>  array('default'=>null),
-        'f_max_hit' =>  array('default'=>null),
-        'f_min_date_available' => array('default'=>null),
-        'f_max_date_available' => array('default'=>null),
-        'f_min_date_created' =>   array('default'=>null),
-        'f_max_date_created' =>   array('default'=>null),
-        'f_min_ratio' => array('default'=>null),
-        'f_max_ratio' => array('default'=>null),
-        'f_max_level' => array('default'=>null),
-        ),
+      array_merge(array(
+        'query' =>        array(),
+        'per_page' =>     array('default'=>100,
+                                'maxValue'=>$conf['ws_max_images_per_page'],
+                                'type'=>WS_TYPE_INT|WS_TYPE_POSITIVE),
+        'page' =>         array('default'=>0,
+                                'type'=>WS_TYPE_INT|WS_TYPE_POSITIVE),
+        'order' =>        array('default'=>null,
+                                'info'=>'id, file, name, hit, rating_score, date_creation, date_available, random'),
+        ), $f_params),
       'Returns elements for the corresponding query search.'
     );
 
@@ -251,101 +263,114 @@ function ws_addDefaultMethods( $arr )
       'pwg.images.setPrivacyLevel',
       'ws_images_setPrivacyLevel',
       array(
-        'image_id' => array('flags'=>WS_PARAM_FORCE_ARRAY),
-        'level' =>    array('maxValue'=>$conf['available_permission_levels']),
+        'image_id' => array('flags'=>WS_PARAM_FORCE_ARRAY,
+                            'type'=>WS_TYPE_ID),
+        'level' =>    array('maxValue'=>max($conf['available_permission_levels']),
+                            'type'=>WS_TYPE_INT|WS_TYPE_POSITIVE),
         ),
-      'sets the privacy levels for the images (POST method only)'
+      '<b>Admin & POST only.</b> Sets the privacy levels for the images.'
     );
 
   $service->addMethod(
       'pwg.images.setRank',
       'ws_images_setRank',
-      array('image_id', 'category_id', 'rank'),
-      'sets the rank of a photo for a given album (POST method only, for admins)'
+      array(
+        'image_id'    => array('type'=>WS_TYPE_ID),
+        'category_id' => array('type'=>WS_TYPE_ID),
+        'rank'        => array('type'=>WS_TYPE_INT|WS_TYPE_POSITIVE|WS_TYPE_NOTNULL)
+        ),
+      '<b>Admin & POST only.</b> Sets the rank of a photo for a given album.'
     );
 
   $service->addMethod(
       'pwg.rates.delete',
       'ws_rates_delete',
       array(
-        'user_id' =>      array(),
+        'user_id' =>      array('type'=>WS_TYPE_ID),
         'anonymous_id' => array('default'=>null),
         ),
-      'deletes all rates for a user (POST method only, admins only)'
+      '<b>Admin & POST only.</b> Deletes all rates for a user.'
     );
 
   $service->addMethod(
       'pwg.session.getStatus',
       'ws_session_getStatus',
       null,
-      null
+      'Gets information about the current session. Also provides a token useable with admin methods.'
     );
 
   $service->addMethod(
       'pwg.session.login',
       'ws_session_login',
       array('username', 'password'),
-      'POST method only'
+      '<b>POST only.</b> Tries to login the user.'
     );
 
   $service->addMethod(
       'pwg.session.logout',
       'ws_session_logout',
       null,
-      null
+      'Ends the current session.'
     );
 
   $service->addMethod(
       'pwg.tags.getList',
       'ws_tags_getList',
       array(
-        'sort_by_counter' => array('default' =>false),
+        'sort_by_counter' => array('default'=>false,
+                                   'type'=>WS_TYPE_BOOL),
         ),
-      'retrieves a list of available tags'
+      'Retrieves a list of available tags.'
     );
 
   $service->addMethod(
       'pwg.tags.getImages',
       'ws_tags_getImages',
-      array(
+      array_merge(array(
         'tag_id' =>       array('default'=>null,
-                                'flags'=>WS_PARAM_FORCE_ARRAY),
+                                'flags'=>WS_PARAM_FORCE_ARRAY,
+                                'type'=>WS_TYPE_ID),
         'tag_url_name' => array('default'=>null,
                                 'flags'=>WS_PARAM_FORCE_ARRAY),
         'tag_name' =>     array('default'=>null,
                                 'flags'=>WS_PARAM_FORCE_ARRAY),
-        'tag_mode_and' => array('default'=>false),
+        'tag_mode_and' => array('default'=>false,
+                                'type'=>WS_TYPE_BOOL),
         'per_page' =>     array('default'=>100,
-                                'maxValue'=>$conf['ws_max_images_per_page']),
-        'page' =>         array('default'=>0),
-        'order' =>        array('default'=>null),
-        'f_min_rate' =>   array('default'=>null),
-        'f_max_rate' =>   array('default'=>null),
-        'f_min_hit' =>    array('default'=>null),
-        'f_max_hit' =>    array('default'=>null),
-        'f_min_date_available' => array('default'=>null),
-        'f_max_date_available' => array('default'=>null),
-        'f_min_date_created' =>   array('default'=>null),
-        'f_max_date_created' =>   array('default'=>null),
-        'f_min_ratio' => array('default'=>null),
-        'f_max_ratio' => array('default'=>null),
-        'f_max_level' => array('default'=>null),
-        ),
-      'Returns elements for the corresponding tags. Note that tag_id, tag_url_name, tag_name an be arrays. Fill at least one of them. '
+                                'maxValue'=>$conf['ws_max_images_per_page'],
+                                'type'=>WS_TYPE_INT|WS_TYPE_POSITIVE),
+        'page' =>         array('default'=>0,
+                                'type'=>WS_TYPE_INT|WS_TYPE_POSITIVE),
+        'order' =>        array('default'=>null,
+                                'info'=>'id, file, name, hit, rating_score, date_creation, date_available, random'),
+        ), $f_params),
+      'Returns elements for the corresponding tags. Fill at least tag_id, tag_url_name or tag_name.'
     );
 
   $service->addMethod(
       'pwg.images.addChunk',
       'ws_images_add_chunk',
-      array('data', 'original_sum', 'type', 'position'),
-      'POST method only. For admin only.'
+      array(
+        'data' =>         array(),
+        'original_sum' => array(),
+        'type' =>         array('default'=>'file',
+                                'info'=>'Must be "file", for backward compatiblity "high" and "thumb" are allowed.'),
+        'position' =>     array()
+        ),
+      '<b>Admin & POST only.</b> Add a chunk of a file.'
     );
 
   $service->addMethod(
       'pwg.images.addFile',
       'ws_images_addFile',
-      array('image_id', 'type', 'sum'),
-      'Add or update a file for an existing photo. pwg.images.addChunk must have been called  before (maybe several times)'
+      array(
+        'image_id' => array('type'=>WS_TYPE_ID),
+        'type' =>     array('default'=>'file',
+                            'info'=>'Must be "file", for backward compatiblity "high" and "thumb" are allowed.'),
+        'sum' =>      array(),
+        ),
+      '<b>Admin only.</b> Add or update a file for an existing photo.
+<br>pwg.images.addChunk must have been called before (maybe several times).'
     );
 
 
@@ -353,43 +378,53 @@ function ws_addDefaultMethods( $arr )
       'pwg.images.add',
       'ws_images_add',
       array(
-        'file_sum' =>           array(),
         'thumbnail_sum' =>      array('default'=>null),
         'high_sum' =>           array('default'=>null),
         'original_sum' =>       array(),
-        'original_filename' =>  array('default'=>null),
+        'original_filename' =>  array('default'=>null,
+                                      'Provide it if "check_uniqueness" is true and $conf["uniqueness_mode"] is "filename".'),
         'name' =>               array('default'=>null),
         'author' =>             array('default'=>null),
         'date_creation' =>      array('default'=>null),
         'comment' =>            array('default'=>null),
-        'categories' =>         array('default'=>null),
-        'tag_ids' =>            array('default'=>null),
+        'categories' =>         array('default'=>null,
+                                      'info'=>'String list "category_id[,rank];category_id[,rank]".<br>The rank is optional and is equivalent to "auto" if not given.'),
+        'tag_ids' =>            array('default'=>null,
+                                      'info'=>'Comma separated ids'),
         'level' =>              array('default'=>0,
-                                      'maxValue'=>$conf['available_permission_levels']),
-        'check_uniqueness' =>   array('default'=>true),
-        'image_id' =>           array('default'=>null),
+                                      'maxValue'=>max($conf['available_permission_levels']),
+                                      'type'=>WS_TYPE_INT|WS_TYPE_POSITIVE),
+        'check_uniqueness' =>   array('default'=>true,
+                                      'type'=>WS_TYPE_BOOL),
+        'image_id' =>           array('default'=>null,
+                                      'type'=>WS_TYPE_ID),
         ),
-      'POST method only.
-<br><b>categories</b> is a string list "category_id[,rank];category_id[,rank]"
-The rank is optional and is equivalent to "auto" if not given.'
+      '<b>Admin only.</b> Add an image.
+<br>pwg.images.addChunk must have been called before (maybe several times).
+<br>Don\'t use "thumbnail_sum" and "high_sum", these parameters are here for backward compatibility.'
     );
 
   $service->addMethod(
       'pwg.images.addSimple',
       'ws_images_addSimple',
       array(
-        'category' => array('default'=>null),
+        'category' => array('default'=>null,
+                            'flags'=>WS_PARAM_FORCE_ARRAY,
+                            'type'=>WS_TYPE_ID),
         'name' =>     array('default'=>null),
         'author' =>   array('default'=>null),
         'comment' =>  array('default'=>null),
         'level' =>    array('default'=>0,
-                            'maxValue'=>$conf['available_permission_levels']),
+                            'maxValue'=>max($conf['available_permission_levels']),
+                            'type'=>WS_TYPE_INT|WS_TYPE_POSITIVE),
         'tags' =>     array('default'=>null,
                             'flags'=>WS_PARAM_ACCEPT_ARRAY),
-        'image_id' => array('default'=>null),
+        'image_id' => array('default'=>null,
+                            'type'=>WS_TYPE_ID),
         ),
-      'POST method only.<br>Use the <b>image</b> field for uploading file.
-<br>Set the form encoding to "form-data"<br><b>category</b> is the numeric identifier of the destination category.
+      '<b>Admin & POST only.</b> Add an image.
+<br>Use the <b>$_FILES[image]</b> field for uploading file.
+<br>Set the form encoding to "form-data".
 <br>You can update an existing photo if you define an existing image_id.'
     );
 
@@ -397,17 +432,17 @@ The rank is optional and is equivalent to "auto" if not given.'
       'pwg.images.delete',
       'ws_images_delete',
       array(
-        'image_id' =>   array('default'=>0),
+        'image_id' =>   array('flags'=>WS_PARAM_ACCEPT_ARRAY),
         'pwg_token' =>  array(),
         ),
-      'Delete photos. You can give several image_ids, comma separated'
+      '<b>Admin & POST only.</b> Deletes image(s).'
     );
 
   $service->addMethod(
       'pwg.categories.getAdminList',
       'ws_categories_getAdminList',
       null,
-      'administration method only'
+      '<b>Admin only.</b>'
     );
 
   $service->addMethod(
@@ -415,24 +450,28 @@ The rank is optional and is equivalent to "auto" if not given.'
       'ws_categories_add',
       array(
         'name' =>         array(),
-        'parent' =>       array('default'=>null),
+        'parent' =>       array('default'=>null,
+                                'type'=>WS_TYPE_ID),
         'comment' =>      array('default'=>null),
-        'visible' =>      array('default'=>null),
-        'status' =>       array('default'=>null),
-        'commentable' =>  array('default'=>'true'),
+        'visible' =>      array('default'=>true,
+                                'type'=>WS_TYPE_BOOL),
+        'status' =>       array('default'=>null,
+                                'info'=>'public, private'),
+        'commentable' =>  array('default'=>true,
+                                'type'=>WS_TYPE_BOOL),
         ),
-      'administration method only'
+      '<b>Admin only.</b> Adds an album.'
     );
 
   $service->addMethod(
       'pwg.categories.delete',
       'ws_categories_delete',
       array(
-        'category_id'=>           array('default'=>0),
-        'pwg_token' =>            array(),
+        'category_id'=>           array('flags'=>WS_PARAM_ACCEPT_ARRAY),
         'photo_deletion_mode' =>  array('default'=>'delete_orphans'),
+        'pwg_token' =>            array(),
         ),
-      'Delete categories. You can give several category_ids, comma separated.
+      '<b>Admin & POST only.</b> Deletes album(s).
 <br><b>photo_deletion_mode</b> can be "no_delete" (may create orphan photos), "delete_orphans"
 (default mode, only deletes photos linked to no other album) or "force_delete" (delete all photos, even those linked to other albums)'
     );
@@ -441,35 +480,36 @@ The rank is optional and is equivalent to "auto" if not given.'
       'pwg.categories.move',
       'ws_categories_move',
       array(
-        'category_id' =>  array('default'=>0),
-        'parent' =>       array('default'=>0),
+        'category_id' =>  array('flags'=>WS_PARAM_ACCEPT_ARRAY),
+        'parent' =>       array('type'=>WS_TYPE_INT|WS_TYPE_POSITIVE),
         'pwg_token' =>    array(),
         ),
-      'Move categories. You can give several category_ids, comma separated. Set parent as 0 to move to gallery root. Only virtual categories can be moved.'
+      '<b>Admin & POST only.</b> Move album(s).
+<br>Set parent as 0 to move to gallery root. Only virtual categories can be moved.'
     );
 
   $service->addMethod(
       'pwg.categories.setRepresentative',
       'ws_categories_setRepresentative',
       array(
-        'category_id' =>  array('default'=>0),
-        'image_id' =>     array('default'=>0),
+        'category_id' =>  array('type'=>WS_TYPE_ID),
+        'image_id' =>     array('type'=>WS_TYPE_ID),
         ),
-      'Set the representative photo for an album. The photo doesn\'t have to belong to the album. POST method only. Administration method only.'
+      '<b>Admin & POST only.</b> Sets the representative photo for an album. The photo doesn\'t have to belong to the album.'
     );
 
   $service->addMethod(
       'pwg.tags.getAdminList',
       'ws_tags_getAdminList',
       null,
-      'administration method only'
+      '<b>Admin only.</b> '
     );
 
-  $service->addMethod(
+  $service->addMethod( // TODO: create multiple tags
       'pwg.tags.add',
       'ws_tags_add',
       array('name'),
-      'administration method only'
+      '<b>Admin only.</b> Adds a new tag.'
     );
 
   $service->addMethod(
@@ -479,114 +519,129 @@ The rank is optional and is equivalent to "auto" if not given.'
         'md5sum_list' =>    array('default'=>null),
         'filename_list' =>  array('default'=>null),
         ),
-      'check existence of a photo list'
+      '<b>Admin only.</b>  Checks existence of images.
+<br>Give <b>md5sum_list</b> if $conf[uniqueness_mode]==md5sum. Give <b>filename_list</b> if $conf[uniqueness_mode]==filename.'
     );
 
   $service->addMethod(
       'pwg.images.checkFiles',
       'ws_images_checkFiles',
       array(
-        'image_id' =>       array(),
-        'thumbnail_sum' =>  array('default'=>null),
+        'image_id' =>       array('type'=>WS_TYPE_ID),
         'file_sum' =>       array('default'=>null),
+        'thumbnail_sum' =>  array('default'=>null),
         'high_sum' =>       array('default'=>null),
         ),
-      'check if you have updated version of your files for a given photo, for each requested file type, the answer can be "missing", "equals" or "differs"'
+      '<b>Admin only.</b> Checks if you have updated version of your files for a given photo, the answer can be "missing", "equals" or "differs".
+<br>Don\'t use "thumbnail_sum" and "high_sum", these parameters are here for backward compatibility.'
     );
 
   $service->addMethod(
       'pwg.images.checkUpload',
       'ws_images_checkUpload',
       null,
-      'check if Piwigo is ready for upload'
+      '<b>Admin only.</b> Checks if Piwigo is ready for upload.'
     );
 
   $service->addMethod(
       'pwg.images.setInfo',
       'ws_images_setInfo',
       array(
-        'image_id' =>       array(),
+        'image_id' =>       array('type'=>WS_TYPE_ID),
         'file' =>           array('default'=>null),
         'name' =>           array('default'=>null),
         'author' =>         array('default'=>null),
         'date_creation' =>  array('default'=>null),
         'comment' =>        array('default'=>null),
-        'categories' =>     array('default'=>null),
-        'tag_ids' =>        array('default'=>null),
+        'categories' =>     array('default'=>null,
+                                  'info'=>'String list "category_id[,rank];category_id[,rank]".<br>The rank is optional and is equivalent to "auto" if not given.'),
+        'tag_ids' =>        array('default'=>null,
+                                  'info'=>'Comma separated ids'),
         'level' =>          array('default'=>null,
-                                  'maxValue'=>$conf['available_permission_levels']),
+                                  'maxValue'=>max($conf['available_permission_levels']),
+                                  'type'=>WS_TYPE_INT|WS_TYPE_POSITIVE),
         'single_value_mode' =>    array('default'=>'fill_if_empty'),
         'multiple_value_mode' =>  array('default'=>'append'),
         ),
-      'POST method only. Admin only
-<br><b>categories</b> is a string list "category_id[,rank];category_id[,rank]" The rank is optional and is equivalent to "auto" if not given.
+      '<b>Admin & POST only.</b> Changes properties of an image.
 <br><b>single_value_mode</b> can be "fill_if_empty" (only use the input value if the corresponding values is currently empty) or "replace"
-(overwrite any existing value) and applies to single values properties like name/author/date_creation/comment
-<br><b>multiple_value_mode</b> can be "append" (no change on existing values, add the new values) or "replace" and applies to multiple values properties like tag_ids/categories'
+(overwrite any existing value) and applies to single values properties like name/author/date_creation/comment.
+<br><b>multiple_value_mode</b> can be "append" (no change on existing values, add the new values) or "replace" and applies to multiple values properties like tag_ids/categories.'
     );
 
   $service->addMethod(
       'pwg.categories.setInfo',
       'ws_categories_setInfo',
       array(
-        'category_id' =>  array(),
+        'category_id' =>  array('type'=>WS_TYPE_ID),
         'name' =>         array('default'=>null),
         'comment' =>      array('default'=>null),
         ),
-      'POST method only.'
+      '<b>Admin & POST only.</b> Changes properties of an album.'
     );
   
   $service->addMethod(
       'pwg.plugins.getList',
       'ws_plugins_getList',
       null,
-      'Admin only
-<br>get the list of plugin with id, name, version, state and description'
+      '<b>Admin only.</b> Gets the list of plugins with id, name, version, state and description.'
     );
 
   $service->addMethod(
       'pwg.plugins.performAction',
       'ws_plugins_performAction',
-      array('action', 'plugin', 'pwg_token'),
-      'Admin only
-<br>install/activate/deactivate/uninstall/delete a plugin'
+      array(
+        'action'    => array('info'=>'install, activate, deactivate, uninstall, delete'),
+        'plugin'    => array(),
+        'pwg_token' => array(),
+        ),
+      '<b>Admin only.</b>'
     );
 
   $service->addMethod(
       'pwg.themes.performAction',
       'ws_themes_performAction',
-      array('action', 'theme', 'pwg_token'),
-      'activate/deactivate/delete/set_default a theme<br>administration status required'
+      array(
+        'action'    => array('info'=>'activate, deactivate, delete, set_default'),
+        'theme'     => array(),
+        'pwg_token' => array(),
+        ),
+      '<b>Admin only.</b>'
     );
 
   $service->addMethod(
       'pwg.extensions.update',
       'ws_extensions_update',
-      array('type', 'id', 'revision', 'pwg_token'),
-      'Update an extension. Webmaster only.
-<br>Parameter type must be "plugins", "languages" or "themes".'
+      array(
+        'type' => array('info'=>'plugins, languages, themes'),
+        'id' => array(),
+        'revision' => array(),
+        'pwg_token' => array(),
+        ),
+      '<b>Webmaster only.</b>'
   );
 
   $service->addMethod(
       'pwg.extensions.ignoreUpdate',
       'ws_extensions_ignoreupdate',
       array(
-        'type' =>       array('default'=>null),
+        'type' =>       array('default'=>null,
+                              'info'=>'plugins, languages, themes'),
         'id' =>         array('default'=>null),
-        'reset' =>      array('default'=>null),
+        'reset' =>      array('default'=>false,
+                              'type'=>WS_TYPE_BOOL,
+                              'info'=>'If true, all ignored extensions will be reinitilized.'),
         'pwg_token' =>  array(),
       ),
-      'Ignore an extension if it need update.
-<br>Parameter type must be "plugins", "languages" or "themes".
-<br>If reset parameter is true, all ignored extensions will be reinitilized.'
+      '<b>Webmaster only.</b> Ignores an extension if it needs update.'
   );
 
   $service->addMethod(
       'pwg.extensions.checkUpdates',
       'ws_extensions_checkupdates',
       null,
-      'Check if piwigo or extensions are up to date.'
+      '<b>Admin only.</b> Checks if piwigo or extensions are up to date.'
   );
 }
 
-?>
+?>
\ No newline at end of file