公有云对象存储 S3 C SDK 文档

一 SDK说明

本文主要介绍 公有云对象存储 C语言 s3-API接口，包括：

• 接口功能和调用方法
• 接口数据类型的定义
• 接口参数和返回值描述。

二 安装 SDK

C SDK 名为 libs3，有三种安装方式:

• 包管理工具安装
• 源码编译安装
• 压缩包安装

2.1 包管理工具安装（不同系统使用工具有所区别）

• CentOS、Redhat、fedora

sudo yum install -y libs3*

• debian、ubuntu

sudo apt-get install -y libs3*

会安装 libs3、libs3-devel;
SDK依赖的头文件通常在 /usr/include/libs3.h
SDK依赖的动态库通常在 /usr/lib64/libs3.so.2.0
各个系统会有所差别

s3 help 
---------------------
s3 is a program for performing single requests to Amazon S3.

 Options:

   Command Line:
   .....

s3安装成功

• 使用s3 工具，测试环境

1. 配置环境变量

export S3_ACCESS_KEY_ID="your access key"
export S3_SECRET_ACCESS_KEY="your secret key"
export S3_HOSTNAME="your s3 server hostname"

2. 运行示例

#获取用户所有的bucket信息
s3 -u list 
#获取 mybucket 下对象信息
s3 -u list mybucket 

• 开发者调用libs3接口

请参照 示例代码
或参照下文

2.2 源码安装

由于libs3依赖libxml2和libcurl，所以需要先对其进行安装。

• 安装依赖

1. 步骤
   1、下载libxml2(2.9.2版本)
   2、编译安装libxml2
   3、下载libcurl(curl-7.48.0版本)
   4、编译安装libcurl
2. 代码

cd;
wget ftp://xmlsoft.org/libxml2/libxml2-2.9.2.tar.gz;
tar -zxvf libxml2-2.9.2.tar.gz;
cd libxml2-2.9.2;
./configure;
make & make install

cd;
wget https://curl.haxx.se/download/curl-7.48.0.tar.gz
tar -zxvf curl-7.48.0.tar.gz
./configure --enable-shared
make 
make install

• 以上依赖包亦可以通过包管理工具安装

1. CentOS、Redhat、fedora

sudo yum install -y libxml2*
sudo yum install -y libcurl*

2. debian、ubuntu

sudo apt-get install -y libxml2*
sudo apt-get install -y libcurl*

依赖包安装完成

• 安装libs3库

1. 步骤
   1、下载libs3-2.0.zip，https://github.com/bji/libs3/tree/2.0 解压
   2、进入libs3-2.0目录
   3、make
   4、make install

cd;
git clone https://github.com/bji/libs3/tree/2.0;
cd libs3-2.0;
make & make install

2. 验证：

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$HOME/libs3-2.0/build/lib ;
s3 help

输入s3命令，给出命令提示，则证明安装libs3成功。

2.3 压缩包安装

• 联系中移物联网 开放平台部工作人员，获取压缩包centos*.zip（不同系统所需的库有所区别）

• 解压sdk到某个目录得到 libs3及相关依赖库

• 解压完成可以进入demo参考示例代码。其中s3.c包含了所有的示例，samples.c中包含了常用的示例。

可以通过修改makefile进行编译不同的示例代码。

• 如果运行s3.c示例，需要配置sdk测试环境

export S3_ACCESS_KEY_ID="your access key"
export S3_SECRET_ACCESS_KEY="your secret key"
export S3_HOSTNAME="your s3 server hostname"

• 运行示例程序

如：在demo目录下执行 ./s3 -u list 获取用户所有的bucket信息
./s3 -u list mybucket 获取bucket下对象信息
其他示例程序可以通过输入./s3 查看详细的帮助信息。

• 如果运行samples.c示例，需要修改samples.c中以下内容：

const char *hostname = "your s3 server hostname";
static const char *accessKeyIdG = "your access key";
static const char *secretAccessKeyG = "your secret key";

• 运行示例程序

#获取用户所有的bucket信息
cd ~/centosxx/demo/
./s3 -u list 

** 确认您已经理解对象存储基本概念，如s3、Bucket、Object、Endpoint、AccessKey和SecretKey等。**

三 公共接口

#include <libs3.h>

libs3实现、封装异步调用的S3接口，在调用不同的接口的时候，都需要进行初始化、设置回调等步骤，本节对这些公共步骤进行讲解。
*本节大部分示例代码引用自 s3.c

3.1 初始化

• 接口描述

1. 功能
   初始化，在调用具体s3接口函数之前必须先调用此函数对libs3进行初始化。

2. 定义

S3Status S3_initialize(const char *userAgentInfo, int flags,
                       const char *defaultS3HostName);

3. 参数

• 示例代码

static void S3_init()
{
    S3Status status;
    const char *hostname = getenv("S3_SERVER_HOSTNAME");
    
    if ((status = S3_initialize("s3", S3_INIT_ALL, hostname)) != S3StatusOK) {
        fprintf(stderr, "Failed to initialize libs3: %s\n", S3_get_status_name(status));
        exit(-1);
    }
}

3.2 取消初始化

• 接口描述

1. 功能
   在调用初始化函数后,如不再使用s3,必须使用此函数进行取消初始化。

2. 定义

void S3_deinitialize();

3. 参数
   无

• 示例代码

S3_deinitialize();

3.3 获取错误信息

• 接口描述

1. 功能
   获取错误描述信息。

2. 定义

const char *S3_get_status_name(S3Status status);

3. 参数

• 示例代码

printf(S3_get_status_name(status));

3.4 响应回调函数

• 接口描述

1. 功能
   响应完全接收时调用的回调函数。

2. 定义

S3Status (S3ResponsePropertiesCallback) (const S3ResponseProperties *properties, void *callbackData);

3. 参数

• 示例代码：

static S3Status responsePropertiesCallback
    (const S3ResponseProperties *properties, void *callbackData)
{
    (void) callbackData;

    if (!showResponsePropertiesG) {
        return S3StatusOK;
    }

#define print_nonnull(name, field)                                 \
    do {                                                           \
        if (properties-> field) {                                  \
            printf("%s: %s\n", name, properties-> field);          \
        }                                                          \
    } while (0)
    
    print_nonnull("Content-Type", contentType);
    print_nonnull("Request-Id", requestId);
    print_nonnull("Request-Id-2", requestId2);
    if (properties->contentLength > 0) {
        printf("Content-Length: %lld\n", 
               (unsigned long long) properties->contentLength);
    }
    print_nonnull("Server", server);
    print_nonnull("ETag", eTag);
    if (properties->lastModified > 0) {
        char timebuf[256];
        time_t t = (time_t) properties->lastModified;
        // gmtime is not thread-safe but we don't care here.
        strftime(timebuf, sizeof(timebuf), "%Y-%m-%dT%H:%M:%SZ", gmtime(&t));
        printf("Last-Modified: %s\n", timebuf);
    }
    int i;
    for (i = 0; i < properties->metaDataCount; i++) {
        printf("x-amz-meta-%s: %s\n", properties->metaData[i].name,
               properties->metaData[i].value);
    }

    return S3StatusOK;
}

3.5 响应完成回调函数

• 接口描述

1. 功能
   响应完成时回调该函数。

2. 定义

void (S3ResponseCompleteCallback)(S3Status status, const S3ErrorDetails *errorDetails, void *callbackData);

3. 参数

• 示例代码

static void responseCompleteCallback(S3Status status,
                                     const S3ErrorDetails *error, 
                                     void *callbackData)
{
    if (!callbackData) {
        //do something;
    }

    statusG = status;
    // Compose the error details message now, although we might not use it.
    // Can't just save a pointer to [error] since it's not guaranteed to last
    // beyond this callback
    int len = 0;
    if (error && error->message) {
        len += snprintf(&(errorDetailsG[len]), sizeof(errorDetailsG) - len,
                        "  Message: %s\n", error->message);
    }
    if (error && error->resource) {
        len += snprintf(&(errorDetailsG[len]), sizeof(errorDetailsG) - len,
                        "  Resource: %s\n", error->resource);
    }
    if (error && error->furtherDetails) {
        len += snprintf(&(errorDetailsG[len]), sizeof(errorDetailsG) - len,
                        "  Further Details: %s\n", error->furtherDetails);
    }
    if (error && error->extraDetailsCount) {
        len += snprintf(&(errorDetailsG[len]), sizeof(errorDetailsG) - len,
                        "%s", "  Extra Details:\n");
        int i;
        for (i = 0; i < error->extraDetailsCount; i++) {
            len += snprintf(&(errorDetailsG[len]), 
                            sizeof(errorDetailsG) - len, "    %s: %s\n", 
                            error->extraDetails[i].name,
                            error->extraDetails[i].value);
        }
    }
}

3.6 获取bucket列表回调函数

• 接口描述

1. 功能
   获取bucket列表的回调函数。

2. 定义

S3Status (S3ListServiceCallback)(const char *ownerId, 
                                         const char *ownerDisplayName,
                                         const char *bucketName,
                                         int64_t creationDateSeconds,
                                         void *callbackData);

3. 参数

• 示例代码

static S3Status listServiceCallback(const char *ownerId, 
                                    const char *ownerDisplayName,
                                    const char *bucketName,
                                    int64_t creationDate, void *callbackData)
{
    list_service_data *data = (list_service_data *) callbackData;

    if (!data->headerPrinted) {
        data->headerPrinted = 1;
        printListServiceHeader(data->allDetails);
    }

    char timebuf[256];
    if (creationDate >= 0) {
        time_t t = (time_t) creationDate;
        strftime(timebuf, sizeof(timebuf), "%Y-%m-%dT%H:%M:%SZ", gmtime(&t));
    }
    else {
        timebuf[0] = 0;
    }

    printf("%-56s  %-20s", bucketName, timebuf);
    if (data->allDetails) {
        printf("  %-64s  %-12s", ownerId ? ownerId : "", 
               ownerDisplayName ? ownerDisplayName : "");
    }
    printf("\n");

    return S3StatusOK;
}

3.7 上传对象回调函数

• 接口描述

1. 功能
   进行上传对象操作时的回调函数。

2. 定义

int (S3PutObjectDataCallback)(int bufferSize, char *buffer, void *callbackData);

3. 参数

示例代码：

static int putObjectDataCallback(int bufferSize, char *buffer, void *callbackData)
{
    put_object_callback_data *data = 
        (put_object_callback_data *) callbackData;
    
    int ret = 0;

    if (data->contentLength) {
        int toRead = ((data->contentLength > (unsigned) bufferSize) ?
                      (unsigned) bufferSize : data->contentLength);
        if (data->gb) {
            growbuffer_read(&(data->gb), toRead, &ret, buffer);
        }
        else if (data->infile) {
            ret = fread(buffer, 1, toRead, data->infile);
        }
    }

    data->contentLength -= ret;

    if (data->contentLength && !data->noStatus) {
        // Avoid a weird bug in MingW, which won't print the second integer
        // value properly when it's in the same call, so print separately
        printf("%llu bytes remaining ", 
               (unsigned long long) data->contentLength);
        printf("(%d%% complete) ...\n",
               (int) (((data->originalContentLength - 
                        data->contentLength) * 100) /
                      data->originalContentLength));
    }

    return ret;
}

3.8 获取对象回调函数

• 接口描述

1. 功能
   获取对象时的回调函数。

2. 定义

S3Status (S3GetObjectDataCallback)(int bufferSize, const char *buffer, void *callbackData);

3. 参数

• 示例代码

static S3Status getObjectDataCallback(int bufferSize, const char *buffer,
                                      void *callbackData)
{
    FILE *outfile = (FILE *) callbackData;

    size_t wrote = fwrite(buffer, 1, bufferSize, outfile);
    
    return ((wrote < (size_t) bufferSize) ? 
            S3StatusAbortedByCallback : S3StatusOK);
}

3.9 list bucket中对象回调函数

• 接口描述

1. 功能
   列举bucket中对象时的回调函数。

2. 定义

S3Status (S3ListBucketCallback)(int isTruncated,
                                        const char *nextMarker,
                                        int contentsCount, 
                                        const S3ListBucketContent *contents,
                                        int commonPrefixesCount,
                                        const char **commonPrefixes,
                                        void *callbackData);

3. 参数

• 示例代码

static S3Status listBucketCallback(int isTruncated, const char *nextMarker,
                                   int contentsCount, 
                                   const S3ListBucketContent *contents,
                                   int commonPrefixesCount,
                                   const char **commonPrefixes,
                                   void *callbackData)
{
    list_bucket_callback_data *data = 
        (list_bucket_callback_data *) callbackData;

    data->isTruncated = isTruncated;
    // This is tricky.  S3 doesn't return the NextMarker if there is no
    // delimiter.  Why, I don't know, since it's still useful for paging
    // through results.  We want NextMarker to be the last content in the
    // list, so set it to that if necessary.
    if ((!nextMarker||!nextMarker[0]) && contentsCount) {
        nextMarker = contents[contentsCount - 1].key;
    }
    if (nextMarker) {
        snprintf(data->nextMarker, sizeof(data->nextMarker), "%s", 
                 nextMarker);
    }
    else {
        data->nextMarker[0] = 0;
    }
    
    if (contentsCount && !data->keyCount) {
        printListBucketHeader(data->allDetails);
    }

    int i;
    for (i = 0; i < contentsCount; i++) {
        const S3ListBucketContent *content = &(contents[i]);
        char timebuf[256];
        if (0) {
            time_t t = (time_t) content->lastModified;
            strftime(timebuf, sizeof(timebuf), "%Y-%m-%dT%H:%M:%SZ",
                     gmtime(&t));
            printf("\nKey: %s\n", content->key);
            printf("Last Modified: %s\n", timebuf);
            printf("ETag: %s\n", content->eTag);
            printf("Size: %llu\n", (unsigned long long) content->size);
            if (content->ownerId) {
                printf("Owner ID: %s\n", content->ownerId);
            }
            if (content->ownerDisplayName) {
                printf("Owner Display Name: %s\n", content->ownerDisplayName);
            }
        }
        else {
            time_t t = (time_t) content->lastModified;
            strftime(timebuf, sizeof(timebuf), "%Y-%m-%dT%H:%M:%SZ", 
                     gmtime(&t));
            char sizebuf[16];
            if (content->size < 100000) {
                sprintf(sizebuf, "%5llu", (unsigned long long) content->size);
            }
            else if (content->size < (1024 * 1024)) {
                sprintf(sizebuf, "%4lluK", 
                        ((unsigned long long) content->size) / 1024ULL);
            }
            else if (content->size < (10 * 1024 * 1024)) {
                float f = content->size;
                f /= (1024 * 1024);
                sprintf(sizebuf, "%1.2fM", f);
            }
            else if (content->size < (1024 * 1024 * 1024)) {
                sprintf(sizebuf, "%4lluM", 
                        ((unsigned long long) content->size) / 
                        (1024ULL * 1024ULL));
            }
            else {
                float f = (content->size / 1024);
                f /= (1024 * 1024);
                sprintf(sizebuf, "%1.2fG", f);
            }
            printf("%-50s  %s  %s", content->key, timebuf, sizebuf);
            if (data->allDetails) {
                printf("  %-34s  %-64s  %-12s",
                       content->eTag, 
                       content->ownerId ? content->ownerId : "",
                       content->ownerDisplayName ? 
                       content->ownerDisplayName : "");
            }
            printf("\n");
        }
    }

    data->keyCount += contentsCount;

    for (i = 0; i < commonPrefixesCount; i++) {
        printf("\nCommon Prefix: %s\n", commonPrefixes[i]);
    }

    return S3StatusOK;
}

四 bucket操作

4.1 test bucket

• 接口描述

1. 功能
   检查bucket是否存在，如果存在则返回bucket的location。

2. 定义

void S3_test_bucket(S3Protocol protocol, S3UriStyle uriStyle,
                    const char *accessKeyId, const char *secretAccessKey,
                    const char *hostName, const char *bucketName,
                    int locationConstraintReturnSize,
                    char *locationConstraintReturn,
                    S3RequestContext *requestContext,
                    const S3ResponseHandler *handler, void *callbackData);

3. 参数

4.2 create bucket

• 接口描述

1. 功能
   创建bucket。

2. 定义

void S3_create_bucket(S3Protocol protocol, const char *accessKeyId,
                      const char *secretAccessKey, const char *hostName,
                      const char *bucketName, S3CannedAcl cannedAcl,
                      const char *locationConstraint,
                      S3RequestContext *requestContext,
                      const S3ResponseHandler *handler, void *callbackData);

3. 参数

4.3 delete bucket

• 接口描述

1. 功能
   删除一个已经存在的bucket。
   *必须是空bucket才能删除

2. 定义

void S3_delete_bucket(S3Protocol protocol, S3UriStyle uriStyle,
                      const char \*accessKeyId, const char \*secretAccessKey,
                      const char \*hostName, const char \*bucketName,
                      S3RequestContext \*requestContext,
                      const S3ResponseHandler \*handler, void \*callbackData);

3. 参数

4.4 list bucket

• 接口描述

1. 功能
   列举bucket中所有的对象。

2. 定义

void S3_list_bucket(const S3BucketContext \*bucketContext,
                    const char \*prefix, const char \*marker, 
                    const char \*delimiter, int maxkeys,
                    S3RequestContext \*requestContext,
                    const S3ListBucketHandler \*handler, void \*callbackData);

3. 参数

五 object操作

5.1 put object

• 接口描述

1. 功能
   上传对象。

2. 定义

void S3_put_object(const S3BucketContext \*bucketContext, const char \*key,
                   uint64_t contentLength,
                   const S3PutProperties \*putProperties,
                   S3RequestContext \*requestContext,
                   const S3PutObjectHandler \*handler, void \*callbackData);

3. 参数

5.2 copy object

• 接口描述

1. 功能
   拷贝对象到目标桶并命名。

2. 定义

void S3_copy_object(const S3BucketContext \*bucketContext,
                    const char \*key, const char \*destinationBucket,
                    const char \*destinationKey,
                    const S3PutProperties \*putProperties,
                    int64_t \*lastModifiedReturn, int eTagReturnSize,
                    char \*eTagReturn, S3RequestContext \*requestContext,
                    const S3ResponseHandler \*handler, void \*callbackData);

3. 参数

5.3 get object

• 接口描述

1. 功能
   下载对象。
2. 定义

void S3_get_object(const S3BucketContext \*bucketContext, const char \*key,
                   const S3GetConditions \*getConditions,
                   uint64_t startByte, uint64_t byteCount,
                   S3RequestContext \*requestContext,
                   const S3GetObjectHandler \*handler, void \*callbackData);

3. 参数

5.4 head object

• 接口描述

1. 功能
   获取对象的属性值。

2. 定义

void S3_head_object(const S3BucketContext \*bucketContext, const char \*key,
                    S3RequestContext \*requestContext,
                    const S3ResponseHandler \*handler, void \*callbackData);

3. 参数

5.5 delete object

• 接口描述

1. 功能
   删除对象。

2. 定义

void S3_delete_object(const S3BucketContext \*bucketContext, const char \*key,
                      S3RequestContext \*requestContext,
                      const S3ResponseHandler \*handler, void \*callbackData);

3. 参数

六 访问控制列表操作

6.1 get acl

• 接口描述

1. 功能
   获取bucket或object的访问控制权限。

2. 定义

void S3_get_acl(const S3BucketContext \*bucketContext, const char \*key, 
                char \*ownerId, char \*ownerDisplayName,
                int \*aclGrantCountReturn, S3AclGrant \*aclGrants, 
                S3RequestContext \*requestContext,
                const S3ResponseHandler \*handler, void \*callbackData);

3. 参数

6.2 set acl

• 接口描述

1. 功能
   设置bucket或object的权限。

2. 定义

void S3_set_acl(const S3BucketContext \*bucketContext, const char \*key, 
                const char \*ownerId, const char \*ownerDisplayName,
                int aclGrantCount, const S3AclGrant \*aclGrants, 
                S3RequestContext \*requestContext,
                const S3ResponseHandler \*handler, void \*callbackData);

3. 参数

七 服务访问日志管理

7.1 get_server_access_logging

• 接口描述

1. 功能
   获取一个bucket的服务访问日志配置。

2. 定义

void S3_get_server_access_logging(const S3BucketContext \*bucketContext,
                                  char \*targetBucketReturn,
                                  char \*targetPrefixReturn,
                                  int \*aclGrantCountReturn, 
                                  S3AclGrant \*aclGrants,
                                  S3RequestContext \*requestContext,
                                  const S3ResponseHandler \*handler,
                                  void \*callbackData);

3. 参数

7.2 set_server_access_logging

• 接口描述

1. 功能
   设置一个bucket的服务访问日志配置。

2. 定义

void S3_set_server_access_logging(const S3BucketContext \*bucketContext,
                                  const char \*targetBucket, 
                                  const char \*targetPrefix, int aclGrantCount, 
                                  const S3AclGrant \*aclGrants, 
                                  S3RequestContext \*requestContext,
                                  const S3ResponseHandler \*handler,
                                  void \*callbackData);

3. 参数