diff options
| author | Morris Jobke <hey@morrisjobke.de> | 2015-04-16 17:00:08 +0200 |
|---|---|---|
| committer | Morris Jobke <hey@morrisjobke.de> | 2015-04-16 17:00:08 +0200 |
| commit | 7644950b48b094bfe5675348aefb7cf5747d325b (patch) | |
| tree | a1792e21239a86f471da99b454134a5d8533ef77 /lib | |
| parent | 8653da6c16597959c7bd0f0b202747ff96204575 (diff) | |
| download | nextcloud-server-7644950b48b094bfe5675348aefb7cf5747d325b.tar.gz nextcloud-server-7644950b48b094bfe5675348aefb7cf5747d325b.zip | |
Add @since tags to all methods in public namespace
* enhance the app development experience - you can look up the
method introduction right inside the code without searching
via git blame
* easier to write apps for multiple versions
Diffstat (limited to 'lib')
141 files changed, 1373 insertions, 152 deletions
diff --git a/lib/public/activity/iconsumer.php b/lib/public/activity/iconsumer.php index 97adc8a3ba0..a55110ababc 100644 --- a/lib/public/activity/iconsumer.php +++ b/lib/public/activity/iconsumer.php @@ -29,6 +29,12 @@ // This means that they should be used by apps instead of the internal ownCloud classes namespace OCP\Activity; +/** + * Interface IConsumer + * + * @package OCP\Activity + * @since 6.0.0 + */ interface IConsumer { /** * @param $app @@ -42,6 +48,7 @@ interface IConsumer { * @param $type * @param $priority * @return mixed + * @since 6.0.0 */ function receive($app, $subject, $subjectParams, $message, $messageParams, $file, $link, $affectedUser, $type, $priority ); } diff --git a/lib/public/activity/iextension.php b/lib/public/activity/iextension.php index 499fc90f7ca..19d1d2e83a0 100644 --- a/lib/public/activity/iextension.php +++ b/lib/public/activity/iextension.php @@ -31,6 +31,12 @@ // This means that they should be used by apps instead of the internal ownCloud classes namespace OCP\Activity; +/** + * Interface IExtension + * + * @package OCP\Activity + * @since 8.0.0 + */ interface IExtension { const PRIORITY_VERYLOW = 10; @@ -45,6 +51,7 @@ interface IExtension { * * @param string $languageCode * @return array|false + * @since 8.0.0 */ public function getNotificationTypes($languageCode); @@ -54,6 +61,7 @@ interface IExtension { * * @param string $method * @return array|false + * @since 8.0.0 */ public function getDefaultTypes($method); @@ -63,6 +71,7 @@ interface IExtension { * * @param string $type * @return string|false + * @since 8.0.0 */ public function getTypeIcon($type); @@ -77,6 +86,7 @@ interface IExtension { * @param boolean $highlightParams * @param string $languageCode * @return string|false + * @since 8.0.0 */ public function translate($app, $text, $params, $stripPath, $highlightParams, $languageCode); @@ -90,6 +100,7 @@ interface IExtension { * @param string $app * @param string $text * @return array|false + * @since 8.0.0 */ public function getSpecialParameterList($app, $text); @@ -99,6 +110,7 @@ interface IExtension { * * @param array $activity * @return integer|false + * @since 8.0.0 */ public function getGroupParameter($activity); @@ -108,6 +120,7 @@ interface IExtension { * If no further entries are to be added false is no be returned. * * @return array|false + * @since 8.0.0 */ public function getNavigation(); @@ -116,6 +129,7 @@ interface IExtension { * * @param string $filterValue * @return boolean + * @since 8.0.0 */ public function isFilterValid($filterValue); @@ -126,6 +140,7 @@ interface IExtension { * @param array $types * @param string $filter * @return array|false + * @since 8.0.0 */ public function filterNotificationTypes($types, $filter); @@ -137,6 +152,7 @@ interface IExtension { * * @param string $filter * @return array|false + * @since 8.0.0 */ public function getQueryForFilter($filter); } diff --git a/lib/public/activity/imanager.php b/lib/public/activity/imanager.php index 2e55c8b45b2..cadb37da03b 100644 --- a/lib/public/activity/imanager.php +++ b/lib/public/activity/imanager.php @@ -31,6 +31,12 @@ // This means that they should be used by apps instead of the internal ownCloud classes namespace OCP\Activity; +/** + * Interface IManager + * + * @package OCP\Activity + * @since 6.0.0 + */ interface IManager { /** @@ -45,6 +51,7 @@ interface IManager { * @param $type * @param $priority * @return mixed + * @since 6.0.0 */ function publishActivity($app, $subject, $subjectParams, $message, $messageParams, $file, $link, $affectedUser, $type, $priority); @@ -56,6 +63,7 @@ interface IManager { * * @param \Closure $callable * @return void + * @since 6.0.0 */ function registerConsumer(\Closure $callable); @@ -67,6 +75,7 @@ interface IManager { * * @param \Closure $callable * @return void + * @since 8.0.0 */ function registerExtension(\Closure $callable); @@ -74,18 +83,21 @@ interface IManager { * Will return additional notification types as specified by other apps * @param string $languageCode * @return array + * @since 8.0.0 */ function getNotificationTypes($languageCode); /** * @param string $method * @return array + * @since 8.0.0 */ function getDefaultTypes($method); /** * @param string $type * @return string + * @since 8.0.0 */ function getTypeIcon($type); @@ -97,6 +109,7 @@ interface IManager { * @param boolean $highlightParams * @param string $languageCode * @return string|false + * @since 8.0.0 */ function translate($app, $text, $params, $stripPath, $highlightParams, $languageCode); @@ -104,23 +117,27 @@ interface IManager { * @param string $app * @param string $text * @return array|false + * @since 8.0.0 */ function getSpecialParameterList($app, $text); /** * @param array $activity * @return integer|false + * @since 8.0.0 */ function getGroupParameter($activity); /** * @return array + * @since 8.0.0 */ function getNavigation(); /** * @param string $filterValue * @return boolean + * @since 8.0.0 */ function isFilterValid($filterValue); @@ -128,12 +145,14 @@ interface IManager { * @param array $types * @param string $filter * @return array + * @since 8.0.0 */ function filterNotificationTypes($types, $filter); /** * @param string $filter * @return array + * @since 8.0.0 */ function getQueryForFilter($filter); @@ -144,6 +163,7 @@ interface IManager { * * @return string * @throws \UnexpectedValueException If the token is invalid, does not exist or is not unique + * @since 8.1.0 */ public function getCurrentUserId(); } diff --git a/lib/public/api.php b/lib/public/api.php index e0c154dcebf..7ef6902634c 100644 --- a/lib/public/api.php +++ b/lib/public/api.php @@ -33,6 +33,7 @@ namespace OCP; /** * This class provides functions to manage apps in ownCloud + * @since 5.0.0 */ class API { @@ -45,6 +46,7 @@ class API { * @param int $authLevel the level of authentication required for the call (See OC_API constants) * @param array $defaults * @param array $requirements + * @since 5.0.0 */ public static function register($method, $url, $action, $app, $authLevel = OC_API::USER_AUTH, $defaults = array(), $requirements = array()){ diff --git a/lib/public/app.php b/lib/public/app.php index df02008a7df..3f30e0cd031 100644 --- a/lib/public/app.php +++ b/lib/public/app.php @@ -38,6 +38,7 @@ namespace OCP; /** * This class provides functions to manage apps in ownCloud + * @since 4.0.0 */ class App { /** @@ -73,6 +74,7 @@ class App { * * @deprecated Use \OC::$server->getNavigationManager()->add() instead to * register a closure, this helps to speed up all requests against ownCloud + * @since 4.0.0 */ public static function addNavigationEntry($data) { \OC::$server->getNavigationManager()->add($data); @@ -89,6 +91,7 @@ class App { * highlighting the current position of the user. * * @deprecated Use \OC::$server->getNavigationManager()->setActiveEntry() instead + * @since 4.0.0 */ public static function setActiveNavigationEntry( $id ) { return \OC_App::setActiveNavigationEntry( $id ); @@ -99,6 +102,7 @@ class App { * @param string $app appid * @param string $page page to be included * @return void + * @since 4.0.0 */ public static function registerPersonal( $app, $page ) { \OC_App::registerPersonal( $app, $page ); @@ -109,6 +113,7 @@ class App { * @param string $app string appid * @param string $page string page to be included * @return void + * @since 4.0.0 */ public static function registerAdmin( $app, $page ) { \OC_App::registerAdmin( $app, $page ); @@ -119,6 +124,7 @@ class App { * @param string $app id of the app or the path of the info.xml file * @param boolean $path (optional) * @return array + * @since 4.0.0 */ public static function getAppInfo( $app, $path=false ) { return \OC_App::getAppInfo( $app, $path); @@ -130,6 +136,7 @@ class App { * @return boolean * * This function checks whether or not an app is enabled. + * @since 4.0.0 */ public static function isEnabled( $app ) { return \OC_App::isEnabled( $app ); @@ -139,6 +146,7 @@ class App { * Check if the app is enabled, redirects to home if not * @param string $app * @return void + * @since 4.0.0 */ public static function checkAppEnabled( $app ) { \OC_Util::checkAppEnabled( $app ); @@ -148,6 +156,7 @@ class App { * Get the last version of the app, either from appinfo/version or from appinfo/info.xml * @param string $app * @return string + * @since 4.0.0 */ public static function getAppVersion( $app ) { return \OC_App::getAppVersion( $app ); diff --git a/lib/public/app/iappmanager.php b/lib/public/app/iappmanager.php index 69b8c335d67..7be5c921841 100644 --- a/lib/public/app/iappmanager.php +++ b/lib/public/app/iappmanager.php @@ -24,6 +24,12 @@ namespace OCP\App; use OCP\IUser; +/** + * Interface IAppManager + * + * @package OCP\App + * @since 8.0.0 + */ interface IAppManager { /** * Check if an app is enabled for user @@ -31,6 +37,7 @@ interface IAppManager { * @param string $appId * @param \OCP\IUser $user (optional) if not defined, the currently loggedin user will be used * @return bool + * @since 8.0.0 */ public function isEnabledForUser($appId, $user = null); @@ -39,6 +46,7 @@ interface IAppManager { * * @param string $appId * @return bool + * @since 8.0.0 */ public function isInstalled($appId); @@ -46,6 +54,7 @@ interface IAppManager { * Enable an app for every user * * @param string $appId + * @since 8.0.0 */ public function enableApp($appId); @@ -54,6 +63,7 @@ interface IAppManager { * * @param string $appId * @param \OCP\IGroup[] $groups + * @since 8.0.0 */ public function enableAppForGroups($appId, $groups); @@ -61,6 +71,7 @@ interface IAppManager { * Disable an app for every user * * @param string $appId + * @since 8.0.0 */ public function disableApp($appId); @@ -69,6 +80,7 @@ interface IAppManager { * * @param \OCP\IUser $user * @return string[] + * @since 8.1.0 */ public function getEnabledAppsForUser(IUser $user); @@ -76,11 +88,13 @@ interface IAppManager { * List all installed apps * * @return string[] + * @since 8.0.0 */ public function getInstalledApps(); /** * Clear the cached list of apps when enabling/disabling an app + * @since 8.1.0 */ public function clearAppsCache(); } diff --git a/lib/public/appframework/apicontroller.php b/lib/public/appframework/apicontroller.php index 0cb5b0c7d5b..0af37f3a616 100644 --- a/lib/public/appframework/apicontroller.php +++ b/lib/public/appframework/apicontroller.php @@ -33,6 +33,7 @@ use OCP\IRequest; /** * Base class to inherit your controllers from that are used for RESTful APIs + * @since 7.0.0 */ abstract class ApiController extends Controller { @@ -52,6 +53,7 @@ abstract class ApiController extends Controller { * defaults to 'Authorization, Content-Type, Accept' * @param int $corsMaxAge number in seconds how long a preflighted OPTIONS * request should be cached, defaults to 1728000 seconds + * @since 7.0.0 */ public function __construct($appName, IRequest $request, @@ -72,6 +74,7 @@ abstract class ApiController extends Controller { * @NoAdminRequired * @NoCSRFRequired * @PublicPage + * @since 7.0.0 */ public function preflightedCors() { if(isset($this->request->server['HTTP_ORIGIN'])) { diff --git a/lib/public/appframework/app.php b/lib/public/appframework/app.php index d070e0d4c83..bf4e14961f5 100644 --- a/lib/public/appframework/app.php +++ b/lib/public/appframework/app.php @@ -38,6 +38,7 @@ use OC\AppFramework\routing\RouteConfig; * * Any application must inherit this call - all controller instances to be used are * to be registered using IContainer::registerService + * @since 6.0.0 */ class App { @@ -50,6 +51,7 @@ class App { * @param string $topNamespace the namespace which should be prepended to * the transformed app id, defaults to OCA\ * @return string the starting namespace for the app + * @since 8.0.0 */ public static function buildAppNamespace($appId, $topNamespace='OCA\\') { return \OC\AppFramework\App::buildAppNamespace($appId, $topNamespace); @@ -58,6 +60,7 @@ class App { /** * @param array $urlParams an array with variables extracted from the routes + * @since 6.0.0 */ public function __construct($appName, $urlParams = array()) { $this->container = new \OC\AppFramework\DependencyInjection\DIContainer($appName, $urlParams); @@ -67,6 +70,7 @@ class App { /** * @return IAppContainer + * @since 6.0.0 */ public function getContainer() { return $this->container; @@ -88,6 +92,7 @@ class App { * * @param \OCP\Route\IRouter $router * @param array $routes + * @since 6.0.0 */ public function registerRoutes($router, $routes) { $routeConfig = new RouteConfig($this->container, $router, $routes); @@ -123,6 +128,7 @@ class App { * @param string $controllerName the name of the controller under which it is * stored in the DI container * @param string $methodName the method that you want to call + * @since 6.0.0 */ public function dispatch($controllerName, $methodName) { \OC\AppFramework\App::main($controllerName, $methodName, $this->container); diff --git a/lib/public/appframework/controller.php b/lib/public/appframework/controller.php index 944fe0383e1..7eff52649ce 100644 --- a/lib/public/appframework/controller.php +++ b/lib/public/appframework/controller.php @@ -34,32 +34,41 @@ namespace OCP\AppFramework; use OCP\AppFramework\Http\TemplateResponse; use OCP\AppFramework\Http\JSONResponse; use OCP\AppFramework\Http\DataResponse; +use OCP\AppFramework\Http\Response; use OCP\IRequest; /** * Base class to inherit your controllers from + * @since 6.0.0 */ abstract class Controller { /** * app name * @var string + * @since 7.0.0 */ protected $appName; /** * current request * @var \OCP\IRequest + * @since 6.0.0 */ protected $request; + /** + * @var array + * @since 7.0.0 + */ private $responders; /** * constructor of the controller * @param string $appName the name of the app * @param IRequest $request an instance of the request + * @since 6.0.0 - parameter $appName was added in 7.0.0 - parameter $app was removed in 7.0.0 */ public function __construct($appName, IRequest $request){ @@ -88,6 +97,7 @@ abstract class Controller { * Parses an HTTP accept header and returns the supported responder type * @param string $acceptHeader * @return string the responder type + * @since 7.0.0 */ public function getResponderByHTTPHeader($acceptHeader) { $headers = explode(',', $acceptHeader); @@ -112,6 +122,7 @@ abstract class Controller { * Registers a formatter for a type * @param string $format * @param \Closure $responder + * @since 7.0.0 */ protected function registerResponder($format, \Closure $responder) { $this->responders[$format] = $responder; @@ -125,6 +136,7 @@ abstract class Controller { * @param string $format the format for which a formatter has been registered * @throws \DomainException if format does not match a registered formatter * @return Response + * @since 7.0.0 */ public function buildResponse($response, $format='json') { if(array_key_exists($format, $this->responders)) { @@ -151,6 +163,7 @@ abstract class Controller { * 3. GET parameters * @param string $default If the key is not found, this value will be returned * @return mixed the content of the array + * @since 6.0.0 */ public function params($key, $default=null){ return $this->request->getParam($key, $default); @@ -162,6 +175,7 @@ abstract class Controller { * (as GET or POST) or through the URL by the route * @deprecated use $this->request instead * @return array the array with all parameters + * @since 6.0.0 */ public function getParams() { return $this->request->getParams(); @@ -172,6 +186,7 @@ abstract class Controller { * Returns the method of the request * @deprecated use $this->request instead * @return string the method of the request (POST, GET, etc) + * @since 6.0.0 */ public function method() { return $this->request->getMethod(); @@ -183,6 +198,7 @@ abstract class Controller { * @deprecated use $this->request instead * @param string $key the key that will be taken from the $_FILES array * @return array the file in the $_FILES element + * @since 6.0.0 */ public function getUploadedFile($key) { return $this->request->getUploadedFile($key); @@ -194,6 +210,7 @@ abstract class Controller { * @deprecated use $this->request instead * @param string $key the key that will be taken from the $_ENV array * @return array the value in the $_ENV element + * @since 6.0.0 */ public function env($key) { return $this->request->getEnv($key); @@ -205,6 +222,7 @@ abstract class Controller { * @deprecated use $this->request instead * @param string $key the key that will be taken from the $_COOKIE array * @return array the value in the $_COOKIE element + * @since 6.0.0 */ public function cookie($key) { return $this->request->getCookie($key); @@ -220,6 +238,7 @@ abstract class Controller { * admin an entry in the admin settings * @param string[] $headers set additional headers in name/value pairs * @return \OCP\AppFramework\Http\TemplateResponse containing the page + * @since 6.0.0 */ public function render($templateName, array $params=array(), $renderAs='user', array $headers=array()){ diff --git a/lib/public/appframework/db/doesnotexistexception.php b/lib/public/appframework/db/doesnotexistexception.php index 2d5d145c223..6df0477498c 100644 --- a/lib/public/appframework/db/doesnotexistexception.php +++ b/lib/public/appframework/db/doesnotexistexception.php @@ -27,6 +27,7 @@ namespace OCP\AppFramework\Db; /** * This is returned or should be returned when a find request does not find an * entry in the database + * @since 7.0.0 */ class DoesNotExistException extends \Exception { @@ -38,4 +39,4 @@ class DoesNotExistException extends \Exception { parent::__construct($msg); } -}
\ No newline at end of file +} diff --git a/lib/public/appframework/db/entity.php b/lib/public/appframework/db/entity.php index 1a9e9777fe4..a12f759357e 100644 --- a/lib/public/appframework/db/entity.php +++ b/lib/public/appframework/db/entity.php @@ -26,6 +26,7 @@ namespace OCP\AppFramework\Db; /** * @method integer getId() * @method void setId(integer $id) + * @since 7.0.0 */ abstract class Entity { @@ -40,6 +41,7 @@ abstract class Entity { * @param array $params the array which was obtained via $this->params('key') * in the controller * @return Entity + * @since 7.0.0 */ public static function fromParams(array $params) { $instance = new static(); @@ -56,6 +58,7 @@ abstract class Entity { /** * Maps the keys of the row array to the attributes * @param array $row the row to map onto the entity + * @since 7.0.0 */ public static function fromRow(array $row){ $instance = new static(); @@ -73,7 +76,8 @@ abstract class Entity { /** - * @return an array with attribute and type + * @return array with attribute and type + * @since 7.0.0 */ public function getFieldTypes() { return $this->_fieldTypes; @@ -82,12 +86,12 @@ abstract class Entity { /** * Marks the entity as clean needed for setting the id after the insertion + * @since 7.0.0 */ public function resetUpdatedFields(){ $this->_updatedFields = array(); } - protected function setter($name, $args) { // setters should only work for existing attributes if(property_exists($this, $name)){ @@ -108,7 +112,6 @@ abstract class Entity { } } - protected function getter($name) { // getters should only work for existing attributes if(property_exists($this, $name)){ @@ -125,6 +128,7 @@ abstract class Entity { * into an array: for instance setId will save Id in the * updated fields array so it can be easily used to create the * getter method + * @since 7.0.0 */ public function __call($methodName, $args){ $attr = lcfirst( substr($methodName, 3) ); @@ -154,6 +158,7 @@ abstract class Entity { * Transform a database columnname to a property * @param string $columnName the name of the column * @return string the property name + * @since 7.0.0 */ public function columnToProperty($columnName){ $parts = explode('_', $columnName); @@ -175,6 +180,7 @@ abstract class Entity { * Transform a property to a database column name * @param string $property the name of the property * @return string the column name + * @since 7.0.0 */ public function propertyToColumn($property){ $parts = preg_split('/(?=[A-Z])/', $property); @@ -194,6 +200,7 @@ abstract class Entity { /** * @return array array of updated fields for update query + * @since 7.0.0 */ public function getUpdatedFields(){ return $this->_updatedFields; @@ -216,6 +223,7 @@ abstract class Entity { * Warning: This doesn't result in a unique value * @param string $attributeName the name of the attribute, which value should be slugified * @return string slugified value + * @since 7.0.0 */ public function slugify($attributeName){ // toSlug should only work for existing attributes diff --git a/lib/public/appframework/db/mapper.php b/lib/public/appframework/db/mapper.php index 16a781f0ead..157bea36916 100644 --- a/lib/public/appframework/db/mapper.php +++ b/lib/public/appframework/db/mapper.php @@ -32,6 +32,7 @@ use OCP\IDb; /** * Simple parent class for inheriting your data access layer from. This class * may be subject to change in the future + * @since 7.0.0 */ abstract class Mapper { @@ -44,6 +45,7 @@ abstract class Mapper { * @param string $tableName the name of the table. set this to allow entity * @param string $entityClass the name of the entity that the sql should be * mapped to queries without using sql + * @since 7.0.0 */ public function __construct(IDBConnection $db, $tableName, $entityClass=null){ $this->db = $db; @@ -61,6 +63,7 @@ abstract class Mapper { /** * @return string the table name + * @since 7.0.0 */ public function getTableName(){ return $this->tableName; @@ -71,6 +74,7 @@ abstract class Mapper { * Deletes an entity from the table * @param Entity $entity the entity that should be deleted * @return Entity the deleted entity + * @since 7.0.0 - return value added in 8.1.0 */ public function delete(Entity $entity){ $sql = 'DELETE FROM `' . $this->tableName . '` WHERE `id` = ?'; @@ -84,6 +88,7 @@ abstract class Mapper { * Creates a new entry in the db from an entity * @param Entity $entity the entity that should be created * @return Entity the saved entity with the set id + * @since 7.0.0 */ public function insert(Entity $entity){ // get updated fields to save, fields have to be set using a setter to @@ -132,6 +137,7 @@ abstract class Mapper { * @throws \InvalidArgumentException if entity has no id * @param Entity $entity the entity that should be created * @return Entity the saved entity with the set id + * @since 7.0.0 - return value was added in 8.0.0 */ public function update(Entity $entity){ // if entity wasn't changed it makes no sense to run a db query @@ -216,6 +222,7 @@ abstract class Mapper { * @param int $limit the maximum number of rows * @param int $offset from which row we want to start * @return \PDOStatement the database query result + * @since 7.0.0 */ protected function execute($sql, array $params=[], $limit=null, $offset=null){ if ($this->db instanceof IDb) { @@ -264,6 +271,7 @@ abstract class Mapper { * @throws DoesNotExistException if the item does not exist * @throws MultipleObjectsReturnedException if more than one item exist * @return array the result as row + * @since 7.0.0 */ protected function findOneQuery($sql, array $params=[], $limit=null, $offset=null){ $stmt = $this->execute($sql, $params, $limit, $offset); @@ -289,6 +297,7 @@ abstract class Mapper { * from the current mapper name (MyEntityMapper -> MyEntity) * @param array $row the row which should be converted to an entity * @return Entity the entity + * @since 7.0.0 */ protected function mapRowToEntity($row) { return call_user_func($this->entityClass .'::fromRow', $row); @@ -302,6 +311,7 @@ abstract class Mapper { * @param int $limit the maximum number of rows * @param int $offset from which row we want to start * @return array all fetched entities + * @since 7.0.0 */ protected function findEntities($sql, array $params=[], $limit=null, $offset=null) { $stmt = $this->execute($sql, $params, $limit, $offset); @@ -328,6 +338,7 @@ abstract class Mapper { * @throws DoesNotExistException if the item does not exist * @throws MultipleObjectsReturnedException if more than one item exist * @return Entity the entity + * @since 7.0.0 */ protected function findEntity($sql, array $params=[], $limit=null, $offset=null){ return $this->mapRowToEntity($this->findOneQuery($sql, $params, $limit, $offset)); diff --git a/lib/public/appframework/db/multipleobjectsreturnedexception.php b/lib/public/appframework/db/multipleobjectsreturnedexception.php index 6aa4ea349dc..cdfb748b145 100644 --- a/lib/public/appframework/db/multipleobjectsreturnedexception.php +++ b/lib/public/appframework/db/multipleobjectsreturnedexception.php @@ -27,6 +27,7 @@ namespace OCP\AppFramework\Db; /** * This is returned or should be returned when a find request finds more than one * row + * @since 7.0.0 */ class MultipleObjectsReturnedException extends \Exception { @@ -38,4 +39,4 @@ class MultipleObjectsReturnedException extends \Exception { parent::__construct($msg); } -}
\ No newline at end of file +} diff --git a/lib/public/appframework/http.php b/lib/public/appframework/http.php index 095b8e30583..65b62ffd15a 100644 --- a/lib/public/appframework/http.php +++ b/lib/public/appframework/http.php @@ -30,6 +30,7 @@ namespace OCP\AppFramework; /** * Base class which contains constants for HTTP status codes + * @since 6.0.0 */ class Http { diff --git a/lib/public/appframework/http/contentsecuritypolicy.php b/lib/public/appframework/http/contentsecuritypolicy.php index 6c527879698..be4b6e60f97 100644 --- a/lib/public/appframework/http/contentsecuritypolicy.php +++ b/lib/public/appframework/http/contentsecuritypolicy.php @@ -35,6 +35,7 @@ use OCP\AppFramework\Http; * should require no modification at all for most use-cases. * * @package OCP\AppFramework\Http + * @since 8.1.0 */ class ContentSecurityPolicy { /** @var bool Whether inline JS snippets are allowed */ @@ -86,6 +87,7 @@ class ContentSecurityPolicy { * Whether inline JavaScript snippets are allowed or forbidden * @param bool $state * @return $this + * @since 8.1.0 */ public function allowInlineScript($state = false) { $this->inlineScriptAllowed = $state; @@ -96,6 +98,7 @@ class ContentSecurityPolicy { * Whether eval in JavaScript is allowed or forbidden * @param bool $state * @return $this + * @since 8.1.0 */ public function allowEvalScript($state = true) { $this->evalScriptAllowed= $state; @@ -107,6 +110,7 @@ class ContentSecurityPolicy { * allow JavaScript from all domains. * @param string $domain Domain to whitelist. Any passed value needs to be properly sanitized. * @return $this + * @since 8.1.0 */ public function addAllowedScriptDomain($domain) { $this->allowedScriptDomains[] = $domain; @@ -117,6 +121,7 @@ class ContentSecurityPolicy { * Whether inline CSS snippets are allowed or forbidden * @param bool $state * @return $this + * @since 8.1.0 */ public function allowInlineStyle($state = true) { $this->inlineStyleAllowed = $state; @@ -128,6 +133,7 @@ class ContentSecurityPolicy { * CSS from all domains. * @param string $domain Domain to whitelist. Any passed value needs to be properly sanitized. * @return $this + * @since 8.1.0 */ public function addAllowedStyleDomain($domain) { $this->allowedStyleDomains[] = $domain; @@ -139,6 +145,7 @@ class ContentSecurityPolicy { * fonts from all domains. * @param string $domain Domain to whitelist. Any passed value needs to be properly sanitized. * @return $this + * @since 8.1.0 */ public function addAllowedFontDomain($domain) { $this->allowedFontDomains[] = $domain; @@ -150,6 +157,7 @@ class ContentSecurityPolicy { * images from all domains. * @param string $domain Domain to whitelist. Any passed value needs to be properly sanitized. * @return $this + * @since 8.1.0 */ public function addAllowedImageDomain($domain) { $this->allowedImageDomains[] = $domain; @@ -160,6 +168,7 @@ class ContentSecurityPolicy { * To which remote domains the JS connect to. * @param string $domain Domain to whitelist. Any passed value needs to be properly sanitized. * @return $this + * @since 8.1.0 */ public function addAllowedConnectDomain($domain) { $this->allowedConnectDomains[] = $domain; @@ -170,6 +179,7 @@ class ContentSecurityPolicy { * From whoch domains media elements can be embedded. * @param string $domain Domain to whitelist. Any passed value needs to be properly sanitized. * @return $this + * @since 8.1.0 */ public function addAllowedMediaDomain($domain) { $this->allowedMediaDomains[] = $domain; @@ -180,6 +190,7 @@ class ContentSecurityPolicy { * From which domains objects such as <object>, <embed> or <applet> are executed * @param string $domain Domain to whitelist. Any passed value needs to be properly sanitized. * @return $this + * @since 8.1.0 */ public function addAllowedObjectDomain($domain) { $this->allowedObjectDomains[] = $domain; @@ -190,6 +201,7 @@ class ContentSecurityPolicy { * Which domains can be embedded in an iframe * @param string $domain Domain to whitelist. Any passed value needs to be properly sanitized. * @return $this + * @since 8.1.0 */ public function addAllowedFrameDomain($domain) { $this->allowedFrameDomains[] = $domain; @@ -200,6 +212,7 @@ class ContentSecurityPolicy { * Domains from which web-workers and nested browsing content can load elements * @param string $domain Domain to whitelist. Any passed value needs to be properly sanitized. * @return $this + * @since 8.1.0 */ public function addAllowedChildSrcDomain($domain) { $this->allowedChildSrcDomains[] = $domain; @@ -209,6 +222,7 @@ class ContentSecurityPolicy { /** * Get the generated Content-Security-Policy as a string * @return string + * @since 8.1.0 */ public function buildPolicy() { $policy = "default-src 'none';"; diff --git a/lib/public/appframework/http/datadisplayresponse.php b/lib/public/appframework/http/datadisplayresponse.php index ebb77950c96..35272d0f823 100644 --- a/lib/public/appframework/http/datadisplayresponse.php +++ b/lib/public/appframework/http/datadisplayresponse.php @@ -23,6 +23,12 @@ namespace OCP\AppFramework\Http; use OCP\AppFramework\Http; +/** + * Class DataDisplayResponse + * + * @package OCP\AppFramework\Http + * @since 8.1.0 + */ class DataDisplayResponse extends Response { /** @@ -36,6 +42,7 @@ class DataDisplayResponse extends Response { * @param string $data the data to display * @param int $statusCode the Http status code, defaults to 200 * @param array $headers additional key value based headers + * @since 8.1.0 */ public function __construct($data="", $statusCode=Http::STATUS_OK, $headers=[]) { @@ -48,6 +55,7 @@ class DataDisplayResponse extends Response { /** * Outputs data. No processing is done. * @return string + * @since 8.1.0 */ public function render() { return $this->data; @@ -58,6 +66,7 @@ class DataDisplayResponse extends Response { * Sets values in the data * @param string $data the data to display * @return DataDisplayResponse Reference to this object + * @since 8.1.0 */ public function setData($data){ $this->data = $data; @@ -69,6 +78,7 @@ class DataDisplayResponse extends Response { /** * Used to get the set parameters * @return string the data + * @since 8.1.0 */ public function getData(){ return $this->data; diff --git a/lib/public/appframework/http/datadownloadresponse.php b/lib/public/appframework/http/datadownloadresponse.php index 837023acb8a..612386f9801 100644 --- a/lib/public/appframework/http/datadownloadresponse.php +++ b/lib/public/appframework/http/datadownloadresponse.php @@ -21,6 +21,12 @@ */ namespace OCP\AppFramework\Http; +/** + * Class DataDownloadResponse + * + * @package OCP\AppFramework\Http + * @since 8.0.0 + */ class DataDownloadResponse extends DownloadResponse { /** * @var string @@ -32,6 +38,7 @@ class DataDownloadResponse extends DownloadResponse { * @param string $data text to be downloaded * @param string $filename the name that the downloaded file should have * @param string $contentType the mimetype that the downloaded file should have + * @since 8.0.0 */ public function __construct($data, $filename, $contentType) { $this->data = $data; @@ -40,6 +47,7 @@ class DataDownloadResponse extends DownloadResponse { /** * @param string $data + * @since 8.0.0 */ public function setData($data) { $this->data = $data; @@ -47,6 +55,7 @@ class DataDownloadResponse extends DownloadResponse { /** * @return string + * @since 8.0.0 */ public function render() { return $this->data; diff --git a/lib/public/appframework/http/dataresponse.php b/lib/public/appframework/http/dataresponse.php index b86686ffe82..555faa6ea1a 100644 --- a/lib/public/appframework/http/dataresponse.php +++ b/lib/public/appframework/http/dataresponse.php @@ -32,6 +32,7 @@ use OCP\AppFramework\Http; /** * A generic DataResponse class that is used to return generic data responses * for responders to transform + * @since 8.0.0 */ class DataResponse extends Response { @@ -46,6 +47,7 @@ class DataResponse extends Response { * @param array|object $data the object or array that should be transformed * @param int $statusCode the Http status code, defaults to 200 * @param array $headers additional key value based headers + * @since 8.0.0 */ public function __construct($data=array(), $statusCode=Http::STATUS_OK, array $headers=array()) { @@ -59,6 +61,7 @@ class DataResponse extends Response { * Sets values in the data json array * @param array|object $data an array or object which will be transformed * @return DataResponse Reference to this object + * @since 8.0.0 */ public function setData($data){ $this->data = $data; @@ -70,6 +73,7 @@ class DataResponse extends Response { /** * Used to get the set parameters * @return array the data + * @since 8.0.0 */ public function getData(){ return $this->data; diff --git a/lib/public/appframework/http/downloadresponse.php b/lib/public/appframework/http/downloadresponse.php index dfcc65ffea5..0b9a8bcc6d8 100644 --- a/lib/public/appframework/http/downloadresponse.php +++ b/lib/public/appframework/http/downloadresponse.php @@ -27,6 +27,7 @@ namespace OCP\AppFramework\Http; /** * Prompts the user to download the a file + * @since 7.0.0 */ class DownloadResponse extends \OCP\AppFramework\Http\Response { @@ -37,6 +38,7 @@ class DownloadResponse extends \OCP\AppFramework\Http\Response { * Creates a response that prompts the user to download the file * @param string $filename the name that the downloaded file should have * @param string $contentType the mimetype that the downloaded file should have + * @since 7.0.0 */ public function __construct($filename, $contentType) { $this->filename = $filename; diff --git a/lib/public/appframework/http/icallbackresponse.php b/lib/public/appframework/http/icallbackresponse.php index 2f27a164897..87da73a5ad5 100644 --- a/lib/public/appframework/http/icallbackresponse.php +++ b/lib/public/appframework/http/icallbackresponse.php @@ -27,6 +27,7 @@ namespace OCP\AppFramework\Http; * Interface ICallbackResponse * * @package OCP\AppFramework\Http + * @since 8.1.0 */ interface ICallbackResponse { @@ -34,6 +35,7 @@ interface ICallbackResponse { * Outputs the content that should be printed * * @param IOutput $output a small wrapper that handles output + * @since 8.1.0 */ function callback(IOutput $output); diff --git a/lib/public/appframework/http/ioutput.php b/lib/public/appframework/http/ioutput.php index 8fd362daf16..ad90dc1e4cb 100644 --- a/lib/public/appframework/http/ioutput.php +++ b/lib/public/appframework/http/ioutput.php @@ -24,11 +24,13 @@ namespace OCP\AppFramework\Http; /** * Very thin wrapper class to make output testable + * @since 8.1.0 */ interface IOutput { /** * @param string $out + * @since 8.1.0 */ public function setOutput($out); @@ -36,21 +38,25 @@ interface IOutput { * @param string $path * * @return bool false if an error occured + * @since 8.1.0 */ public function setReadfile($path); /** * @param string $header + * @since 8.1.0 */ public function setHeader($header); /** * @return int returns the current http response code + * @since 8.1.0 */ public function getHttpResponseCode(); /** * @param int $code sets the http status code + * @since 8.1.0 */ public function setHttpResponseCode($code); @@ -62,6 +68,7 @@ interface IOutput { * @param string $domain * @param bool $secure * @param bool $httponly + * @since 8.1.0 */ public function setCookie($name, $value, $expire, $path, $domain, $secure, $httponly); diff --git a/lib/public/appframework/http/jsonresponse.php b/lib/public/appframework/http/jsonresponse.php index 492811043f1..1a770109d45 100644 --- a/lib/public/appframework/http/jsonresponse.php +++ b/lib/public/appframework/http/jsonresponse.php @@ -33,6 +33,7 @@ use OCP\AppFramework\Http; /** * A renderer for JSON calls + * @since 6.0.0 */ class JSONResponse extends Response { @@ -47,6 +48,7 @@ class JSONResponse extends Response { * constructor of JSONResponse * @param array|object $data the object or array that should be transformed * @param int $statusCode the Http status code, defaults to 200 + * @since 6.0.0 */ public function __construct($data=array(), $statusCode=Http::STATUS_OK) { $this->data = $data; @@ -58,6 +60,7 @@ class JSONResponse extends Response { /** * Returns the rendered json * @return string the rendered json + * @since 6.0.0 */ public function render(){ return json_encode($this->data); @@ -68,6 +71,7 @@ class JSONResponse extends Response { * @param array|object $data an array or object which will be transformed * to JSON * @return JSONResponse Reference to this object + * @since 6.0.0 - return value was added in 7.0.0 */ public function setData($data){ $this->data = $data; @@ -79,6 +83,7 @@ class JSONResponse extends Response { /** * Used to get the set parameters * @return array the data + * @since 6.0.0 */ public function getData(){ return $this->data; diff --git a/lib/public/appframework/http/notfoundresponse.php b/lib/public/appframework/http/notfoundresponse.php index 21f0461f5e6..8f59384faf1 100644 --- a/lib/public/appframework/http/notfoundresponse.php +++ b/lib/public/appframework/http/notfoundresponse.php @@ -26,15 +26,20 @@ use OCP\Template; /** * A generic 404 response showing an 404 error page as well to the end-user + * @since 8.1.0 */ class NotFoundResponse extends Response { + /** + * @since 8.1.0 + */ public function __construct() { $this->setStatus(404); } /** * @return string + * @since 8.1.0 */ public function render() { $template = new Template('core', '404', 'guest'); diff --git a/lib/public/appframework/http/ocsresponse.php b/lib/public/appframework/http/ocsresponse.php index 4cc1ba80d03..c098e306656 100644 --- a/lib/public/appframework/http/ocsresponse.php +++ b/lib/public/appframework/http/ocsresponse.php @@ -33,6 +33,7 @@ use OC_OCS; /** * A renderer for OCS responses + * @since 8.1.0 */ class OCSResponse extends Response { @@ -58,6 +59,7 @@ class OCSResponse extends Response { * @param int $dimension * @param int|string $itemscount * @param int|string $itemsperpage + * @since 8.1.0 */ public function __construct($format, $status, $statuscode, $message, $data=[], $tag='', $tagattribute='', @@ -86,7 +88,10 @@ class OCSResponse extends Response { } } - + /** + * @return string + * @since 8.1.0 + */ public function render() { return OC_OCS::generateXml( $this->format, $this->status, $this->statuscode, $this->message, @@ -96,4 +101,4 @@ class OCSResponse extends Response { } -}
\ No newline at end of file +} diff --git a/lib/public/appframework/http/redirectresponse.php b/lib/public/appframework/http/redirectresponse.php index a9108be8c04..41a2e48035e 100644 --- a/lib/public/appframework/http/redirectresponse.php +++ b/lib/public/appframework/http/redirectresponse.php @@ -31,6 +31,7 @@ use OCP\AppFramework\Http; /** * Redirects to a different URL + * @since 7.0.0 */ class RedirectResponse extends Response { @@ -39,6 +40,7 @@ class RedirectResponse extends Response { /** * Creates a response that redirects to a url * @param string $redirectURL the url to redirect to + * @since 7.0.0 */ public function __construct($redirectURL) { $this->redirectURL = $redirectURL; @@ -49,6 +51,7 @@ class RedirectResponse extends Response { /** * @return string the url to redirect + * @since 7.0.0 */ public function getRedirectURL() { return $this->redirectURL; diff --git a/lib/public/appframework/http/response.php b/lib/public/appframework/http/response.php index b79777c5f1d..8fd5fdd8f53 100644 --- a/lib/public/appframework/http/response.php +++ b/lib/public/appframework/http/response.php @@ -37,6 +37,7 @@ use OCP\AppFramework\Http; * Base class for responses. Also used to just send headers. * * It handles headers, HTTP status code, last modified and ETag. + * @since 6.0.0 */ class Response { @@ -85,6 +86,7 @@ class Response { * @param int $cacheSeconds the amount of seconds that should be cached * if 0 then caching will be disabled * @return $this + * @since 6.0.0 - return value was added in 7.0.0 */ public function cacheFor($cacheSeconds) { @@ -106,6 +108,7 @@ class Response { * to null cookie will be considered as session * cookie. * @return $this + * @since 8.0.0 */ public function addCookie($name, $value, \DateTime $expireDate = null) { $this->cookies[$name] = array('value' => $value, 'expireDate' => $expireDate); @@ -117,6 +120,7 @@ class Response { * Set the specified cookies * @param array $cookies array('foo' => array('value' => 'bar', 'expire' => null)) * @return $this + * @since 8.0.0 */ public function setCookies(array $cookies) { $this->cookies = $cookies; @@ -128,6 +132,7 @@ class Response { * Invalidates the specified cookie * @param string $name * @return $this + * @since 8.0.0 */ public function invalidateCookie($name) { $this->addCookie($name, 'expired', new \DateTime('1971-01-01 00:00')); @@ -138,6 +143,7 @@ class Response { * Invalidates the specified cookies * @param array $cookieNames array('foo', 'bar') * @return $this + * @since 8.0.0 */ public function invalidateCookies(array $cookieNames) { foreach($cookieNames as $cookieName) { @@ -149,6 +155,7 @@ class Response { /** * Returns the cookies * @return array + * @since 8.0.0 */ public function getCookies() { return $this->cookies; @@ -160,6 +167,7 @@ class Response { * @param string $name The name of the HTTP header * @param string $value The value, null will delete it * @return $this + * @since 6.0.0 - return value was added in 7.0.0 */ public function addHeader($name, $value) { $name = trim($name); // always remove leading and trailing whitespace @@ -180,6 +188,7 @@ class Response { * Set the headers * @param array $headers value header pairs * @return $this + * @since 8.0.0 */ public function setHeaders(array $headers) { $this->headers = $headers; @@ -191,6 +200,7 @@ class Response { /** * Returns the set headers * @return array the headers + * @since 6.0.0 */ public function getHeaders() { $mergeWith = []; @@ -217,6 +227,7 @@ class Response { /** * By default renders no output * @return null + * @since 6.0.0 */ public function render() { return null; @@ -224,10 +235,11 @@ class Response { /** - * Set response status - * @param int $status a HTTP status code, see also the STATUS constants - * @return Response Reference to this object - */ + * Set response status + * @param int $status a HTTP status code, see also the STATUS constants + * @return Response Reference to this object + * @since 6.0.0 - return value was added in 7.0.0 + */ public function setStatus($status) { $this->status = $status; @@ -238,6 +250,7 @@ class Response { * Set a Content-Security-Policy * @param ContentSecurityPolicy $csp Policy to set for the response object * @return $this + * @since 8.1.0 */ public function setContentSecurityPolicy(ContentSecurityPolicy $csp) { $this->contentSecurityPolicy = $csp; @@ -248,6 +261,7 @@ class Response { * Get the currently used Content-Security-Policy * @return ContentSecurityPolicy|null Used Content-Security-Policy or null if * none specified. + * @since 8.1.0 */ public function getContentSecurityPolicy() { return $this->contentSecurityPolicy; @@ -256,6 +270,7 @@ class Response { /** * Get response status + * @since 6.0.0 */ public function getStatus() { return $this->status; @@ -265,6 +280,7 @@ class Response { /** * Get the ETag * @return string the etag + * @since 6.0.0 */ public function getETag() { return $this->ETag; @@ -274,6 +290,7 @@ class Response { /** * Get "last modified" date * @return \DateTime RFC2822 formatted last modified date + * @since 6.0.0 */ public function getLastModified() { return $this->lastModified; @@ -284,6 +301,7 @@ class Response { * Set the ETag * @param string $ETag * @return Response Reference to this object + * @since 6.0.0 - return value was added in 7.0.0 */ public function setETag($ETag) { $this->ETag = $ETag; @@ -296,6 +314,7 @@ class Response { * Set "last modified" date * @param \DateTime $lastModified * @return Response Reference to this object + * @since 6.0.0 - return value was added in 7.0.0 */ public function setLastModified($lastModified) { $this->lastModified = $lastModified; diff --git a/lib/public/appframework/http/streamresponse.php b/lib/public/appframework/http/streamresponse.php index 057c395d84f..625b3d62278 100644 --- a/lib/public/appframework/http/streamresponse.php +++ b/lib/public/appframework/http/streamresponse.php @@ -28,6 +28,7 @@ use OCP\AppFramework\Http; * Class StreamResponse * * @package OCP\AppFramework\Http + * @since 8.1.0 */ class StreamResponse extends Response implements ICallbackResponse { /** @var string */ @@ -35,6 +36,7 @@ class StreamResponse extends Response implements ICallbackResponse { /** * @param string $filePath the path to the file which should be streamed + * @since 8.1.0 */ public function __construct ($filePath) { $this->filePath = $filePath; @@ -45,6 +47,7 @@ class StreamResponse extends Response implements ICallbackResponse { * Streams the file using readfile * * @param IOutput $output a small wrapper that handles output + * @since 8.1.0 */ public function callback (IOutput $output) { // handle caching diff --git a/lib/public/appframework/http/templateresponse.php b/lib/public/appframework/http/templateresponse.php index 209b069c89a..961903a8eab 100644 --- a/lib/public/appframework/http/templateresponse.php +++ b/lib/public/appframework/http/templateresponse.php @@ -32,6 +32,7 @@ namespace OCP\AppFramework\Http; /** * Response for a normal template + * @since 6.0.0 */ class TemplateResponse extends Response { @@ -66,6 +67,7 @@ class TemplateResponse extends Response { * @param array $params an array of parameters which should be passed to the * template * @param string $renderAs how the page should be rendered, defaults to user + * @since 6.0.0 - parameters $params and $renderAs were added in 7.0.0 */ public function __construct($appName, $templateName, array $params=array(), $renderAs='user') { @@ -81,6 +83,7 @@ class TemplateResponse extends Response { * @param array $params an array with key => value structure which sets template * variables * @return TemplateResponse Reference to this object + * @since 6.0.0 - return value was added in 7.0.0 */ public function setParams(array $params){ $this->params = $params; @@ -92,6 +95,7 @@ class TemplateResponse extends Response { /** * Used for accessing the set parameters * @return array the params + * @since 6.0.0 */ public function getParams(){ return $this->params; @@ -101,6 +105,7 @@ class TemplateResponse extends Response { /** * Used for accessing the name of the set template * @return string the name of the used template + * @since 6.0.0 */ public function getTemplateName(){ return $this->templateName; @@ -114,6 +119,7 @@ class TemplateResponse extends Response { * normal page including footer and header and blank * just renders the plain template * @return TemplateResponse Reference to this object + * @since 6.0.0 - return value was added in 7.0.0 */ public function renderAs($renderAs){ $this->renderAs = $renderAs; @@ -125,6 +131,7 @@ class TemplateResponse extends Response { /** * Returns the set renderAs * @return string the renderAs value + * @since 6.0.0 */ public function getRenderAs(){ return $this->renderAs; @@ -134,6 +141,7 @@ class TemplateResponse extends Response { /** * Returns the rendered html * @return string the rendered html + * @since 6.0.0 */ public function render(){ // \OCP\Template needs an empty string instead of 'blank' for an unwrapped response diff --git a/lib/public/appframework/iappcontainer.php b/lib/public/appframework/iappcontainer.php index a577d31ed93..47eba58aece 100644 --- a/lib/public/appframework/iappcontainer.php +++ b/lib/public/appframework/iappcontainer.php @@ -32,35 +32,41 @@ use OCP\IContainer; * @package OCP\AppFramework * * This container interface provides short cuts for app developers to access predefined app service. + * @since 6.0.0 */ interface IAppContainer extends IContainer { /** * used to return the appname of the set application * @return string the name of your application + * @since 6.0.0 */ function getAppName(); /** * @deprecated implements only deprecated methods * @return IApi + * @since 6.0.0 */ function getCoreApi(); /** * @return \OCP\IServerContainer + * @since 6.0.0 */ function getServer(); /** * @param string $middleWare * @return boolean + * @since 6.0.0 */ function registerMiddleWare($middleWare); /** * @deprecated use IUserSession->isLoggedIn() * @return boolean + * @since 6.0.0 */ function isLoggedIn(); @@ -69,6 +75,7 @@ interface IAppContainer extends IContainer { * @return boolean * @deprecated use the groupmanager instead to find out if the user is in * the admin group + * @since 6.0.0 */ function isAdminUser(); @@ -77,6 +84,7 @@ interface IAppContainer extends IContainer { * @param string $message * @param string $level * @return mixed + * @since 6.0.0 */ function log($message, $level); diff --git a/lib/public/appframework/middleware.php b/lib/public/appframework/middleware.php index c7c46347623..6c75a2dfc74 100644 --- a/lib/public/appframework/middleware.php +++ b/lib/public/appframework/middleware.php @@ -37,6 +37,7 @@ use OCP\AppFramework\Http\Response; * deal with possible exceptions raised in the controller methods. * They're modeled after Django's middleware system: * https://docs.djangoproject.com/en/dev/topics/http/middleware/ + * @since 6.0.0 */ abstract class Middleware { @@ -48,6 +49,7 @@ abstract class Middleware { * @param Controller $controller the controller that is being called * @param string $methodName the name of the method that will be called on * the controller + * @since 6.0.0 */ public function beforeController($controller, $methodName){ @@ -67,6 +69,7 @@ abstract class Middleware { * @param \Exception $exception the thrown exception * @throws \Exception the passed in exception if it cant handle it * @return Response a Response object in case that the exception was handled + * @since 6.0.0 */ public function afterException($controller, $methodName, \Exception $exception){ throw $exception; @@ -82,6 +85,7 @@ abstract class Middleware { * the controller * @param Response $response the generated response from the controller * @return Response a Response object + * @since 6.0.0 */ public function afterController($controller, $methodName, Response $response){ return $response; @@ -97,6 +101,7 @@ abstract class Middleware { * the controller * @param string $output the generated output from a response * @return string the output that should be printed + * @since 6.0.0 */ public function beforeOutput($controller, $methodName, $output){ return $output; diff --git a/lib/public/appframework/ocscontroller.php b/lib/public/appframework/ocscontroller.php index e3fca47e487..93077586f43 100644 --- a/lib/public/appframework/ocscontroller.php +++ b/lib/public/appframework/ocscontroller.php @@ -34,6 +34,7 @@ use OCP\IRequest; /** * Base class to inherit your controllers from that are used for RESTful APIs + * @since 8.1.0 */ abstract class OCSController extends ApiController { @@ -49,6 +50,7 @@ abstract class OCSController extends ApiController { * defaults to 'Authorization, Content-Type, Accept' * @param int $corsMaxAge number in seconds how long a preflighted OPTIONS * request should be cached, defaults to 1728000 seconds + * @since 8.1.0 */ public function __construct($appName, IRequest $request, @@ -70,6 +72,7 @@ abstract class OCSController extends ApiController { * Unwrap data and build ocs response * @param string $format json or xml * @param array|DataResponse $data the data which should be transformed + * @since 8.1.0 */ private function buildOCSResponse($format, $data) { if ($data instanceof DataResponse) { diff --git a/lib/public/appframework/queryexception.php b/lib/public/appframework/queryexception.php index bf038e19976..c8cd0cfe9fb 100644 --- a/lib/public/appframework/queryexception.php +++ b/lib/public/appframework/queryexception.php @@ -24,5 +24,10 @@ namespace OCP\AppFramework; use Exception; - +/** + * Class QueryException + * + * @package OCP\AppFramework + * @since 8.1.0 + */ class QueryException extends Exception {} diff --git a/lib/public/appframework/utility/icontrollermethodreflector.php b/lib/public/appframework/utility/icontrollermethodreflector.php index 39cf99515c0..a3b57cf6936 100644 --- a/lib/public/appframework/utility/icontrollermethodreflector.php +++ b/lib/public/appframework/utility/icontrollermethodreflector.php @@ -28,12 +28,14 @@ namespace OCP\AppFramework\Utility; * Reads and parses annotations from doc comments * * @package OCP\AppFramework\Utility + * @since 8.0.0 */ interface IControllerMethodReflector { /** * @param object $object an object or classname * @param string $method the method which we want to inspect + * @since 8.0.0 */ public function reflect($object, $method); @@ -44,11 +46,13 @@ interface IControllerMethodReflector { * parsed * @return string|null type in the type parameters (@param int $something) * would return int or null if not existing + * @since 8.0.0 */ public function getType($parameter); /** * @return array the arguments of the method with key => default value + * @since 8.0.0 */ public function getParameters(); @@ -57,7 +61,8 @@ interface IControllerMethodReflector { * * @param string $name the name of the annotation * @return bool true if the annotation is found + * @since 8.0.0 */ public function hasAnnotation($name); -}
\ No newline at end of file +} diff --git a/lib/public/appframework/utility/itimefactory.php b/lib/public/appframework/utility/itimefactory.php index 54013adfbf4..6fe2fab2557 100644 --- a/lib/public/appframework/utility/itimefactory.php +++ b/lib/public/appframework/utility/itimefactory.php @@ -26,11 +26,13 @@ namespace OCP\AppFramework\Utility; /** * Needed to mock calls to time() + * @since 8.0.0 */ interface ITimeFactory { /** * @return int the result of a call to time() + * @since 8.0.0 */ public function getTime(); diff --git a/lib/public/authentication/iapachebackend.php b/lib/public/authentication/iapachebackend.php index 343873a115c..51ca57788f3 100644 --- a/lib/public/authentication/iapachebackend.php +++ b/lib/public/authentication/iapachebackend.php @@ -29,12 +29,19 @@ // This means that they should be used by apps instead of the internal ownCloud classes namespace OCP\Authentication; +/** + * Interface IApacheBackend + * + * @package OCP\Authentication + * @since 6.0.0 + */ interface IApacheBackend { /** * In case the user has been authenticated by Apache true is returned. * * @return boolean whether Apache reports a user as currently logged in. + * @since 6.0.0 */ public function isSessionActive(); @@ -43,12 +50,14 @@ interface IApacheBackend { * supply any attribute(s) which are valid for <a>. * * @return string with one or more HTML attributes. + * @since 6.0.0 */ public function getLogoutAttribute(); /** * Return the id of the current user * @return string + * @since 6.0.0 */ public function getCurrentUserId(); diff --git a/lib/public/backgroundjob.php b/lib/public/backgroundjob.php index 1286a4bbff5..40fdd4b6e63 100644 --- a/lib/public/backgroundjob.php +++ b/lib/public/backgroundjob.php @@ -47,6 +47,7 @@ use \OC\BackgroundJob\JobList; * A regular Job will be executed every time cron.php is run, a QueuedJob will only run once and a TimedJob * will only run at a specific interval which is to be specified in the constructor of the job by calling * $this->setInterval($interval) with $interval in seconds. + * @since 4.5.0 */ class BackgroundJob { /** @@ -56,6 +57,7 @@ class BackgroundJob { * * This method returns the type how background jobs are executed. If the user * did not select something, the type is ajax. + * @since 5.0.0 */ public static function getExecutionType() { return \OC_BackgroundJob::getExecutionType(); @@ -69,6 +71,7 @@ class BackgroundJob { * * This method sets the execution type of the background jobs. Possible types * are "none", "ajax", "webcron", "cron" + * @since 5.0.0 */ public static function setExecutionType($type) { return \OC_BackgroundJob::setExecutionType($type); @@ -77,6 +80,7 @@ class BackgroundJob { /** * @param string $job * @param mixed $argument + * @since 6.0.0 */ public static function registerJob($job, $argument = null) { $jobList = \OC::$server->getJobList(); @@ -89,6 +93,7 @@ class BackgroundJob { * @param string $klass class name * @param string $method method name * @return boolean|null + * @since 4.5.0 */ public static function addRegularTask($klass, $method) { if (!\OC::needUpgrade()) { @@ -103,6 +108,7 @@ class BackgroundJob { * @return array * * key is string "$klass-$method", value is array( $klass, $method ) + * @since 4.5.0 */ static public function allRegularTasks() { $jobList = \OC::$server->getJobList(); @@ -122,6 +128,7 @@ class BackgroundJob { * Gets one queued task * @param int $id ID of the task * @return BackgroundJob\IJob|null + * @since 4.5.0 */ public static function findQueuedTask($id) { $jobList = \OC::$server->getJobList(); @@ -132,6 +139,7 @@ class BackgroundJob { * @deprecated * Gets all queued tasks * @return array an array of associative arrays + * @since 4.5.0 */ public static function allQueuedTasks() { $jobList = \OC::$server->getJobList(); @@ -152,6 +160,7 @@ class BackgroundJob { * Gets all queued tasks of a specific app * @param string $app app name * @return array an array of associative arrays + * @since 4.5.0 */ public static function queuedTaskWhereAppIs($app) { $jobList = \OC::$server->getJobList(); @@ -177,6 +186,7 @@ class BackgroundJob { * @param string $method method name * @param string $parameters all useful data as text * @return boolean id of task + * @since 4.5.0 */ public static function addQueuedTask($app, $class, $method, $parameters) { self::registerJob('OC\BackgroundJob\Legacy\QueuedJob', array('app' => $app, 'klass' => $class, 'method' => $method, 'parameters' => $parameters)); @@ -190,6 +200,7 @@ class BackgroundJob { * @return boolean|null * * Deletes a report + * @since 4.5.0 */ public static function deleteQueuedTask($id) { $jobList = \OC::$server->getJobList(); diff --git a/lib/public/backgroundjob/ijob.php b/lib/public/backgroundjob/ijob.php index 9206590dd05..3a1be86ef4e 100644 --- a/lib/public/backgroundjob/ijob.php +++ b/lib/public/backgroundjob/ijob.php @@ -23,6 +23,12 @@ namespace OCP\BackgroundJob; +/** + * Interface IJob + * + * @package OCP\BackgroundJob + * @since 7.0.0 + */ interface IJob { /** * Run the background job with the registered argument @@ -30,6 +36,7 @@ interface IJob { * @param \OCP\BackgroundJob\IJobList $jobList The job list that manages the state of this job * @param \OC\Log $logger * @return void + * @since 7.0.0 */ public function execute($jobList, $logger = null); @@ -38,6 +45,7 @@ interface IJob { * This id is determined by the job list when a job is added to the list * * @return int + * @since 7.0.0 */ public function getId(); @@ -45,6 +53,7 @@ interface IJob { * Get the last time this job was run as unix timestamp * * @return int + * @since 7.0.0 */ public function getLastRun(); @@ -53,6 +62,7 @@ interface IJob { * This is the argument that will be passed to the background job * * @return mixed + * @since 7.0.0 */ public function getArgument(); } diff --git a/lib/public/backgroundjob/ijoblist.php b/lib/public/backgroundjob/ijoblist.php index 2f551265976..e2dc348e54d 100644 --- a/lib/public/backgroundjob/ijoblist.php +++ b/lib/public/backgroundjob/ijoblist.php @@ -24,6 +24,12 @@ namespace OCP\BackgroundJob; +/** + * Interface IJobList + * + * @package OCP\BackgroundJob + * @since 7.0.0 + */ interface IJobList { /** * Add a job to the list @@ -32,6 +38,7 @@ interface IJobList { * @param mixed $argument The argument to be passed to $job->run() when the job is exectured * @param string $job * @return void + * @since 7.0.0 */ public function add($job, $argument = null); @@ -41,6 +48,7 @@ interface IJobList { * @param \OCP\BackgroundJob\IJob|string $job * @param mixed $argument * @return void + * @since 7.0.0 */ public function remove($job, $argument = null); @@ -50,6 +58,7 @@ interface IJobList { * @param \OCP\BackgroundJob\IJob|string $job * @param mixed $argument * @return bool + * @since 7.0.0 */ public function has($job, $argument); @@ -57,6 +66,7 @@ interface IJobList { * get all jobs in the list * * @return \OCP\BackgroundJob\IJob[] + * @since 7.0.0 */ public function getAll(); @@ -64,12 +74,14 @@ interface IJobList { * get the next job in the list * * @return \OCP\BackgroundJob\IJob + * @since 7.0.0 */ public function getNext(); /** * @param int $id * @return \OCP\BackgroundJob\IJob + * @since 7.0.0 */ public function getById($id); @@ -78,6 +90,7 @@ interface IJobList { * * @param \OCP\BackgroundJob\IJob $job * @return void + * @since 7.0.0 */ public function setLastJob($job); @@ -85,6 +98,7 @@ interface IJobList { * get the id of the last ran job * * @return int + * @since 7.0.0 */ public function getLastJob(); @@ -93,6 +107,7 @@ interface IJobList { * * @param \OCP\BackgroundJob\IJob $job * @return void + * @since 7.0.0 */ public function setLastRun($job); } diff --git a/lib/public/command/ibus.php b/lib/public/command/ibus.php index 237bbd3f40f..b27edc04742 100644 --- a/lib/public/command/ibus.php +++ b/lib/public/command/ibus.php @@ -21,11 +21,18 @@ namespace OCP\Command; +/** + * Interface IBus + * + * @package OCP\Command + * @since 8.1.0 + */ interface IBus { /** * Schedule a command to be fired * * @param \OCP\Command\ICommand | callable $command + * @since 8.1.0 */ public function push($command); @@ -33,6 +40,7 @@ interface IBus { * Require all commands using a trait to be run synchronous * * @param string $trait + * @since 8.1.0 */ public function requireSync($trait); } diff --git a/lib/public/command/icommand.php b/lib/public/command/icommand.php index b3a7fc8d9a0..6ec07575b44 100644 --- a/lib/public/command/icommand.php +++ b/lib/public/command/icommand.php @@ -21,9 +21,16 @@ namespace OCP\Command; +/** + * Interface ICommand + * + * @package OCP\Command + * @since 8.1.0 + */ interface ICommand { /** * Run the command + * @since 8.1.0 */ public function handle(); } diff --git a/lib/public/constants.php b/lib/public/constants.php index 014da9f0edd..e104f767c03 100644 --- a/lib/public/constants.php +++ b/lib/public/constants.php @@ -49,6 +49,12 @@ const PERMISSION_ALL = 31; /** @deprecated Use \OCP\Constants::FILENAME_INVALID_CHARS instead */ const FILENAME_INVALID_CHARS = "\\/<>:\"|?*\n"; +/** + * Class Constants + * + * @package OCP + * @since 8.0.0 + */ class Constants { /** * CRUDS permissions. diff --git a/lib/public/contacts.php b/lib/public/contacts.php index 6aa15ce4408..ee741678fcb 100644 --- a/lib/public/contacts.php +++ b/lib/public/contacts.php @@ -46,6 +46,7 @@ namespace OCP { * For updating it is mandatory to keep the id. * Without an id a new contact will be created. * + * @since 5.0.0 */ class Contacts { @@ -90,6 +91,7 @@ namespace OCP { * @param array $searchProperties defines the properties within the query pattern should match * @param array $options - for future use. One should always have options! * @return array an array of contacts which are arrays of key-value-pairs + * @since 5.0.0 */ public static function search($pattern, $searchProperties = array(), $options = array()) { $cm = \OC::$server->getContactsManager(); @@ -102,6 +104,7 @@ namespace OCP { * @param object $id the unique identifier to a contact * @param string $address_book_key * @return bool successful or not + * @since 5.0.0 */ public static function delete($id, $address_book_key) { $cm = \OC::$server->getContactsManager(); @@ -115,6 +118,7 @@ namespace OCP { * @param array $properties this array if key-value-pairs defines a contact * @param string $address_book_key identifier of the address book in which the contact shall be created or updated * @return array an array representing the contact just created or updated + * @since 5.0.0 */ public static function createOrUpdate($properties, $address_book_key) { $cm = \OC::$server->getContactsManager(); @@ -125,6 +129,7 @@ namespace OCP { * Check if contacts are available (e.g. contacts app enabled) * * @return bool true if enabled, false if not + * @since 5.0.0 */ public static function isEnabled() { $cm = \OC::$server->getContactsManager(); @@ -133,6 +138,7 @@ namespace OCP { /** * @param \OCP\IAddressBook $address_book + * @since 5.0.0 */ public static function registerAddressBook(\OCP\IAddressBook $address_book) { $cm = \OC::$server->getContactsManager(); @@ -141,6 +147,7 @@ namespace OCP { /** * @param \OCP\IAddressBook $address_book + * @since 5.0.0 */ public static function unregisterAddressBook(\OCP\IAddressBook $address_book) { $cm = \OC::$server->getContactsManager(); @@ -149,6 +156,7 @@ namespace OCP { /** * @return array + * @since 5.0.0 */ public static function getAddressBooks() { $cm = \OC::$server->getContactsManager(); @@ -157,6 +165,7 @@ namespace OCP { /** * removes all registered address book instances + * @since 5.0.0 */ public static function clear() { $cm = \OC::$server->getContactsManager(); diff --git a/lib/public/contacts/imanager.php b/lib/public/contacts/imanager.php index a745445b2c7..4b7d0f7d40a 100644 --- a/lib/public/contacts/imanager.php +++ b/lib/public/contacts/imanager.php @@ -47,6 +47,7 @@ namespace OCP\Contacts { * For updating it is mandatory to keep the id. * Without an id a new contact will be created. * + * @since 6.0.0 */ interface IManager { @@ -92,6 +93,7 @@ namespace OCP\Contacts { * @param array $searchProperties defines the properties within the query pattern should match * @param array $options - for future use. One should always have options! * @return array an array of contacts which are arrays of key-value-pairs + * @since 6.0.0 */ function search($pattern, $searchProperties = array(), $options = array()); @@ -101,6 +103,7 @@ namespace OCP\Contacts { * @param object $id the unique identifier to a contact * @param string $address_book_key identifier of the address book in which the contact shall be deleted * @return bool successful or not + * @since 6.0.0 */ function delete($id, $address_book_key); @@ -111,6 +114,7 @@ namespace OCP\Contacts { * @param array $properties this array if key-value-pairs defines a contact * @param string $address_book_key identifier of the address book in which the contact shall be created or updated * @return array an array representing the contact just created or updated + * @since 6.0.0 */ function createOrUpdate($properties, $address_book_key); @@ -118,6 +122,7 @@ namespace OCP\Contacts { * Check if contacts are available (e.g. contacts app enabled) * * @return bool true if enabled, false if not + * @since 6.0.0 */ function isEnabled(); @@ -126,6 +131,7 @@ namespace OCP\Contacts { * * @param \OCP\IAddressBook $address_book * @return void + * @since 6.0.0 */ function registerAddressBook(\OCP\IAddressBook $address_book); @@ -134,6 +140,7 @@ namespace OCP\Contacts { * * @param \OCP\IAddressBook $address_book * @return void + * @since 6.0.0 */ function unregisterAddressBook(\OCP\IAddressBook $address_book); @@ -143,17 +150,20 @@ namespace OCP\Contacts { * * @param \Closure $callable * @return void + * @since 6.0.0 */ function register(\Closure $callable); /** * @return array + * @since 6.0.0 */ function getAddressBooks(); /** * removes all registered address book instances * @return void + * @since 6.0.0 */ function clear(); } diff --git a/lib/public/db.php b/lib/public/db.php index 49f0a091716..02d0f6ddef4 100644 --- a/lib/public/db.php +++ b/lib/public/db.php @@ -40,6 +40,7 @@ namespace OCP; /** * This class provides access to the internal database system. Use this class exlusively if you want to access databases + * @since 4.5.0 */ class DB { /** @@ -50,6 +51,7 @@ class DB { * @return \OC_DB_StatementWrapper prepared SQL query * * SQL query via Doctrine prepare(), needs to be execute()'d! + * @since 4.5.0 */ static public function prepare( $query, $limit=null, $offset=null ) { return(\OC_DB::prepare($query, $limit, $offset)); @@ -64,6 +66,7 @@ class DB { * If this is null or an empty array, all keys of $input will be compared * @return int number of inserted rows * @throws \Doctrine\DBAL\DBALException + * @since 5.0.0 - parameter $compare was added in 8.1.0 * */ public static function insertIfNotExist($table, $input, array $compare = null) { @@ -79,6 +82,7 @@ class DB { * * Call this method right after the insert command or other functions may * cause trouble! + * @since 4.5.0 */ public static function insertid($table=null) { return(\OC_DB::insertid($table)); @@ -86,6 +90,7 @@ class DB { /** * Start a transaction + * @since 4.5.0 */ public static function beginTransaction() { \OC_DB::beginTransaction(); @@ -93,6 +98,7 @@ class DB { /** * Commit the database changes done during a transaction that is in progress + * @since 4.5.0 */ public static function commit() { \OC_DB::commit(); @@ -100,6 +106,7 @@ class DB { /** * Rollback the database changes done during a transaction that is in progress + * @since 8.0.0 */ public static function rollback() { \OC_DB::rollback(); @@ -109,6 +116,7 @@ class DB { * Check if a result is an error, works with Doctrine * @param mixed $result * @return bool + * @since 4.5.0 */ public static function isError($result) { return(\OC_DB::isError($result)); @@ -119,6 +127,7 @@ class DB { * works with DoctrineException * @param mixed $error * @return string + * @since 6.0.0 */ public static function getErrorMessage($error) { return(\OC_DB::getErrorMessage($error)); diff --git a/lib/public/defaults.php b/lib/public/defaults.php index 190cc98507b..2d55a64f002 100644 --- a/lib/public/defaults.php +++ b/lib/public/defaults.php @@ -34,12 +34,14 @@ namespace OCP; /** * public api to access default strings and urls for your templates + * @since 6.0.0 */ class Defaults { /** * \OC_Defaults instance to retrieve the defaults * @return string + * @since 6.0.0 */ private $defaults; @@ -54,6 +56,7 @@ class Defaults { /** * get base URL for the organisation behind your ownCloud instance * @return string + * @since 6.0.0 */ public function getBaseUrl() { return $this->defaults->getBaseUrl(); @@ -62,6 +65,7 @@ class Defaults { /** * link to the desktop sync client * @return string + * @since 6.0.0 */ public function getSyncClientUrl() { return $this->defaults->getSyncClientUrl(); @@ -70,6 +74,7 @@ class Defaults { /** * link to the iOS client * @return string + * @since 8.0.0 */ public function getiOSClientUrl() { return $this->defaults->getiOSClientUrl(); @@ -78,6 +83,7 @@ class Defaults { /** * link to the Android client * @return string + * @since 8.0.0 */ public function getAndroidClientUrl() { return $this->defaults->getAndroidClientUrl(); @@ -86,6 +92,7 @@ class Defaults { /** * base URL to the documentation of your ownCloud instance * @return string + * @since 6.0.0 */ public function getDocBaseUrl() { return $this->defaults->getDocBaseUrl(); @@ -94,6 +101,7 @@ class Defaults { /** * name of your ownCloud instance * @return string + * @since 6.0.0 */ public function getName() { return $this->defaults->getName(); @@ -102,6 +110,7 @@ class Defaults { /** * name of your ownCloud instance containing HTML styles * @return string + * @since 8.0.0 */ public function getHTMLName() { return $this->defaults->getHTMLName(); @@ -110,6 +119,7 @@ class Defaults { /** * Entity behind your onwCloud instance * @return string + * @since 6.0.0 */ public function getEntity() { return $this->defaults->getEntity(); @@ -118,6 +128,7 @@ class Defaults { /** * ownCloud slogan * @return string + * @since 6.0.0 */ public function getSlogan() { return $this->defaults->getSlogan(); @@ -126,6 +137,7 @@ class Defaults { /** * logo claim * @return string + * @since 6.0.0 */ public function getLogoClaim() { return $this->defaults->getLogoClaim(); @@ -134,6 +146,7 @@ class Defaults { /** * footer, short version * @return string + * @since 6.0.0 */ public function getShortFooter() { return $this->defaults->getShortFooter(); @@ -142,6 +155,7 @@ class Defaults { /** * footer, long version * @return string + * @since 6.0.0 */ public function getLongFooter() { return $this->defaults->getLongFooter(); @@ -150,6 +164,7 @@ class Defaults { /** * Returns the AppId for the App Store for the iOS Client * @return string AppId + * @since 8.0.0 */ public function getiTunesAppId() { return $this->defaults->getiTunesAppId(); diff --git a/lib/public/diagnostics/ievent.php b/lib/public/diagnostics/ievent.php index cff3d31f55b..733d5e4832c 100644 --- a/lib/public/diagnostics/ievent.php +++ b/lib/public/diagnostics/ievent.php @@ -22,29 +22,40 @@ namespace OCP\Diagnostics; +/** + * Interface IEvent + * + * @package OCP\Diagnostics + * @since 8.0.0 + */ interface IEvent { /** * @return string + * @since 8.0.0 */ public function getId(); /** * @return string + * @since 8.0.0 */ public function getDescription(); /** * @return float + * @since 8.0.0 */ public function getStart(); /** * @return float + * @since 8.0.0 */ public function getEnd(); /** * @return float + * @since 8.0.0 */ public function getDuration(); } diff --git a/lib/public/diagnostics/ieventlogger.php b/lib/public/diagnostics/ieventlogger.php index cc10862fc79..c9b4653393b 100644 --- a/lib/public/diagnostics/ieventlogger.php +++ b/lib/public/diagnostics/ieventlogger.php @@ -22,12 +22,19 @@ namespace OCP\Diagnostics; +/** + * Interface IEventLogger + * + * @package OCP\Diagnostics + * @since 8.0.0 + */ interface IEventLogger { /** * Mark the start of an event * * @param string $id * @param string $description + * @since 8.0.0 */ public function start($id, $description); @@ -35,6 +42,7 @@ interface IEventLogger { * Mark the end of an event * * @param string $id + * @since 8.0.0 */ public function end($id); @@ -43,11 +51,13 @@ interface IEventLogger { * @param string $description * @param float $start * @param float $end + * @since 8.0.0 */ public function log($id, $description, $start, $end); /** * @return \OCP\Diagnostics\IEvent[] + * @since 8.0.0 */ public function getEvents(); } diff --git a/lib/public/diagnostics/iquery.php b/lib/public/diagnostics/iquery.php index 78808ddc381..54853f733c9 100644 --- a/lib/public/diagnostics/iquery.php +++ b/lib/public/diagnostics/iquery.php @@ -22,19 +22,28 @@ namespace OCP\Diagnostics; +/** + * Interface IQuery + * + * @package OCP\Diagnostics + * @since 8.0.0 + */ interface IQuery { /** * @return string + * @since 8.0.0 */ public function getSql(); /** * @return array + * @since 8.0.0 */ public function getParams(); /** * @return float + * @since 8.0.0 */ public function getDuration(); } diff --git a/lib/public/diagnostics/iquerylogger.php b/lib/public/diagnostics/iquerylogger.php index 8c51c35ae36..4a6a0d0704b 100644 --- a/lib/public/diagnostics/iquerylogger.php +++ b/lib/public/diagnostics/iquerylogger.php @@ -24,18 +24,30 @@ namespace OCP\Diagnostics; use Doctrine\DBAL\Logging\SQLLogger; +/** + * Interface IQueryLogger + * + * @package OCP\Diagnostics + * @since 8.0.0 + */ interface IQueryLogger extends SQLLogger { /** * @param string $sql * @param array $params * @param array $types + * @since 8.0.0 */ public function startQuery($sql, array $params = null, array $types = null); + /** + * @return mixed + * @since 8.0.0 + */ public function stopQuery(); /** * @return \OCP\Diagnostics\IQuery[] + * @since 8.0.0 */ public function getQueries(); } diff --git a/lib/public/encryption/exceptions/genericencryptionexception.php b/lib/public/encryption/exceptions/genericencryptionexception.php index c488d4df162..be96450d431 100644 --- a/lib/public/encryption/exceptions/genericencryptionexception.php +++ b/lib/public/encryption/exceptions/genericencryptionexception.php @@ -22,13 +22,19 @@ namespace OCP\Encryption\Exceptions; - +/** + * Class GenericEncryptionException + * + * @package OCP\Encryption\Exceptions + * @since 8.1.0 + */ class GenericEncryptionException extends \Exception { /** * @param string $message * @param int $code * @param \Exception $previous + * @since 8.1.0 */ public function __construct($message = '', $code = 0, \Exception $previous = null) { if (empty($message)) { diff --git a/lib/public/encryption/iencryptionmodule.php b/lib/public/encryption/iencryptionmodule.php index d22ca0ec86c..dc55f8939ef 100644 --- a/lib/public/encryption/iencryptionmodule.php +++ b/lib/public/encryption/iencryptionmodule.php @@ -21,10 +21,17 @@ namespace OCP\Encryption; +/** + * Interface IEncryptionModule + * + * @package OCP\Encryption + * @since 8.1.0 + */ interface IEncryptionModule { /** * @return string defining the technical unique id + * @since 8.1.0 */ public function getId(); @@ -32,6 +39,7 @@ interface IEncryptionModule { * In comparison to getKey() this function returns a human readable (maybe translated) name * * @return string + * @since 8.1.0 */ public function getDisplayName(); @@ -48,6 +56,7 @@ interface IEncryptionModule { * $return array $header contain data as key-value pairs which should be * written to the header, in case of a write operation * or if no additional data is needed return a empty array + * @since 8.1.0 */ public function begin($path, $user, array $header, array $accessList); @@ -59,6 +68,7 @@ interface IEncryptionModule { * @param string $path to the file * @return string remained data which should be written to the file in case * of a write operation + * @since 8.1.0 */ public function end($path); @@ -67,6 +77,7 @@ interface IEncryptionModule { * * @param string $data you want to encrypt * @return mixed encrypted data + * @since 8.1.0 */ public function encrypt($data); @@ -75,6 +86,7 @@ interface IEncryptionModule { * * @param string $data you want to decrypt * @return mixed decrypted data + * @since 8.1.0 */ public function decrypt($data); @@ -85,6 +97,7 @@ interface IEncryptionModule { * @param string $uid of the user who performs the operation * @param array $accessList who has access to the file contains the key 'users' and 'public' * @return boolean + * @since 8.1.0 */ public function update($path, $uid, array $accessList); @@ -93,6 +106,7 @@ interface IEncryptionModule { * * @param string $path * @return boolean + * @since 8.1.0 */ public function shouldEncrypt($path); @@ -101,6 +115,7 @@ interface IEncryptionModule { * ownCloud read/write files with a block size of 8192 byte * * @return integer + * @since 8.1.0 */ public function getUnencryptedBlockSize(); } diff --git a/lib/public/encryption/ifile.php b/lib/public/encryption/ifile.php index cc1e8f426b2..8b3f0fa4bf3 100644 --- a/lib/public/encryption/ifile.php +++ b/lib/public/encryption/ifile.php @@ -22,6 +22,12 @@ namespace OCP\Encryption; +/** + * Interface IFile + * + * @package OCP\Encryption + * @since 8.1.0 + */ interface IFile { /** @@ -29,6 +35,7 @@ interface IFile { * * @param string $path to the file * @return array + * @since 8.1.0 */ public function getAccessList($path); diff --git a/lib/public/encryption/imanager.php b/lib/public/encryption/imanager.php index 3dcdbf5d03a..badc91c9023 100644 --- a/lib/public/encryption/imanager.php +++ b/lib/public/encryption/imanager.php @@ -27,6 +27,7 @@ use OC\Encryption\Exceptions\ModuleAlreadyExistsException; /** * This class provides access to files encryption apps. * + * @since 8.1.0 */ interface IManager { @@ -34,6 +35,7 @@ interface IManager { * Check if encryption is available (at least one encryption module needs to be enabled) * * @return bool true if enabled, false if not + * @since 8.1.0 */ function isEnabled(); @@ -42,6 +44,7 @@ interface IManager { * * @param IEncryptionModule $module * @throws ModuleAlreadyExistsException + * @since 8.1.0 */ function registerEncryptionModule(IEncryptionModule $module); @@ -49,6 +52,7 @@ interface IManager { * Unregisters an encryption module * * @param IEncryptionModule $module + * @since 8.1.0 */ function unregisterEncryptionModule(IEncryptionModule $module); @@ -56,6 +60,7 @@ interface IManager { * get a list of all encryption modules * * @return array + * @since 8.1.0 */ function getEncryptionModules(); @@ -66,6 +71,7 @@ interface IManager { * @param string $moduleId * @return IEncryptionModule * @throws ModuleDoesNotExistsException + * @since 8.1.0 */ function getEncryptionModule($moduleId); @@ -74,6 +80,7 @@ interface IManager { * * @return \OCP\Encryption\IEncryptionModule * @throws ModuleDoesNotExistsException + * @since 8.1.0 */ public function getDefaultEncryptionModule(); @@ -82,6 +89,7 @@ interface IManager { * * @param string $moduleId * @return string + * @since 8.1.0 */ public function setDefaultEncryptionModule($moduleId); diff --git a/lib/public/encryption/keys/istorage.php b/lib/public/encryption/keys/istorage.php index c6933e7afab..3e497ed2c75 100644 --- a/lib/public/encryption/keys/istorage.php +++ b/lib/public/encryption/keys/istorage.php @@ -22,6 +22,12 @@ namespace OCP\Encryption\Keys; +/** + * Interface IStorage + * + * @package OCP\Encryption\Keys + * @since 8.1.0 + */ interface IStorage { /** @@ -31,6 +37,7 @@ interface IStorage { * @param string $keyId id of the key * * @return mixed key + * @since 8.1.0 */ public function getUserKey($uid, $keyId); @@ -41,6 +48,7 @@ interface IStorage { * @param string $keyId id of the key * * @return mixed key + * @since 8.1.0 */ public function getFileKey($path, $keyId); @@ -51,6 +59,7 @@ interface IStorage { * @param string $keyId id of the key * * @return mixed key + * @since 8.1.0 */ public function getSystemUserKey($keyId); @@ -60,6 +69,7 @@ interface IStorage { * @param string $uid ID if the user for whom we want the key * @param string $keyId id of the key * @param mixed $key + * @since 8.1.0 */ public function setUserKey($uid, $keyId, $key); @@ -69,6 +79,7 @@ interface IStorage { * @param string $path path to file * @param string $keyId id of the key * @param boolean + * @since 8.1.0 */ public function setFileKey($path, $keyId, $key); @@ -80,6 +91,7 @@ interface IStorage { * @param mixed $key * * @return mixed key + * @since 8.1.0 */ public function setSystemUserKey($keyId, $key); @@ -90,6 +102,7 @@ interface IStorage { * @param string $keyId id of the key * * @return boolean False when the key could not be deleted + * @since 8.1.0 */ public function deleteUserKey($uid, $keyId); @@ -100,6 +113,7 @@ interface IStorage { * @param string $keyId id of the key * * @return boolean False when the key could not be deleted + * @since 8.1.0 */ public function deleteFileKey($path, $keyId); @@ -108,6 +122,7 @@ interface IStorage { * * @param string $path to the file * @return boolean False when the keys could not be deleted + * @since 8.1.0 */ public function deleteAllFileKeys($path); @@ -118,6 +133,7 @@ interface IStorage { * @param string $keyId id of the key * * @return boolean False when the key could not be deleted + * @since 8.1.0 */ public function deleteSystemUserKey($keyId); @@ -126,6 +142,7 @@ interface IStorage { * * @param string $source * @param string $target + * @since 8.1.0 */ public function renameKeys($source, $target); @@ -134,6 +151,7 @@ interface IStorage { * * @param string $source * @param string $target + * @since 8.1.0 */ public function copyKeys($source, $target); diff --git a/lib/public/files.php b/lib/public/files.php index e6910e8799b..57747a4c354 100644 --- a/lib/public/files.php +++ b/lib/public/files.php @@ -40,11 +40,13 @@ namespace OCP; /** * This class provides access to the internal filesystem abstraction layer. Use * this class exlusively if you want to access files + * @since 5.0.0 */ class Files { /** * Recusive deletion of folders * @return bool + * @since 5.0.0 */ static function rmdirr( $dir ) { return \OC_Helper::rmdirr( $dir ); @@ -55,6 +57,7 @@ class Files { * @param string $path * @return string * does NOT work for ownClouds filesystem, use OC_FileSystem::getMimeType instead + * @since 5.0.0 */ static function getMimeType( $path ) { return(\OC_Helper::getMimeType( $path )); @@ -64,6 +67,7 @@ class Files { * Search for files by mimetype * @param string $mimetype * @return array + * @since 6.0.0 */ static public function searchByMime( $mimetype ) { return(\OC\Files\Filesystem::searchByMime( $mimetype )); @@ -74,6 +78,7 @@ class Files { * @param resource $source * @param resource $target * @return int the number of bytes copied + * @since 5.0.0 */ public static function streamCopy( $source, $target ) { list($count, $result) = \OC_Helper::streamCopy( $source, $target ); @@ -86,6 +91,7 @@ class Files { * @return string * * temporary files are automatically cleaned up after the script is finished + * @since 5.0.0 */ public static function tmpFile( $postfix='' ) { return(\OC_Helper::tmpFile( $postfix )); @@ -96,6 +102,7 @@ class Files { * @return string * * temporary files are automatically cleaned up after the script is finished + * @since 5.0.0 */ public static function tmpFolder() { return(\OC_Helper::tmpFolder()); @@ -106,6 +113,7 @@ class Files { * @param string $path * @param string $filename * @return string + * @since 5.0.0 */ public static function buildNotExistingFileName( $path, $filename ) { return(\OC_Helper::buildNotExistingFileName( $path, $filename )); @@ -116,6 +124,7 @@ class Files { * existant * @param string $app * @return \OC\Files\View + * @since 5.0.0 */ public static function getStorage( $app ) { return \OC_App::getStorage( $app ); diff --git a/lib/public/files/alreadyexistsexception.php b/lib/public/files/alreadyexistsexception.php index 0709a6bf94c..2ff231c56f4 100644 --- a/lib/public/files/alreadyexistsexception.php +++ b/lib/public/files/alreadyexistsexception.php @@ -31,5 +31,6 @@ namespace OCP\Files; /** * Exception for already existing files/folders + * @since 6.0.0 */ class AlreadyExistsException extends \Exception {} diff --git a/lib/public/files/config/imountprovider.php b/lib/public/files/config/imountprovider.php index 01d71618aa6..8e21e4c8650 100644 --- a/lib/public/files/config/imountprovider.php +++ b/lib/public/files/config/imountprovider.php @@ -27,6 +27,7 @@ use OCP\IUser; /** * Provides + * @since 8.0.0 */ interface IMountProvider { /** @@ -35,6 +36,7 @@ interface IMountProvider { * @param \OCP\IUser $user * @param \OCP\Files\Storage\IStorageFactory $loader * @return \OCP\Files\Mount\IMountPoint[] + * @since 8.0.0 */ public function getMountsForUser(IUser $user, IStorageFactory $loader); } diff --git a/lib/public/files/config/imountprovidercollection.php b/lib/public/files/config/imountprovidercollection.php index 467aa05b8a2..a458cbf3ce7 100644 --- a/lib/public/files/config/imountprovidercollection.php +++ b/lib/public/files/config/imountprovidercollection.php @@ -26,6 +26,7 @@ use OCP\IUser; /** * Manages the different mount providers + * @since 8.0.0 */ interface IMountProviderCollection { /** @@ -33,6 +34,7 @@ interface IMountProviderCollection { * * @param \OCP\IUser $user * @return \OCP\Files\Mount\IMountPoint[] + * @since 8.0.0 */ public function getMountsForUser(IUser $user); @@ -40,6 +42,7 @@ interface IMountProviderCollection { * Add a provider for mount points * * @param \OCP\Files\Config\IMountProvider $provider + * @since 8.0.0 */ public function registerProvider(IMountProvider $provider); } diff --git a/lib/public/files/entitytoolargeexception.php b/lib/public/files/entitytoolargeexception.php index 770d1153876..4dcfa77728b 100644 --- a/lib/public/files/entitytoolargeexception.php +++ b/lib/public/files/entitytoolargeexception.php @@ -31,5 +31,6 @@ namespace OCP\Files; /** * Exception for too large entity + * @since 6.0.0 */ class EntityTooLargeException extends \Exception {} diff --git a/lib/public/files/file.php b/lib/public/files/file.php index 69e6e510c8f..839d646edb1 100644 --- a/lib/public/files/file.php +++ b/lib/public/files/file.php @@ -30,12 +30,19 @@ // This means that they should be used by apps instead of the internal ownCloud classes namespace OCP\Files; +/** + * Interface File + * + * @package OCP\Files + * @since 6.0.0 + */ interface File extends Node { /** * Get the content of the file as string * * @return string * @throws \OCP\Files\NotPermittedException + * @since 6.0.0 */ public function getContent(); @@ -45,6 +52,7 @@ interface File extends Node { * @param string $data * @throws \OCP\Files\NotPermittedException * @return void + * @since 6.0.0 */ public function putContent($data); @@ -52,6 +60,7 @@ interface File extends Node { * Get the mimetype of the file * * @return string + * @since 6.0.0 */ public function getMimeType(); @@ -61,6 +70,7 @@ interface File extends Node { * @param string $mode * @return resource * @throws \OCP\Files\NotPermittedException + * @since 6.0.0 */ public function fopen($mode); @@ -71,6 +81,7 @@ interface File extends Node { * @param string $type * @param bool $raw * @return string + * @since 6.0.0 */ public function hash($type, $raw = false); } diff --git a/lib/public/files/fileinfo.php b/lib/public/files/fileinfo.php index 69bca284cc5..accbe04e044 100644 --- a/lib/public/files/fileinfo.php +++ b/lib/public/files/fileinfo.php @@ -24,20 +24,35 @@ */ namespace OCP\Files; +/** + * Interface FileInfo + * + * @package OCP\Files + * @since 7.0.0 + */ interface FileInfo { + /** + * @since 7.0.0 + */ const TYPE_FILE = 'file'; + /** + * @since 7.0.0 + */ const TYPE_FOLDER = 'dir'; - /* + /** * @const \OCP\Files\FileInfo::SPACE_NOT_COMPUTED Return value for a not computed space value + * @since 8.0.0 */ const SPACE_NOT_COMPUTED = -1; - /* + /** * @const \OCP\Files\FileInfo::SPACE_UNKNOWN Return value for unknown space value + * @since 8.0.0 */ const SPACE_UNKNOWN = -2; - /* + /** * @const \OCP\Files\FileInfo::SPACE_UNKNOWN Return value for unlimited space + * @since 8.0.0 */ const SPACE_UNLIMITED = -3; @@ -45,6 +60,7 @@ interface FileInfo { * Get the Etag of the file or folder * * @return string + * @since 7.0.0 */ public function getEtag(); @@ -52,6 +68,7 @@ interface FileInfo { * Get the size in bytes for the file or folder * * @return int + * @since 7.0.0 */ public function getSize(); @@ -59,6 +76,7 @@ interface FileInfo { * Get the last modified date as timestamp for the file or folder * * @return int + * @since 7.0.0 */ public function getMtime(); @@ -66,6 +84,7 @@ interface FileInfo { * Get the name of the file or folder * * @return string + * @since 7.0.0 */ public function getName(); @@ -73,6 +92,7 @@ interface FileInfo { * Get the path relative to the storage * * @return string + * @since 7.0.0 */ public function getInternalPath(); @@ -80,6 +100,7 @@ interface FileInfo { * Get the absolute path * * @return string + * @since 7.0.0 */ public function getPath(); @@ -87,6 +108,7 @@ interface FileInfo { * Get the full mimetype of the file or folder i.e. 'image/png' * * @return string + * @since 7.0.0 */ public function getMimetype(); @@ -94,6 +116,7 @@ interface FileInfo { * Get the first part of the mimetype of the file or folder i.e. 'image' * * @return string + * @since 7.0.0 */ public function getMimePart(); @@ -101,6 +124,7 @@ interface FileInfo { * Get the storage the file or folder is storage on * * @return \OCP\Files\Storage + * @since 7.0.0 */ public function getStorage(); @@ -108,6 +132,7 @@ interface FileInfo { * Get the file id of the file or folder * * @return int + * @since 7.0.0 */ public function getId(); @@ -115,6 +140,7 @@ interface FileInfo { * Check whether the file is encrypted * * @return bool + * @since 7.0.0 */ public function isEncrypted(); @@ -128,6 +154,7 @@ interface FileInfo { * \OCP\Constants::PERMISSION_ALL * * @return int + * @since 7.0.0 - namespace of constants has changed in 8.0.0 */ public function getPermissions(); @@ -135,6 +162,7 @@ interface FileInfo { * Check whether this is a file or a folder * * @return \OCP\Files\FileInfo::TYPE_FILE|\OCP\Files\FileInfo::TYPE_FOLDER + * @since 7.0.0 */ public function getType(); @@ -142,6 +170,7 @@ interface FileInfo { * Check if the file or folder is readable * * @return bool + * @since 7.0.0 */ public function isReadable(); @@ -149,6 +178,7 @@ interface FileInfo { * Check if a file is writable * * @return bool + * @since 7.0.0 */ public function isUpdateable(); @@ -156,6 +186,7 @@ interface FileInfo { * Check whether new files or folders can be created inside this folder * * @return bool + * @since 8.0.0 */ public function isCreatable(); @@ -163,6 +194,7 @@ interface FileInfo { * Check if a file or folder can be deleted * * @return bool + * @since 7.0.0 */ public function isDeletable(); @@ -170,6 +202,7 @@ interface FileInfo { * Check if a file or folder can be shared * * @return bool + * @since 7.0.0 */ public function isShareable(); @@ -177,6 +210,7 @@ interface FileInfo { * Check if a file or folder is shared * * @return bool + * @since 7.0.0 */ public function isShared(); @@ -184,6 +218,7 @@ interface FileInfo { * Check if a file or folder is mounted * * @return bool + * @since 7.0.0 */ public function isMounted(); @@ -191,6 +226,7 @@ interface FileInfo { * Get the mountpoint the file belongs to * * @return \OCP\Files\Mount\IMountPoint + * @since 8.0.0 */ public function getMountPoint(); } diff --git a/lib/public/files/filenametoolongexception.php b/lib/public/files/filenametoolongexception.php index 260a749f3ac..ccf56e19a6b 100644 --- a/lib/public/files/filenametoolongexception.php +++ b/lib/public/files/filenametoolongexception.php @@ -28,6 +28,11 @@ // This means that they should be used by apps instead of the internal ownCloud classes namespace OCP\Files; - +/** + * Class FileNameTooLongException + * + * @package OCP\Files + * @since 8.1.0 + */ class FileNameTooLongException extends InvalidPathException { } diff --git a/lib/public/files/folder.php b/lib/public/files/folder.php index 7082d917cf4..f5f91e8158c 100644 --- a/lib/public/files/folder.php +++ b/lib/public/files/folder.php @@ -30,6 +30,9 @@ // This means that they should be used by apps instead of the internal ownCloud classes namespace OCP\Files; +/** + * @since 6.0.0 + */ interface Folder extends Node { /** * Get the full path of an item in the folder within owncloud's filesystem @@ -37,6 +40,7 @@ interface Folder extends Node { * @param string $path relative path of an item in the folder * @return string * @throws \OCP\Files\NotPermittedException + * @since 6.0.0 */ public function getFullPath($path); @@ -46,6 +50,7 @@ interface Folder extends Node { * @param string $path absolute path of an item in the folder * @throws \OCP\Files\NotFoundException * @return string + * @since 6.0.0 */ public function getRelativePath($path); @@ -54,6 +59,7 @@ interface Folder extends Node { * * @param \OCP\Files\Node $node * @return bool + * @since 6.0.0 */ public function isSubNode($node); @@ -62,6 +68,7 @@ interface Folder extends Node { * * @throws \OCP\Files\NotFoundException * @return \OCP\Files\Node[] + * @since 6.0.0 */ public function getDirectoryListing(); @@ -71,6 +78,7 @@ interface Folder extends Node { * @param string $path relative path of the file or folder * @return \OCP\Files\Node * @throws \OCP\Files\NotFoundException + * @since 6.0.0 */ public function get($path); @@ -79,6 +87,7 @@ interface Folder extends Node { * * @param string $path relative path of the file or folder * @return bool + * @since 6.0.0 */ public function nodeExists($path); @@ -88,6 +97,7 @@ interface Folder extends Node { * @param string $path relative path of the new folder * @return \OCP\Files\Folder * @throws \OCP\Files\NotPermittedException + * @since 6.0.0 */ public function newFolder($path); @@ -105,6 +115,7 @@ interface Folder extends Node { * * @param string $query * @return \OCP\Files\Node[] + * @since 6.0.0 */ public function search($query); @@ -114,6 +125,7 @@ interface Folder extends Node { * * @param string $mimetype * @return \OCP\Files\Node[] + * @since 6.0.0 */ public function searchByMime($mimetype); @@ -123,6 +135,7 @@ interface Folder extends Node { * @param string|int $tag tag name or tag id * @param string $userId owner of the tags * @return \OCP\Files\Node[] + * @since 8.0.0 */ public function searchByTag($tag, $userId); @@ -131,6 +144,7 @@ interface Folder extends Node { * * @param int $id * @return \OCP\Files\Node[] + * @since 6.0.0 */ public function getById($id); @@ -138,6 +152,7 @@ interface Folder extends Node { * Get the amount of free space inside the folder * * @return int + * @since 6.0.0 */ public function getFreeSpace(); @@ -145,6 +160,7 @@ interface Folder extends Node { * Check if new files or folders can be created within the folder * * @return bool + * @since 6.0.0 */ public function isCreatable(); @@ -154,6 +170,7 @@ interface Folder extends Node { * @param string $name * @return string * @throws NotPermittedException + * @since 8.1.0 */ public function getNonExistingName($name); } diff --git a/lib/public/files/ihomestorage.php b/lib/public/files/ihomestorage.php index b9766e6f4c2..fc9b0357578 100644 --- a/lib/public/files/ihomestorage.php +++ b/lib/public/files/ihomestorage.php @@ -29,6 +29,12 @@ // This means that they should be used by apps instead of the internal ownCloud classes namespace OCP\Files; +/** + * Interface IHomeStorage + * + * @package OCP\Files + * @since 7.0.0 + */ interface IHomeStorage { } diff --git a/lib/public/files/invalidcharacterinpathexception.php b/lib/public/files/invalidcharacterinpathexception.php index 0ac79a3b8ae..a25712353b6 100644 --- a/lib/public/files/invalidcharacterinpathexception.php +++ b/lib/public/files/invalidcharacterinpathexception.php @@ -30,6 +30,7 @@ namespace OCP\Files; /** * Exception for invalid path + * @since 8.1.0 */ class InvalidCharacterInPathException extends InvalidPathException { diff --git a/lib/public/files/invalidcontentexception.php b/lib/public/files/invalidcontentexception.php index d02118da8a2..6aebf367241 100644 --- a/lib/public/files/invalidcontentexception.php +++ b/lib/public/files/invalidcontentexception.php @@ -31,5 +31,6 @@ namespace OCP\Files; /** * Exception for invalid content + * @since 6.0.0 */ class InvalidContentException extends \Exception {} diff --git a/lib/public/files/invalidpathexception.php b/lib/public/files/invalidpathexception.php index 06ea5cd872a..e86d58bde7a 100644 --- a/lib/public/files/invalidpathexception.php +++ b/lib/public/files/invalidpathexception.php @@ -31,5 +31,6 @@ namespace OCP\Files; /** * Exception for invalid path + * @since 6.0.0 */ class InvalidPathException extends \Exception {} diff --git a/lib/public/files/irootfolder.php b/lib/public/files/irootfolder.php index cbea0c0979b..19192cd9cc9 100644 --- a/lib/public/files/irootfolder.php +++ b/lib/public/files/irootfolder.php @@ -25,7 +25,12 @@ namespace OCP\Files; use OC\Hooks\Emitter; - +/** + * Interface IRootFolder + * + * @package OCP\Files + * @since 8.0.0 + */ interface IRootFolder extends Folder, Emitter { } diff --git a/lib/public/files/locknotacquiredexception.php b/lib/public/files/locknotacquiredexception.php index aa8e7e97d89..66e131ab1e5 100644 --- a/lib/public/files/locknotacquiredexception.php +++ b/lib/public/files/locknotacquiredexception.php @@ -32,6 +32,7 @@ namespace OCP\Files; /** * Exception for a file that is locked + * @since 7.0.0 */ class LockNotAcquiredException extends \Exception { /** @var string $path The path that could not be locked */ diff --git a/lib/public/files/mount/imountpoint.php b/lib/public/files/mount/imountpoint.php index 50126e1fcf0..5452bcdb03a 100644 --- a/lib/public/files/mount/imountpoint.php +++ b/lib/public/files/mount/imountpoint.php @@ -24,6 +24,7 @@ namespace OCP\Files\Mount; /** * A storage mounted to folder on the filesystem + * @since 8.0.0 */ interface IMountPoint { @@ -31,6 +32,7 @@ interface IMountPoint { * get complete path to the mount point * * @return string + * @since 8.0.0 */ public function getMountPoint(); @@ -38,6 +40,7 @@ interface IMountPoint { * Set the mountpoint * * @param string $mountPoint new mount point + * @since 8.0.0 */ public function setMountPoint($mountPoint); @@ -45,6 +48,7 @@ interface IMountPoint { * Get the storage that is mounted * * @return \OC\Files\Storage\Storage + * @since 8.0.0 */ public function getStorage(); @@ -52,6 +56,7 @@ interface IMountPoint { * Get the id of the storages * * @return string + * @since 8.0.0 */ public function getStorageId(); @@ -60,6 +65,7 @@ interface IMountPoint { * * @param string $path absolute path to a file or folder * @return string + * @since 8.0.0 */ public function getInternalPath($path); @@ -67,6 +73,7 @@ interface IMountPoint { * Apply a storage wrapper to the mounted storage * * @param callable $wrapper + * @since 8.0.0 */ public function wrapStorage($wrapper); @@ -76,6 +83,7 @@ interface IMountPoint { * @param string $name Name of the mount option to get * @param mixed $default Default value for the mount option * @return mixed + * @since 8.0.0 */ public function getOption($name, $default); @@ -83,6 +91,7 @@ interface IMountPoint { * Get all options for the mount * * @return array + * @since 8.1.0 */ public function getOptions(); } diff --git a/lib/public/files/node.php b/lib/public/files/node.php index 6739d8cc391..aa1115f8c28 100644 --- a/lib/public/files/node.php +++ b/lib/public/files/node.php @@ -32,6 +32,12 @@ // This means that they should be used by apps instead of the internal ownCloud classes namespace OCP\Files; +/** + * Interface Node + * + * @package OCP\Files + * @since 6.0.0 - extends FileInfo was added in 8.0.0 + */ interface Node extends FileInfo { /** * Move the file or folder to a new location @@ -39,12 +45,14 @@ interface Node extends FileInfo { * @param string $targetPath the absolute target path * @throws \OCP\Files\NotPermittedException * @return \OCP\Files\Node + * @since 6.0.0 */ public function move($targetPath); /** * Delete the file or folder * @return void + * @since 6.0.0 */ public function delete(); @@ -53,6 +61,7 @@ interface Node extends FileInfo { * * @param string $targetPath the absolute target path * @return \OCP\Files\Node + * @since 6.0.0 */ public function copy($targetPath); @@ -63,6 +72,7 @@ interface Node extends FileInfo { * @param int $mtime (optional) modified date as unix timestamp * @throws \OCP\Files\NotPermittedException * @return void + * @since 6.0.0 */ public function touch($mtime = null); @@ -71,6 +81,7 @@ interface Node extends FileInfo { * * @return \OCP\Files\Storage * @throws \OCP\Files\NotFoundException + * @since 6.0.0 */ public function getStorage(); @@ -78,6 +89,7 @@ interface Node extends FileInfo { * Get the full path of the file or folder * * @return string + * @since 6.0.0 */ public function getPath(); @@ -85,6 +97,7 @@ interface Node extends FileInfo { * Get the path of the file or folder relative to the mountpoint of it's storage * * @return string + * @since 6.0.0 */ public function getInternalPath(); @@ -94,6 +107,7 @@ interface Node extends FileInfo { * @return int * @throws InvalidPathException * @throws NotFoundException + * @since 6.0.0 */ public function getId(); @@ -104,6 +118,7 @@ interface Node extends FileInfo { * - size * * @return array + * @since 6.0.0 */ public function stat(); @@ -113,6 +128,7 @@ interface Node extends FileInfo { * @return int * @throws InvalidPathException * @throws NotFoundException + * @since 6.0.0 */ public function getMTime(); @@ -122,6 +138,7 @@ interface Node extends FileInfo { * @return int * @throws InvalidPathException * @throws NotFoundException + * @since 6.0.0 */ public function getSize(); @@ -133,6 +150,7 @@ interface Node extends FileInfo { * @return string * @throws InvalidPathException * @throws NotFoundException + * @since 6.0.0 */ public function getEtag(); @@ -148,6 +166,7 @@ interface Node extends FileInfo { * @return int * @throws InvalidPathException * @throws NotFoundException + * @since 6.0.0 - namespace of constants has changed in 8.0.0 */ public function getPermissions(); @@ -157,6 +176,7 @@ interface Node extends FileInfo { * @return bool * @throws InvalidPathException * @throws NotFoundException + * @since 6.0.0 */ public function isReadable(); @@ -166,6 +186,7 @@ interface Node extends FileInfo { * @return bool * @throws InvalidPathException * @throws NotFoundException + * @since 6.0.0 */ public function isUpdateable(); @@ -175,6 +196,7 @@ interface Node extends FileInfo { * @return bool * @throws InvalidPathException * @throws NotFoundException + * @since 6.0.0 */ public function isDeletable(); @@ -184,6 +206,7 @@ interface Node extends FileInfo { * @return bool * @throws InvalidPathException * @throws NotFoundException + * @since 6.0.0 */ public function isShareable(); @@ -191,6 +214,7 @@ interface Node extends FileInfo { * Get the parent folder of the file or folder * * @return Folder + * @since 6.0.0 */ public function getParent(); @@ -198,6 +222,7 @@ interface Node extends FileInfo { * Get the filename of the file or folder * * @return string + * @since 6.0.0 */ public function getName(); } diff --git a/lib/public/files/notenoughspaceexception.php b/lib/public/files/notenoughspaceexception.php index d79caff6872..a2cc0d6956b 100644 --- a/lib/public/files/notenoughspaceexception.php +++ b/lib/public/files/notenoughspaceexception.php @@ -31,5 +31,6 @@ namespace OCP\Files; /** * Exception for not enough space + * @since 6.0.0 */ class NotEnoughSpaceException extends \Exception {} diff --git a/lib/public/files/notfoundexception.php b/lib/public/files/notfoundexception.php index 13aa04c57dc..ae93e8d1e6d 100644 --- a/lib/public/files/notfoundexception.php +++ b/lib/public/files/notfoundexception.php @@ -31,5 +31,6 @@ namespace OCP\Files; /** * Exception for not found entity + * @since 6.0.0 */ class NotFoundException extends \Exception {} diff --git a/lib/public/files/notpermittedexception.php b/lib/public/files/notpermittedexception.php index 6f2475a174f..ee82ae56e51 100644 --- a/lib/public/files/notpermittedexception.php +++ b/lib/public/files/notpermittedexception.php @@ -31,5 +31,6 @@ namespace OCP\Files; /** * Exception for not permitted action + * @since 6.0.0 */ class NotPermittedException extends \Exception {} diff --git a/lib/public/files/objectstore/iobjectstore.php b/lib/public/files/objectstore/iobjectstore.php index 0eeecc1204d..5943731849e 100644 --- a/lib/public/files/objectstore/iobjectstore.php +++ b/lib/public/files/objectstore/iobjectstore.php @@ -21,32 +21,42 @@ */ namespace OCP\Files\ObjectStore; +/** + * Interface IObjectStore + * + * @package OCP\Files\ObjectStore + * @since 7.0.0 + */ interface IObjectStore { /** * @return string the container or bucket name where objects are stored + * @since 7.0.0 */ function getStorageId(); /** * @param string $urn the unified resource name used to identify the object * @return resource stream with the read data - * @throws Exception when something goes wrong, message will be logged + * @throws \Exception when something goes wrong, message will be logged + * @since 7.0.0 */ function readObject($urn); /** * @param string $urn the unified resource name used to identify the object * @param resource $stream stream with the data to write - * @throws Exception when something goes wrong, message will be logged + * @throws \Exception when something goes wrong, message will be logged + * @since 7.0.0 */ function writeObject($urn, $stream); /** * @param string $urn the unified resource name used to identify the object * @return void - * @throws Exception when something goes wrong, message will be logged + * @throws \Exception when something goes wrong, message will be logged + * @since 7.0.0 */ function deleteObject($urn); -}
\ No newline at end of file +} diff --git a/lib/public/files/reservedwordexception.php b/lib/public/files/reservedwordexception.php index 15527a86f69..0fda9841194 100644 --- a/lib/public/files/reservedwordexception.php +++ b/lib/public/files/reservedwordexception.php @@ -30,6 +30,7 @@ namespace OCP\Files; /** * Exception for invalid path + * @since 8.1.0 */ class ReservedWordException extends InvalidPathException { diff --git a/lib/public/files/storage.php b/lib/public/files/storage.php index bac2c95ebce..17e09af9832 100644 --- a/lib/public/files/storage.php +++ b/lib/public/files/storage.php @@ -38,6 +38,7 @@ use OCP\Files\InvalidPathException; * Provide a common interface to all different storage options * * All paths passed to the storage are relative to the storage and should NOT have a leading slash. + * @since 6.0.0 */ interface Storage { /** @@ -45,6 +46,7 @@ interface Storage { * * @param array $parameters * @return void + * @since 6.0.0 */ public function __construct($parameters); @@ -54,6 +56,7 @@ interface Storage { * and two storage objects with the same id should refer to two storages that display the same files. * * @return string + * @since 6.0.0 */ public function getId(); @@ -62,6 +65,7 @@ interface Storage { * * @param string $path * @return bool + * @since 6.0.0 */ public function mkdir($path); @@ -70,6 +74,7 @@ interface Storage { * * @param string $path * @return bool + * @since 6.0.0 */ public function rmdir($path); @@ -78,6 +83,7 @@ interface Storage { * * @param string $path * @return resource|false + * @since 6.0.0 */ public function opendir($path); @@ -86,6 +92,7 @@ interface Storage { * * @param string $path * @return bool + * @since 6.0.0 */ public function is_dir($path); @@ -94,6 +101,7 @@ interface Storage { * * @param string $path * @return bool + * @since 6.0.0 */ public function is_file($path); @@ -103,6 +111,7 @@ interface Storage { * * @param string $path * @return array|false + * @since 6.0.0 */ public function stat($path); @@ -111,6 +120,7 @@ interface Storage { * * @param string $path * @return string|false + * @since 6.0.0 */ public function filetype($path); @@ -120,6 +130,7 @@ interface Storage { * * @param string $path * @return int|false + * @since 6.0.0 */ public function filesize($path); @@ -128,6 +139,7 @@ interface Storage { * * @param string $path * @return bool + * @since 6.0.0 */ public function isCreatable($path); @@ -136,6 +148,7 @@ interface Storage { * * @param string $path * @return bool + * @since 6.0.0 */ public function isReadable($path); @@ -144,6 +157,7 @@ interface Storage { * * @param string $path * @return bool + * @since 6.0.0 */ public function isUpdatable($path); @@ -152,6 +166,7 @@ interface Storage { * * @param string $path * @return bool + * @since 6.0.0 */ public function isDeletable($path); @@ -160,6 +175,7 @@ interface Storage { * * @param string $path * @return bool + * @since 6.0.0 */ public function isSharable($path); @@ -169,6 +185,7 @@ interface Storage { * * @param string $path * @return int + * @since 6.0.0 */ public function getPermissions($path); @@ -177,6 +194,7 @@ interface Storage { * * @param string $path * @return bool + * @since 6.0.0 */ public function file_exists($path); @@ -185,6 +203,7 @@ interface Storage { * * @param string $path * @return int|false + * @since 6.0.0 */ public function filemtime($path); @@ -193,6 +212,7 @@ interface Storage { * * @param string $path * @return string|false + * @since 6.0.0 */ public function file_get_contents($path); @@ -202,6 +222,7 @@ interface Storage { * @param string $path * @param string $data * @return bool + * @since 6.0.0 */ public function file_put_contents($path, $data); @@ -210,6 +231,7 @@ interface Storage { * * @param string $path * @return bool + * @since 6.0.0 */ public function unlink($path); @@ -219,6 +241,7 @@ interface Storage { * @param string $path1 * @param string $path2 * @return bool + * @since 6.0.0 */ public function rename($path1, $path2); @@ -228,6 +251,7 @@ interface Storage { * @param string $path1 * @param string $path2 * @return bool + * @since 6.0.0 */ public function copy($path1, $path2); @@ -237,6 +261,7 @@ interface Storage { * @param string $path * @param string $mode * @return resource|false + * @since 6.0.0 */ public function fopen($path, $mode); @@ -246,6 +271,7 @@ interface Storage { * * @param string $path * @return string|false + * @since 6.0.0 */ public function getMimeType($path); @@ -256,6 +282,7 @@ interface Storage { * @param string $path * @param bool $raw * @return string|false + * @since 6.0.0 */ public function hash($type, $path, $raw = false); @@ -264,6 +291,7 @@ interface Storage { * * @param string $path * @return int|false + * @since 6.0.0 */ public function free_space($path); @@ -272,6 +300,7 @@ interface Storage { * * @param string $query * @return array|false + * @since 6.0.0 */ public function search($query); @@ -282,6 +311,7 @@ interface Storage { * @param string $path * @param int $mtime * @return bool + * @since 6.0.0 */ public function touch($path, $mtime = null); @@ -291,6 +321,7 @@ interface Storage { * * @param string $path * @return string|false + * @since 6.0.0 */ public function getLocalFile($path); @@ -300,6 +331,7 @@ interface Storage { * * @param string $path * @return string|false + * @since 6.0.0 */ public function getLocalFolder($path); /** @@ -308,6 +340,7 @@ interface Storage { * @param string $path * @param int $time * @return bool + * @since 6.0.0 * * hasUpdated for folders should return at least true if a file inside the folder is add, removed or renamed. * returning true for other changes in the folder is optional @@ -319,6 +352,7 @@ interface Storage { * * @param string $path * @return string|false + * @since 6.0.0 */ public function getETag($path); @@ -330,6 +364,7 @@ interface Storage { * it might return a temporary file. * * @return bool true if the files are stored locally, false otherwise + * @since 7.0.0 */ public function isLocal(); @@ -338,6 +373,7 @@ interface Storage { * * @param string $class * @return bool + * @since 7.0.0 */ public function instanceOfStorage($class); @@ -348,6 +384,7 @@ interface Storage { * * @param string $path * @return array|false + * @since 8.0.0 */ public function getDirectDownload($path); @@ -356,6 +393,7 @@ interface Storage { * @param string $fileName the name of the file itself * @return void * @throws InvalidPathException + * @since 8.1.0 */ public function verifyPath($path, $fileName); @@ -364,6 +402,7 @@ interface Storage { * @param string $sourceInternalPath * @param string $targetInternalPath * @return bool + * @since 8.1.0 */ public function copyFromStorage(\OCP\Files\Storage $sourceStorage, $sourceInternalPath, $targetInternalPath); @@ -372,6 +411,7 @@ interface Storage { * @param string $sourceInternalPath * @param string $targetInternalPath * @return bool + * @since 8.1.0 */ public function moveFromStorage(\OCP\Files\Storage $sourceStorage, $sourceInternalPath, $targetInternalPath); } diff --git a/lib/public/files/storage/istoragefactory.php b/lib/public/files/storage/istoragefactory.php index e7827297f03..bd9651299cf 100644 --- a/lib/public/files/storage/istoragefactory.php +++ b/lib/public/files/storage/istoragefactory.php @@ -26,6 +26,7 @@ use OCP\Files\Mount\IMountPoint; /** * Creates storage instances and manages and applies storage wrappers + * @since 8.0.0 */ interface IStorageFactory { /** @@ -37,6 +38,7 @@ interface IStorageFactory { * @param callable $callback * @return bool true if the wrapper was added, false if there was already a wrapper with this * name registered + * @since 8.0.0 */ public function addStorageWrapper($wrapperName, $callback); @@ -45,6 +47,7 @@ interface IStorageFactory { * @param string $class * @param array $arguments * @return \OCP\Files\Storage + * @since 8.0.0 */ public function getInstance(IMountPoint $mountPoint, $class, $arguments); } diff --git a/lib/public/files/storageinvalidexception.php b/lib/public/files/storageinvalidexception.php index c6036a58046..11099c2fe03 100644 --- a/lib/public/files/storageinvalidexception.php +++ b/lib/public/files/storageinvalidexception.php @@ -31,6 +31,7 @@ namespace OCP\Files; /** * Storage has invalid configuration + * @since 7.0.0 */ class StorageInvalidException extends \Exception { } diff --git a/lib/public/files/storagenotavailableexception.php b/lib/public/files/storagenotavailableexception.php index 4b912caa5bd..842867ba567 100644 --- a/lib/public/files/storagenotavailableexception.php +++ b/lib/public/files/storagenotavailableexception.php @@ -31,6 +31,7 @@ namespace OCP\Files; /** * Storage is temporarily not available + * @since 6.0.0 */ class StorageNotAvailableException extends \Exception { } diff --git a/lib/public/groupinterface.php b/lib/public/groupinterface.php index 7f4932a0775..16de6bc8663 100644 --- a/lib/public/groupinterface.php +++ b/lib/public/groupinterface.php @@ -31,4 +31,10 @@ // This means that they should be used by apps instead of the internal ownCloud classes namespace OCP; +/** + * Interface GroupInterface + * + * @package OCP + * @since 4.5.0 + */ interface GroupInterface extends \OC_Group_Interface {} diff --git a/lib/public/http/client/iclient.php b/lib/public/http/client/iclient.php index 88c61bc3cd5..ab907dcfb82 100644 --- a/lib/public/http/client/iclient.php +++ b/lib/public/http/client/iclient.php @@ -25,6 +25,7 @@ namespace OCP\Http\Client; * Interface IClient * * @package OCP\Http + * @since 8.1.0 */ interface IClient { @@ -54,6 +55,7 @@ interface IClient { * 'debug' => true, * @return IResponse * @throws \Exception If the request could not get completed + * @since 8.1.0 */ public function get($uri, array $options = []); @@ -77,6 +79,7 @@ interface IClient { * 'verify' => true, // bool or string to CA file * 'debug' => true, * @return IResponse + * @since 8.1.0 */ public function head($uri, $options = []); @@ -105,6 +108,7 @@ interface IClient { * 'verify' => true, // bool or string to CA file * 'debug' => true, * @return IResponse + * @since 8.1.0 */ public function post($uri, array $options = []); @@ -133,6 +137,7 @@ interface IClient { * 'verify' => true, // bool or string to CA file * 'debug' => true, * @return IResponse + * @since 8.1.0 */ public function put($uri, array $options = []); @@ -161,6 +166,7 @@ interface IClient { * 'verify' => true, // bool or string to CA file * 'debug' => true, * @return IResponse + * @since 8.1.0 */ public function delete($uri, array $options = []); @@ -189,6 +195,7 @@ interface IClient { * 'verify' => true, // bool or string to CA file * 'debug' => true, * @return IResponse + * @since 8.1.0 */ public function options($uri, array $options = []); } diff --git a/lib/public/http/client/iclientservice.php b/lib/public/http/client/iclientservice.php index 98cf035c71a..2a8bff7bc69 100644 --- a/lib/public/http/client/iclientservice.php +++ b/lib/public/http/client/iclientservice.php @@ -25,10 +25,12 @@ namespace OCP\Http\Client; * Interface IClientService * * @package OCP\Http + * @since 8.1.0 */ interface IClientService { /** * @return IClient + * @since 8.1.0 */ public function newClient(); } diff --git a/lib/public/http/client/iresponse.php b/lib/public/http/client/iresponse.php index 041d9f454e8..3a717d1650c 100644 --- a/lib/public/http/client/iresponse.php +++ b/lib/public/http/client/iresponse.php @@ -25,26 +25,31 @@ namespace OCP\Http\Client; * Interface IResponse * * @package OCP\Http + * @since 8.1.0 */ interface IResponse { /** * @return string + * @since 8.1.0 */ public function getBody(); /** * @return int + * @since 8.1.0 */ public function getStatusCode(); /** * @param $key * @return string + * @since 8.1.0 */ public function getHeader($key); /** * @return array + * @since 8.1.0 */ public function getHeaders(); } diff --git a/lib/public/iaddressbook.php b/lib/public/iaddressbook.php index 978becf16d9..f3f60ab22d7 100644 --- a/lib/public/iaddressbook.php +++ b/lib/public/iaddressbook.php @@ -30,16 +30,24 @@ // use OCP namespace for all classes that are considered public. // This means that they should be used by apps instead of the internal ownCloud classes namespace OCP { + /** + * Interface IAddressBook + * + * @package OCP + * @since 5.0.0 + */ interface IAddressBook { /** * @return string defining the technical unique key + * @since 5.0.0 */ public function getKey(); /** * In comparison to getKey() this function returns a human readable (maybe translated) name * @return mixed + * @since 5.0.0 */ public function getDisplayName(); @@ -48,6 +56,7 @@ namespace OCP { * @param array $searchProperties defines the properties within the query pattern should match * @param array $options - for future use. One should always have options! * @return array an array of contacts which are arrays of key-value-pairs + * @since 5.0.0 */ public function search($pattern, $searchProperties, $options); // // dummy results @@ -59,6 +68,7 @@ namespace OCP { /** * @param array $properties this array if key-value-pairs defines a contact * @return array an array representing the contact just created or updated + * @since 5.0.0 */ public function createOrUpdate($properties); // // dummy @@ -69,12 +79,14 @@ namespace OCP { /** * @return mixed + * @since 5.0.0 */ public function getPermissions(); /** * @param object $id the unique identifier to a contact * @return bool successful or not + * @since 5.0.0 */ public function delete($id); } diff --git a/lib/public/iappconfig.php b/lib/public/iappconfig.php index 33fc3e4e362..5cf704a71a3 100644 --- a/lib/public/iappconfig.php +++ b/lib/public/iappconfig.php @@ -27,6 +27,7 @@ namespace OCP; /** * This class provides an easy way for apps to store config values in the * database. + * @since 7.0.0 */ interface IAppConfig { /** @@ -34,6 +35,7 @@ interface IAppConfig { * @param string $app * @param string $key * @return bool + * @since 7.0.0 */ public function hasKey($app, $key); @@ -47,6 +49,7 @@ interface IAppConfig { * * This function gets a value from the appconfig table. If the key does * not exist the default value will be returned + * @since 7.0.0 */ public function getValue($app, $key, $default = null); @@ -56,6 +59,7 @@ interface IAppConfig { * @param string $key key * @return bool * @deprecated use method deleteAppValue of \OCP\IConfig + * @since 7.0.0 */ public function deleteKey($app, $key); @@ -67,6 +71,7 @@ interface IAppConfig { * * This function gets all keys of an app. Please note that the values are * not returned. + * @since 7.0.0 */ public function getKeys($app); @@ -76,6 +81,7 @@ interface IAppConfig { * @param string|false $key * @param string|false $app * @return array|false + * @since 7.0.0 */ public function getValues($app, $key); @@ -88,6 +94,7 @@ interface IAppConfig { * * Sets a value. If the key did not exist before it will be created. * @return void + * @since 7.0.0 */ public function setValue($app, $key, $value); @@ -97,6 +104,7 @@ interface IAppConfig { * * This function returns a list of all apps that have at least one * entry in the appconfig table. + * @since 7.0.0 */ public function getApps(); @@ -107,6 +115,7 @@ interface IAppConfig { * @deprecated use method deleteAppValue of \OCP\IConfig * * Removes all keys in appconfig belonging to the app. + * @since 7.0.0 */ public function deleteApp($app); } diff --git a/lib/public/iavatar.php b/lib/public/iavatar.php index f6e41d16696..6bf2ce1f19b 100644 --- a/lib/public/iavatar.php +++ b/lib/public/iavatar.php @@ -27,14 +27,15 @@ namespace OCP; /** * This class provides avatar functionality + * @since 6.0.0 */ - interface IAvatar { /** * get the users avatar * @param int $size size in px of the avatar, avatars are square, defaults to 64 * @return boolean|\OCP\IImage containing the avatar or false if there's no image + * @since 6.0.0 */ function get($size = 64); @@ -42,6 +43,7 @@ interface IAvatar { * Check if an avatar exists for the user * * @return bool + * @since 8.1.0 */ public function exists(); @@ -52,12 +54,14 @@ interface IAvatar { * @throws \Exception if the provided image is not valid * @throws \OC\NotSquareException if the image is not square * @return void + * @since 6.0.0 */ function set($data); /** * remove the users avatar * @return void + * @since 6.0.0 */ function remove(); } diff --git a/lib/public/iavatarmanager.php b/lib/public/iavatarmanager.php index 218f8cb41c7..583b7f0afca 100644 --- a/lib/public/iavatarmanager.php +++ b/lib/public/iavatarmanager.php @@ -26,6 +26,7 @@ namespace OCP; /** * This class provides avatar functionality + * @since 6.0.0 */ interface IAvatarManager { @@ -35,6 +36,7 @@ interface IAvatarManager { * @see \OCP\IAvatar * @param string $user the ownCloud user id * @return \OCP\IAvatar + * @since 6.0.0 */ function getAvatar($user); } diff --git a/lib/public/icache.php b/lib/public/icache.php index 215b490fb5f..d7593a263c8 100644 --- a/lib/public/icache.php +++ b/lib/public/icache.php @@ -33,6 +33,7 @@ namespace OCP; /** * This interface defines method for accessing the file based user cache. + * @since 6.0.0 */ interface ICache { @@ -40,6 +41,7 @@ interface ICache { * Get a value from the user cache * @param string $key * @return mixed + * @since 6.0.0 */ public function get($key); @@ -49,6 +51,7 @@ interface ICache { * @param mixed $value * @param int $ttl Time To Live in seconds. Defaults to 60*60*24 * @return bool + * @since 6.0.0 */ public function set($key, $value, $ttl = 0); @@ -56,6 +59,7 @@ interface ICache { * Check if a value is set in the user cache * @param string $key * @return bool + * @since 6.0.0 */ public function hasKey($key); @@ -63,6 +67,7 @@ interface ICache { * Remove an item from the user cache * @param string $key * @return bool + * @since 6.0.0 */ public function remove($key); @@ -70,6 +75,7 @@ interface ICache { * Clear the user cache of all entries starting with a prefix * @param string $prefix (optional) * @return bool + * @since 6.0.0 */ public function clear($prefix = ''); } diff --git a/lib/public/icachefactory.php b/lib/public/icachefactory.php index 173ace2242a..a030b7fc5bc 100644 --- a/lib/public/icachefactory.php +++ b/lib/public/icachefactory.php @@ -22,6 +22,12 @@ namespace OCP; +/** + * Interface ICacheFactory + * + * @package OCP + * @since 7.0.0 + */ interface ICacheFactory{ /** * Get a memory cache instance @@ -30,6 +36,7 @@ interface ICacheFactory{ * * @param string $prefix * @return \OCP\ICache + * @since 7.0.0 */ public function create($prefix = ''); @@ -37,6 +44,7 @@ interface ICacheFactory{ * Check if any memory cache backend is available * * @return bool + * @since 7.0.0 */ public function isAvailable(); } diff --git a/lib/public/icertificate.php b/lib/public/icertificate.php index 19f64b7b042..73abc030934 100644 --- a/lib/public/icertificate.php +++ b/lib/public/icertificate.php @@ -22,44 +22,58 @@ namespace OCP; +/** + * Interface ICertificate + * + * @package OCP + * @since 8.0.0 + */ interface ICertificate { /** * @return string + * @since 8.0.0 */ public function getName(); /** * @return string + * @since 8.0.0 */ public function getCommonName(); /** * @return string + * @since 8.0.0 */ public function getOrganization(); /** * @return \DateTime + * @since 8.0.0 */ public function getIssueDate(); /** * @return \DateTime + * @since 8.0.0 */ public function getExpireDate(); /** * @return bool + * @since 8.0.0 */ public function isExpired(); /** * @return string + * @since 8.0.0 */ public function getIssuerName(); /** * @return string + * @since 8.0.0 */ public function getIssuerOrganization(); } diff --git a/lib/public/icertificatemanager.php b/lib/public/icertificatemanager.php index f6045fe5b28..ec88f32e291 100644 --- a/lib/public/icertificatemanager.php +++ b/lib/public/icertificatemanager.php @@ -24,12 +24,14 @@ namespace OCP; /** * Manage trusted certificates for users + * @since 8.0.0 */ interface ICertificateManager { /** * Returns all certificates trusted by the user * * @return \OCP\ICertificate[] + * @since 8.0.0 */ public function listCertificates(); @@ -37,11 +39,13 @@ interface ICertificateManager { * @param string $certificate the certificate data * @param string $name the filename for the certificate * @return bool | \OCP\ICertificate + * @since 8.0.0 */ public function addCertificate($certificate, $name); /** * @param string $name + * @since 8.0.0 */ public function removeCertificate($name); @@ -49,6 +53,7 @@ interface ICertificateManager { * Get the path to the certificate bundle for this user * * @return string + * @since 8.0.0 */ public function getCertificateBundle(); } diff --git a/lib/public/iconfig.php b/lib/public/iconfig.php index f28a114a2bb..ff0b6c6a5b0 100644 --- a/lib/public/iconfig.php +++ b/lib/public/iconfig.php @@ -37,6 +37,7 @@ namespace OCP; /** * Access to all the configuration options ownCloud offers + * @since 6.0.0 */ interface IConfig { /** @@ -44,6 +45,7 @@ interface IConfig { * * @param array $configs Associative array with `key => value` pairs * If value is null, the config key will be deleted + * @since 8.0.0 */ public function setSystemValues(array $configs); @@ -52,6 +54,7 @@ interface IConfig { * * @param string $key the key of the value, under which will be saved * @param mixed $value the value that should be stored + * @since 8.0.0 */ public function setSystemValue($key, $value); @@ -61,6 +64,7 @@ interface IConfig { * @param string $key the key of the value, under which it was saved * @param mixed $default the default value to be returned if the value isn't set * @return mixed the value or $default + * @since 6.0.0 - parameter $default was added in 7.0.0 */ public function getSystemValue($key, $default = ''); @@ -68,6 +72,7 @@ interface IConfig { * Delete a system wide defined value * * @param string $key the key of the value, under which it was saved + * @since 8.0.0 */ public function deleteSystemValue($key); @@ -76,6 +81,7 @@ interface IConfig { * * @param string $appName the appName that we stored the value under * @return string[] the keys stored for the app + * @since 8.0.0 */ public function getAppKeys($appName); @@ -86,6 +92,7 @@ interface IConfig { * @param string $key the key of the value, under which will be saved * @param string $value the value that should be stored * @return void + * @since 6.0.0 */ public function setAppValue($appName, $key, $value); @@ -96,6 +103,7 @@ interface IConfig { * @param string $key the key of the value, under which it was saved * @param string $default the default value to be returned if the value isn't set * @return string the saved value + * @since 6.0.0 - parameter $default was added in 7.0.0 */ public function getAppValue($appName, $key, $default = ''); @@ -104,6 +112,7 @@ interface IConfig { * * @param string $appName the appName that we stored the value under * @param string $key the key of the value, under which it was saved + * @since 8.0.0 */ public function deleteAppValue($appName, $key); @@ -111,6 +120,7 @@ interface IConfig { * Removes all keys in appconfig belonging to the app * * @param string $appName the appName the configs are stored under + * @since 8.0.0 */ public function deleteAppValues($appName); @@ -124,6 +134,7 @@ interface IConfig { * @param string $value the value that you want to store * @param string $preCondition only update if the config value was previously the value passed as $preCondition * @throws \OCP\PreConditionNotMetException if a precondition is specified and is not met + * @since 6.0.0 - parameter $precondition was added in 8.0.0 */ public function setUserValue($userId, $appName, $key, $value, $preCondition = null); @@ -135,6 +146,7 @@ interface IConfig { * @param string $key the key under which the value is being stored * @param mixed $default the default value to be returned if the value isn't set * @return string + * @since 6.0.0 - parameter $default was added in 7.0.0 */ public function getUserValue($userId, $appName, $key, $default = ''); @@ -145,6 +157,7 @@ interface IConfig { * @param string $key the key to get the value for * @param array $userIds the user IDs to fetch the values for * @return array Mapped values: userId => value + * @since 8.0.0 */ public function getUserValueForUsers($appName, $key, $userIds); @@ -154,6 +167,7 @@ interface IConfig { * @param string $userId the userId of the user that we want to store the value under * @param string $appName the appName that we stored the value under * @return string[] + * @since 8.0.0 */ public function getUserKeys($userId, $appName); @@ -163,6 +177,7 @@ interface IConfig { * @param string $userId the userId of the user that we want to store the value under * @param string $appName the appName that we stored the value under * @param string $key the key under which the value is being stored + * @since 8.0.0 */ public function deleteUserValue($userId, $appName, $key); @@ -170,6 +185,7 @@ interface IConfig { * Delete all user values * * @param string $userId the userId of the user that we want to remove all values from + * @since 8.0.0 */ public function deleteAllUserValues($userId); @@ -177,6 +193,7 @@ interface IConfig { * Delete all user related values of one app * * @param string $appName the appName of the app that we want to remove all values from + * @since 8.0.0 */ public function deleteAppFromAllUsers($appName); @@ -187,6 +204,7 @@ interface IConfig { * @param string $key the key to get the user for * @param string $value the value to get the user for * @return array of user IDs + * @since 8.0.0 */ public function getUsersForUserValue($appName, $key, $value); } diff --git a/lib/public/icontainer.php b/lib/public/icontainer.php index 10cb6bbe37d..27ca544ec67 100644 --- a/lib/public/icontainer.php +++ b/lib/public/icontainer.php @@ -36,6 +36,7 @@ namespace OCP; * IContainer is the basic interface to be used for any internal dependency injection mechanism * * @package OCP + * @since 6.0.0 */ interface IContainer { @@ -44,6 +45,7 @@ interface IContainer { * * @param string $name * @return mixed + * @since 6.0.0 */ function query($name); @@ -53,6 +55,7 @@ interface IContainer { * @param string $name * @param mixed $value * @return void + * @since 6.0.0 */ function registerParameter($name, $value); @@ -67,6 +70,7 @@ interface IContainer { * @param \Closure $closure * @param bool $shared * @return void + * @since 6.0.0 */ function registerService($name, \Closure $closure, $shared = true); } diff --git a/lib/public/idatetimeformatter.php b/lib/public/idatetimeformatter.php index 1eed73cda00..77afd6930ce 100644 --- a/lib/public/idatetimeformatter.php +++ b/lib/public/idatetimeformatter.php @@ -22,6 +22,12 @@ namespace OCP; +/** + * Interface IDateTimeFormatter + * + * @package OCP + * @since 8.0.0 + */ interface IDateTimeFormatter { /** * Formats the date of the given timestamp @@ -36,6 +42,7 @@ interface IDateTimeFormatter { * @param \DateTimeZone $timeZone The timezone to use * @param \OCP\IL10N $l The locale to use * @return string Formatted date string + * @since 8.0.0 */ public function formatDate($timestamp, $format = 'long', \DateTimeZone $timeZone = null, \OCP\IL10N $l = null); @@ -53,6 +60,7 @@ interface IDateTimeFormatter { * @param \DateTimeZone $timeZone The timezone to use * @param \OCP\IL10N $l The locale to use * @return string Formatted relative date string + * @since 8.0.0 */ public function formatDateRelativeDay($timestamp, $format = 'long', \DateTimeZone $timeZone = null, \OCP\IL10N $l = null); @@ -68,6 +76,7 @@ interface IDateTimeFormatter { * >= 13 month => last year, n years ago * @param \OCP\IL10N $l The locale to use * @return string Formatted date span + * @since 8.0.0 */ public function formatDateSpan($timestamp, $baseTimestamp = null, \OCP\IL10N $l = null); @@ -84,6 +93,7 @@ interface IDateTimeFormatter { * @param \DateTimeZone $timeZone The timezone to use * @param \OCP\IL10N $l The locale to use * @return string Formatted time string + * @since 8.0.0 */ public function formatTime($timestamp, $format = 'medium', \DateTimeZone $timeZone = null, \OCP\IL10N $l = null); @@ -101,6 +111,7 @@ interface IDateTimeFormatter { * >= 13 month => last year, n years ago * @param \OCP\IL10N $l The locale to use * @return string Formatted time span + * @since 8.0.0 */ public function formatTimeSpan($timestamp, $baseTimestamp = null, \OCP\IL10N $l = null); @@ -113,6 +124,7 @@ interface IDateTimeFormatter { * @param \DateTimeZone $timeZone The timezone to use * @param \OCP\IL10N $l The locale to use * @return string Formatted date and time string + * @since 8.0.0 */ public function formatDateTime($timestamp, $formatDate = 'long', $formatTime = 'medium', \DateTimeZone $timeZone = null, \OCP\IL10N $l = null); @@ -126,6 +138,7 @@ interface IDateTimeFormatter { * @param \DateTimeZone $timeZone The timezone to use * @param \OCP\IL10N $l The locale to use * @return string Formatted relative date and time string + * @since 8.0.0 */ public function formatDateTimeRelativeDay($timestamp, $formatDate = 'long', $formatTime = 'medium', \DateTimeZone $timeZone = null, \OCP\IL10N $l = null); } diff --git a/lib/public/idatetimezone.php b/lib/public/idatetimezone.php index eb74074aa46..2334f1314b5 100644 --- a/lib/public/idatetimezone.php +++ b/lib/public/idatetimezone.php @@ -22,11 +22,17 @@ namespace OCP; - +/** + * Interface IDateTimeZone + * + * @package OCP + * @since 8.0.0 + */ interface IDateTimeZone { /** * @param bool|int $timestamp * @return \DateTimeZone + * @since 8.0.0 - parameter $timestamp was added in 8.1.0 */ public function getTimeZone($timestamp = false); } diff --git a/lib/public/idb.php b/lib/public/idb.php index 8d7060f66d6..f3e7915d9f7 100644 --- a/lib/public/idb.php +++ b/lib/public/idb.php @@ -25,6 +25,7 @@ namespace OCP; /** * Small Facade for being able to inject the database connection for tests + * @since 7.0.0 - extends IDBConnection was added in 8.1.0 */ interface IDb extends IDBConnection { @@ -35,6 +36,7 @@ interface IDb extends IDBConnection { * @param int $limit the maximum number of rows * @param int $offset from which row we want to start * @return \OC_DB_StatementWrapper prepared SQL query + * @since 7.0.0 */ public function prepareQuery($sql, $limit=null, $offset=null); @@ -43,6 +45,7 @@ interface IDb extends IDBConnection { * Used to get the id of the just inserted element * @param string $tableName the name of the table where we inserted the item * @return int the id of the inserted element + * @since 7.0.0 */ public function getInsertId($tableName); diff --git a/lib/public/idbconnection.php b/lib/public/idbconnection.php index ac909dfe5de..ebad3c1f693 100644 --- a/lib/public/idbconnection.php +++ b/lib/public/idbconnection.php @@ -34,7 +34,10 @@ namespace OCP; /** - * TODO: Description + * Interface IDBConnection + * + * @package OCP + * @since 6.0.0 */ interface IDBConnection { /** @@ -43,6 +46,7 @@ interface IDBConnection { * @param int $limit the maximum number of rows * @param int $offset from which row we want to start * @return \Doctrine\DBAL\Driver\Statement The prepared statement. + * @since 6.0.0 */ public function prepare($sql, $limit=null, $offset=null); @@ -56,6 +60,7 @@ interface IDBConnection { * @param string[] $params The parameters to bind to the query, if any. * @param array $types The types the previous parameters are in. * @return \Doctrine\DBAL\Driver\Statement The executed statement. + * @since 8.0.0 */ public function executeQuery($query, array $params = array(), $types = array()); @@ -69,6 +74,7 @@ interface IDBConnection { * @param array $params The query parameters. * @param array $types The parameter types. * @return integer The number of affected rows. + * @since 8.0.0 */ public function executeUpdate($query, array $params = array(), array $types = array()); @@ -76,6 +82,7 @@ interface IDBConnection { * Used to get the id of the just inserted element * @param string $table the name of the table where we inserted the item * @return int the id of the inserted element + * @since 6.0.0 */ public function lastInsertId($table = null); @@ -89,27 +96,32 @@ interface IDBConnection { * Please note: text fields (clob) must not be used in the compare array * @return int number of inserted rows * @throws \Doctrine\DBAL\DBALException + * @since 6.0.0 - parameter $compare was added in 8.1.0, return type changed from boolean in 8.1.0 */ public function insertIfNotExist($table, $input, array $compare = null); /** * Start a transaction + * @since 6.0.0 */ public function beginTransaction(); /** * Commit the database changes done during a transaction that is in progress + * @since 6.0.0 */ public function commit(); /** * Rollback the database changes done during a transaction that is in progress + * @since 6.0.0 */ public function rollBack(); /** * Gets the error code and message as a string for logging * @return string + * @since 6.0.0 */ public function getError(); @@ -117,6 +129,7 @@ interface IDBConnection { * Fetch the SQLSTATE associated with the last database operation. * * @return integer The last error code. + * @since 8.0.0 */ public function errorCode(); @@ -124,6 +137,7 @@ interface IDBConnection { * Fetch extended error information associated with the last database operation. * * @return array The last error information. + * @since 8.0.0 */ public function errorInfo(); @@ -131,11 +145,13 @@ interface IDBConnection { * Establishes the connection with the database. * * @return bool + * @since 8.0.0 */ public function connect(); /** * Close the database connection + * @since 8.0.0 */ public function close(); @@ -145,6 +161,7 @@ interface IDBConnection { * @param mixed $input Parameter to be quoted. * @param int $type Type of the parameter. * @return string The quoted parameter. + * @since 8.0.0 */ public function quote($input, $type = \PDO::PARAM_STR); @@ -153,6 +170,7 @@ interface IDBConnection { * the platform this driver connects to. * * @return \Doctrine\DBAL\Platforms\AbstractPlatform The database platform. + * @since 8.0.0 */ public function getDatabasePlatform(); @@ -160,6 +178,7 @@ interface IDBConnection { * Drop a table from the database if it exists * * @param string $table table name without the prefix + * @since 8.0.0 */ public function dropTable($table); @@ -168,6 +187,7 @@ interface IDBConnection { * * @param string $table table name without the prefix * @return bool + * @since 8.0.0 */ public function tableExists($table); } diff --git a/lib/public/ieventsource.php b/lib/public/ieventsource.php index ad5c44eb239..176d5677f0a 100644 --- a/lib/public/ieventsource.php +++ b/lib/public/ieventsource.php @@ -29,6 +29,7 @@ namespace OCP; * use server side events with caution, to many open requests can hang the server * * The event source will initialize the connection to the client when the first data is sent + * @since 8.0.0 */ interface IEventSource { /** @@ -38,11 +39,13 @@ interface IEventSource { * @param mixed $data * * if only one parameter is given, a typeless message will be send with that parameter as data + * @since 8.0.0 */ public function send($type, $data = null); /** * close the connection of the event source + * @since 8.0.0 */ public function close(); } diff --git a/lib/public/igroup.php b/lib/public/igroup.php index a5fc44e0d5d..b16bb94d43f 100644 --- a/lib/public/igroup.php +++ b/lib/public/igroup.php @@ -22,9 +22,16 @@ namespace OCP; +/** + * Interface IGroup + * + * @package OCP + * @since 8.0.0 + */ interface IGroup { /** * @return string + * @since 8.0.0 */ public function getGID(); @@ -32,6 +39,7 @@ interface IGroup { * get all users in the group * * @return \OCP\IUser[] + * @since 8.0.0 */ public function getUsers(); @@ -40,6 +48,7 @@ interface IGroup { * * @param \OCP\IUser $user * @return bool + * @since 8.0.0 */ public function inGroup($user); @@ -47,6 +56,7 @@ interface IGroup { * add a user to the group * * @param \OCP\IUser $user + * @since 8.0.0 */ public function addUser($user); @@ -54,6 +64,7 @@ interface IGroup { * remove a user from the group * * @param \OCP\IUser $user + * @since 8.0.0 */ public function removeUser($user); @@ -64,6 +75,7 @@ interface IGroup { * @param int $limit * @param int $offset * @return \OCP\IUser[] + * @since 8.0.0 */ public function searchUsers($search, $limit = null, $offset = null); @@ -72,6 +84,7 @@ interface IGroup { * * @param string $search * @return int|bool + * @since 8.0.0 */ public function count($search = ''); @@ -82,6 +95,7 @@ interface IGroup { * @param int $limit * @param int $offset * @return \OCP\IUser[] + * @since 8.0.0 */ public function searchDisplayName($search, $limit = null, $offset = null); @@ -89,6 +103,7 @@ interface IGroup { * delete the group * * @return bool + * @since 8.0.0 */ public function delete(); } diff --git a/lib/public/igroupmanager.php b/lib/public/igroupmanager.php index 89998ecf65b..ffd459b09e1 100644 --- a/lib/public/igroupmanager.php +++ b/lib/public/igroupmanager.php @@ -37,30 +37,38 @@ namespace OCP; * - postCreate(\OC\Group\Group $group) * * @package OC\Group + * @since 8.0.0 */ interface IGroupManager { /** * @param \OCP\UserInterface $backend + * @since 8.0.0 */ public function addBackend($backend); + /** + * @since 8.0.0 + */ public function clearBackends(); /** * @param string $gid * @return \OCP\IGroup + * @since 8.0.0 */ public function get($gid); /** * @param string $gid * @return bool + * @since 8.0.0 */ public function groupExists($gid); /** * @param string $gid * @return \OCP\IGroup + * @since 8.0.0 */ public function createGroup($gid); @@ -69,18 +77,21 @@ interface IGroupManager { * @param int $limit * @param int $offset * @return \OCP\IGroup[] + * @since 8.0.0 */ public function search($search, $limit = null, $offset = null); /** * @param \OCP\IUser $user * @return \OCP\IGroup[] + * @since 8.0.0 */ public function getUserGroups($user); /** * @param \OCP\IUser $user * @return array with group names + * @since 8.0.0 */ public function getUserGroupIds($user); @@ -92,6 +103,7 @@ interface IGroupManager { * @param int $limit * @param int $offset * @return array an array of display names (value) and user ids (key) + * @since 8.0.0 */ public function displayNamesInGroup($gid, $search = '', $limit = -1, $offset = 0); @@ -99,6 +111,7 @@ interface IGroupManager { * Checks if a userId is in the admin group * @param string $userId * @return bool if admin + * @since 8.0.0 */ public function isAdmin($userId); @@ -107,6 +120,7 @@ interface IGroupManager { * @param string $userId * @param group $group * @return bool if in group + * @since 8.0.0 */ public function isInGroup($userId, $group); } diff --git a/lib/public/ihelper.php b/lib/public/ihelper.php index 0eb265f5a61..a42dbf5ec61 100644 --- a/lib/public/ihelper.php +++ b/lib/public/ihelper.php @@ -32,6 +32,7 @@ namespace OCP; /** * Functions that don't have any specific interface to place + * @since 6.0.0 */ interface IHelper { /** @@ -39,6 +40,7 @@ interface IHelper { * installed * @param string $url the url that should be fetched * @return string the content of the webpage + * @since 6.0.0 */ public function getUrlContent($url); } diff --git a/lib/public/iimage.php b/lib/public/iimage.php index 36e5492138c..202adeaba54 100644 --- a/lib/public/iimage.php +++ b/lib/public/iimage.php @@ -23,12 +23,14 @@ namespace OCP; /** * Class for basic image manipulation + * @since 8.1.0 */ interface IImage { /** * Determine whether the object contains an image resource. * * @return bool + * @since 8.1.0 */ public function valid(); @@ -36,6 +38,7 @@ interface IImage { * Returns the MIME type of the image or an empty string if no image is loaded. * * @return string + * @since 8.1.0 */ public function mimeType(); @@ -43,6 +46,7 @@ interface IImage { * Returns the width of the image or -1 if no image is loaded. * * @return int + * @since 8.1.0 */ public function width(); @@ -50,6 +54,7 @@ interface IImage { * Returns the height of the image or -1 if no image is loaded. * * @return int + * @since 8.1.0 */ public function height(); @@ -57,6 +62,7 @@ interface IImage { * Returns the width when the image orientation is top-left. * * @return int + * @since 8.1.0 */ public function widthTopLeft(); @@ -64,6 +70,7 @@ interface IImage { * Returns the height when the image orientation is top-left. * * @return int + * @since 8.1.0 */ public function heightTopLeft(); @@ -72,6 +79,7 @@ interface IImage { * * @param string $mimeType * @return bool + * @since 8.1.0 */ public function show($mimeType = null); @@ -81,16 +89,19 @@ interface IImage { * @param string $filePath * @param string $mimeType * @return bool + * @since 8.1.0 */ public function save($filePath = null, $mimeType = null); /** * @return resource Returns the image resource in any. + * @since 8.1.0 */ public function resource(); /** * @return string Returns the raw image data. + * @since 8.1.0 */ public function data(); @@ -99,6 +110,7 @@ interface IImage { * Get the orientation based on EXIF data. * * @return int The orientation or -1 if no EXIF data is available. + * @since 8.1.0 */ public function getOrientation(); @@ -106,7 +118,8 @@ interface IImage { * (I'm open for suggestions on better method name ;) * Fixes orientation based on EXIF data. * - * @return bool. + * @return bool + * @since 8.1.0 */ public function fixOrientation(); @@ -115,6 +128,7 @@ interface IImage { * * @param integer $maxSize The maximum size of either the width or height. * @return bool + * @since 8.1.0 */ public function resize($maxSize); @@ -122,6 +136,7 @@ interface IImage { * @param int $width * @param int $height * @return bool + * @since 8.1.0 */ public function preciseResize($width, $height); @@ -130,6 +145,7 @@ interface IImage { * * @param int $size maximum size for the result (optional) * @return bool for success or failure + * @since 8.1.0 */ public function centerCrop($size = 0); @@ -141,6 +157,7 @@ interface IImage { * @param int $w Width * @param int $h Height * @return bool for success or failure + * @since 8.1.0 */ public function crop($x, $y, $w, $h); @@ -150,6 +167,7 @@ interface IImage { * @param integer $maxWidth * @param integer $maxHeight * @return bool + * @since 8.1.0 */ public function fitIn($maxWidth, $maxHeight); } diff --git a/lib/public/il10n.php b/lib/public/il10n.php index 35c09268825..edb66392435 100644 --- a/lib/public/il10n.php +++ b/lib/public/il10n.php @@ -35,7 +35,10 @@ namespace OCP; /** - * TODO: Description + * Interface IL10N + * + * @package OCP + * @since 6.0.0 */ interface IL10N { /** @@ -46,6 +49,7 @@ interface IL10N { * * Returns the translation. If no translation is found, $text will be * returned. + * @since 6.0.0 */ public function t($text, $parameters = array()); @@ -62,6 +66,7 @@ interface IL10N { * * The correct plural is determined by the plural_forms-function * provided by the po file. + * @since 6.0.0 * */ public function n($text_singular, $text_plural, $count, $parameters = array()); @@ -87,6 +92,7 @@ interface IL10N { * - Creates a time * - l10n-field: time * - params: timestamp (int/string) + * @since 6.0.0 */ public function l($type, $data); @@ -95,6 +101,7 @@ interface IL10N { * The code (en, de, ...) of the language that is used for this OC_L10N object * * @return string language + * @since 7.0.0 */ public function getLanguageCode(); } diff --git a/lib/public/ilogger.php b/lib/public/ilogger.php index cd4e61fcbc4..c36d9ff285c 100644 --- a/lib/public/ilogger.php +++ b/lib/public/ilogger.php @@ -25,6 +25,7 @@ namespace OCP; /** * Interface ILogger * @package OCP + * @since 7.0.0 * * This logger interface follows the design guidelines of PSR-3 * https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-3-logger-interface.md#3-psrlogloggerinterface @@ -36,6 +37,7 @@ interface ILogger { * @param string $message * @param array $context * @return null + * @since 7.0.0 */ function emergency($message, array $context = array()); @@ -45,6 +47,7 @@ interface ILogger { * @param string $message * @param array $context * @return null + * @since 7.0.0 */ function alert($message, array $context = array()); @@ -54,6 +57,7 @@ interface ILogger { * @param string $message * @param array $context * @return null + * @since 7.0.0 */ function critical($message, array $context = array()); @@ -64,6 +68,7 @@ interface ILogger { * @param string $message * @param array $context * @return null + * @since 7.0.0 */ function error($message, array $context = array()); @@ -73,6 +78,7 @@ interface ILogger { * @param string $message * @param array $context * @return null + * @since 7.0.0 */ function warning($message, array $context = array()); @@ -82,6 +88,7 @@ interface ILogger { * @param string $message * @param array $context * @return null + * @since 7.0.0 */ function notice($message, array $context = array()); @@ -91,6 +98,7 @@ interface ILogger { * @param string $message * @param array $context * @return null + * @since 7.0.0 */ function info($message, array $context = array()); @@ -100,6 +108,7 @@ interface ILogger { * @param string $message * @param array $context * @return null + * @since 7.0.0 */ function debug($message, array $context = array()); @@ -110,6 +119,7 @@ interface ILogger { * @param string $message * @param array $context * @return mixed + * @since 7.0.0 */ function log($level, $message, array $context = array()); } diff --git a/lib/public/image.php b/lib/public/image.php index cf30bacd899..ebcae80f8e8 100644 --- a/lib/public/image.php +++ b/lib/public/image.php @@ -33,6 +33,7 @@ namespace OCP; /** * This class provides functions to handle images + * @since 6.0.0 */ class Image extends \OC_Image { } diff --git a/lib/public/inavigationmanager.php b/lib/public/inavigationmanager.php index 19366b4a1dd..fe2a4cfee27 100644 --- a/lib/public/inavigationmanager.php +++ b/lib/public/inavigationmanager.php @@ -35,6 +35,7 @@ namespace OCP; /** * Manages the ownCloud navigation + * @since 6.0.0 */ interface INavigationManager { /** @@ -44,6 +45,7 @@ interface INavigationManager { * The use of a closure is preferred, because it will avoid * loading the routing of your app, unless required. * @return void + * @since 6.0.0 */ public function add($entry); @@ -51,6 +53,7 @@ interface INavigationManager { * Sets the current navigation entry of the currently running app * @param string $appId id of the app entry to activate (from added $entry) * @return void + * @since 6.0.0 */ public function setActiveEntry($appId); } diff --git a/lib/public/ipreview.php b/lib/public/ipreview.php index d0a7972714c..fc81da976b9 100644 --- a/lib/public/ipreview.php +++ b/lib/public/ipreview.php @@ -34,6 +34,7 @@ namespace OCP; /** * This class provides functions to render and show thumbnails and previews of files + * @since 6.0.0 */ interface IPreview { /** @@ -45,18 +46,21 @@ interface IPreview { * @param string $mimeTypeRegex Regex with the mime types that are supported by this provider * @param \Closure $callable * @return void + * @since 8.1.0 */ public function registerProvider($mimeTypeRegex, \Closure $callable); /** * Get all providers * @return array + * @since 8.1.0 */ public function getProviders(); /** * Does the manager have any providers * @return bool + * @since 8.1.0 */ public function hasProviders(); @@ -67,6 +71,7 @@ interface IPreview { * @param int $maxY The maximum Y size of the thumbnail. It can be smaller depending on the shape of the image * @param boolean $scaleUp Scale smaller images up to the thumbnail size or not. Might look ugly * @return \OCP\IImage + * @since 6.0.0 */ public function createPreview($file, $maxX = 100, $maxY = 75, $scaleUp = false); @@ -75,6 +80,7 @@ interface IPreview { * Returns true if the passed mime type is supported * @param string $mimeType * @return boolean + * @since 6.0.0 */ public function isMimeSupported($mimeType = '*'); @@ -83,6 +89,7 @@ interface IPreview { * * @param \OCP\Files\FileInfo $file * @return bool + * @since 8.0.0 */ public function isAvailable(\OCP\Files\FileInfo $file); } diff --git a/lib/public/irequest.php b/lib/public/irequest.php index 1b83eaf2c36..a236c5df9a0 100644 --- a/lib/public/irequest.php +++ b/lib/public/irequest.php @@ -58,6 +58,7 @@ namespace OCP; * * @property-read string[] $server * @property-read string[] $urlParams + * @since 6.0.0 */ interface IRequest { @@ -65,6 +66,7 @@ interface IRequest { * @param string $name * * @return string + * @since 6.0.0 */ function getHeader($name); @@ -80,6 +82,7 @@ interface IRequest { * 3. GET parameters * @param mixed $default If the key is not found, this value will be returned * @return mixed the content of the array + * @since 6.0.0 */ public function getParam($key, $default = null); @@ -89,6 +92,7 @@ interface IRequest { * * (as GET or POST) or through the URL by the route * @return array the array with all parameters + * @since 6.0.0 */ public function getParams(); @@ -96,6 +100,7 @@ interface IRequest { * Returns the method of the request * * @return string the method of the request (POST, GET, etc) + * @since 6.0.0 */ public function getMethod(); @@ -104,6 +109,7 @@ interface IRequest { * * @param string $key the key that will be taken from the $_FILES array * @return array the file in the $_FILES element + * @since 6.0.0 */ public function getUploadedFile($key); @@ -113,6 +119,7 @@ interface IRequest { * * @param string $key the key that will be taken from the $_ENV array * @return array the value in the $_ENV element + * @since 6.0.0 */ public function getEnv($key); @@ -122,6 +129,7 @@ interface IRequest { * * @param string $key the key that will be taken from the $_COOKIE array * @return array the value in the $_COOKIE element + * @since 6.0.0 */ function getCookie($key); @@ -129,6 +137,7 @@ interface IRequest { /** * Checks if the CSRF check was correct * @return bool true if CSRF check passed + * @since 6.0.0 */ public function passesCSRFCheck(); @@ -136,6 +145,7 @@ interface IRequest { * Returns an ID for the request, value is not guaranteed to be unique and is mostly meant for logging * If `mod_unique_id` is installed this value will be taken. * @return string + * @since 8.1.0 */ public function getId(); @@ -145,6 +155,7 @@ interface IRequest { * specified in this header will be returned instead. * Do always use this instead of $_SERVER['REMOTE_ADDR'] * @return string IP address + * @since 8.1.0 */ public function getRemoteAddress(); @@ -152,6 +163,7 @@ interface IRequest { * Returns the server protocol. It respects reverse proxy servers and load * balancers. * @return string Server protocol (http or https) + * @since 8.1.0 */ public function getServerProtocol(); @@ -159,6 +171,7 @@ interface IRequest { * Returns the request uri, even if the website uses one or more * reverse proxies * @return string + * @since 8.1.0 */ public function getRequestUri(); @@ -166,6 +179,7 @@ interface IRequest { * Get raw PathInfo from request (not urldecoded) * @throws \Exception * @return string Path info + * @since 8.1.0 */ public function getRawPathInfo(); @@ -173,6 +187,7 @@ interface IRequest { * Get PathInfo from request * @throws \Exception * @return string|false Path info or false when not found + * @since 8.1.0 */ public function getPathInfo(); @@ -180,6 +195,7 @@ interface IRequest { * Returns the script name, even if the website uses one or more * reverse proxies * @return string the script name + * @since 8.1.0 */ public function getScriptName(); @@ -187,6 +203,7 @@ interface IRequest { * Checks whether the user agent matches a given regex * @param array $agent array of agent names * @return bool true if at least one of the given agent matches, false otherwise + * @since 8.1.0 */ public function isUserAgent(array $agent); @@ -194,6 +211,7 @@ interface IRequest { * Returns the unverified server host from the headers without checking * whether it is a trusted domain * @return string Server host + * @since 8.1.0 */ public function getInsecureServerHost(); @@ -201,6 +219,7 @@ interface IRequest { * Returns the server host from the headers, or the first configured * trusted domain if the host isn't in the trusted list * @return string Server host + * @since 8.1.0 */ public function getServerHost(); } diff --git a/lib/public/isearch.php b/lib/public/isearch.php index fe25d5b49f7..bb7ada86e31 100644 --- a/lib/public/isearch.php +++ b/lib/public/isearch.php @@ -28,6 +28,7 @@ namespace OCP; /** * Small Interface for Search + * @since 7.0.0 */ interface ISearch { @@ -37,6 +38,7 @@ interface ISearch { * @param string[] $inApps optionally limit results to the given apps * @return array An array of OCP\Search\Result's * @deprecated use searchPaged() with page and size + * @since 7.0.0 - parameter $inApps was added in 8.0.0 */ public function search($query, array $inApps = array()); @@ -47,6 +49,7 @@ interface ISearch { * @param int $page pages start at page 1 * @param int $size * @return array An array of OCP\Search\Result's + * @since 8.0.0 */ public function searchPaged($query, array $inApps = array(), $page = 1, $size = 30); @@ -54,17 +57,20 @@ interface ISearch { * Register a new search provider to search with * @param string $class class name of a OCP\Search\Provider * @param array $options optional + * @since 7.0.0 */ public function registerProvider($class, array $options = array()); /** * Remove one existing search provider * @param string $provider class name of a OCP\Search\Provider + * @since 7.0.0 */ public function removeProvider($provider); /** * Remove all registered search providers + * @since 7.0.0 */ public function clearProviders(); diff --git a/lib/public/iservercontainer.php b/lib/public/iservercontainer.php index dd0d2f417cf..7eb753b3fff 100644 --- a/lib/public/iservercontainer.php +++ b/lib/public/iservercontainer.php @@ -44,6 +44,7 @@ namespace OCP; * @package OCP * * This container holds all ownCloud services + * @since 6.0.0 */ interface IServerContainer { @@ -52,6 +53,7 @@ interface IServerContainer { * providers which actual deliver the contact information. * * @return \OCP\Contacts\IManager + * @since 6.0.0 */ function getContactsManager(); @@ -61,6 +63,7 @@ interface IServerContainer { * In case the current execution was not initiated by a web request null is returned * * @return \OCP\IRequest + * @since 6.0.0 */ function getRequest(); @@ -68,6 +71,7 @@ interface IServerContainer { * Returns the preview manager which can create preview images for a given file * * @return \OCP\IPreview + * @since 6.0.0 */ function getPreviewManager(); @@ -76,6 +80,7 @@ interface IServerContainer { * * @see \OCP\ITagManager::load() * @return \OCP\ITagManager + * @since 6.0.0 */ function getTagManager(); @@ -83,6 +88,7 @@ interface IServerContainer { * Returns the root folder of ownCloud's data directory * * @return \OCP\Files\Folder + * @since 6.0.0 */ function getRootFolder(); @@ -91,6 +97,7 @@ interface IServerContainer { * * @param string $userId user ID * @return \OCP\Files\Folder + * @since 6.0.0 - parameter $userId was added in 8.0.0 */ function getUserFolder($userId = null); @@ -98,6 +105,7 @@ interface IServerContainer { * Returns an app-specific view in ownClouds data directory * * @return \OCP\Files\Folder + * @since 6.0.0 */ function getAppFolder(); @@ -105,6 +113,7 @@ interface IServerContainer { * Returns a user manager * * @return \OCP\IUserManager + * @since 8.0.0 */ function getUserManager(); @@ -112,6 +121,7 @@ interface IServerContainer { * Returns a group manager * * @return \OCP\IGroupManager + * @since 8.0.0 */ function getGroupManager(); @@ -119,6 +129,7 @@ interface IServerContainer { * Returns the user session * * @return \OCP\IUserSession + * @since 6.0.0 */ function getUserSession(); @@ -126,6 +137,7 @@ interface IServerContainer { * Returns the navigation manager * * @return \OCP\INavigationManager + * @since 6.0.0 */ function getNavigationManager(); @@ -133,6 +145,7 @@ interface IServerContainer { * Returns the config manager * * @return \OCP\IConfig + * @since 6.0.0 */ function getConfig(); @@ -140,6 +153,7 @@ interface IServerContainer { * Returns a Crypto instance * * @return \OCP\Security\ICrypto + * @since 8.0.0 */ function getCrypto(); @@ -147,6 +161,7 @@ interface IServerContainer { * Returns a Hasher instance * * @return \OCP\Security\IHasher + * @since 8.0.0 */ function getHasher(); @@ -154,6 +169,7 @@ interface IServerContainer { * Returns a SecureRandom instance * * @return \OCP\Security\ISecureRandom + * @since 8.1.0 */ function getSecureRandom(); @@ -161,6 +177,7 @@ interface IServerContainer { * Returns an instance of the db facade * @deprecated use getDatabaseConnection, will be removed in ownCloud 10 * @return \OCP\IDb + * @since 7.0.0 */ function getDb(); @@ -168,6 +185,7 @@ interface IServerContainer { * Returns the app config manager * * @return \OCP\IAppConfig + * @since 7.0.0 */ function getAppConfig(); @@ -176,16 +194,19 @@ interface IServerContainer { * @param string $app appid * @param string $lang * @return \OCP\IL10N + * @since 6.0.0 - parameter $lang was added in 8.0.0 */ function getL10N($app, $lang = null); /** * @return \OC\Encryption\Manager + * @since 8.1.0 */ function getEncryptionManager(); /** * @return \OC\Encryption\File + * @since 8.1.0 */ function getEncryptionFilesHelper(); @@ -193,6 +214,7 @@ interface IServerContainer { * @param string $encryptionModuleId encryption module ID * * @return \OCP\Encryption\Keys\IStorage + * @since 8.1.0 */ function getEncryptionKeyStorage($encryptionModuleId); @@ -200,6 +222,7 @@ interface IServerContainer { * Returns the URL generator * * @return \OCP\IURLGenerator + * @since 6.0.0 */ function getURLGenerator(); @@ -207,6 +230,7 @@ interface IServerContainer { * Returns the Helper * * @return \OCP\IHelper + * @since 6.0.0 */ function getHelper(); @@ -214,6 +238,7 @@ interface IServerContainer { * Returns an ICache instance * * @return \OCP\ICache + * @since 6.0.0 */ function getCache(); @@ -221,6 +246,7 @@ interface IServerContainer { * Returns an \OCP\CacheFactory instance * * @return \OCP\ICacheFactory + * @since 7.0.0 */ function getMemCacheFactory(); @@ -228,6 +254,7 @@ interface IServerContainer { * Returns the current session * * @return \OCP\ISession + * @since 6.0.0 */ function getSession(); @@ -235,6 +262,7 @@ interface IServerContainer { * Returns the activity manager * * @return \OCP\Activity\IManager + * @since 6.0.0 */ function getActivityManager(); @@ -242,6 +270,7 @@ interface IServerContainer { * Returns the current session * * @return \OCP\IDBConnection + * @since 6.0.0 */ function getDatabaseConnection(); @@ -249,6 +278,7 @@ interface IServerContainer { * Returns an avatar manager, used for avatar functionality * * @return \OCP\IAvatarManager + * @since 6.0.0 */ function getAvatarManager(); @@ -256,6 +286,7 @@ interface IServerContainer { * Returns an job list for controlling background jobs * * @return \OCP\BackgroundJob\IJobList + * @since 7.0.0 */ function getJobList(); @@ -263,6 +294,7 @@ interface IServerContainer { * Returns a logger instance * * @return \OCP\ILogger + * @since 8.0.0 */ function getLogger(); @@ -270,6 +302,7 @@ interface IServerContainer { * Returns a router for generating and matching urls * * @return \OCP\Route\IRouter + * @since 7.0.0 */ function getRouter(); @@ -277,6 +310,7 @@ interface IServerContainer { * Returns a search instance * * @return \OCP\ISearch + * @since 7.0.0 */ function getSearch(); @@ -285,6 +319,7 @@ interface IServerContainer { * * @param \OCP\IUser $user (optional) if not specified the current loggedin user is used * @return \OCP\ICertificateManager + * @since 8.0.0 */ function getCertificateManager($user = null); @@ -292,6 +327,7 @@ interface IServerContainer { * Create a new event source * * @return \OCP\IEventSource + * @since 8.0.0 */ function createEventSource(); @@ -299,6 +335,7 @@ interface IServerContainer { * Returns an instance of the HTTP helper class * @return \OC\HTTPHelper * @deprecated Use \OCP\Http\Client\IClientService + * @since 8.0.0 */ function getHTTPHelper(); @@ -306,6 +343,7 @@ interface IServerContainer { * Returns an instance of the HTTP client service * * @return \OCP\Http\Client\IClientService + * @since 8.1.0 */ function getHTTPClientService(); @@ -313,6 +351,7 @@ interface IServerContainer { * Get the active event logger * * @return \OCP\Diagnostics\IEventLogger + * @since 8.0.0 */ function getEventLogger(); @@ -322,6 +361,7 @@ interface IServerContainer { * The returned logger only logs data when debug mode is enabled * * @return \OCP\Diagnostics\IQueryLogger + * @since 8.0.0 */ function getQueryLogger(); @@ -329,6 +369,7 @@ interface IServerContainer { * Get the manager for temporary files and folders * * @return \OCP\ITempManager + * @since 8.0.0 */ function getTempManager(); @@ -336,6 +377,7 @@ interface IServerContainer { * Get the app manager * * @return \OCP\App\IAppManager + * @since 8.0.0 */ function getAppManager(); @@ -343,11 +385,13 @@ interface IServerContainer { * Get the webroot * * @return string + * @since 8.0.0 */ function getWebRoot(); /** * @return \OCP\Files\Config\IMountProviderCollection + * @since 8.0.0 */ function getMountProviderCollection(); @@ -355,10 +399,12 @@ interface IServerContainer { * Get the IniWrapper * * @return \bantu\IniGetWrapper\IniGetWrapper + * @since 8.0.0 */ function getIniWrapper(); /** * @return \OCP\Command\IBus + * @since 8.1.0 */ function getCommandBus(); @@ -366,6 +412,7 @@ interface IServerContainer { * Creates a new mailer * * @return \OCP\Mail\IMailer + * @since 8.1.0 */ function getMailer(); } diff --git a/lib/public/isession.php b/lib/public/isession.php index 9a996455f6b..aee635d7a9d 100644 --- a/lib/public/isession.php +++ b/lib/public/isession.php @@ -35,6 +35,7 @@ namespace OCP; * Interface ISession * * wrap PHP's internal session handling into the ISession interface + * @since 6.0.0 */ interface ISession { @@ -43,6 +44,7 @@ interface ISession { * * @param string $key * @param mixed $value + * @since 6.0.0 */ public function set($key, $value); @@ -51,6 +53,7 @@ interface ISession { * * @param string $key * @return mixed should return null if $key does not exist + * @since 6.0.0 */ public function get($key); @@ -59,6 +62,7 @@ interface ISession { * * @param string $key * @return bool + * @since 6.0.0 */ public function exists($key); @@ -66,16 +70,19 @@ interface ISession { * Remove a $key/$value pair from the session * * @param string $key + * @since 6.0.0 */ public function remove($key); /** * Reset and recreate the session + * @since 6.0.0 */ public function clear(); /** * Close the session and release the lock + * @since 7.0.0 */ public function close(); diff --git a/lib/public/itagmanager.php b/lib/public/itagmanager.php index af980d29dab..5ed005548d3 100644 --- a/lib/public/itagmanager.php +++ b/lib/public/itagmanager.php @@ -41,19 +41,21 @@ namespace OCP; * Tag names are not case-sensitive, but will be saved with the case they * are entered in. If a user already has a tag 'family' for a type, and * tries to add a tag named 'Family' it will be silently ignored. + * @since 6.0.0 */ interface ITagManager { /** - * Create a new \OCP\ITags instance and load tags from db for the current user. - * - * @see \OCP\ITags - * @param string $type The type identifier e.g. 'contact' or 'event'. - * @param array $defaultTags An array of default tags to be used if none are stored. - * @param boolean $includeShared Whether to include tags for items shared with this user by others. - * @param string $userId user for which to retrieve the tags, defaults to the currently - * logged in user - * @return \OCP\ITags + * Create a new \OCP\ITags instance and load tags from db for the current user. + * + * @see \OCP\ITags + * @param string $type The type identifier e.g. 'contact' or 'event'. + * @param array $defaultTags An array of default tags to be used if none are stored. + * @param boolean $includeShared Whether to include tags for items shared with this user by others. + * @param string $userId user for which to retrieve the tags, defaults to the currently + * logged in user + * @return \OCP\ITags + * @since 6.0.0 - parameter $includeShared and $userId were added in 8.0.0 */ public function load($type, $defaultTags = array(), $includeShared = false, $userId = null); } diff --git a/lib/public/itags.php b/lib/public/itags.php index 7a9b1e556ea..7faeb619fde 100644 --- a/lib/public/itags.php +++ b/lib/public/itags.php @@ -47,37 +47,41 @@ namespace OCP; * Tag names are not case-sensitive, but will be saved with the case they * are entered in. If a user already has a tag 'family' for a type, and * tries to add a tag named 'Family' it will be silently ignored. + * @since 6.0.0 */ interface ITags { /** - * Check if any tags are saved for this type and user. - * - * @return boolean - */ + * Check if any tags are saved for this type and user. + * + * @return boolean + * @since 6.0.0 + */ public function isEmpty(); /** - * Returns an array mapping a given tag's properties to its values: - * ['id' => 0, 'name' = 'Tag', 'owner' = 'User', 'type' => 'tagtype'] - * - * @param string $id The ID of the tag that is going to be mapped - * @return array|false - */ + * Returns an array mapping a given tag's properties to its values: + * ['id' => 0, 'name' = 'Tag', 'owner' = 'User', 'type' => 'tagtype'] + * + * @param string $id The ID of the tag that is going to be mapped + * @return array|false + * @since 8.0.0 + */ public function getTag($id); /** - * Get the tags for a specific user. - * - * This returns an array with id/name maps: - * [ - * ['id' => 0, 'name' = 'First tag'], - * ['id' => 1, 'name' = 'Second tag'], - * ] - * - * @return array - */ + * Get the tags for a specific user. + * + * This returns an array with id/name maps: + * [ + * ['id' => 0, 'name' = 'First tag'], + * ['id' => 1, 'name' = 'Second tag'], + * ] + * + * @return array + * @since 6.0.0 + */ public function getTags(); /** @@ -93,120 +97,134 @@ interface ITags { * @param array $objIds item ids * @return array|boolean with object id as key and an array * of tag names as value or false if an error occurred + * @since 8.0.0 */ public function getTagsForObjects(array $objIds); /** - * Get a list of items tagged with $tag. - * - * Throws an exception if the tag could not be found. - * - * @param string|integer $tag Tag id or name. - * @return array|false An array of object ids or false on error. - */ + * Get a list of items tagged with $tag. + * + * Throws an exception if the tag could not be found. + * + * @param string|integer $tag Tag id or name. + * @return array|false An array of object ids or false on error. + * @since 6.0.0 + */ public function getIdsForTag($tag); /** - * Checks whether a tag is already saved. - * - * @param string $name The name to check for. - * @return bool - */ + * Checks whether a tag is already saved. + * + * @param string $name The name to check for. + * @return bool + * @since 6.0.0 + */ public function hasTag($name); /** - * Checks whether a tag is saved for the given user, - * disregarding the ones shared with him or her. - * - * @param string $name The tag name to check for. - * @param string $user The user whose tags are to be checked. - * @return bool - */ + * Checks whether a tag is saved for the given user, + * disregarding the ones shared with him or her. + * + * @param string $name The tag name to check for. + * @param string $user The user whose tags are to be checked. + * @return bool + * @since 8.0.0 + */ public function userHasTag($name, $user); /** - * Add a new tag. - * - * @param string $name A string with a name of the tag - * @return int|false the id of the added tag or false if it already exists. - */ + * Add a new tag. + * + * @param string $name A string with a name of the tag + * @return int|false the id of the added tag or false if it already exists. + * @since 6.0.0 + */ public function add($name); /** - * Rename tag. - * - * @param string|integer $from The name or ID of the existing tag - * @param string $to The new name of the tag. - * @return bool - */ + * Rename tag. + * + * @param string|integer $from The name or ID of the existing tag + * @param string $to The new name of the tag. + * @return bool + * @since 6.0.0 + */ public function rename($from, $to); /** - * Add a list of new tags. - * - * @param string[] $names A string with a name or an array of strings containing - * the name(s) of the to add. - * @param bool $sync When true, save the tags - * @param int|null $id int Optional object id to add to this|these tag(s) - * @return bool Returns false on error. - */ + * Add a list of new tags. + * + * @param string[] $names A string with a name or an array of strings containing + * the name(s) of the to add. + * @param bool $sync When true, save the tags + * @param int|null $id int Optional object id to add to this|these tag(s) + * @return bool Returns false on error. + * @since 6.0.0 + */ public function addMultiple($names, $sync=false, $id = null); /** - * Delete tag/object relations from the db - * - * @param array $ids The ids of the objects - * @return boolean Returns false on error. - */ + * Delete tag/object relations from the db + * + * @param array $ids The ids of the objects + * @return boolean Returns false on error. + * @since 6.0.0 + */ public function purgeObjects(array $ids); /** - * Get favorites for an object type - * - * @return array|false An array of object ids. - */ + * Get favorites for an object type + * + * @return array|false An array of object ids. + * @since 6.0.0 + */ public function getFavorites(); /** - * Add an object to favorites - * - * @param int $objid The id of the object - * @return boolean - */ + * Add an object to favorites + * + * @param int $objid The id of the object + * @return boolean + * @since 6.0.0 + */ public function addToFavorites($objid); /** - * Remove an object from favorites - * - * @param int $objid The id of the object - * @return boolean - */ + * Remove an object from favorites + * + * @param int $objid The id of the object + * @return boolean + * @since 6.0.0 + */ public function removeFromFavorites($objid); /** - * Creates a tag/object relation. - * - * @param int $objid The id of the object - * @param string $tag The id or name of the tag - * @return boolean Returns false on database error. - */ + * Creates a tag/object relation. + * + * @param int $objid The id of the object + * @param string $tag The id or name of the tag + * @return boolean Returns false on database error. + * @since 6.0.0 + */ public function tagAs($objid, $tag); /** - * Delete single tag/object relation from the db - * - * @param int $objid The id of the object - * @param string $tag The id or name of the tag - * @return boolean - */ + * Delete single tag/object relation from the db + * + * @param int $objid The id of the object + * @param string $tag The id or name of the tag + * @return boolean + * @since 6.0.0 + */ public function unTag($objid, $tag); /** - * Delete tags from the database - * - * @param string[]|integer[] $names An array of tags (names or IDs) to delete - * @return bool Returns false on error - */ + * Delete tags from the database + * + * @param string[]|integer[] $names An array of tags (names or IDs) to delete + * @return bool Returns false on error + * @since 6.0.0 + */ public function delete($names); } diff --git a/lib/public/itempmanager.php b/lib/public/itempmanager.php index ac67a852a31..7ba5b1e7bff 100644 --- a/lib/public/itempmanager.php +++ b/lib/public/itempmanager.php @@ -22,12 +22,19 @@ namespace OCP; +/** + * Interface ITempManager + * + * @package OCP + * @since 8.0.0 + */ interface ITempManager { /** * Create a temporary file and return the path * * @param string $postFix * @return string + * @since 8.0.0 */ public function getTemporaryFile($postFix = ''); @@ -36,16 +43,19 @@ interface ITempManager { * * @param string $postFix * @return string + * @since 8.0.0 */ public function getTemporaryFolder($postFix = ''); /** * Remove the temporary files and folders generated during this request + * @since 8.0.0 */ public function clean(); /** * Remove old temporary files and folders that were failed to be cleaned + * @since 8.0.0 */ public function cleanOld(); } diff --git a/lib/public/iurlgenerator.php b/lib/public/iurlgenerator.php index 57bf73f9d24..4324a4b5a97 100644 --- a/lib/public/iurlgenerator.php +++ b/lib/public/iurlgenerator.php @@ -34,6 +34,7 @@ namespace OCP; /** * Class to generate URLs + * @since 6.0.0 */ interface IURLGenerator { /** @@ -41,6 +42,7 @@ interface IURLGenerator { * @param string $routeName the name of the route * @param array $arguments an array with arguments which will be filled into the url * @return string the url + * @since 6.0.0 */ public function linkToRoute($routeName, $arguments = array()); @@ -49,6 +51,7 @@ interface IURLGenerator { * @param string $routeName the name of the route * @param array $arguments an array with arguments which will be filled into the url * @return string the absolute url + * @since 8.0.0 */ public function linkToRouteAbsolute($routeName, $arguments = array()); @@ -57,6 +60,7 @@ interface IURLGenerator { * @param string $appName the name of the app * @param string $file the name of the file * @return string the url + * @since 6.0.0 */ public function linkTo($appName, $file); @@ -65,6 +69,7 @@ interface IURLGenerator { * @param string $appName the name of the app * @param string $file the name of the file * @return string the url + * @since 6.0.0 */ public function imagePath($appName, $file); @@ -73,12 +78,14 @@ interface IURLGenerator { * Makes an URL absolute * @param string $url the url in the ownCloud host * @return string the absolute version of the url + * @since 6.0.0 */ public function getAbsoluteURL($url); /** * @param string $key * @return string url to the online documentation + * @since 8.0.0 */ public function linkToDocs($key); } diff --git a/lib/public/iuser.php b/lib/public/iuser.php index 9f75b8145f0..393ab90d260 100644 --- a/lib/public/iuser.php +++ b/lib/public/iuser.php @@ -24,11 +24,18 @@ namespace OCP; +/** + * Interface IUser + * + * @package OCP + * @since 8.0.0 + */ interface IUser { /** * get the user id * * @return string + * @since 8.0.0 */ public function getUID(); @@ -36,6 +43,7 @@ interface IUser { * get the display name for the user, if no specific display name is set it will fallback to the user id * * @return string + * @since 8.0.0 */ public function getDisplayName(); @@ -44,6 +52,7 @@ interface IUser { * * @param string $displayName * @return bool + * @since 8.0.0 */ public function setDisplayName($displayName); @@ -52,11 +61,13 @@ interface IUser { * login * * @return int + * @since 8.0.0 */ public function getLastLogin(); /** * updates the timestamp of the most recent login of this user + * @since 8.0.0 */ public function updateLastLoginTimestamp(); @@ -64,6 +75,7 @@ interface IUser { * Delete the user * * @return bool + * @since 8.0.0 */ public function delete(); @@ -73,6 +85,7 @@ interface IUser { * @param string $password * @param string $recoveryPassword for the encryption app to reset encryption keys * @return bool + * @since 8.0.0 */ public function setPassword($password, $recoveryPassword = null); @@ -87,6 +100,7 @@ interface IUser { * Get the name of the backend class the user is connected with * * @return string + * @since 8.0.0 */ public function getBackendClassName(); @@ -94,6 +108,7 @@ interface IUser { * check if the backend allows the user to change his avatar on Personal page * * @return bool + * @since 8.0.0 */ public function canChangeAvatar(); @@ -108,6 +123,7 @@ interface IUser { * check if the backend supports changing display names * * @return bool + * @since 8.0.0 */ public function canChangeDisplayName(); @@ -115,6 +131,7 @@ interface IUser { * check if the user is enabled * * @return bool + * @since 8.0.0 */ public function isEnabled(); @@ -122,6 +139,7 @@ interface IUser { * set the enabled status for the user * * @param bool $enabled + * @since 8.0.0 */ public function setEnabled($enabled); } diff --git a/lib/public/iuserbackend.php b/lib/public/iuserbackend.php index 64035bf7acd..2c472596b77 100644 --- a/lib/public/iuserbackend.php +++ b/lib/public/iuserbackend.php @@ -29,11 +29,18 @@ // This means that they should be used by apps instead of the internal ownCloud classes namespace OCP; +/** + * Interface IUserBackend + * + * @package OCP + * @since 8.0.0 + */ interface IUserBackend { /** * Backend name to be shown in user management * @return string the name of the backend to be shown + * @since 8.0.0 */ public function getBackendName(); diff --git a/lib/public/iusermanager.php b/lib/public/iusermanager.php index df0975b70a0..23fb84e6ada 100644 --- a/lib/public/iusermanager.php +++ b/lib/public/iusermanager.php @@ -36,18 +36,21 @@ namespace OCP; * - postCreateUser(\OC\User\User $user, string $password) * * @package OC\User + * @since 8.0.0 */ interface IUserManager { /** * register a user backend * * @param \OCP\UserInterface $backend + * @since 8.0.0 */ public function registerBackend($backend); /** * Get the active backends * @return \OCP\UserInterface[] + * @since 8.0.0 */ public function getBackends(); @@ -55,6 +58,7 @@ interface IUserManager { * remove a user backend * * @param \OCP\UserInterface $backend + * @since 8.0.0 */ public function removeBackend($backend); @@ -68,6 +72,7 @@ interface IUserManager { * * @param string $uid * @return \OCP\IUser|null Either the user or null if the specified user does not exist + * @since 8.0.0 */ public function get($uid); @@ -76,6 +81,7 @@ interface IUserManager { * * @param string $uid * @return bool + * @since 8.0.0 */ public function userExists($uid); @@ -85,6 +91,7 @@ interface IUserManager { * @param string $loginname * @param string $password * @return mixed the User object on success, false otherwise + * @since 8.0.0 */ public function checkPassword($loginname, $password); @@ -95,6 +102,7 @@ interface IUserManager { * @param int $limit * @param int $offset * @return \OCP\IUser[] + * @since 8.0.0 */ public function search($pattern, $limit = null, $offset = null); @@ -105,6 +113,7 @@ interface IUserManager { * @param int $limit * @param int $offset * @return \OCP\IUser[] + * @since 8.0.0 */ public function searchDisplayName($pattern, $limit = null, $offset = null); @@ -113,6 +122,7 @@ interface IUserManager { * @param string $password * @throws \Exception * @return bool|\OCP\IUser the created user of false + * @since 8.0.0 */ public function createUser($uid, $password); @@ -120,6 +130,7 @@ interface IUserManager { * returns how many users per backend exist (if supported by backend) * * @return array an array of backend class as key and count number as value + * @since 8.0.0 */ public function countUsers(); } diff --git a/lib/public/iusersession.php b/lib/public/iusersession.php index ec0978ab8a3..2dde25634d6 100644 --- a/lib/public/iusersession.php +++ b/lib/public/iusersession.php @@ -36,6 +36,7 @@ namespace OCP; /** * User session + * @since 6.0.0 */ interface IUserSession { /** @@ -43,6 +44,7 @@ interface IUserSession { * @param string $user the username * @param string $password the password * @return bool true if successful + * @since 6.0.0 */ public function login($user, $password); @@ -50,6 +52,7 @@ interface IUserSession { * Logs the user out including all the session data * Logout, destroys session * @return void + * @since 6.0.0 */ public function logout(); @@ -57,6 +60,7 @@ interface IUserSession { * set the currently active user * * @param \OCP\IUser|null $user + * @since 8.0.0 */ public function setUser($user); @@ -64,6 +68,7 @@ interface IUserSession { * get the current active user * * @return \OCP\IUser|null Current user, otherwise null + * @since 8.0.0 */ public function getUser(); @@ -71,6 +76,7 @@ interface IUserSession { * Checks whether the user is logged in * * @return bool if logged in + * @since 8.0.0 */ public function isLoggedIn(); } diff --git a/lib/public/mail/imailer.php b/lib/public/mail/imailer.php index 806a3d23150..9580104a8bf 100644 --- a/lib/public/mail/imailer.php +++ b/lib/public/mail/imailer.php @@ -39,12 +39,14 @@ use OC\Mail\Message; * This message can then be passed to send() of \OC\Mail\Mailer * * @package OCP\Mail + * @since 8.1.0 */ interface IMailer { /** * Creates a new message object that can be passed to send() * * @return Message + * @since 8.1.0 */ public function createMessage(); @@ -57,6 +59,7 @@ interface IMailer { * therefore should be considered * @throws \Exception In case it was not possible to send the message. (for example if an invalid mail address * has been supplied.) + * @since 8.1.0 */ public function send(Message $message); @@ -65,6 +68,7 @@ interface IMailer { * * @param string $email Email address to be validated * @return bool True if the mail address is valid, false otherwise + * @since 8.1.0 */ public function validateMailAddress($email); } diff --git a/lib/public/preconditionnotmetexception.php b/lib/public/preconditionnotmetexception.php index 4622da80c9b..6f1b683526d 100644 --- a/lib/public/preconditionnotmetexception.php +++ b/lib/public/preconditionnotmetexception.php @@ -25,5 +25,6 @@ namespace OCP; /** * Exception if the precondition of the config update method isn't met + * @since 8.0.0 */ class PreConditionNotMetException extends \Exception {} diff --git a/lib/public/preview/iprovider.php b/lib/public/preview/iprovider.php index e176aa94fca..1a581768ad4 100644 --- a/lib/public/preview/iprovider.php +++ b/lib/public/preview/iprovider.php @@ -20,9 +20,16 @@ */ namespace OCP\Preview; +/** + * Interface IProvider + * + * @package OCP\Preview + * @since 8.1.0 + */ interface IProvider { /** * @return string Regex with the mimetypes that are supported by this provider + * @since 8.1.0 */ public function getMimeType(); @@ -31,6 +38,7 @@ interface IProvider { * * @param \OCP\Files\FileInfo $file * @return bool + * @since 8.1.0 */ public function isAvailable(\OCP\Files\FileInfo $file); @@ -43,6 +51,7 @@ interface IProvider { * @param bool $scalingup Disable/Enable upscaling of previews * @param \OC\Files\View $fileview fileview object of user folder * @return bool|\OCP\IImage false if no preview was generated + * @since 8.1.0 */ public function getThumbnail($path, $maxX, $maxY, $scalingup, $fileview); } diff --git a/lib/public/response.php b/lib/public/response.php index d4d32e89ab7..1942c1ec373 100644 --- a/lib/public/response.php +++ b/lib/public/response.php @@ -36,6 +36,7 @@ namespace OCP; /** * This class provides convenient functions to send the correct http response headers + * @since 4.0.0 */ class Response { /** @@ -44,6 +45,7 @@ class Response { * >0 cache time in seconds * 0 and <0 enable default browser caching * null cache indefinitly + * @since 4.0.0 */ static public function enableCaching( $cache_time = null ) { \OC_Response::enableCaching( $cache_time ); @@ -53,6 +55,7 @@ class Response { * Checks and set Last-Modified header, when the request matches sends a * 'not modified' response * @param string $lastModified time when the reponse was last modified + * @since 4.0.0 */ static public function setLastModifiedHeader( $lastModified ) { \OC_Response::setLastModifiedHeader( $lastModified ); @@ -62,6 +65,7 @@ class Response { * Sets the content disposition header (with possible workarounds) * @param string $filename file name * @param string $type disposition type, either 'attachment' or 'inline' + * @since 7.0.0 */ static public function setContentDispositionHeader( $filename, $type = 'attachment' ) { \OC_Response::setContentDispositionHeader( $filename, $type ); @@ -70,6 +74,7 @@ class Response { /** * Sets the content length header (with possible workarounds) * @param string|int|float $length Length to be sent + * @since 8.1.0 */ static public function setContentLengthHeader($length) { \OC_Response::setContentLengthHeader($length); @@ -78,6 +83,7 @@ class Response { /** * Disable browser caching * @see enableCaching with cache_time = 0 + * @since 4.0.0 */ static public function disableCaching() { \OC_Response::disableCaching(); @@ -87,6 +93,7 @@ class Response { * Checks and set ETag header, when the request matches sends a * 'not modified' response * @param string $etag token to use for modification check + * @since 4.0.0 */ static public function setETagHeader( $etag ) { \OC_Response::setETagHeader( $etag ); @@ -95,6 +102,7 @@ class Response { /** * Send file as response, checking and setting caching headers * @param string $filepath of file to send + * @since 4.0.0 */ static public function sendFile( $filepath ) { \OC_Response::sendFile( $filepath ); @@ -105,6 +113,7 @@ class Response { * @param string|\DateTime $expires date-time when the response expires * string for DateInterval from now * DateTime object when to expire response + * @since 4.0.0 */ static public function setExpiresHeader( $expires ) { \OC_Response::setExpiresHeader( $expires ); @@ -113,6 +122,7 @@ class Response { /** * Send redirect response * @param string $location to redirect to + * @since 4.0.0 */ static public function redirect( $location ) { \OC_Response::redirect( $location ); diff --git a/lib/public/route/iroute.php b/lib/public/route/iroute.php index ec770e9845d..4c9b4ca9b47 100644 --- a/lib/public/route/iroute.php +++ b/lib/public/route/iroute.php @@ -23,10 +23,17 @@ */ namespace OCP\Route; +/** + * Interface IRoute + * + * @package OCP\Route + * @since 7.0.0 + */ interface IRoute { /** * Specify PATCH as the method to use with this route * @return \OCP\Route\IRoute + * @since 7.0.0 */ public function patch(); @@ -35,6 +42,7 @@ interface IRoute { * * @param string $method HTTP method (uppercase) * @return \OCP\Route\IRoute + * @since 7.0.0 */ public function method($method); @@ -44,24 +52,28 @@ interface IRoute { * * @param string $file * @return void + * @since 7.0.0 */ public function actionInclude($file); /** * Specify GET as the method to use with this route * @return \OCP\Route\IRoute + * @since 7.0.0 */ public function get(); /** * Specify POST as the method to use with this route * @return \OCP\Route\IRoute + * @since 7.0.0 */ public function post(); /** * Specify DELETE as the method to use with this route * @return \OCP\Route\IRoute + * @since 7.0.0 */ public function delete(); @@ -74,6 +86,7 @@ interface IRoute { * * This function is called with $class set to a callable or * to the class with $function + * @since 7.0.0 */ public function action($class, $function = null); @@ -82,6 +95,7 @@ interface IRoute { * * @param array $defaults The defaults * @return \OCP\Route\IRoute + * @since 7.0.0 */ public function defaults($defaults); @@ -90,12 +104,14 @@ interface IRoute { * * @param array $requirements The requirements * @return \OCP\Route\IRoute + * @since 7.0.0 */ public function requirements($requirements); /** * Specify PUT as the method to use with this route * @return \OCP\Route\IRoute + * @since 7.0.0 */ public function put(); } diff --git a/lib/public/route/irouter.php b/lib/public/route/irouter.php index fbbcdcbb1af..3f5b58ac416 100644 --- a/lib/public/route/irouter.php +++ b/lib/public/route/irouter.php @@ -24,23 +24,32 @@ namespace OCP\Route; +/** + * Interface IRouter + * + * @package OCP\Route + * @since 7.0.0 + */ interface IRouter { /** * Get the files to load the routes from * * @return string[] + * @since 7.0.0 */ public function getRoutingFiles(); /** * @return string + * @since 7.0.0 */ public function getCacheKey(); /** * loads the api routes * @return void + * @since 7.0.0 */ public function loadRoutes($app = null); @@ -49,6 +58,7 @@ interface IRouter { * * @param string $name Name of the collection to use. * @return void + * @since 7.0.0 */ public function useCollection($name); @@ -56,6 +66,7 @@ interface IRouter { * returns the current collection name in use for adding routes * * @return string the collection name + * @since 8.0.0 */ public function getCurrentCollection(); @@ -67,6 +78,7 @@ interface IRouter { * @param array $defaults An array of default parameter values * @param array $requirements An array of requirements for parameters (regexes) * @return \OCP\Route\IRoute + * @since 7.0.0 */ public function create($name, $pattern, array $defaults = array(), array $requirements = array()); @@ -76,12 +88,14 @@ interface IRouter { * @param string $url The url to find * @throws \Exception * @return void + * @since 7.0.0 */ public function match($url); /** * Get the url generator * + * @since 7.0.0 */ public function getGenerator(); @@ -92,6 +106,7 @@ interface IRouter { * @param array $parameters Parameters for the route * @param bool $absolute * @return string + * @since 7.0.0 */ public function generate($name, $parameters = array(), $absolute = false); diff --git a/lib/public/search/pagedprovider.php b/lib/public/search/pagedprovider.php index 1ba1459604a..7452bbd47bb 100644 --- a/lib/public/search/pagedprovider.php +++ b/lib/public/search/pagedprovider.php @@ -23,18 +23,21 @@ namespace OCP\Search; /** - * Provides a template for search functionality throughout ownCloud; + * Provides a template for search functionality throughout ownCloud; + * @since 8.0.0 */ abstract class PagedProvider extends Provider { /** * show all results + * @since 8.0.0 */ const SIZE_ALL = 0; /** * Constructor * @param array $options + * @since 8.0.0 */ public function __construct($options) { $this->options = $options; @@ -44,6 +47,7 @@ abstract class PagedProvider extends Provider { * Search for $query * @param string $query * @return array An array of OCP\Search\Result's + * @since 8.0.0 */ public function search($query) { // old apps might assume they get all results, so we use SIZE_ALL @@ -56,6 +60,7 @@ abstract class PagedProvider extends Provider { * @param int $page pages start at page 1 * @param int $size, 0 = SIZE_ALL * @return array An array of OCP\Search\Result's + * @since 8.0.0 */ abstract public function searchPaged($query, $page, $size); } diff --git a/lib/public/search/provider.php b/lib/public/search/provider.php index 6746bf14824..2f2cd03eb6a 100644 --- a/lib/public/search/provider.php +++ b/lib/public/search/provider.php @@ -26,21 +26,27 @@ namespace OCP\Search; /** - * Provides a template for search functionality throughout ownCloud; + * Provides a template for search functionality throughout ownCloud; + * @since 7.0.0 */ abstract class Provider { + /** + * @since 8.0.0 + */ const OPTION_APPS = 'apps'; /** * List of options * @var array + * @since 7.0.0 */ protected $options; /** * Constructor * @param array $options as key => value + * @since 7.0.0 - default value for $options was added in 8.0.0 */ public function __construct($options = array()) { $this->options = $options; @@ -50,6 +56,7 @@ abstract class Provider { * get a value from the options array or null * @param string $key * @return mixed + * @since 8.0.0 */ public function getOption($key) { if (is_array($this->options) && isset($this->options[$key])) { @@ -66,6 +73,7 @@ abstract class Provider { * or if the two above arrays have elements in common (intersect) * @param string[] $apps * @return bool + * @since 8.0.0 */ public function providesResultsFor(array $apps = array()) { $forApps = $this->getOption(self::OPTION_APPS); @@ -76,6 +84,7 @@ abstract class Provider { * Search for $query * @param string $query * @return array An array of OCP\Search\Result's + * @since 7.0.0 */ abstract public function search($query); } diff --git a/lib/public/search/result.php b/lib/public/search/result.php index 5004e5679de..71c8b021a8e 100644 --- a/lib/public/search/result.php +++ b/lib/public/search/result.php @@ -26,6 +26,7 @@ namespace OCP\Search; /** * The generic result of a search + * @since 7.0.0 */ class Result { @@ -33,6 +34,7 @@ class Result { * A unique identifier for the result, usually given as the item ID in its * corresponding application. * @var string + * @since 7.0.0 */ public $id; @@ -40,12 +42,14 @@ class Result { * The name of the item returned; this will be displayed in the search * results. * @var string + * @since 7.0.0 */ public $name; /** * URL to the application item. * @var string + * @since 7.0.0 */ public $link; @@ -53,6 +57,7 @@ class Result { * The type of search result returned; for consistency, name this the same * as the class name (e.g. \OC\Search\File -> 'file') in lowercase. * @var string + * @since 7.0.0 */ public $type = 'generic'; @@ -61,6 +66,7 @@ class Result { * @param string $id unique identifier from application: '[app_name]/[item_identifier_in_app]' * @param string $name displayed text of result * @param string $link URL to the result within its app + * @since 7.0.0 */ public function __construct($id = null, $name = null, $link = null) { $this->id = $id; diff --git a/lib/public/security/icrypto.php b/lib/public/security/icrypto.php index 2b1c0bf8e4d..167baab8233 100644 --- a/lib/public/security/icrypto.php +++ b/lib/public/security/icrypto.php @@ -31,6 +31,7 @@ namespace OCP\Security; * $encryptWithCustomPassword = \OC::$server->getCrypto()->encrypt('EncryptedText', 'password'); * * @package OCP\Security + * @since 8.0.0 */ interface ICrypto { @@ -38,6 +39,7 @@ interface ICrypto { * @param string $message The message to authenticate * @param string $password Password to use (defaults to `secret` in config.php) * @return string Calculated HMAC + * @since 8.0.0 */ public function calculateHMAC($message, $password = ''); @@ -46,6 +48,7 @@ interface ICrypto { * @param string $plaintext * @param string $password Password to encrypt, if not specified the secret from config.php will be taken * @return string Authenticated ciphertext + * @since 8.0.0 */ public function encrypt($plaintext, $password = ''); @@ -55,6 +58,7 @@ interface ICrypto { * @param string $password Password to encrypt, if not specified the secret from config.php will be taken * @return string plaintext * @throws \Exception If the HMAC does not match + * @since 8.0.0 */ public function decrypt($authenticatedCiphertext, $password = ''); } diff --git a/lib/public/security/ihasher.php b/lib/public/security/ihasher.php index b06dd236077..14229ba99c1 100644 --- a/lib/public/security/ihasher.php +++ b/lib/public/security/ihasher.php @@ -40,6 +40,7 @@ namespace OCP\Security; * var_dump($newHash); * * @package OCP\Security + * @since 8.0.0 */ interface IHasher { /** @@ -49,6 +50,7 @@ interface IHasher { * * @param string $message Message to generate hash from * @return string Hash of the message with appended version parameter + * @since 8.0.0 */ public function hash($message); @@ -57,6 +59,7 @@ interface IHasher { * @param string $hash Assumed hash of the message * @param null|string &$newHash Reference will contain the updated hash if necessary. Update the existing hash with this one. * @return bool Whether $hash is a valid hash of $message + * @since 8.0.0 */ public function verify($message, $hash, &$newHash = null); } diff --git a/lib/public/security/isecurerandom.php b/lib/public/security/isecurerandom.php index 9a91a2f027a..69e6ec21b13 100644 --- a/lib/public/security/isecurerandom.php +++ b/lib/public/security/isecurerandom.php @@ -31,6 +31,7 @@ namespace OCP\Security; * $randomString = $rng->getMediumStrengthGenerator()->generateString(30); * * @package OCP\Security + * @since 8.0.0 */ interface ISecureRandom { @@ -50,6 +51,7 @@ interface ISecureRandom { * used as keys or salts. They are however useful for one-time use tokens. * * @return $this + * @since 8.0.0 */ public function getLowStrengthGenerator(); @@ -61,6 +63,7 @@ interface ISecureRandom { * take some time and resources to generate, so they should not be over-used * * @return $this + * @since 8.0.0 */ public function getMediumStrengthGenerator(); @@ -71,6 +74,7 @@ interface ISecureRandom { * specified all valid base64 characters are used. * @return string * @throws \Exception If the generator is not initialized. + * @since 8.0.0 */ public function generate($length, $characters = ''); } diff --git a/lib/public/security/stringutils.php b/lib/public/security/stringutils.php index bfe5820c758..4f41fcf8262 100644 --- a/lib/public/security/stringutils.php +++ b/lib/public/security/stringutils.php @@ -23,6 +23,12 @@ namespace OCP\Security; +/** + * Class StringUtils + * + * @package OCP\Security + * @since 8.0.0 + */ class StringUtils { /** * Compares whether two strings are equal. To prevent guessing of the string @@ -32,6 +38,7 @@ class StringUtils { * @param string $expected The expected value * @param string $input The input to compare against * @return bool True if the two strings are equal, otherwise false. + * @since 8.0.0 */ public static function equals($expected, $input) { return \OC\Security\StringUtils::equals($expected, $input); diff --git a/lib/public/share.php b/lib/public/share.php index fcdcc6a6d2c..a96239a5c31 100644 --- a/lib/public/share.php +++ b/lib/public/share.php @@ -45,6 +45,7 @@ namespace OCP; * * It provides the following hooks: * - post_shared + * @since 5.0.0 */ class Share extends \OC\Share\Constants { @@ -55,6 +56,7 @@ class Share extends \OC\Share\Constants { * @param string $collectionOf (optional) Depends on item type * @param array $supportedFileExtensions (optional) List of supported file extensions if this item type depends on files * @return boolean true if backend is registered or false if error + * @since 5.0.0 */ public static function registerBackend($itemType, $class, $collectionOf = null, $supportedFileExtensions = null) { return \OC\Share\Share::registerBackend($itemType, $class, $collectionOf, $supportedFileExtensions); @@ -65,6 +67,7 @@ class Share extends \OC\Share\Constants { * @return boolean true if enabled or false * * The Share API is enabled by default if not configured + * @since 5.0.0 */ public static function isEnabled() { return \OC\Share\Share::isEnabled(); @@ -79,6 +82,7 @@ class Share extends \OC\Share\Constants { * @return array * @note $path needs to be relative to user data dir, e.g. 'file.txt' * not '/admin/data/file.txt' + * @since 5.0.0 */ public static function getUsersSharingFile($path, $ownerUser, $includeOwner = false, $returnUserPaths = false) { return \OC\Share\Share::getUsersSharingFile($path, $ownerUser, $includeOwner, $returnUserPaths); @@ -92,6 +96,7 @@ class Share extends \OC\Share\Constants { * @param int $limit Number of items to return (optional) Returns all by default * @param bool $includeCollections (optional) * @return mixed Return depends on format + * @since 5.0.0 */ public static function getItemsSharedWith($itemType, $format = self::FORMAT_NONE, $parameters = null, $limit = -1, $includeCollections = false) { @@ -108,6 +113,7 @@ class Share extends \OC\Share\Constants { * @param int $limit Number of items to return (optional) Returns all by default * @param bool $includeCollections (optional) * @return mixed Return depends on format + * @since 7.0.0 */ public static function getItemsSharedWithUser($itemType, $user, $format = self::FORMAT_NONE, $parameters = null, $limit = -1, $includeCollections = false) { @@ -123,6 +129,7 @@ class Share extends \OC\Share\Constants { * @param mixed $parameters (optional) * @param bool $includeCollections (optional) * @return mixed Return depends on format + * @since 5.0.0 */ public static function getItemSharedWith($itemType, $itemTarget, $format = self::FORMAT_NONE, $parameters = null, $includeCollections = false) { @@ -137,6 +144,7 @@ class Share extends \OC\Share\Constants { * @param string $user User to whom the item was shared * @param string $owner Owner of the share * @return array Return list of items with file_target, permissions and expiration + * @since 6.0.0 - parameter $owner was added in 8.0.0 */ public static function getItemSharedWithUser($itemType, $itemSource, $user, $owner = null) { return \OC\Share\Share::getItemSharedWithUser($itemType, $itemSource, $user, $owner); @@ -150,6 +158,7 @@ class Share extends \OC\Share\Constants { * @param mixed $parameters * @param bool $includeCollections * @return array + * @since 5.0.0 */ public static function getItemSharedWithBySource($itemType, $itemSource, $format = self::FORMAT_NONE, $parameters = null, $includeCollections = false) { @@ -162,6 +171,7 @@ class Share extends \OC\Share\Constants { * @param string $itemSource * @param string $uidOwner Owner of link * @return Item + * @since 5.0.0 */ public static function getItemSharedWithByLink($itemType, $itemSource, $uidOwner) { return \OC\Share\Share::getItemSharedWithByLink($itemType, $itemSource, $uidOwner); @@ -171,6 +181,7 @@ class Share extends \OC\Share\Constants { * Based on the given token the share information will be returned - password protected shares will be verified * @param string $token * @return array|bool false will be returned in case the token is unknown or unauthorized + * @since 5.0.0 - parameter $checkPasswordProtection was added in 7.0.0 */ public static function getShareByToken($token, $checkPasswordProtection = true) { return \OC\Share\Share::getShareByToken($token, $checkPasswordProtection); @@ -180,6 +191,7 @@ class Share extends \OC\Share\Constants { * resolves reshares down to the last real share * @param array $linkItem * @return array file owner + * @since 6.0.0 */ public static function resolveReShare($linkItem) { return \OC\Share\Share::resolveReShare($linkItem); @@ -194,6 +206,7 @@ class Share extends \OC\Share\Constants { * @param int $limit Number of items to return (optional) Returns all by default * @param bool $includeCollections * @return mixed Return depends on format + * @since 5.0.0 */ public static function getItemsShared($itemType, $format = self::FORMAT_NONE, $parameters = null, $limit = -1, $includeCollections = false) { @@ -209,6 +222,7 @@ class Share extends \OC\Share\Constants { * @param mixed $parameters * @param bool $includeCollections * @return mixed Return depends on format + * @since 5.0.0 */ public static function getItemShared($itemType, $itemSource, $format = self::FORMAT_NONE, $parameters = null, $includeCollections = false) { @@ -224,6 +238,7 @@ class Share extends \OC\Share\Constants { * @param bool $includeCollections * @param bool $checkExpireDate * @return array Return array of users + * @since 5.0.0 - parameter $checkExpireDate was added in 7.0.0 */ public static function getUsersItemShared($itemType, $itemSource, $uidOwner, $includeCollections = false, $checkExpireDate = true) { return \OC\Share\Share::getUsersItemShared($itemType, $itemSource, $uidOwner, $includeCollections, $checkExpireDate); @@ -240,6 +255,7 @@ class Share extends \OC\Share\Constants { * @param \DateTime $expirationDate * @return bool|string Returns true on success or false on failure, Returns token on success for links * @throws \Exception + * @since 5.0.0 - parameter $itemSourceName was added in 6.0.0, parameter $expirationDate was added in 7.0.0 */ public static function shareItem($itemType, $itemSource, $shareType, $shareWith, $permissions, $itemSourceName = null, \DateTime $expirationDate = null) { return \OC\Share\Share::shareItem($itemType, $itemSource, $shareType, $shareWith, $permissions, $itemSourceName, $expirationDate); @@ -253,6 +269,7 @@ class Share extends \OC\Share\Constants { * @param string $shareWith User or group the item is being shared with * @param string $owner owner of the share, if null the current user is used * @return boolean true on success or false on failure + * @since 5.0.0 - parameter $owner was added in 8.0.0 */ public static function unshare($itemType, $itemSource, $shareType, $shareWith, $owner = null) { return \OC\Share\Share::unshare($itemType, $itemSource, $shareType, $shareWith, $owner); @@ -263,6 +280,7 @@ class Share extends \OC\Share\Constants { * @param string $itemType * @param string $itemSource * @return boolean true on success or false on failure + * @since 5.0.0 */ public static function unshareAll($itemType, $itemSource) { return \OC\Share\Share::unshareAll($itemType, $itemSource); @@ -275,6 +293,7 @@ class Share extends \OC\Share\Constants { * @return boolean true on success or false on failure * * Unsharing from self is not allowed for items inside collections + * @since 5.0.0 - parameter $originIsSource was added in 8.0.0 */ public static function unshareFromSelf($itemType, $itemOrigin, $originIsSource = false) { return \OC\Share\Share::unshareFromSelf($itemType, $itemOrigin, $originIsSource); @@ -287,6 +306,7 @@ class Share extends \OC\Share\Constants { * @param int $shareType SHARE_TYPE_USER, SHARE_TYPE_GROUP, or SHARE_TYPE_LINK * @param string $recipient with whom was the item shared * @param bool $status + * @since 6.0.0 - parameter $originIsSource was added in 8.0.0 */ public static function setSendMailStatus($itemType, $itemSource, $shareType, $recipient, $status) { return \OC\Share\Share::setSendMailStatus($itemType, $itemSource, $shareType, $recipient, $status); @@ -300,6 +320,7 @@ class Share extends \OC\Share\Constants { * @param string $shareWith User or group the item is being shared with * @param int $permissions CRUDS permissions * @return boolean true on success or false on failure + * @since 5.0.0 */ public static function setPermissions($itemType, $itemSource, $shareType, $shareWith, $permissions) { return \OC\Share\Share::setPermissions($itemType, $itemSource, $shareType, $shareWith, $permissions); @@ -312,6 +333,7 @@ class Share extends \OC\Share\Constants { * @param string $date expiration date * @param int $shareTime timestamp from when the file was shared * @return boolean + * @since 5.0.0 - parameter $shareTime was added in 8.0.0 */ public static function setExpirationDate($itemType, $itemSource, $date, $shareTime = null) { return \OC\Share\Share::setExpirationDate($itemType, $itemSource, $date, $shareTime); @@ -322,6 +344,7 @@ class Share extends \OC\Share\Constants { * @param int $shareId * @param string $password * @return boolean + * @since 8.1.0 */ public static function setPassword($shareId, $password) { $userSession = \OC::$server->getUserSession(); @@ -335,6 +358,7 @@ class Share extends \OC\Share\Constants { * Get the backend class for the specified item type * @param string $itemType * @return Share_Backend + * @since 5.0.0 */ public static function getBackend($itemType) { return \OC\Share\Share::getBackend($itemType); @@ -342,6 +366,7 @@ class Share extends \OC\Share\Constants { /** * Delete all shares with type SHARE_TYPE_LINK + * @since 6.0.0 */ public static function removeAllLinkShares() { return \OC\Share\Share::removeAllLinkShares(); @@ -352,6 +377,7 @@ class Share extends \OC\Share\Constants { * * @param array $linkItem * @return bool + * @since 7.0.0 */ public static function checkPasswordProtectedShare(array $linkItem) { return \OC\Share\Share::checkPasswordProtectedShare($linkItem); @@ -361,6 +387,7 @@ class Share extends \OC\Share\Constants { * Check if resharing is allowed * * @return boolean true if allowed or false + * @since 5.0.0 */ public static function isResharingAllowed() { return \OC\Share\Share::isResharingAllowed(); diff --git a/lib/public/share_backend.php b/lib/public/share_backend.php index b82f265b383..35ed650b173 100644 --- a/lib/public/share_backend.php +++ b/lib/public/share_backend.php @@ -28,6 +28,7 @@ namespace OCP; /** * Interface that apps must implement to share content. + * @since 5.0.0 */ interface Share_Backend { @@ -38,6 +39,7 @@ interface Share_Backend { * @return boolean|null Source * * Return false if the item does not exist for the user + * @since 5.0.0 */ public function isValidSource($itemSource, $uidOwner); @@ -50,6 +52,7 @@ interface Share_Backend { * * This function needs to verify that the user does not already have an item with this name. * If it does generate a new name e.g. name_# + * @since 5.0.0 */ public function generateTarget($itemSource, $shareWith, $exclude = null); @@ -73,6 +76,7 @@ interface Share_Backend { * * This function allows the backend to control the output of shared items with custom formats. * It is only called through calls to the public getItem(s)Shared(With) functions. + * @since 5.0.0 */ public function formatItems($items, $format, $parameters = null); @@ -85,6 +89,7 @@ interface Share_Backend { * The back-end can enable/disable specific share types. Just return true if * the back-end doesn't provide any specific settings for it and want to allow * all share types defined by the share API + * @since 8.0.0 */ public function isShareTypeAllowed($shareType); diff --git a/lib/public/share_backend_collection.php b/lib/public/share_backend_collection.php index 7317a574a7d..7378fd2a46d 100644 --- a/lib/public/share_backend_collection.php +++ b/lib/public/share_backend_collection.php @@ -27,12 +27,14 @@ namespace OCP; /** * Interface for collections of of items implemented by another share backend. * Extends the Share_Backend interface. + * @since 5.0.0 */ interface Share_Backend_Collection extends Share_Backend { /** * Get the sources of the children of the item * @param string $itemSource * @return array Returns an array of children each inside an array with the keys: source, target, and file_path if applicable + * @since 5.0.0 */ public function getChildren($itemSource); } diff --git a/lib/public/share_backend_file_dependent.php b/lib/public/share_backend_file_dependent.php index b5bde29dfc2..b95e0bd84d2 100644 --- a/lib/public/share_backend_file_dependent.php +++ b/lib/public/share_backend_file_dependent.php @@ -27,6 +27,7 @@ namespace OCP; /** * Interface for share backends that share content that is dependent on files. * Extends the Share_Backend interface. + * @since 5.0.0 */ interface Share_Backend_File_Dependent extends Share_Backend { /** @@ -34,6 +35,7 @@ interface Share_Backend_File_Dependent extends Share_Backend { * @param string $itemSource * @param string $uidOwner User that is the owner of shared item * @return string|false + * @since 5.0.0 */ public function getFilePath($itemSource, $uidOwner); diff --git a/lib/public/template.php b/lib/public/template.php index eee5abfc445..be891369869 100644 --- a/lib/public/template.php +++ b/lib/public/template.php @@ -148,6 +148,7 @@ class Template extends \OC_Template { * @param string $app * @param string $image * @return string to the image + * @since 8.0.0 */ public static function image_path($app, $image) { return \image_path($app, $image); @@ -159,6 +160,7 @@ class Template extends \OC_Template { * * @param string $mimetype * @return string to the image of this file type. + * @since 8.0.0 */ public static function mimetype_icon($mimetype) { return \mimetype_icon($mimetype); @@ -169,6 +171,7 @@ class Template extends \OC_Template { * * @param string $path path to file * @return string to the preview of the image + * @since 8.0.0 */ public static function preview_icon($path) { return \preview_icon($path); @@ -181,6 +184,7 @@ class Template extends \OC_Template { * @param string $path of file * @param string $token * @return string link to the preview + * @since 8.0.0 */ public static function publicPreview_icon($path, $token) { return \publicPreview_icon($path, $token); @@ -192,18 +196,20 @@ class Template extends \OC_Template { * * @param int $bytes in bytes * @return string size as string + * @since 8.0.0 */ public static function human_file_size($bytes) { return \human_file_size($bytes); } /** - * Return the relative date in relation to today. Returns something like "last hour" or "two month ago" - * - * @param int $timestamp unix timestamp - * @param boolean $dateOnly - * @return string human readable interpretation of the timestamp - */ + * Return the relative date in relation to today. Returns something like "last hour" or "two month ago" + * + * @param int $timestamp unix timestamp + * @param boolean $dateOnly + * @return string human readable interpretation of the timestamp + * @since 8.0.0 + */ public static function relative_modified_date($timestamp, $dateOnly = false) { return \relative_modified_date($timestamp, null, $dateOnly); } @@ -215,6 +221,7 @@ class Template extends \OC_Template { * @param mixed $selected which one is selected? * @param array $params the parameters * @return string html options + * @since 8.0.0 */ public static function html_select_options($options, $selected, $params=array()) { return \html_select_options($options, $selected, $params); diff --git a/lib/public/user.php b/lib/public/user.php index f3802220b37..c21a4b01ea5 100644 --- a/lib/public/user.php +++ b/lib/public/user.php @@ -42,12 +42,14 @@ namespace OCP; /** * This class provides access to the user management. You can get information * about the currently logged in user and the permissions for example + * @since 5.0.0 */ class User { /** * Get the user id of the user currently logged in. * @return string uid or false * @deprecated Use \OC::$server->getUserSession()->getUser()->getUID() + * @since 5.0.0 */ public static function getUser() { return \OC_User::getUser(); @@ -59,6 +61,7 @@ class User { * @param int|null $limit * @param int|null $offset * @return array an array of all uids + * @since 5.0.0 */ public static function getUsers( $search = '', $limit = null, $offset = null ) { return \OC_User::getUsers( $search, $limit, $offset ); @@ -68,6 +71,7 @@ class User { * Get the user display name of the user currently logged in. * @param string|null $user user id or null for current user * @return string display name + * @since 5.0.0 */ public static function getDisplayName( $user = null ) { return \OC_User::getDisplayName( $user ); @@ -79,6 +83,7 @@ class User { * @param int|null $limit * @param int|null $offset * @return array an array of all display names (value) and the correspondig uids (key) + * @since 5.0.0 */ public static function getDisplayNames( $search = '', $limit = null, $offset = null ) { return \OC_User::getDisplayNames( $search, $limit, $offset ); @@ -87,6 +92,7 @@ class User { /** * Check if the user is logged in * @return boolean + * @since 5.0.0 */ public static function isLoggedIn() { return \OC_User::isLoggedIn(); @@ -97,6 +103,7 @@ class User { * @param string $uid the username * @param string $excludingBackend (default none) * @return boolean + * @since 5.0.0 */ public static function userExists( $uid, $excludingBackend = null ) { return \OC_User::userExists( $uid, $excludingBackend ); @@ -105,6 +112,7 @@ class User { * Logs the user out including all the session data * Logout, destroys session * @deprecated Use \OC::$server->getUserSession()->logout(); + * @since 5.0.0 */ public static function logout() { \OC_User::logout(); @@ -118,22 +126,25 @@ class User { * * Check if the password is correct without logging in the user * @deprecated Use \OC::$server->getUserManager()->checkPassword(); + * @since 5.0.0 */ public static function checkPassword( $uid, $password ) { return \OC_User::checkPassword( $uid, $password ); } /** - * Check if the user is a admin, redirects to home if not - */ + * Check if the user is a admin, redirects to home if not + * @since 5.0.0 + */ public static function checkAdminUser() { \OC_Util::checkAdminUser(); } /** - * Check if the user is logged in, redirects to home if not. With - * redirect URL parameter to the request URI. - */ + * Check if the user is logged in, redirects to home if not. With + * redirect URL parameter to the request URI. + * @since 5.0.0 + */ public static function checkLoggedIn() { \OC_Util::checkLoggedIn(); } diff --git a/lib/public/userinterface.php b/lib/public/userinterface.php index 0848139be91..cf91e519813 100644 --- a/lib/public/userinterface.php +++ b/lib/public/userinterface.php @@ -31,4 +31,10 @@ // This means that they should be used by apps instead of the internal ownCloud classes namespace OCP; +/** + * Interface UserInterface + * + * @package OCP + * @since 4.5.0 + */ interface UserInterface extends \OC_User_Interface {} diff --git a/lib/public/util.php b/lib/public/util.php index 721bcaadb62..626c98022e3 100644 --- a/lib/public/util.php +++ b/lib/public/util.php @@ -51,6 +51,7 @@ use DateTimeZone; /** * This class provides different helper functions to make the life of a developer easier + * @since 4.0.0 */ class Util { // consts for Logging @@ -63,6 +64,7 @@ class Util { /** * get the current installed version of ownCloud * @return array + * @since 4.0.0 */ public static function getVersion() { return(\OC_Util::getVersion()); @@ -82,6 +84,7 @@ class Util { * @param string $ccname * @param string $bcc * @deprecated Use \OCP\Mail\IMailer instead + * @since 4.0.0 */ public static function sendMail($toaddress, $toname, $subject, $mailtext, $fromaddress, $fromname, $html = 0, $altbody = '', $ccaddress = '', $ccname = '', $bcc = '') { @@ -122,6 +125,7 @@ class Util { * @param string $app * @param string $message * @param int $level + * @since 4.0.0 */ public static function writeLog( $app, $message, $level ) { // call the internal log class @@ -133,6 +137,7 @@ class Util { * @param string $app app name * @param \Exception $ex exception to log * @param int $level log level, defaults to \OCP\Util::FATAL + * @since ....0.0 - parameter $level was added in 7.0.0 */ public static function logException( $app, \Exception $ex, $level = \OCP\Util::FATAL ) { $exception = array( @@ -149,6 +154,7 @@ class Util { * check if sharing is disabled for the current user * * @return boolean + * @since 7.0.0 */ public static function isSharingDisabledForUser() { return \OC_Util::isSharingDisabledForUser(); @@ -159,6 +165,7 @@ class Util { * @param string $application * @param string|null $language * @return \OC_L10N + * @since 6.0.0 - parameter $language was added in 8.0.0 */ public static function getL10N($application, $language = null) { return \OC::$server->getL10N($application, $language); @@ -168,6 +175,7 @@ class Util { * add a css file * @param string $application * @param string $file + * @since 4.0.0 */ public static function addStyle( $application, $file = null ) { \OC_Util::addStyle( $application, $file ); @@ -177,6 +185,7 @@ class Util { * add a javascript file * @param string $application * @param string $file + * @since 4.0.0 */ public static function addScript( $application, $file = null ) { \OC_Util::addScript( $application, $file ); @@ -186,6 +195,7 @@ class Util { * Add a translation JS file * @param string $application application id * @param string $languageCode language code, defaults to the current locale + * @since 8.0.0 */ public static function addTranslations($application, $languageCode = null) { \OC_Util::addTranslations($application, $languageCode); @@ -198,6 +208,7 @@ class Util { * @param string $tag tag name of the element * @param array $attributes array of attributes for the element * @param string $text the text content for the element + * @since 4.0.0 */ public static function addHeader($tag, $attributes, $text=null) { \OC_Util::addHeader($tag, $attributes, $text); @@ -211,6 +222,7 @@ class Util { * @return string timestamp * * @deprecated Use \OC::$server->query('DateTimeFormatter') instead + * @since 4.0.0 */ public static function formatDate($timestamp, $dateOnly=false, $timeZone = null) { return(\OC_Util::formatDate($timestamp, $dateOnly, $timeZone)); @@ -221,6 +233,7 @@ class Util { * @return bool * * @deprecated No longer required + * @since 6.0.0 */ public static function encryptedFiles() { return false; @@ -233,6 +246,7 @@ class Util { * @param array $args array with param=>value, will be appended to the returned url * The value of $args will be urlencoded * @return string the url + * @since 4.0.0 - parameter $args was added in 4.5.0 */ public static function linkToAbsolute( $app, $file, $args = array() ) { return(\OC_Helper::linkToAbsolute( $app, $file, $args )); @@ -242,6 +256,7 @@ class Util { * Creates an absolute url for remote use. * @param string $service id * @return string the url + * @since 4.0.0 */ public static function linkToRemote( $service ) { return(\OC_Helper::linkToRemote( $service )); @@ -251,6 +266,7 @@ class Util { * Creates an absolute url for public use * @param string $service id * @return string the url + * @since 4.5.0 */ public static function linkToPublic($service) { return \OC_Helper::linkToPublic($service); @@ -263,20 +279,22 @@ class Util { * @internal param array $args with param=>value, will be appended to the returned url * @return string the url * @deprecated Use \OC::$server->getURLGenerator()->linkToRoute($route, $parameters) + * @since 5.0.0 */ public static function linkToRoute( $route, $parameters = array() ) { return \OC_Helper::linkToRoute($route, $parameters); } /** - * Creates an url to the given app and file - * @param string $app app - * @param string $file file - * @param array $args array with param=>value, will be appended to the returned url - * The value of $args will be urlencoded - * @return string the url - * @deprecated Use \OC::$server->getURLGenerator()->linkTo($app, $file, $args) - */ + * Creates an url to the given app and file + * @param string $app app + * @param string $file file + * @param array $args array with param=>value, will be appended to the returned url + * The value of $args will be urlencoded + * @return string the url + * @deprecated Use \OC::$server->getURLGenerator()->linkTo($app, $file, $args) + * @since 4.0.0 - parameter $args was added in 4.5.0 + */ public static function linkTo( $app, $file, $args = array() ) { return(\OC_Helper::linkTo( $app, $file, $args )); } @@ -285,6 +303,7 @@ class Util { * Returns the server host, even if the website uses one or more reverse proxy * @return string the server host * @deprecated Use \OCP\IRequest::getServerHost + * @since 4.0.0 */ public static function getServerHost() { return \OC::$server->getRequest()->getServerHost(); @@ -293,6 +312,7 @@ class Util { /** * Returns the server host name without an eventual port number * @return string the server hostname + * @since 5.0.0 */ public static function getServerHostName() { $host_name = self::getServerHost(); @@ -318,6 +338,7 @@ class Util { * If the configuration value 'mail_from_address' is set in * config.php, this value will override the $user_part that * is passed to this function + * @since 5.0.0 */ public static function getDefaultEmailAddress($user_part) { $user_part = \OC_Config::getValue('mail_from_address', $user_part); @@ -338,6 +359,7 @@ class Util { * Returns the server protocol. It respects reverse proxy servers and load balancers * @return string the server protocol * @deprecated Use \OCP\IRequest::getServerProtocol + * @since 4.5.0 */ public static function getServerProtocol() { return \OC::$server->getRequest()->getServerProtocol(); @@ -347,6 +369,7 @@ class Util { * Returns the request uri, even if the website uses one or more reverse proxies * @return string the request uri * @deprecated Use \OCP\IRequest::getRequestUri + * @since 5.0.0 */ public static function getRequestUri() { return \OC::$server->getRequest()->getRequestUri(); @@ -356,6 +379,7 @@ class Util { * Returns the script name, even if the website uses one or more reverse proxies * @return string the script name * @deprecated Use \OCP\IRequest::getScriptName + * @since 5.0.0 */ public static function getScriptName() { return \OC::$server->getRequest()->getScriptName(); @@ -367,6 +391,7 @@ class Util { * @param string $image image name * @return string the url * @deprecated Use \OC::$server->getURLGenerator()->imagePath($app, $image) + * @since 4.0.0 */ public static function imagePath( $app, $image ) { return(\OC_Helper::imagePath( $app, $image )); @@ -376,6 +401,7 @@ class Util { * Make a human file size (2048 to 2 kB) * @param int $bytes file size in bytes * @return string a human readable file size + * @since 4.0.0 */ public static function humanFileSize( $bytes ) { return(\OC_Helper::humanFileSize( $bytes )); @@ -387,6 +413,7 @@ class Util { * @return int a file size in bytes * * Inspired by: http://www.php.net/manual/en/function.filesize.php#92418 + * @since 4.0.0 */ public static function computerFileSize( $str ) { return(\OC_Helper::computerFileSize( $str )); @@ -404,6 +431,7 @@ class Util { * This function makes it very easy to connect to use hooks. * * TODO: write example + * @since 4.0.0 */ static public function connectHook($signalClass, $signalName, $slotClass, $slotName ) { return(\OC_Hook::connect($signalClass, $signalName, $slotClass, $slotName )); @@ -417,6 +445,7 @@ class Util { * @return bool true if slots exists or false if not * * TODO: write example + * @since 4.0.0 */ static public function emitHook( $signalclass, $signalname, $params = array()) { return(\OC_Hook::emit( $signalclass, $signalname, $params )); @@ -425,6 +454,7 @@ class Util { /** * Register an get/post call. This is important to prevent CSRF attacks * TODO: write example + * @since 4.5.0 */ public static function callRegister() { return(\OC_Util::callRegister()); @@ -433,6 +463,7 @@ class Util { /** * Check an ajax get/post call if the request token is valid. exit if not. * Todo: Write howto + * @since 4.5.0 */ public static function callCheck() { \OC_Util::callCheck(); @@ -446,6 +477,7 @@ class Util { * * @param string|array $value * @return string|array an array of sanitized strings or a single sinitized string, depends on the input parameter. + * @since 4.5.0 */ public static function sanitizeHTML( $value ) { return(\OC_Util::sanitizeHTML($value)); @@ -460,6 +492,7 @@ class Util { * * @param string $component part of URI to encode * @return string + * @since 6.0.0 */ public static function encodePath($component) { return(\OC_Util::encodePath($component)); @@ -472,6 +505,7 @@ class Util { * @param int $case Either MB_CASE_UPPER or MB_CASE_LOWER (default) * @param string $encoding The encoding parameter is the character encoding. Defaults to UTF-8 * @return array + * @since 4.5.0 */ public static function mb_array_change_key_case($input, $case = MB_CASE_LOWER, $encoding = 'UTF-8') { return(\OC_Helper::mb_array_change_key_case($input, $case, $encoding)); @@ -486,6 +520,7 @@ class Util { * @param int $length Length of the part to be replaced * @param string $encoding The encoding parameter is the character encoding. Defaults to UTF-8 * @return string + * @since 4.5.0 */ public static function mb_substr_replace($string, $replacement, $start, $length = null, $encoding = 'UTF-8') { return(\OC_Helper::mb_substr_replace($string, $replacement, $start, $length, $encoding)); @@ -500,6 +535,7 @@ class Util { * @param string $encoding The encoding parameter is the character encoding. Defaults to UTF-8 * @param int $count If passed, this will be set to the number of replacements performed. * @return string + * @since 4.5.0 */ public static function mb_str_replace($search, $replace, $subject, $encoding = 'UTF-8', &$count = null) { return(\OC_Helper::mb_str_replace($search, $replace, $subject, $encoding, $count)); @@ -512,6 +548,7 @@ class Util { * @param string $needle the search string * @param int $index optional, only search this key name * @return mixed the key of the matching field, otherwise false + * @since 4.5.0 */ public static function recursiveArraySearch($haystack, $needle, $index = null) { return(\OC_Helper::recursiveArraySearch($haystack, $needle, $index)); @@ -523,6 +560,7 @@ class Util { * @param string $dir the current folder where the user currently operates * @param int $free the number of bytes free on the storage holding $dir, if not set this will be received from the storage directly * @return int number of bytes representing + * @since 5.0.0 */ public static function maxUploadFilesize($dir, $free = null) { return \OC_Helper::maxUploadFilesize($dir, $free); @@ -532,6 +570,7 @@ class Util { * Calculate free space left within user quota * @param string $dir the current folder where the user currently operates * @return int number of bytes representing + * @since 7.0.0 */ public static function freeSpace($dir) { return \OC_Helper::freeSpace($dir); @@ -541,6 +580,7 @@ class Util { * Calculate PHP upload limit * * @return int number of bytes representing + * @since 7.0.0 */ public static function uploadLimit() { return \OC_Helper::uploadLimit(); @@ -551,6 +591,7 @@ class Util { * @param string $file file name to check * @return bool true if the file name is valid, false otherwise * @deprecated use \OC\Files\View::verifyPath() + * @since 7.0.0 */ public static function isValidFileName($file) { return \OC_Util::isValidFileName($file); @@ -561,6 +602,7 @@ class Util { * @param int $length of the random string * @return string * @deprecated Use \OC::$server->getSecureRandom()->getMediumStrengthGenerator()->generate($length); instead + * @since 7.0.0 */ public static function generateRandomBytes($length = 30) { return \OC_Util::generateRandomBytes($length); @@ -572,6 +614,7 @@ class Util { * @param string $b second string to compare * @return -1 if $b comes before $a, 1 if $a comes before $b * or 0 if the strings are identical + * @since 7.0.0 */ public static function naturalSortCompare($a, $b) { return \OC\NaturalSort::getInstance()->compare($a, $b); @@ -580,6 +623,7 @@ class Util { /** * check if a password is required for each public link * @return boolean + * @since 7.0.0 */ public static function isPublicLinkPasswordRequired() { return \OC_Util::isPublicLinkPasswordRequired(); @@ -588,6 +632,7 @@ class Util { /** * check if share API enforces a default expire date * @return boolean + * @since 8.0.0 */ public static function isDefaultExpireDateEnforced() { return \OC_Util::isDefaultExpireDateEnforced(); @@ -598,6 +643,7 @@ class Util { * Checks whether the current version needs upgrade. * * @return bool true if upgrade is needed, false otherwise + * @since 7.0.0 */ public static function needUpgrade() { return \OC_Util::needUpgrade(\OC::$server->getConfig()); |