2
* Copyright (C) 2016 Canonical Ltd
4
* This program is free software: you can redistribute it and/or modify
5
* it under the terms of the GNU Lesser General Public License version 3 as
6
* published by the Free Software Foundation.
8
* This program is distributed in the hope that it will be useful,
9
* but WITHOUT ANY WARRANTY; without even the implied warranty of
10
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11
* GNU Lesser General Public License for more details.
13
* You should have received a copy of the GNU Lesser General Public License
14
* along with this program. If not, see <http://www.gnu.org/licenses/>.
16
* Authors: Michi Henning <michi.henning@canonical.com>
21
#include <unity/storage/qt/client/File.h>
36
namespace local_client
42
} // namespace local_client
44
namespace remote_client
50
} // namespace local_client
51
} // namespace internal
54
\brief Class that represents a folder.
56
A folder is an unordered set of files and/or folders.
58
class UNITY_STORAGE_EXPORT Folder : public Item
66
Folder& operator=(Folder&&);
68
typedef std::shared_ptr<Folder> SPtr;
71
\brief Returns the contents of a folder.
72
\return A vector of items or, if this folder is empty,
73
an empty vector. If there is a large number of items,
74
the returned future may become ready
75
more than once. (See QFutureWatcher for more information.)
77
QFuture<QVector<Item::SPtr>> list() const;
80
\brief Returns the item within this folder with the given name.
81
\return The item. If no such item exists, retrieving the result
82
from the future throws an exception.
84
QFuture<QVector<Item::SPtr>> lookup(QString const& name) const;
87
\brief Creates a new folder with the current folder as the parent.
88
\param name The name of the new folder. Note that the actual name may be changed
89
by the provider; call Item::name() once the folder is created to get its actual name.
90
\warn Do not rely on create_folder() to fail if an attempt is made to create
91
a folder with the same name as an already existing folder or file. Depending on the cloud
92
provider, it may be possible to have several folders with the same name.
93
// TODO: Explain issues with metacharacters.
94
\return The new folder.
96
QFuture<Folder::SPtr> create_folder(QString const& name);
99
\brief Creates a new file with the current folder as the parent.
101
Use the returned Uploader to write data to the file. You must call Uploader::finish_upload()
102
for the file to actually be created (whether data was written to the file or not).
103
\param name The name of the new file. Note that the actual name may be changed
104
by the provider; call Item::name() once the file is created to get its actual name.
105
\param size The size of the upload in bytes.
106
\note The provided file size must match the number of bytes that you write for the upload, otherwise
107
an attampt to retrive the File instance from the future returned by Uploader::finish_upload()
108
throws LogicException.
109
\warn Do not rely on create_file() to fail if an attempt is made to create
110
a file with the same name as an already existing file or folder. Depending on the cloud
111
provider, it may be possible to have several files with the same name.
112
// TODO: Explain issues with metacharacters.
114
QFuture<std::shared_ptr<Uploader>> create_file(QString const& name, int64_t size);
117
Folder(internal::FolderBase*) UNITY_STORAGE_HIDDEN;
119
friend class internal::local_client::FolderImpl;
120
friend class internal::local_client::ItemImpl;
121
friend class internal::remote_client::FolderImpl;
124
} // namespace client
126
} // namespace storage