aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authormistic100 <mistic@piwigo.org>2013-10-22 12:58:58 +0000
committermistic100 <mistic@piwigo.org>2013-10-22 12:58:58 +0000
commit24b977d8775e70e15b60cbd5143e84f4c08d4e23 (patch)
tree586d34b971897e705b9803abf6ad4a9686f22e8f
parent677fe6f8881e43b009c8a2babb0565b6ba1620df (diff)
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
Diffstat (limited to '')
-rw-r--r--include/ws_core.inc.php233
-rw-r--r--include/ws_functions.inc.php288
-rw-r--r--tools/ws.htm38
-rw-r--r--ws.php417
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