開發手記OSSC-阿里雲開發存儲服務(OSS)的C SDK

OSSC（Aliyun Open Storage Service C SDK）是我和實驗室@王維同學在2012首屆阿里雲開發者大賽中的參賽項目（http://2012.aliyun.com），我們作品提交是在10月2號，但是11月8號才揭曉最終結果，所以剩下的半個月還要慢慢等吧。

從GIT的提交記錄來看開發時間應該是2012-09-03 21:08:02首次提交，最終提交記錄是在2012-10-02 23:14:46，剛好整整一個月時間，除了實驗室導師的活需要完成，就只能零零散散的利用空余時間來完成OSSC。雖然時間很緊，不過還好完成了此次比賽的項目，從中也學到了很多東西。

下圖是OSSC代碼演進，總的代碼（在GIT統計中包括第三方庫，如壓縮庫LZ4，miniLZO，MD5等）大概接近4.6W行，除開第三發庫，我們自己的代碼大概在3.0W行左右。

下圖是每個作者代碼統計：

下圖是活動統計：

下圖是文件類型統計：

下圖是代碼提交時刻統計：

關於OSS

阿里雲存儲服務(Open Storage Service,簡稱 OSS)，是阿里雲對外提供的海量，安全，低成本，高可靠的雲存儲服務。 用戶可以通過簡單的 REST 接口，在任何時間、任何地點、任何互聯網設備上進行上傳和下載數據， 也可以使用WEB 頁面對數據進行管理。同時，OSS 提供 Java、Python、PHP SDK,簡化用戶的編程。 基於 OSS，用戶可以搭建出各種多媒體分享網站、網盤、個人企業數據備份等基於大規模數據的服務。 【摘自《OSS API 開放接口規范文檔》】。

我們為OSS做了什么？

目前 OSSC 提供了 OSS 開放接口中所描述的所有功能, 特點包括：

1. Bucket 所有操作，如創建 Bucket、刪除 Bucket、獲取某個 Bucket 訪問權限、設置 Bucket 訪問權限、獲取所有 Bucket 信息、 獲取 Bucket 中所有 Object 的信息。
2. Object 所有操作，創建 Object（PUT），獲取 Object，刪除 Object，獲取 Object 元信息，拷貝 Object，一次性刪除多個 Object，另外，還在此基礎上
   實現了從文件上傳 Object、從內存緩沖區上傳 Object、下載 Object 至文件、下載 Object 至內存緩沖區、多線程斷點續傳上傳大文件。
3. Multipart Upload 操作，初始化 Multipart Upload、上傳 Part、完成 Multipart 上傳、終止 Multipart Upload、查看 Multipart Upload，查看正在上傳的 Part。
4. Object Group 操作，創建 Object Group，獲取 Object Group，獲取 Object Group 中的 Object List 信息、獲取 Object Group 元信息，刪除 Object Group。

OSS 文件壓縮格式

我們為OSS設計了一種可支持多種實時壓縮算法(如LZO, LZ4，LZF)的文件存儲格式，並實現了LZO,LZ4兩種壓縮算法(今后可能支持更多)的文件和內存塊的實時壓縮上傳和下載解壓縮功能，用戶在壓縮上 傳文件時需要指定壓縮算法(目前只能指定OSS_LZ4, OSS_LZO)，但是在下載解壓縮時並不需要指定解壓縮算法，OSSC會自動根據文件格式選擇適當的解壓縮算法對文件或內存塊進行解壓縮。

該壓縮存儲格式文件名稱以.ossz結尾，但是不強制使用.ossz后綴，事實上，你可以使用任意文件名和后綴，OSSC會自動檢查文件是否為合法 的壓縮格式。 另外，我們為文件和內存塊的實時壓縮上傳和下載解壓縮分別提供了相應的API，我們建議壓縮上傳和下載API成對使用，即上傳時如果采用壓縮上傳，下載最 好采用壓縮下載的API進行文件下載，以免在下載解壓縮時不必要的文件格式檢查，更詳細的原理可以參考《OSSC 實現原理》一節，或源碼 src/util/oss_compression.c, src/util/oss_decompress 或 src/core/client_object_operation.c。

OSSC亮點

目前 OSSC 除了提供 OSS 開放接口中所描述的所有功能以外，還包括以下亮點：

• 多線程斷點上傳功能;
• 文件實時壓縮上傳和實時解壓縮下載;
• 內存塊實時壓縮上傳和實時解壓縮下載;
• 簡易的文件夾同步上傳和同步下載功能。

注解:

由於在Get Object操作設置HTTP的Range請求參數時會出現："connection reset by peer"，無法進行測試，所以多線程斷點下載功能未經過測試，沒有集成到代碼庫中。

OSSC安裝細節

OSSC安裝步驟

操作系統

OSSC 在 Ubuntu 12.04 上開發，我們測試了OSSC在不同Linux操作系統發行版的穩定性，以下是OSSC經過測試操作系統：

• Ubuntu 12.04, 11.10, 11.04, 10.10, 10.04
• CentOS 5.5
• Fedora 15, 16, 17
• openSUSE 12.2

注意:

目前我們沒有在Windows上經過嚴格測試，雖然 OSSC 是標准C (C99) 寫的，理論上也可以在 Windows 上編譯運行，但是目前不建議在Windows系統下使用 OSSC，我們以后會對此改進。

OSSC依賴庫

OSSC 采用 CURL 庫處理 HTTP 請求，因此在編譯 OSSC 之前你需要安裝 CURL，CURL 源碼中包含了C調用API，最新版 CURL下載地址：http://curl.haxx.se/libcurl/。 除此之外，OSSC 不依賴任何其他程序庫。

CURL安裝

本節介紹如何編譯 CURL

1. 下載 CURL，http://curl.haxx.se/download.html
2. 安裝 CURL，在Unix/Linux按照如下步驟，

    $ ./configure
    $ make
    $ make test (optional)
    $ make install(需root用戶權限)
   

   你也可以參考 CURL 的官方安裝文檔，http://curl.haxx.se/docs/install.html
3. 完成依賴庫安裝后執行 ldconfig（需root用戶權限）

OSSC編譯步驟

本節介紹如何編譯OSSC。

OSSC采用 CMake 管理構建過程，應該先安裝CMake，

1. 安裝CMake。
2. 創建 build 目錄，進入到該目錄，mkdir build && cd build
3. 執行 cmake ../.
4. 編譯和安裝 make && make install

   注解:

   如果需要設置編譯選項，可以參考CMake文檔，目前默認的編譯模式為 Release，如果需要調試OSSC， 請將編譯模式設置為Debug。

   OSSC默認安裝在 /usr/local目錄下，當然你可以在 cmake 中設置，方法如下：

    cmake -DCMAKE_INSTALL_PREFIX=/your-path ../.
   

在你的程序中使用OSSC

OSSC以程序庫的形式提供給上層開發者使用，因此如果你想基於OSSC開發上層應用，必須鏈接OSSC程序庫，OSSC大部分都集中到了 osscore 中，
只是支持多線程調用模式的API單獨放在 ossextra庫中（目前多線程只支持 pthread 線程庫，后期會考慮在 Windows 下也支持多線程）
以下是你的程序需要連接OSSC，鏈接參數為：-L/path-to-your-ossc-installation -losscore.

另外需要注意的是，OSSC支持多線程斷點續傳模式下上傳文件，如果你想體驗該功能，你需要鏈接如下庫： -L/path-to-your-ossc-installation -lossextra.

OSSC編碼規范

OSSC編碼規范詳述

一個優秀的項目必須遵循良好的編碼規范，良好的編碼風格可以促進團隊協作，減少 BUG 產生幾率，有助於開發后的代碼審查，降低后期維護成本。

OSSC雖然只是我們在業余時間完成的小項目，但是也注重了編碼風格的一致性，我們強烈建議那些希望基於OSSC做二次開發的編碼人員閱讀本規范， 相信本規范能夠讓你快速熟悉 OSSC 的整體結構和OSSC API 的使用方法。

OSSC實現原理

OSSC詳細的實現原理請參考： OSSC實現原理

概括

OSSC（OSS-C-SDK）完全采用C語言開發，並實現了類似面向對象的調用方式，即“對象（struct 結構）”的“成員函數（函數指針）“采用函數指針形式實現， 我們盡量和OSS-JAVA的使用方式切合，每個對象都有相關的頭文件和實現文件，並存放在modules目錄下，其中與oss功能相關的所有的文件名均 以oss_為前綴，
每個文件實現了一個對象（即模塊），另外，為了方便開發人員記憶，OSSC中的所有結構和函數我們采用如下命名；

1. 類名（本文指代struct 結構）以 “oss_” 為前綴，並以 “_t” 為后綴，名字中間的單詞用來標識該結構的用途，單詞以下划線“_”連接，比如：包含終止一個Multipart上傳事件的請求參數被命名為
   oss_abort_multipart_upload_request_t，或者包含訪問阿里雲開放存儲服務的入口“類”被命名為 oss_client_t，其他以此類推。
2. 與各個類（struct 結構指針，以下均以“類”指代）對應的函數均以函數指針的形式調用（除了oss_client_t），比如oss_abort_multipart_upload_request_t中設置 Bucket 名稱可以按照如下方式調用，

    request->set_bucket_name(request，"bucket-name-001");
   

3. 所有類對外均提供初始化函數和析構函數，其它與該類相關的操作均通過該類的函數指針調用，其中初始化函數命名規則為：該類的(BARE)類名（即 類名去掉“oss_”前綴和“_t”后綴）+initialize， 析構函數為該類的(BARE)類名（即類名去掉“oss_”前綴和“_t”后綴）+finalize。
4. 訪問阿里雲開放存儲服務（Open Storage Service， OSS）的入口“類”是 oss_client_t，與此對應的所有函數均以client_前綴開頭，並且第一個參數都是指向client結構的指針。

比如上傳一個對象，你需要定義標識上傳對象的請求結構（oss_put_object_request_t *request）和
上傳對象之后返回信息的結構(oss_put_object_result_t *result)，然后將request作為參數傳遞給上傳對象函數中（client_put_object_from_file(）
或者client_put_object()中），最后返回值會保存在result指針所指向的結構中。

下面的代碼概括了使用 OSSC 的步驟(單線程上傳文件示例)：

 const char *access_id = "ACSGmv9fkV1TDO9L";// Access ID
 const char *access_key = "BedoWbsje2"; // Access key
 const char *bucket_name = "bucketname001"; //Bucket 名稱
 const char *key = "put-test.data"; // Key, Object 名稱

 FILE *file = fopen("proactor.pdf", "r"); //打開需要上傳的文件
 unsigned short retcode = 0; //設置返回碼，關於返回碼的定義將在后文中詳細介紹
 oss_client_t *client = client_initialize(access_id, access_key); // 初始化 oss_client_t *clien

 oss_object_metadata_t *metadata = object_metadata_initialize(); // 初始化 oss_object_metadata_t *metadata
 metadata->set_content_length(metadata, file_len); // 設置 metadata 元信息
 metadata->set_content_type(metadata, "application/octet-stream"); // 設置 metadata 元信息

 client_put_object_from_file(client, bucket_name, key, file, metadata, &retcode);// 核心操作：調用上傳對象API
 client_finalize(client); //使用以后程序退出時需要釋放 oss_client_t *client 分配的空間

OSSC高級模塊Extra庫

OSSC 高級模塊中包含了多線程上傳大文件的 API，並支持斷點續傳，由於時間和精力有限，我們目前並沒有實現 Windows 平台的多線程上傳下載功能， 希望今后會有其他開發者實現這一功能。

另外 Extra 庫還支持簡單的文件夾上傳同步和下載同步的功能，希望該API對其他開發者有用。

OSSC 采用了POSIX多線程標准庫 pthread,理論上只要你的操作系統支持 pthread都可以使用 OSSC 的 extra 庫中的 API。

OSSC高級模塊Extra庫

API使用示例

OSSC API 使用示例

關於OSSC授權

OSSC 使用的開源程序：

1. GNUlib 中的 base64, sha1, hmac-sha1等模塊，並進行了適當改造。
2. CCAN 的 ttxml，一個極簡單的 xml 文件只讀庫
3. Glib 的 GString，進行了適當的改造，在此基礎上實現了 tstring_t，一個類似 C++ 的 std::string實現
4. UThash, A hash table for C structure, http://uthash.sourceforge.net/
5. LZ4: http://code.google.com/p/lz4/
6. miniLZO: http://www.oberhumer.com/opensource/lzo/

OSSC 采用 LGPL（GNU Lesser General Public License：GNU 寬通用公共許可證）授權形式發布，有關 LGPL 可以查閱 GNU 官方文檔： http://www.gnu.org/licenses/lgpl.html

關於作者

傅海平：中國科學院計算技術研究所網絡數據中心([e-mail])
王 維：中國科院學計算技術研究所網絡數據中心([e-mail])