全部產品
Search

搜尋本產品

    ：用戶端

    文件中心

    ：用戶端

    更新時間：Aug 30, 2018

    用戶端操作

    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;
    11. /**
    12.  * OSS MEDIA FILE的屬性資訊
    13.  */
    14. typedef struct oss_media_file_s {
    15.     void   *ipc;
    16.     char   *endpoint;
    17.     int8_t is_cname; 
    18.     char   *bucket_name;  
    19.     char   *object_key;
    20.     char   *access_key_id;
    21.     char   *access_key_secret;
    22.     char   *token;
    23.     char   *mode;
    24.     oss_media_file_stat_t _stat;
    26.     time_t expiration;
    27.     auth_fn_t auth_func;
    28. } 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);

    註：

    • 範例程式碼參考：GitHub

    銷毀

    1. /**
    2.  *  @brief  銷毀oss meida
    3.  *  @note   在程式結束的時候應該最後調用此介面，銷毀OSS MEDIA C SDK
    4.  */
    5. void oss_media_destroy();

    註：

    • 範例程式碼參考：GitHub

    開啟檔案

    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);

    註：

    • 範例程式碼參考：GitHub

    寫檔案

    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";
    9.     /* 本次授權的有效時間 */
    10.     file->expiration = time(NULL) + 300;
    11. }
    13. static void write_file() {
    14.     oss_clean(g_filename);
    16.     int64_t write_size;
    17.     oss_media_file_t *file;
    18.     char *bucket_name = "<your bucket name>";
    19.     char *key = "<your object key>";
    20.     char *content = "aliyun oss media c sdk";
    22.     /* 開啟一個檔案 */
    23.     file = oss_media_file_open(bucket_name, key, "w", auth_func);
    24.     if (!file) {
    25.         printf("open media file failed\n");
    26.         return;
    27.     }
    29.     /* 寫檔案 */
    30.     write_size = oss_media_file_write(file, content, strlen(content));
    31.     if (-1 != write_size) {
    32.          printf("write %" PRId64 " bytes succeeded\n", write_size);
    33.     } else {
    34.         oss_media_file_close(file);
    35.         printf("write failed\n");
    36.         return;
    37.     }
    39.     /* 關閉檔案，釋放資源 */
    40.     oss_media_file_close(file);
    41. }

    註：

    • 樣本中，開啟檔案的模式為覆蓋寫("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>";
    7.     oss_media_file_t *file;
    9.     /* 開啟檔案 */
    10.     file = oss_media_file_open(bucket_name, key, "r", auth_func);
    11.     if (!file) {
    12.         printf("open media file failed\n");
    13.         return;
    14.     }
    16.     /* 讀檔案 */
    17.     content = malloc(stat.length + 1);
    18.     ntotal = 0;
    19.     while ((nread = oss_media_file_read(file, buf, nbuf)) > 0) {
    20.         memcpy(content + ntotal, buf, nread);
    21.         ntotal += nread;
    22.     }
    23.     content[ntotal] = '\0';
    25.     /* 關閉檔案 */
    26.     oss_media_file_close(file);
    27.     free(content);
    29.     printf("oss media c sdk read object succeeded\n");
    30. }

    註：

    • 範例程式碼參考：GitHub

    管理檔案

    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);
    9. /**
    10.  *  @brief  設定OSS MEDIA FILE的指標到指定位置
    11.  *  @return:
    12.  *      返回0時表示成功
    13.  *      否則, 返回-1時表示出現了錯誤，可能導致失敗的原因包括：不是以讀模式開啟的檔案，無法連接OSS，無許可權讀OSS等
    14.  */
    15. int64_t oss_media_file_seek(oss_media_file_t *file, int64_t offset);
    17. /**
    18.  *  @brief 獲取OSS MEDIA FILE的元資料
    19.  *  @return:
    20.  *      返回0時表示成功
    21.  *      否則, 返回-1時表示出現了錯誤，可能導致失敗的原因包括：無法連接OSS，無許可權讀OSS等
    22.  */
    23. 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>";
    7.     oss_media_file_t *file;
    9.     /* 開啟檔案 */
    10.     file = oss_media_file_open(bucket_name, key, "r", auth_func);
    11.     if (!file) {
    12.         printf("open media file failed\n");
    13.         return;
    14.     }
    16.     /* 獲取檔案meta資訊 */
    17.     oss_media_file_stat_t stat;
    18.     if (0 != oss_media_file_stat(file, &stat)) {
    19.         oss_media_file_close(file);
    20.         oss_media_file_free(file);
    22.         printf("stat media file[%s] failed\n", file->object_key);
    23.         return;
    24.     }
    26.     printf("file [name=%s, length=%ld, type=%s]", 
    27.            file->object_key, stat.length, stat.type);
    29.     /* tell */
    30.     printf("file [position=%" PRId64 "]", oss_media_file_tell(file));
    32.     /* seek */
    33.     oss_media_file_seek(file, stat.length / 2);
    35.     /* 關閉檔案 */
    36.     oss_media_file_close(file);
    38.     printf("oss media c sdk seek object succeeded\n");
    39. }

    註：

    • 範例程式碼參考：GitHub