Commit 84c677de authored by Paweł Wegner's avatar Paweł Wegner

Added docs for public api.

parent 94ed3f79
......@@ -56,47 +56,225 @@ class ICloudProvider {
enum class Status { WaitForAuthorizationCode, None };
virtual ~ICallback() = default;
/**
* Determines whether library should try to obtain authorization code or
* not.
*
* @return Status::WaitForAuthorizationCode if the user wants to obtain the
* authorization code, Status::None otherwise
*/
virtual Status userConsentRequired(const ICloudProvider&) = 0;
/**
* Called when user gave his consent to our library.
*/
virtual void accepted(const ICloudProvider&) = 0;
/**
* Called when user declined consent to our library.
*/
virtual void declined(const ICloudProvider&) = 0;
/**
* Called when an error occurred.
*
* @param description error's description
*/
virtual void error(const ICloudProvider&,
const std::string& description) = 0;
};
virtual ~ICloudProvider() = default;
virtual void initialize(const std::string& token, ICallback::Pointer,
/**
* Initializes the cloud provider, doesn't do any authorization just yet. The
* actual authorization will be done the first time it's actually needed.
*
* @param token token retrieved by some previous run with
* ICloudProvider::token or any string, library will detect whether it's valid
* and ask for user consent if it isn't
*
* @param callback callback which will manage future authorization
* process
*
* @param hints various hints which can be retrieved by some previous run with
* ICloudProvider::hints; providing them may speed up the authorization
* process; may contain oauth's "client_id" and "client_secret"
*/
virtual void initialize(const std::string& token, ICallback::Pointer callback,
const Hints& hints = Hints()) = 0;
/**
* Token which should be saved and reused as a parameter to
* ICloudProvider::initialize. Usually it's oauth2 refresh token.
*
* @return token
*/
virtual std::string token() const = 0;
/**
* Returns hints which can be reused as a parameter to
* ICloudProvider::initialize.
*
* @return hints
*/
virtual Hints hints() const = 0;
/**
* Returns the name of cloud provider, used to instantinate it with
* ICloudStorage::provider.
*
* @return name of cloud provider
*/
virtual std::string name() const = 0;
/**
* Returns the url to which user has to go in his web browser in order to give
* consent to our library.
*
* @return authorization url
*/
virtual std::string authorizeLibraryUrl() const = 0;
/**
* Returns IItem representing the root folder in cloud provider.
*
* @return root directory
*/
virtual IItem::Pointer rootDirectory() const = 0;
/**
* Lists directory.
*
* @param directory directory to list
* @return object representing the pending request
*/
virtual ListDirectoryRequest::Pointer listDirectoryAsync(
IItem::Pointer, IListDirectoryCallback::Pointer) = 0;
IItem::Pointer directory, IListDirectoryCallback::Pointer) = 0;
/**
* Tries to get the Item by its absolute path.
*
* @param absolute_path should start with /
*
* @param callback called when finished; if successful, it gets IItem
* object as a parameter, otherwise it gets nullptr
*
* @return object representing the pending request
*/
virtual GetItemRequest::Pointer getItemAsync(const std::string& absolute_path,
GetItemCallback) = 0;
GetItemCallback callback) = 0;
/**
* Downloads the item, the file is provided by callback.
*
* @param item item to be downloaded
* @return object representing the pending request
*/
virtual DownloadFileRequest::Pointer downloadFileAsync(
IItem::Pointer, IDownloadFileCallback::Pointer) = 0;
IItem::Pointer item, IDownloadFileCallback::Pointer) = 0;
/**
* Uploads the file provided by callback.
*
* @param parent parent of the uploaded file
*
* @param filename name at which the uploaded file will be saved in cloud
* provider
*
* @return object representing the pending request
*/
virtual UploadFileRequest::Pointer uploadFileAsync(
IItem::Pointer, const std::string& filename,
IItem::Pointer parent, const std::string& filename,
IUploadFileCallback::Pointer) = 0;
virtual GetItemDataRequest::Pointer getItemDataAsync(const std::string& id,
GetItemDataCallback) = 0;
/**
* Retrieves IItem object from it's id. That's the preferred way of updating
* the IItem structure; IItem caches some data(e.g. thumbnail url or file url)
* which may get invalidated over time, this function makes sure all IItem's
* cached data is up to date.
*
* @param id
*
* @param callback called when finished; if successful, it gets
* IItem object as a parameter, otherwise it gets nullptr
*
* @return object representing the pending request
*/
virtual GetItemDataRequest::Pointer getItemDataAsync(
const std::string& id, GetItemDataCallback callback) = 0;
/**
* Downloads thumbnail image, before calling the function, make sure provided
* IItem is up to date.
*
* @param item
* @return object representing the pending request
*/
virtual DownloadFileRequest::Pointer getThumbnailAsync(
IItem::Pointer item, IDownloadFileCallback::Pointer) = 0;
virtual DeleteItemRequest::Pointer deleteItemAsync(IItem::Pointer,
DeleteItemCallback) = 0;
/**
* Deletes the item from cloud provider.
*
* @param item item to be deleted
*
* @param callback called when finished; if successful, it gets true,
* otherwise false
*
* @return object representing the pending request
*/
virtual DeleteItemRequest::Pointer deleteItemAsync(
IItem::Pointer item, DeleteItemCallback callback) = 0;
/**
* Creates directory in cloud provider.
*
* @param parent parent directory
*
* @param name new directory's name
*
* @param callback called when finished; if successful, it gets IItem
* object, otherwise nullptr
*
* @return object representing the pending request
*/
virtual CreateDirectoryRequest::Pointer createDirectoryAsync(
IItem::Pointer parent, const std::string& name,
CreateDirectoryCallback) = 0;
CreateDirectoryCallback callback) = 0;
/**
* Moves item.
*
* @param source file to be moved
*
* @param destination destination directory
*
* @param callback called when finished; if successful, it gets true,
* otherwise false
*
* @return object representing the pending request
*/
virtual MoveItemRequest::Pointer moveItemAsync(IItem::Pointer source,
IItem::Pointer destination,
MoveItemCallback) = 0;
virtual RenameItemRequest::Pointer renameItemAsync(IItem::Pointer item,
const std::string& name,
RenameItemCallback) = 0;
MoveItemCallback callback) = 0;
/**
* Renames item.
*
* @param item item to be renamed
*
* @param name new name
*
* @param callback called when finished; if successful, it gets true,
* otherwise false
*
* @return object representing the pending request
*/
virtual RenameItemRequest::Pointer renameItemAsync(
IItem::Pointer item, const std::string& name,
RenameItemCallback callback) = 0;
};
} // namespace cloudstorage
......
......@@ -30,13 +30,28 @@
namespace cloudstorage {
/**
* Contains available CloudStorage providers.
*/
class ICloudStorage {
public:
using Pointer = std::unique_ptr<ICloudStorage>;
virtual ~ICloudStorage() = default;
/**
* Retrieves list of available cloud providers.
*
* @return cloud providers
*/
virtual std::vector<ICloudProvider::Pointer> providers() const = 0;
/**
* Gets provider by name.
*
* @param name
* @return cloud provider
*/
virtual ICloudProvider::Pointer provider(const std::string& name) const = 0;
static ICloudStorage::Pointer create();
......
......@@ -39,7 +39,17 @@ class IItem {
virtual std::string filename() const = 0;
virtual std::string id() const = 0;
/**
* This url is valid if IItem instance was received by
* ICloudProvider::getItemDataAsync; it's because some cloud providers require
* to generate temporary urls per item; ICloudProvider::getItemDataAsync cares
* about that, ICloudProvider::listDirectoryAsync does not.
*
* @return url
*/
virtual std::string url() const = 0;
virtual bool is_hidden() const = 0;
virtual FileType type() const = 0;
};
......
......@@ -31,6 +31,10 @@
namespace cloudstorage {
/**
* Class representing pending request. When there is no reference to the
* request, it's immediately cancelled.
*/
template <class ReturnValue>
class IRequest {
public:
......@@ -38,8 +42,21 @@ class IRequest {
virtual ~IRequest() = default;
/**
* Blocks until request finishes.
*/
virtual void finish() = 0;
/**
* Cancels request; may involve curl request cancellation which may last very
* long if curl was compiled without asynchronous name resolver(c-ares).
*/
virtual void cancel() = 0;
/**
* Retrieves the result, blocks if it wasn't computed just yet.
* @return result
*/
virtual ReturnValue result() = 0;
};
......@@ -49,8 +66,25 @@ class IListDirectoryCallback {
virtual ~IListDirectoryCallback() = default;
/**
* Called when directory's child was fetched.
*
* @param item fetched item
*/
virtual void receivedItem(IItem::Pointer item) = 0;
/**
* Called when the request was successfully finished.
*
* @param result contains all retrieved children
*/
virtual void done(const std::vector<IItem::Pointer>& result) = 0;
/**
* Called when error occurred.
*
* @param description error description
*/
virtual void error(const std::string& description) = 0;
};
......@@ -60,9 +94,32 @@ class IDownloadFileCallback {
virtual ~IDownloadFileCallback() = default;
/**
* Called when received a part of file.
*
* @param data buffer
* @param length length of buffer
*/
virtual void receivedData(const char* data, uint32_t length) = 0;
/**
* Called when the download has finished.
*/
virtual void done() = 0;
/**
* Called when error occurred.
*
* @param description error description
*/
virtual void error(const std::string& description) = 0;
/**
* Called when progress has changed.
*
* @param total count of bytes to download
* @param now count of bytes downloaded
*/
virtual void progress(uint32_t total, uint32_t now) = 0;
};
......@@ -72,11 +129,43 @@ class IUploadFileCallback {
virtual ~IUploadFileCallback() = default;
/**
* Called when upload starts, can be also called when retransmission is
* required due to network issues.
*/
virtual void reset() = 0;
/**
* Called when the file data should be uploaded.
*
* @param data buffer to put data to
* @param maxlength max count of bytes which can be put to the buffer
* @return count of bytes put to the buffer
*/
virtual uint32_t putData(char* data, uint32_t maxlength) = 0;
/**
* @return size of currently uploaded file
*/
virtual uint64_t size() = 0;
/**
* Called when the upload is finished sucessfully.
*/
virtual void done() = 0;
/**
* Called when error occurred.
* @param description
*/
virtual void error(const std::string& description) = 0;
/**
* Called when upload progress changed.
*
* @param total count of bytes to upload
* @param now count of bytes already uploaded
*/
virtual void progress(uint32_t total, uint32_t now) = 0;
};
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment