diff options
| -rw-r--r-- | include/ws_core.inc.php | 233 | ||||
| -rw-r--r-- | include/ws_functions.inc.php | 288 | ||||
| -rw-r--r-- | tools/ws.htm | 38 | ||||
| -rw-r--r-- | ws.php | 417 |
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>ø</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, '"') + '">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>ø</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 }); } @@ -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 |