全部产品
对象存储 OSS

客户端

更新时间:2017-06-07 13:26:11   分享:   

OSS MEDIA C SDK分为客户端,服务端和HLS三部分,下面主要介绍客户端的相关操作,其他的操作请访问后面章节

接口

客户端相关的操作接口都位于oss_media_file.h中,目前提供的接口有:

  • oss_media_file_open
  • oss_media_file_stat
  • oss_media_file_tell
  • oss_media_file_seek
  • oss_media_file_read
  • oss_media_file_write
  • oss_media_file_close

下面会详细介绍各个接口的功能和注意事项

基础结构体介绍

  1. /**
  2. * OSS MEDIA FILE的元数据,包括文件长度,位置和类型
  3. */
  4. typedef struct {
  5. int64_t length;
  6. int64_t pos;
  7. char *type;
  8. } oss_media_file_stat_t;
  9. /**
  10. * OSS MEDIA FILE的属性信息
  11. */
  12. typedef struct oss_media_file_s {
  13. void *ipc;
  14. char *endpoint;
  15. int8_t is_cname;
  16. char *bucket_name;
  17. char *object_key;
  18. char *access_key_id;
  19. char *access_key_secret;
  20. char *token;
  21. char *mode;
  22. oss_media_file_stat_t _stat;
  23. time_t expiration;
  24. auth_fn_t auth_func;
  25. } oss_media_file_t;

注:

  • type,文件类型, Normal或者Appendable
  • ipc,用于设置设备唯一标识,根据用户的需要可以在auth func中使用,如果用不到可以忽略。
  • endpoint,比如oss-cn-hangzhou.aliyuncs.com。
  • is_cname,是否使用了CNAME
  • bucket_name,OSS上存储空间的名称
  • object_key,OSS上文件的名称
  • access_key_id,阿里云提供的访问控制的access key id,这里有两种使用方式,第一种,使用主账号或者子账号的永久access key id,此时后面的token需要设置为NULL,第二种使用通过get_token获取到的临时access key id。
  • access_key_secret,阿里云提供的访问控制的access key secret,这里也有两种使用方式,第一种,使用主账号或者子账号的永久access key secret,此时后面的token需要设置为NULL,第二种使用通过get_token获取到的临时access key secret。access_key_id和access_key_secret必须同时使用同种方式。
  • token,如果是使用主账号或者子账号的永久access key id和access key secret,这里需要设置为NULL。如果是终端设备上传下载资源,此时需要应用服务器给终端设备提供临时的访问权限,可以通过服务端的get_token获取到临时的access_key_id,access_key_secret和token。如果用户设置了token不为NULL,则会认为是使用了临时access key id,临时access key secrety和临时token,所以,如果不想使用临时token,请将其设置为NULL。
  • expiration,授权失效的时间,首次授权后,后续超过失效时间后才会再次授权
  • auth,授权函数,用户需要实现一个函数,在这个函数内部为host,bucket,token等赋值
  • mode,读写模式

初始化

  1. /**
  2. * @brief 初始化oss media
  3. * @note 在程序开始的时候应该首先调用此接口,初始化OSS MEDIA C SDK
  4. * @return:
  5. * 返回0时表示成功
  6. * 否则, 表示出现了错误,可能导致失败的原因包括:内存不足,apr、curl版本太低等
  7. */
  8. int oss_media_init(aos_log_level_e log_level);

注:

销毁

  1. /**
  2. * @brief 销毁oss meida
  3. * @note 在程序结束的时候应该最后调用此接口,销毁OSS MEDIA C SDK
  4. */
  5. void oss_media_destroy();

注:

打开文件

  1. /**
  2. * @brief 打开一个oss文件
  3. * @param[in] bucket_name oss上存储文件的存储空间名称
  4. * @param[in] object_key oss上的文件名称
  5. * @param[in] mode:
  6. * 'r': 读模式
  7. * 'w': 覆盖写模式
  8. * 'a': 追加写模式
  9. * notes: 不允许组合使用
  10. * @param[in] auth_func 授权函数,设置access_key_id/access_key_secret等
  11. * @return:
  12. * 返回非NULL时成功,否则失败
  13. */
  14. oss_media_file_t* oss_media_file_open(char *bucket_name,
  15. char *object_key,
  16. char *mode,
  17. auth_fn_t auth_func);

注:

  • mode,支持只读、覆盖写、追加写三种模式,不支持组合模式。读模式,打开文件后,一次读取部分文件内容,完整内容一般需要多次读取;覆盖写,打开文件后,一次写入完整的文件内容,可以多次写入,但是最后一次写会覆盖的前面写入的内容;追加写,打开文件后,可以多次追加写文件。
  • 示例代码参考:GitHub

关闭文件

  1. /**
  2. * @brief 关闭oss文件
  3. */
  4. void oss_media_file_close(oss_media_file_t *file);

注:

写文件

  1. /**
  2. * @brief 写文件到oss上
  3. * @return:
  4. * 成功时返回写入的数据大小,返回-1表示写失败
  5. */
  6. int64_t oss_media_file_write(oss_media_file_t *file, const void *buf, int64_t nbyte);

示例程序:

  1. /* 授权函数 */
  2. static void auth_func(oss_media_file_t *file) {
  3. file->endpoint = "your endpoint";
  4. file->is_cname = 0;
  5. file->access_key_id = "阿里云提供的access key id或者临时access key id";
  6. file->access_key_secret = "阿里云提供的access key secret或者临时access key secret";
  7. file->token = "通过get_token接口获取到得临时token";
  8. /* 本次授权的有效时间 */
  9. file->expiration = time(NULL) + 300;
  10. }
  11. static void write_file() {
  12. oss_clean(g_filename);
  13. int64_t write_size;
  14. oss_media_file_t *file;
  15. char *bucket_name = "<your bucket name>";
  16. char *key = "<your object key>";
  17. char *content = "aliyun oss media c sdk";
  18. /* 打开一个文件 */
  19. file = oss_media_file_open(bucket_name, key, "w", auth_func);
  20. if (!file) {
  21. printf("open media file failed\n");
  22. return;
  23. }
  24. /* 写文件 */
  25. write_size = oss_media_file_write(file, content, strlen(content));
  26. if (-1 != write_size) {
  27. printf("write %" PRId64 " bytes succeeded\n", write_size);
  28. } else {
  29. oss_media_file_close(file);
  30. printf("write failed\n");
  31. return;
  32. }
  33. /* 关闭文件,释放资源 */
  34. oss_media_file_close(file);
  35. }

注:

  • 示例中,打开文件的模式为覆盖写("w"),如果多次写入,后一次写会覆盖前一次写;如果需要追加写,打开文件的模式请指定为追加写("a");。
  • 示例代码参考:GitHub

读文件

  1. /**
  2. * @brief 读取固定数目nbyte的数据
  3. * @note buf的大小应该大于等于nbyte + 1
  4. * @return:
  5. * 返回0时表示成功
  6. * 否则, 返回-1时表示出现了错误,可能导致失败的原因包括:不是以读模式打开的文件,无法连接OSS,无权限读OSS等
  7. */
  8. int64_t oss_media_file_read(oss_media_file_t *file, void *buf, int64_t nbyte);

示例程序:

  1. int ntotal, nread, nbuf = 16;
  2. char buf[nbuf];
  3. char *content;
  4. char *bucket_name = "<your bucket name>";
  5. char *key = "<your object key>";
  6. oss_media_file_t *file;
  7. /* 打开文件 */
  8. file = oss_media_file_open(bucket_name, key, "r", auth_func);
  9. if (!file) {
  10. printf("open media file failed\n");
  11. return;
  12. }
  13. /* 读文件 */
  14. content = malloc(stat.length + 1);
  15. ntotal = 0;
  16. while ((nread = oss_media_file_read(file, buf, nbuf)) > 0) {
  17. memcpy(content + ntotal, buf, nread);
  18. ntotal += nread;
  19. }
  20. content[ntotal] = '\0';
  21. /* 关闭文件 */
  22. oss_media_file_close(file);
  23. free(content);
  24. printf("oss media c sdk read object succeeded\n");
  25. }

注:

管理文件

OSS MEDIA FILE也支持tell,seek和stat操作

  1. /**
  2. * @brief 获取当前OSS MEDIA FILE的位置
  3. * @return:
  4. * 返回0时表示成功
  5. * 否则, 返回-1时表示出现了错误,可能导致失败的原因包括:不是以读模式打开的文件,无法连接OSS,无权限读OSS等
  6. */
  7. int64_t oss_media_file_tell(oss_media_file_t *file);
  8. /**
  9. * @brief 设置OSS MEDIA FILE的指针到指定位置
  10. * @return:
  11. * 返回0时表示成功
  12. * 否则, 返回-1时表示出现了错误,可能导致失败的原因包括:不是以读模式打开的文件,无法连接OSS,无权限读OSS等
  13. */
  14. int64_t oss_media_file_seek(oss_media_file_t *file, int64_t offset);
  15. /**
  16. * @brief 获取OSS MEDIA FILE的元数据
  17. * @return:
  18. * 返回0时表示成功
  19. * 否则, 返回-1时表示出现了错误,可能导致失败的原因包括:无法连接OSS,无权限读OSS等
  20. */
  21. int oss_media_file_stat(oss_media_file_t *file, oss_media_file_stat_t *stat);

示例程序:

  1. static void seek_tell_stat_file() {
  2. int ntotal, nread, nbuf = 16;
  3. char buf[nbuf];
  4. char *bucket_name = "<your bucket name>";
  5. char *key = "<your object key>";
  6. oss_media_file_t *file;
  7. /* 打开文件 */
  8. file = oss_media_file_open(bucket_name, key, "r", auth_func);
  9. if (!file) {
  10. printf("open media file failed\n");
  11. return;
  12. }
  13. /* 获取文件meta信息 */
  14. oss_media_file_stat_t stat;
  15. if (0 != oss_media_file_stat(file, &stat)) {
  16. oss_media_file_close(file);
  17. oss_media_file_free(file);
  18. printf("stat media file[%s] failed\n", file->object_key);
  19. return;
  20. }
  21. printf("file [name=%s, length=%ld, type=%s]",
  22. file->object_key, stat.length, stat.type);
  23. /* tell */
  24. printf("file [position=%" PRId64 "]", oss_media_file_tell(file));
  25. /* seek */
  26. oss_media_file_seek(file, stat.length / 2);
  27. /* 关闭文件 */
  28. oss_media_file_close(file);
  29. printf("oss media c sdk seek object succeeded\n");
  30. }

注:

本文导读目录
本文导读目录
以上内容是否对您有帮助?