QUpYun - 又拍云Qt SDK

======

QUpYun是又拍云存储的Qt SDK，基于又拍云存储HTTP REST API接口开发，适用于Qt 4.8.x/5.x版本(其它版本没有进行测试)。

QUpYun使用QNetworkAccessManager进行网络访问。通常，一个应用程序仅需要一个QUpYun实例即可满足需要，不需要创建多个QUpYun对象。QUpYun提供的访问接口全部为异步访问模式，程序开发人员需要连接相应的信号获得又拍云服务器返回的数据。与此同时，QUpYun还提供了requestError(QNetworkReply::NetworkError, const QString &)信号，用于处理可能发生的错误。

云存储基础接口

准备操作

QUpYun的全部代码位于source目录中。在需要使用QUpYun的工程文件中引入qupyun.pri即可正常使用：

include("qupyun.pri")

源代码文件中，我们可以通过下面语句引入QUpYun：

#include <QUpYun>

创建空间

用户需要自行在又拍云网站创建个性化空间。具体教程请参见创建空间。

初始化QUpYun

QUpYun *upyun = new QUpYun(BucketName, Operator, Password, parent);

若不了解“授权操作员”，请参见授权操作员

选择最优的接入点

根据国内的网络情况，又拍云存储API目前提供了电信、联通网通、移动铁通三个接入点。我们可以通过QUpYun的接口进行设置：

upyun->setAPIDomain(QUpYun::ED_AUTO);

若没有明确进行设置，QUpYun默认将根据网络条件自动选择接入点。使用apiDomain()函数可以获取当前设置的接入点。

接入点有四个值可选：

QUpYun::ED_AUTO ：根据网络条件自动选择接入点
QUpYun::ED_TELECOM ：电信接入点
QUpYun::ED_CNC ：联通网通接入点
QUpYun::ED_CTT ：移动铁通接入点

**注：**建议根据服务器网络状况，手动设置合理的接入点已获取最佳的访问速度。

上传文件

基本用法

QUpYun提供了两个用于上传的函数：

void uploadFile(const QString &path,
                const QString &localPath,
                bool autoMkdir = false,
                bool appendFileMD5 = false,
                const QString &fileSecret = QString(),
                const RequestParams &params = RequestParams());
				
void uploadFile(const QString &path,
                QFile *file,
                bool autoMkdir = false,
                bool appendFileMD5 = false,
                const QString &fileSecret = QString(),
                const RequestParams &params = RequestParams());

我们可以根据使用=文件路径还是文件对象区别使用这两个函数，例如：

QUpYun *upyun = new QUpYun(BucketName, Operator, Password, parent);
connect(upyun, &QUpYun::requestUploadFinished, [=] (bool success, const PicInfo &picInfo) {
	...
});
						   
// 使用文件所在路径
upyun->uploadFile(savePath, localFilePath);

// 上传文件对象
QFile file(localFilePath);
upyun->uploadFile(savePath, &file);

参数说明

savePath：上传到的又拍云存储的具体地址
- 比如/dir/sample.jpg表示以sample.jpg为文件名保存到/dir目录下；
- 若保存路径为/sample.jpg，则表示保存到根目录下；
- 注意savePath必须以/开始，下同。
第二个参数可以是QString或QFile *类型，即需要上传的文件路径或文件本身。
autoMkdir：可选的bool类型参数，表示当不存在父级目录时是否自动创建父级目录（只支持自动创建10级以内的父级目录）。
appendFileMD5：可选的bool类型参数，表示是否需要附加文件的MD5校验值。如果设置了该参数，上传时会附加被上传文件的MD5校验值。若又拍云服务器计算而得的文件MD5值与此不同，则服务器返回406 Not Acceptable错误。对于需要确保上传文件的完整性要求的业务，可以设置该参数。
fileSecret：可选的QString类型参数，表示是否添加文件访问密钥。该访问密钥仅支持图片空间。图片类空间若设置过缩略图版本号，即可使用原图保护功能（文件类空间无效）。如果设置了该参数，上传时会附加文件访问密钥。待文件保存成功后，将无法根据http://空间名.b0.upaiyun.com/savePath直接访问上传的文件，而是需要在URL后面加上缩略图间隔标志符+密钥进行访问。例如，缩略图间隔标志符为!，密钥为abc，上传的文件路径为/dir/sample.jpg，那么该图片的对外访问地址为: http://空间名.b0.upaiyun.com/dir/sample.jpg!abc。注意，原图保护密钥若与缩略图版本号名称相同，则在对外访问时将被视为是缩略图功能，而原图将无法访问，请慎重使用。
params：上传图片时，允许直接对图片进行旋转、裁剪、缩略图等操作，具体请参见图片处理接口。

其他说明

文件上传成功后，可直接通过http://空间名.b0.upaiyun.com/savePath（或设置的自定义域名）访问文件。
图片类空间上传文件后，会返回文件的基本信息，可通过信号的PicInfo参数获取。PicInfo会返回以下信息：
- QString type：图片类型
- qulonglong width：图片宽度
- qulonglong height：图片高度
- qulonglong frames：图片帧数

注意事项

如果空间内savePath已经存在文件，将进行覆盖操作，并且是不可逆的。所以如果需要避免文件被覆盖的情况，可以先通过获取文件信息操作来判断是否已经存在旧文件。
图片类空间只允许上传图片类文件，其他文件上传时将返回“不是图片”的错误。
使用requestError(QNetworkReply::NetworkError, const QString &)信号处理错误。

下载文件

QUpYun *upyun = new QUpYun(BucketName, Operator, Password, parent);
connect(upyun, &QUpYun::requestDownloadFinished, [=] (const QByteArray &data) {
	...
});

upyun->downloadFile(savePath);

参数说明

savePath：又拍云存储中文件的具体保存地址。比如/dir/sample.jpg。

注意事项

下载文件时必须确保空间下存在该文件，否则将返回文件不存在错误。
使用requestError(QNetworkReply::NetworkError, const QString &)信号处理错误。

获取文件信息

QUpYun *upyun = new QUpYun(BucketName, Operator, Password, parent);
connect(upyun, &QUpYun::requestFileInfoFinished, [=] (const FileInfo &fileInfo) {
	...
});

upyun->downloadFile(savePath);

FileInfo可以获得以下文件信息：

QString type：文件类型
qulonglong size：文件大小
QDateTime createDate：创建日期

参数说明

savePath：又拍云存储中文件的具体保存地址。比如/dir/sample.jpg。

其他说明

若文件不存在，则返回错误。
使用requestError(QNetworkReply::NetworkError, const QString &)信号处理错误。

删除文件

QUpYun *upyun = new QUpYun(BucketName, Operator, Password, parent);
connect(upyun, &QUpYun::requestRemoveFileFinished, [=] (bool success) {
	...
});

upyun->removeFile(savePath);

参数说明

savePath：又拍云存储中文件的具体保存地址。比如/dir/sample.jpg。

其他说明

删除文件时必须确保空间下存在该文件，否则将返回文件不存在的错误。
使用requestError(QNetworkReply::NetworkError, const QString &)信号处理错误。

创建目录

QUpYun *upyun = new QUpYun(BucketName, Operator, Password, parent);
connect(upyun, &QUpYun::requestMkdirFinished, [=] (bool success) {
	...
});

upyun->mkdir(dir, autoMkdir);

参数说明

dir：待创建的目录结构。比如/dir1/dir2/dir3/。
autoMkdir：可选的boolean类型参数，表示当不存在父级目录时是否自动创建父级目录（只支持自动创建10级以内的父级目录）。

其他说明

待创建的目录路径必须以斜杠 / 结尾。
创建目录操作可在上传文件时一并完成，功能是相同的。
若空间相同目录下已经存在同名的文件，则将返回不允许创建目录的错误。
使用requestError(QNetworkReply::NetworkError, const QString &)信号处理错误。

删除目录

QUpYun *upyun = new QUpYun(BucketName, Operator, Password, parent);
connect(upyun, &QUpYun::requestRmdirFinished, [=] (bool success) {
	...
});

upyun->rmdir(dir);

参数说明

dir：待删除的目录结构。比如/dir1/dir2/dir3/。

其他说明

该操作只能删除单级目录，不能一次性同时删除多级目录，比如当存在/dir1/dir2/dir3/目录时，不能试图只传递/dir1/来删除所有目录。
若待删除的目录dir下还存在任何文件或子目录，将返回不允许删除的错误。比如当存在/dir1/dir2/dir3/目录时，将无法删除/dir1/dir2/目录。
使用requestError(QNetworkReply::NetworkError, const QString &)信号处理错误。

获取目录文件列表

QUpYun *upyun = new QUpYun(BucketName, Operator, Password, parent);
connect(upyun, &QUpYun::requestLsFinished, [=] (const QList<ItemInfo> &itemInfos) {
	...
});

upyun->ls(dir);

ItemInfo可以获得以下信息：

QString name：文件名字
bool isFolder：是否目录
qulonglong size：文件大小
QDateTime date：文件时间

参数说明

dir：待查询的目录结构。比如/dir1/。

其他说明

若dir目录不存在任何内容时，将返回空列表。
若dir目录不存在时，则将返回不存在目录的错误。
使用requestError(QNetworkReply::NetworkError, const QString &)信号处理错误。

获取空间使用量情况

QUpYun *upyun = new QUpYun(BucketName, Operator, Password, parent);
connect(upyun, &QUpYun::requestBucketUsageFinished, [=] (qulonglong usage) {
	...
});

upyun->bucketUsage();

其他说明

使用量的单位为 byte，比如1M的使用量将以1048576这样的数字返回。
使用requestError(QNetworkReply::NetworkError, const QString &)信号处理错误。

图片处理接口

对于图片的自定义处理，又拍云存储支持以下两种方式：

自定义版本方式
上传图片时传递图片处理参数

虽然两种方式都能够达到图片处理的效果，但存在以下区别：

区别点	自定义版本方式	参数处理方式
是否保留原图	是，各个缩略图都在这个原图的基础上制作	否，只保留处理后的图片，若再使用缩略图版本号的方式来访问（这种方法是可行的），则将在处理后的图片基础上制作
空间使用量	以原图的大小计算使用量，后续各个版本的缩略图都不会计算在用户的空间使用量中	以处理后的图片大小计算使用量，大小视具体的处理参数而定
灵活性	可通过修改自定义版本的参数来满足变化的需求，参数修改后若没有自动刷新缓存，则可以手动强制刷新来确保新参数生效	只能调整代码中的处理参数，且原先保存的图片无法自动更新

我们更推荐大家使用自定义版本的方式对图片进行处理，但您可以根据自己业务的使用场景来选用合适的方式。

以下内容只是介绍传递图片处理参数的方法。

缩略图

QUpYun *upyun = new QUpYun(BucketName, Operator, Password, parent);

// 设置缩略图的参数
QUpYun::RequestParams params;

// 设置缩略图类型，必须搭配缩略图参数值（X_GMKERL_VALUE）使用，否则无效
params.insert(QUpYun::extraParamHeader(QUpYun::X_GMKERL_TYPE), QUpYun::extraParamHeader(QUpYun::FIX_BOTH));

// 设置缩略图参数值，必须搭配缩略图类型（X_GMKERL_TYPE）使用，否则无效
params.insert(QUpYun::extraParamHeader(QUpYun::X_GMKERL_VALUE), QVariant("150x150"));

// 设置缩略图的质量，默认 95
params.insert(QUpYun::extraParamHeader(QUpYun::X_GMKERL_QUALITY), QVariant("95"));

connect(upyun, &QUpYun::requestUploadFinished, [=] (bool success, const PicInfo &pi) {
	...
});

upyun->uploadFile(savePath,
                  file,
				  autoMkdir,
				  appendFileMD5,
				  secret,
				  params);

参数说明

savePath：上传到的又拍云存储的具体地址。
- 比如/dir/sample.jpg表示以sample.jpg为文件名保存到/dir目录下；
- 若保存路径为/sample.jpg，则表示保存到根目录下；
- 注意savePath必须以/开始，下同。
第二个参数可以是QString或QFile *类型，即需要上传的文件路径或文件本身。
autoMkdir：可选的bool类型参数，表示当不存在父级目录时是否自动创建父级目录（只支持自动创建10级以内的父级目录）。
appendFileMD5：可选的bool类型参数，表示是否需要附加文件的MD5校验值。如果设置了该参数，上传时会附加被上传文件的MD5校验值。若又拍云服务器计算而得的文件MD5值与此不同，则服务器返回406 Not Acceptable错误。对于需要确保上传文件的完整性要求的业务，可以设置该参数。
fileSecret：可选的QString类型参数，表示是否添加文件访问密钥。该访问密钥仅支持图片空间。图片类空间若设置过缩略图版本号，即可使用原图保护功能（文件类空间无效）。如果设置了该参数，上传时会附加文件访问密钥。待文件保存成功后，将无法根据http://空间名.b0.upaiyun.com/savePath直接访问上传的文件，而是需要在URL后面加上缩略图间隔标志符+密钥进行访问。例如，缩略图间隔标志符为!，密钥为abc，上传的文件路径为/dir/sample.jpg，那么该图片的对外访问地址为: http://空间名.b0.upaiyun.com/dir/sample.jpg!abc。注意，原图保护密钥若与缩略图版本号名称相同，则在对外访问时将被视为是缩略图功能，而原图将无法访问，请慎重使用。
params：自定义组合的图片处理参数，现提供的参数有：
- QUpYun::X_GMKERL_THUMBNAIL：自定义缩略图版本号，需要通过upyun后台来创建和配置；
- QUpYun::X_GMKERL_TYPE：缩略图类型，必须搭配缩略图参数值（QUpYun::X_GMKERL_VALUE）使用，否则无效；
- QUpYun::X_GMKERL_VALUE：缩略图参数值，必须搭配缩略图类型（QUpYun::X_GMKERL_TYPE）使用，否则无效；
- QUpYun::X_GMKERL_QUALITY：缩略图的质量，默认 95；
- QUpYun::X_GMKERL_UNSHARP：缩略图的锐化，默认锐化（true）；
- QUpYun::X_GMKERL_CROP：图片裁剪；
- QUpYun::X_GMKERL_ROTATE：图片旋转；
- 所有提供的预定义参数都必须使用QUpYun::extraParamHeader函数处理。

其他说明

图片处理参数的具体使用方法，请参考标准API上传文件。
缩略图功能只能处理图片文件；若上传非图片文件且传递了图片处理参数时，将返回不是图片的错误。
使用requestError(QNetworkReply::NetworkError, const QString &)信号处理错误。

图片裁剪

QUpYun *upyun = new QUpYun(BucketName, Operator, Password, parent);

// 设置缩略图的参数
QUpYun::RequestParams params;

// 设置图片裁剪，参数格式：x,y,width,height
params.insert(QUpYun::extraParamHeader(QUpYun::X_GMKERL_CROP), QVariant("0,0,100,100"));

connect(upyun, &QUpYun::requestUploadFinished, [=] (bool success, const PicInfo &pi) {
	...
});

upyun->uploadFile(savePath,
                  file,
				  autoMkdir,
				  appendFileMD5,
				  secret,
				  params);

参数说明

savePath：要保存到又拍云存储的具体地址。
第二个参数可以是QString或QFile *类型，即需要上传的文件路径或文件本身。
autoMkdir：可选的bool类型参数，表示当不存在父级目录时是否自动创建父级目录（只支持自动创建10级以内的父级目录）。
appendFileMD5：可选的bool类型参数，表示是否需要附加文件的MD5校验值。
fileSecret：可选的QString类型参数，表示是否添加文件访问密钥。
params：自定义组合的图片处理参数。

其他说明

参数格式暂时只支持：x,y,width,height。比如0,0,100,100表示从左上角顶点裁剪100px × 100px大小的图片
具体可参考图片裁剪

图片旋转

QUpYun *upyun = new QUpYun(BucketName, Operator, Password, parent);

// 设置缩略图的参数
QUpYun::RequestParams params;

// 设置图片旋转：只接受"auto"，"90"，"180"，"270"四种参数
params.insert(QUpYun::extraParamHeader(QUpYun::X_GMKERL_ROTATE), QUpYun::extraParamHeader(QUpYun::VALUE_ROTATE_90));

connect(upyun, &QUpYun::requestUploadFinished, [=] (bool success, const PicInfo &pi) {
	...
});

upyun->uploadFile(savePath,
                  file,
				  autoMkdir,
				  appendFileMD5,
				  secret,
				  params);

参数说明

savePath：要保存到又拍云存储的具体地址。
第二个参数可以是QString或QFile *类型，即需要上传的文件路径或文件本身。
autoMkdir：可选的bool类型参数，表示当不存在父级目录时是否自动创建父级目录（只支持自动创建10级以内的父级目录）。
appendFileMD5：可选的bool类型参数，表示是否需要附加文件的MD5校验值。
fileSecret：可选的QString类型参数，表示是否添加文件访问密钥。
params：自定义组合的图片处理参数。

其他说明

暂时只接受"auto"，"90"，"180"，"270"四种参数，其中auto处理时需要图片包含EXIF信息
具体可参考图片旋转

Name		Name	Last commit message	Last commit date
Latest commit History 6 Commits
source		source
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md

License

devbean/QUpYun

Folders and files

Latest commit

History

Repository files navigation

QUpYun - 又拍云Qt SDK

目录

云存储基础接口

准备操作

创建空间

初始化QUpYun

选择最优的接入点

上传文件

基本用法

参数说明

其他说明

注意事项

下载文件

参数说明

注意事项

获取文件信息

参数说明

其他说明

删除文件

参数说明

其他说明

创建目录

参数说明

其他说明

删除目录

参数说明

其他说明

获取目录文件列表

参数说明

其他说明

获取空间使用量情况

其他说明

图片处理接口

缩略图

参数说明

其他说明

图片裁剪

参数说明

其他说明

图片旋转

参数说明

其他说明

About

Resources

License

Stars

Watchers

Forks

Languages