diff --git a/lib/files/exceptions.php b/lib/files/exceptions.php deleted file mode 100644 index 8a3c40ab0c..0000000000 --- a/lib/files/exceptions.php +++ /dev/null @@ -1,21 +0,0 @@ - - * This file is licensed under the Affero General Public License version 3 or - * later. - * See the COPYING-README file. - */ - -namespace OC\Files; - -class NotFoundException extends \Exception { -} - -class NotPermittedException extends \Exception { -} - -class AlreadyExistsException extends \Exception { -} - -class NotEnoughSpaceException extends \Exception { -} diff --git a/lib/public/files/file.php b/lib/public/files/file.php index c571e184ce..916b2edd6c 100644 --- a/lib/public/files/file.php +++ b/lib/public/files/file.php @@ -8,34 +8,43 @@ namespace OCP\Files; -use OC\Files\NotPermittedException; - interface File extends Node { /** + * Get the content of the file as string + * * @return string - * @throws \OC\Files\NotPermittedException + * @throws \OCP\Files\NotPermittedException */ public function getContent(); /** + * Write to the file from string data + * * @param string $data - * @throws \OC\Files\NotPermittedException + * @throws \OCP\Files\NotPermittedException */ public function putContent($data); /** + * Get the mimetype of the file + * * @return string */ public function getMimeType(); /** + * Open the file as stream, resulting resource can be operated as stream like the result from php's own fopen + * * @param string $mode * @return resource - * @throws \OC\Files\NotPermittedException + * @throws \OCP\Files\NotPermittedException */ public function fopen($mode); /** + * Compute the hash of the file + * Type of hash is set with $type and can be anything supported by php's hash_file + * * @param string $type * @param bool $raw * @return string diff --git a/lib/public/files/folder.php b/lib/public/files/folder.php index a8e57f7ae2..da7f20fd36 100644 --- a/lib/public/files/folder.php +++ b/lib/public/files/folder.php @@ -8,22 +8,21 @@ namespace OCP\Files; -use OC\Files\Cache\Cache; -use OC\Files\Cache\Scanner; -use OC\Files\NotFoundException; -use OC\Files\NotPermittedException; - interface Folder extends Node { /** - * @param string $path path relative to the folder + * Get the full path of an item in the folder within owncloud's filesystem + * + * @param string $path relative path of an item in the folder * @return string - * @throws \OC\Files\NotPermittedException + * @throws \OCP\Files\NotPermittedException */ public function getFullPath($path); /** - * @param string $path - * @throws \OC\Files\NotFoundException + * Get the path of an item in the folder relative to the folder + * + * @param string $path absolute path of an item in the folder + * @throws \OCP\Files\NotFoundException * @return string */ public function getRelativePath($path); @@ -39,7 +38,7 @@ interface Folder extends Node { /** * get the content of this directory * - * @throws \OC\Files\NotFoundException + * @throws \OCP\Files\NotFoundException * @return \OCP\Files\Node[] */ public function getDirectoryListing(); @@ -47,29 +46,35 @@ interface Folder extends Node { /** * Get the node at $path * - * @param string $path + * @param string $path relative path of the file or folder * @return \OCP\Files\Node - * @throws \OC\Files\NotFoundException + * @throws \OCP\Files\NotFoundException */ public function get($path); /** - * @param string $path + * Check if a file or folder exists in the folder + * + * @param string $path relative path of the file or folder * @return bool */ public function nodeExists($path); /** - * @param string $path + * Create a new folder + * + * @param string $path relative path of the new folder * @return \OCP\Files\Folder - * @throws NotPermittedException + * @throws \OCP\Files\NotPermittedException */ public function newFolder($path); /** - * @param string $path + * Create a new file + * + * @param string $path relative path of the new file * @return \OCP\Files\File - * @throws NotPermittedException + * @throws \OCP\Files\NotPermittedException */ public function newFile($path); @@ -83,6 +88,7 @@ interface Folder extends Node { /** * search for files by mimetype + * $mimetype can either be a full mimetype (image/png) or a wildcard mimetype (image) * * @param string $mimetype * @return \OCP\Files\Node[] @@ -90,14 +96,23 @@ interface Folder extends Node { public function searchByMime($mimetype); /** - * @param $id + * get a file or folder inside the folder by it's internal id + * + * @param int $id * @return \OCP\Files\Node[] */ public function getById($id); + /** + * Get the amount of free space inside the folder + * + * @return int + */ public function getFreeSpace(); /** + * Check if new files or folders can be created within the folder + * * @return bool */ public function isCreatable(); diff --git a/lib/public/files/node.php b/lib/public/files/node.php index d3b71803f5..42dd910871 100644 --- a/lib/public/files/node.php +++ b/lib/public/files/node.php @@ -10,98 +10,149 @@ namespace OCP\Files; interface Node { /** - * @param string $targetPath - * @throws \OC\Files\NotPermittedException + * Move the file or folder to a new location + * + * @param string $targetPath the absolute target path + * @throws \OCP\Files\NotPermittedException * @return \OCP\Files\Node */ public function move($targetPath); + /** + * Delete the file or folder + */ public function delete(); /** - * @param string $targetPath + * Cope the file or folder to a new location + * + * @param string $targetPath the absolute target path * @return \OCP\Files\Node */ public function copy($targetPath); /** - * @param int $mtime - * @throws \OC\Files\NotPermittedException + * Change the modified date of the file or folder + * If $mtime is omitted the current time will be used + * + * @param int $mtime (optional) modified date as unix timestamp + * @throws \OCP\Files\NotPermittedException */ public function touch($mtime = null); /** + * Get the storage backend the file or folder is stored on + * * @return \OC\Files\Storage\Storage - * @throws \OC\Files\NotFoundException + * @throws \OCP\Files\NotFoundException */ public function getStorage(); /** + * Get the full path of the file or folder + * * @return string */ public function getPath(); /** + * Get the path of the file or folder relative to the mountpoint of it's storage + * * @return string */ public function getInternalPath(); /** + * Get the internal file id for the file or folder + * * @return int */ public function getId(); /** + * Get metadata of the file or folder + * The returned array contains the following values: + * - mtime + * - size + * * @return array */ public function stat(); /** + * Get the modified date of the file or folder as unix timestamp + * * @return int */ public function getMTime(); /** + * Get the size of the file or folder in bytes + * * @return int */ public function getSize(); /** + * Get the Etag of the file or folder + * The Etag is an string id used to detect changes to a file or folder, + * every time the file or folder is changed the Etag will change to + * * @return string */ public function getEtag(); + /** + * Get the permissions of the file or folder as a combination of one or more of the following constants: + * - \OCP\PERMISSION_READ + * - \OCP\PERMISSION_UPDATE + * - \OCP\PERMISSION_CREATE + * - \OCP\PERMISSION_DELETE + * - \OCP\PERMISSION_SHARE + * * @return int */ public function getPermissions(); /** + * Check if the file or folder is readable + * * @return bool */ public function isReadable(); /** + * Check if the file or folder is writable + * * @return bool */ public function isUpdateable(); /** + * Check if the file or folder is deletable + * * @return bool */ public function isDeletable(); /** + * Check if the file or folder is shareable + * * @return bool */ public function isShareable(); /** - * @return Node + * Get the parent folder of the file or folder + * + * @return Folder */ public function getParent(); /** + * Get the filename of the file or folder + * * @return string */ public function getName();