1<?php
2/**
3 * @copyright Copyright (c) 2016, ownCloud, Inc.
4 *
5 * @author Christoph Wurst <christoph@winzerhof-wurst.at>
6 * @author J0WI <J0WI@users.noreply.github.com>
7 * @author Lukas Reschke <lukas@statuscode.ch>
8 * @author Robin Appelman <robin@icewind.nl>
9 * @author Roeland Jago Douma <roeland@famdouma.nl>
10 * @author Tigran Mkrtchyan <tigran.mkrtchyan@desy.de>
11 *
12 * @license AGPL-3.0
13 *
14 * This code is free software: you can redistribute it and/or modify
15 * it under the terms of the GNU Affero General Public License, version 3,
16 * as published by the Free Software Foundation.
17 *
18 * This program is distributed in the hope that it will be useful,
19 * but WITHOUT ANY WARRANTY; without even the implied warranty of
20 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
21 * GNU Affero General Public License for more details.
22 *
23 * You should have received a copy of the GNU Affero General Public License, version 3,
24 * along with this program. If not, see <http://www.gnu.org/licenses/>
25 *
26 */
27// use OCP namespace for all classes that are considered public.
28// This means that they should be used by apps instead of the internal Nextcloud classes
29
30namespace OCP\Files\Storage;
31
32use OCP\Files\Cache\ICache;
33use OCP\Files\Cache\IPropagator;
34use OCP\Files\Cache\IScanner;
35use OCP\Files\Cache\IUpdater;
36use OCP\Files\Cache\IWatcher;
37use OCP\Files\InvalidPathException;
38
39/**
40 * Provide a common interface to all different storage options
41 *
42 * All paths passed to the storage are relative to the storage and should NOT have a leading slash.
43 *
44 * @since 9.0.0
45 */
46interface IStorage {
47	/**
48	 * $parameters is a free form array with the configuration options needed to construct the storage
49	 *
50	 * @param array $parameters
51	 * @since 9.0.0
52	 */
53	public function __construct($parameters);
54
55	/**
56	 * Get the identifier for the storage,
57	 * the returned id should be the same for every storage object that is created with the same parameters
58	 * and two storage objects with the same id should refer to two storages that display the same files.
59	 *
60	 * @return string
61	 * @since 9.0.0
62	 */
63	public function getId();
64
65	/**
66	 * see https://www.php.net/manual/en/function.mkdir.php
67	 * implementations need to implement a recursive mkdir
68	 *
69	 * @param string $path
70	 * @return bool
71	 * @since 9.0.0
72	 */
73	public function mkdir($path);
74
75	/**
76	 * see https://www.php.net/manual/en/function.rmdir.php
77	 *
78	 * @param string $path
79	 * @return bool
80	 * @since 9.0.0
81	 */
82	public function rmdir($path);
83
84	/**
85	 * see https://www.php.net/manual/en/function.opendir.php
86	 *
87	 * @param string $path
88	 * @return resource|bool
89	 * @since 9.0.0
90	 */
91	public function opendir($path);
92
93	/**
94	 * see https://www.php.net/manual/en/function.is-dir.php
95	 *
96	 * @param string $path
97	 * @return bool
98	 * @since 9.0.0
99	 */
100	public function is_dir($path);
101
102	/**
103	 * see https://www.php.net/manual/en/function.is-file.php
104	 *
105	 * @param string $path
106	 * @return bool
107	 * @since 9.0.0
108	 */
109	public function is_file($path);
110
111	/**
112	 * see https://www.php.net/manual/en/function.stat.php
113	 * only the following keys are required in the result: size and mtime
114	 *
115	 * @param string $path
116	 * @return array|bool
117	 * @since 9.0.0
118	 */
119	public function stat($path);
120
121	/**
122	 * see https://www.php.net/manual/en/function.filetype.php
123	 *
124	 * @param string $path
125	 * @return string|bool
126	 * @since 9.0.0
127	 */
128	public function filetype($path);
129
130	/**
131	 * see https://www.php.net/manual/en/function.filesize.php
132	 * The result for filesize when called on a folder is required to be 0
133	 *
134	 * @param string $path
135	 * @return int|bool
136	 * @since 9.0.0
137	 */
138	public function filesize($path);
139
140	/**
141	 * check if a file can be created in $path
142	 *
143	 * @param string $path
144	 * @return bool
145	 * @since 9.0.0
146	 */
147	public function isCreatable($path);
148
149	/**
150	 * check if a file can be read
151	 *
152	 * @param string $path
153	 * @return bool
154	 * @since 9.0.0
155	 */
156	public function isReadable($path);
157
158	/**
159	 * check if a file can be written to
160	 *
161	 * @param string $path
162	 * @return bool
163	 * @since 9.0.0
164	 */
165	public function isUpdatable($path);
166
167	/**
168	 * check if a file can be deleted
169	 *
170	 * @param string $path
171	 * @return bool
172	 * @since 9.0.0
173	 */
174	public function isDeletable($path);
175
176	/**
177	 * check if a file can be shared
178	 *
179	 * @param string $path
180	 * @return bool
181	 * @since 9.0.0
182	 */
183	public function isSharable($path);
184
185	/**
186	 * get the full permissions of a path.
187	 * Should return a combination of the PERMISSION_ constants defined in lib/public/constants.php
188	 *
189	 * @param string $path
190	 * @return int
191	 * @since 9.0.0
192	 */
193	public function getPermissions($path);
194
195	/**
196	 * see https://www.php.net/manual/en/function.file_exists.php
197	 *
198	 * @param string $path
199	 * @return bool
200	 * @since 9.0.0
201	 */
202	public function file_exists($path);
203
204	/**
205	 * see https://www.php.net/manual/en/function.filemtime.php
206	 *
207	 * @param string $path
208	 * @return int|bool
209	 * @since 9.0.0
210	 */
211	public function filemtime($path);
212
213	/**
214	 * see https://www.php.net/manual/en/function.file_get_contents.php
215	 *
216	 * @param string $path
217	 * @return string|bool
218	 * @since 9.0.0
219	 */
220	public function file_get_contents($path);
221
222	/**
223	 * see https://www.php.net/manual/en/function.file_put_contents.php
224	 *
225	 * @param string $path
226	 * @param mixed $data
227	 * @return int|false
228	 * @since 9.0.0
229	 */
230	public function file_put_contents($path, $data);
231
232	/**
233	 * see https://www.php.net/manual/en/function.unlink.php
234	 *
235	 * @param string $path
236	 * @return bool
237	 * @since 9.0.0
238	 */
239	public function unlink($path);
240
241	/**
242	 * see https://www.php.net/manual/en/function.rename.php
243	 *
244	 * @param string $path1
245	 * @param string $path2
246	 * @return bool
247	 * @since 9.0.0
248	 */
249	public function rename($path1, $path2);
250
251	/**
252	 * see https://www.php.net/manual/en/function.copy.php
253	 *
254	 * @param string $path1
255	 * @param string $path2
256	 * @return bool
257	 * @since 9.0.0
258	 */
259	public function copy($path1, $path2);
260
261	/**
262	 * see https://www.php.net/manual/en/function.fopen.php
263	 *
264	 * @param string $path
265	 * @param string $mode
266	 * @return resource|bool
267	 * @since 9.0.0
268	 */
269	public function fopen($path, $mode);
270
271	/**
272	 * get the mimetype for a file or folder
273	 * The mimetype for a folder is required to be "httpd/unix-directory"
274	 *
275	 * @param string $path
276	 * @return string|bool
277	 * @since 9.0.0
278	 */
279	public function getMimeType($path);
280
281	/**
282	 * see https://www.php.net/manual/en/function.hash-file.php
283	 *
284	 * @param string $type
285	 * @param string $path
286	 * @param bool $raw
287	 * @return string|bool
288	 * @since 9.0.0
289	 */
290	public function hash($type, $path, $raw = false);
291
292	/**
293	 * see https://www.php.net/manual/en/function.free_space.php
294	 *
295	 * @param string $path
296	 * @return int|bool
297	 * @since 9.0.0
298	 */
299	public function free_space($path);
300
301	/**
302	 * see https://www.php.net/manual/en/function.touch.php
303	 * If the backend does not support the operation, false should be returned
304	 *
305	 * @param string $path
306	 * @param int $mtime
307	 * @return bool
308	 * @since 9.0.0
309	 */
310	public function touch($path, $mtime = null);
311
312	/**
313	 * get the path to a local version of the file.
314	 * The local version of the file can be temporary and doesn't have to be persistent across requests
315	 *
316	 * @param string $path
317	 * @return string|bool
318	 * @since 9.0.0
319	 */
320	public function getLocalFile($path);
321
322	/**
323	 * check if a file or folder has been updated since $time
324	 *
325	 * @param string $path
326	 * @param int $time
327	 * @return bool
328	 * @since 9.0.0
329	 *
330	 * hasUpdated for folders should return at least true if a file inside the folder is add, removed or renamed.
331	 * returning true for other changes in the folder is optional
332	 */
333	public function hasUpdated($path, $time);
334
335	/**
336	 * get the ETag for a file or folder
337	 *
338	 * @param string $path
339	 * @return string|bool
340	 * @since 9.0.0
341	 */
342	public function getETag($path);
343
344	/**
345	 * Returns whether the storage is local, which means that files
346	 * are stored on the local filesystem instead of remotely.
347	 * Calling getLocalFile() for local storages should always
348	 * return the local files, whereas for non-local storages
349	 * it might return a temporary file.
350	 *
351	 * @return bool true if the files are stored locally, false otherwise
352	 * @since 9.0.0
353	 */
354	public function isLocal();
355
356	/**
357	 * Check if the storage is an instance of $class or is a wrapper for a storage that is an instance of $class
358	 *
359	 * @param string $class
360	 * @return bool
361	 * @since 9.0.0
362	 */
363	public function instanceOfStorage($class);
364
365	/**
366	 * A custom storage implementation can return an url for direct download of a give file.
367	 *
368	 * For now the returned array can hold the parameter url - in future more attributes might follow.
369	 *
370	 * @param string $path
371	 * @return array|bool
372	 * @since 9.0.0
373	 */
374	public function getDirectDownload($path);
375
376	/**
377	 * @param string $path the path of the target folder
378	 * @param string $fileName the name of the file itself
379	 * @return void
380	 * @throws InvalidPathException
381	 * @since 9.0.0
382	 */
383	public function verifyPath($path, $fileName);
384
385	/**
386	 * @param IStorage $sourceStorage
387	 * @param string $sourceInternalPath
388	 * @param string $targetInternalPath
389	 * @return bool
390	 * @since 9.0.0
391	 */
392	public function copyFromStorage(IStorage $sourceStorage, $sourceInternalPath, $targetInternalPath);
393
394	/**
395	 * @param IStorage $sourceStorage
396	 * @param string $sourceInternalPath
397	 * @param string $targetInternalPath
398	 * @return bool
399	 * @since 9.0.0
400	 */
401	public function moveFromStorage(IStorage $sourceStorage, $sourceInternalPath, $targetInternalPath);
402
403	/**
404	 * Test a storage for availability
405	 *
406	 * @since 9.0.0
407	 * @return bool
408	 */
409	public function test();
410
411	/**
412	 * @since 9.0.0
413	 * @return array [ available, last_checked ]
414	 */
415	public function getAvailability();
416
417	/**
418	 * @since 9.0.0
419	 * @param bool $isAvailable
420	 */
421	public function setAvailability($isAvailable);
422
423	/**
424	 * @param string $path path for which to retrieve the owner
425	 * @since 9.0.0
426	 */
427	public function getOwner($path);
428
429	/**
430	 * @param string $path
431	 * @param IStorage|null $storage
432	 * @return ICache
433	 * @since 9.0.0
434	 */
435	public function getCache($path = '', $storage = null);
436
437	/**
438	 * @return IPropagator
439	 * @since 9.0.0
440	 */
441	public function getPropagator();
442
443	/**
444	 * @return IScanner
445	 * @since 9.0.0
446	 */
447	public function getScanner();
448
449	/**
450	 * @return IUpdater
451	 * @since 9.0.0
452	 */
453	public function getUpdater();
454
455	/**
456	 * @return IWatcher
457	 * @since 9.0.0
458	 */
459	public function getWatcher();
460}
461