improve phpdoc for the public files interface
This commit is contained in:
parent
e271a55783
commit
9ad7891b4e
|
@ -1,21 +0,0 @@
|
||||||
<?php
|
|
||||||
/**
|
|
||||||
* Copyright (c) 2013 Robin Appelman <icewind@owncloud.com>
|
|
||||||
* 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 {
|
|
||||||
}
|
|
|
@ -8,34 +8,43 @@
|
||||||
|
|
||||||
namespace OCP\Files;
|
namespace OCP\Files;
|
||||||
|
|
||||||
use OC\Files\NotPermittedException;
|
|
||||||
|
|
||||||
interface File extends Node {
|
interface File extends Node {
|
||||||
/**
|
/**
|
||||||
|
* Get the content of the file as string
|
||||||
|
*
|
||||||
* @return string
|
* @return string
|
||||||
* @throws \OC\Files\NotPermittedException
|
* @throws \OCP\Files\NotPermittedException
|
||||||
*/
|
*/
|
||||||
public function getContent();
|
public function getContent();
|
||||||
|
|
||||||
/**
|
/**
|
||||||
|
* Write to the file from string data
|
||||||
|
*
|
||||||
* @param string $data
|
* @param string $data
|
||||||
* @throws \OC\Files\NotPermittedException
|
* @throws \OCP\Files\NotPermittedException
|
||||||
*/
|
*/
|
||||||
public function putContent($data);
|
public function putContent($data);
|
||||||
|
|
||||||
/**
|
/**
|
||||||
|
* Get the mimetype of the file
|
||||||
|
*
|
||||||
* @return string
|
* @return string
|
||||||
*/
|
*/
|
||||||
public function getMimeType();
|
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
|
* @param string $mode
|
||||||
* @return resource
|
* @return resource
|
||||||
* @throws \OC\Files\NotPermittedException
|
* @throws \OCP\Files\NotPermittedException
|
||||||
*/
|
*/
|
||||||
public function fopen($mode);
|
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 string $type
|
||||||
* @param bool $raw
|
* @param bool $raw
|
||||||
* @return string
|
* @return string
|
||||||
|
|
|
@ -8,22 +8,21 @@
|
||||||
|
|
||||||
namespace OCP\Files;
|
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 {
|
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
|
* @return string
|
||||||
* @throws \OC\Files\NotPermittedException
|
* @throws \OCP\Files\NotPermittedException
|
||||||
*/
|
*/
|
||||||
public function getFullPath($path);
|
public function getFullPath($path);
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* @param string $path
|
* Get the path of an item in the folder relative to the folder
|
||||||
* @throws \OC\Files\NotFoundException
|
*
|
||||||
|
* @param string $path absolute path of an item in the folder
|
||||||
|
* @throws \OCP\Files\NotFoundException
|
||||||
* @return string
|
* @return string
|
||||||
*/
|
*/
|
||||||
public function getRelativePath($path);
|
public function getRelativePath($path);
|
||||||
|
@ -39,7 +38,7 @@ interface Folder extends Node {
|
||||||
/**
|
/**
|
||||||
* get the content of this directory
|
* get the content of this directory
|
||||||
*
|
*
|
||||||
* @throws \OC\Files\NotFoundException
|
* @throws \OCP\Files\NotFoundException
|
||||||
* @return \OCP\Files\Node[]
|
* @return \OCP\Files\Node[]
|
||||||
*/
|
*/
|
||||||
public function getDirectoryListing();
|
public function getDirectoryListing();
|
||||||
|
@ -47,29 +46,35 @@ interface Folder extends Node {
|
||||||
/**
|
/**
|
||||||
* Get the node at $path
|
* Get the node at $path
|
||||||
*
|
*
|
||||||
* @param string $path
|
* @param string $path relative path of the file or folder
|
||||||
* @return \OCP\Files\Node
|
* @return \OCP\Files\Node
|
||||||
* @throws \OC\Files\NotFoundException
|
* @throws \OCP\Files\NotFoundException
|
||||||
*/
|
*/
|
||||||
public function get($path);
|
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
|
* @return bool
|
||||||
*/
|
*/
|
||||||
public function nodeExists($path);
|
public function nodeExists($path);
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* @param string $path
|
* Create a new folder
|
||||||
|
*
|
||||||
|
* @param string $path relative path of the new folder
|
||||||
* @return \OCP\Files\Folder
|
* @return \OCP\Files\Folder
|
||||||
* @throws NotPermittedException
|
* @throws \OCP\Files\NotPermittedException
|
||||||
*/
|
*/
|
||||||
public function newFolder($path);
|
public function newFolder($path);
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* @param string $path
|
* Create a new file
|
||||||
|
*
|
||||||
|
* @param string $path relative path of the new file
|
||||||
* @return \OCP\Files\File
|
* @return \OCP\Files\File
|
||||||
* @throws NotPermittedException
|
* @throws \OCP\Files\NotPermittedException
|
||||||
*/
|
*/
|
||||||
public function newFile($path);
|
public function newFile($path);
|
||||||
|
|
||||||
|
@ -83,6 +88,7 @@ interface Folder extends Node {
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* search for files by mimetype
|
* search for files by mimetype
|
||||||
|
* $mimetype can either be a full mimetype (image/png) or a wildcard mimetype (image)
|
||||||
*
|
*
|
||||||
* @param string $mimetype
|
* @param string $mimetype
|
||||||
* @return \OCP\Files\Node[]
|
* @return \OCP\Files\Node[]
|
||||||
|
@ -90,14 +96,23 @@ interface Folder extends Node {
|
||||||
public function searchByMime($mimetype);
|
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[]
|
* @return \OCP\Files\Node[]
|
||||||
*/
|
*/
|
||||||
public function getById($id);
|
public function getById($id);
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Get the amount of free space inside the folder
|
||||||
|
*
|
||||||
|
* @return int
|
||||||
|
*/
|
||||||
public function getFreeSpace();
|
public function getFreeSpace();
|
||||||
|
|
||||||
/**
|
/**
|
||||||
|
* Check if new files or folders can be created within the folder
|
||||||
|
*
|
||||||
* @return bool
|
* @return bool
|
||||||
*/
|
*/
|
||||||
public function isCreatable();
|
public function isCreatable();
|
||||||
|
|
|
@ -10,98 +10,149 @@ namespace OCP\Files;
|
||||||
|
|
||||||
interface Node {
|
interface Node {
|
||||||
/**
|
/**
|
||||||
* @param string $targetPath
|
* Move the file or folder to a new location
|
||||||
* @throws \OC\Files\NotPermittedException
|
*
|
||||||
|
* @param string $targetPath the absolute target path
|
||||||
|
* @throws \OCP\Files\NotPermittedException
|
||||||
* @return \OCP\Files\Node
|
* @return \OCP\Files\Node
|
||||||
*/
|
*/
|
||||||
public function move($targetPath);
|
public function move($targetPath);
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Delete the file or folder
|
||||||
|
*/
|
||||||
public function delete();
|
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
|
* @return \OCP\Files\Node
|
||||||
*/
|
*/
|
||||||
public function copy($targetPath);
|
public function copy($targetPath);
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* @param int $mtime
|
* Change the modified date of the file or folder
|
||||||
* @throws \OC\Files\NotPermittedException
|
* 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);
|
public function touch($mtime = null);
|
||||||
|
|
||||||
/**
|
/**
|
||||||
|
* Get the storage backend the file or folder is stored on
|
||||||
|
*
|
||||||
* @return \OC\Files\Storage\Storage
|
* @return \OC\Files\Storage\Storage
|
||||||
* @throws \OC\Files\NotFoundException
|
* @throws \OCP\Files\NotFoundException
|
||||||
*/
|
*/
|
||||||
public function getStorage();
|
public function getStorage();
|
||||||
|
|
||||||
/**
|
/**
|
||||||
|
* Get the full path of the file or folder
|
||||||
|
*
|
||||||
* @return string
|
* @return string
|
||||||
*/
|
*/
|
||||||
public function getPath();
|
public function getPath();
|
||||||
|
|
||||||
/**
|
/**
|
||||||
|
* Get the path of the file or folder relative to the mountpoint of it's storage
|
||||||
|
*
|
||||||
* @return string
|
* @return string
|
||||||
*/
|
*/
|
||||||
public function getInternalPath();
|
public function getInternalPath();
|
||||||
|
|
||||||
/**
|
/**
|
||||||
|
* Get the internal file id for the file or folder
|
||||||
|
*
|
||||||
* @return int
|
* @return int
|
||||||
*/
|
*/
|
||||||
public function getId();
|
public function getId();
|
||||||
|
|
||||||
/**
|
/**
|
||||||
|
* Get metadata of the file or folder
|
||||||
|
* The returned array contains the following values:
|
||||||
|
* - mtime
|
||||||
|
* - size
|
||||||
|
*
|
||||||
* @return array
|
* @return array
|
||||||
*/
|
*/
|
||||||
public function stat();
|
public function stat();
|
||||||
|
|
||||||
/**
|
/**
|
||||||
|
* Get the modified date of the file or folder as unix timestamp
|
||||||
|
*
|
||||||
* @return int
|
* @return int
|
||||||
*/
|
*/
|
||||||
public function getMTime();
|
public function getMTime();
|
||||||
|
|
||||||
/**
|
/**
|
||||||
|
* Get the size of the file or folder in bytes
|
||||||
|
*
|
||||||
* @return int
|
* @return int
|
||||||
*/
|
*/
|
||||||
public function getSize();
|
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
|
* @return string
|
||||||
*/
|
*/
|
||||||
public function getEtag();
|
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
|
* @return int
|
||||||
*/
|
*/
|
||||||
public function getPermissions();
|
public function getPermissions();
|
||||||
|
|
||||||
/**
|
/**
|
||||||
|
* Check if the file or folder is readable
|
||||||
|
*
|
||||||
* @return bool
|
* @return bool
|
||||||
*/
|
*/
|
||||||
public function isReadable();
|
public function isReadable();
|
||||||
|
|
||||||
/**
|
/**
|
||||||
|
* Check if the file or folder is writable
|
||||||
|
*
|
||||||
* @return bool
|
* @return bool
|
||||||
*/
|
*/
|
||||||
public function isUpdateable();
|
public function isUpdateable();
|
||||||
|
|
||||||
/**
|
/**
|
||||||
|
* Check if the file or folder is deletable
|
||||||
|
*
|
||||||
* @return bool
|
* @return bool
|
||||||
*/
|
*/
|
||||||
public function isDeletable();
|
public function isDeletable();
|
||||||
|
|
||||||
/**
|
/**
|
||||||
|
* Check if the file or folder is shareable
|
||||||
|
*
|
||||||
* @return bool
|
* @return bool
|
||||||
*/
|
*/
|
||||||
public function isShareable();
|
public function isShareable();
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* @return Node
|
* Get the parent folder of the file or folder
|
||||||
|
*
|
||||||
|
* @return Folder
|
||||||
*/
|
*/
|
||||||
public function getParent();
|
public function getParent();
|
||||||
|
|
||||||
/**
|
/**
|
||||||
|
* Get the filename of the file or folder
|
||||||
|
*
|
||||||
* @return string
|
* @return string
|
||||||
*/
|
*/
|
||||||
public function getName();
|
public function getName();
|
||||||
|
|
Loading…
Reference in New Issue