開發手記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高級模塊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

關於做者

傅海平：中國科學院計算技術研究所網絡數據中心(haipingf@gmail.com)
王 維：中國科院學計算技術研究所網絡數據中心(wangwei881116@gmail.com)