cStor云存储系统API开发手册初稿_20130109.doc

cStor云存储系统API开发手册 cStor云存储系统API开发手册 目录一、引言31.1.编写目的31.2.更新时间3二、获取方法3三、系统高速API33.1.总体设计33.2.使用方法43.3.数据结构43.3.1错误类型定义43.3.2文件打开类型定义53.4.函数说明53.4.1cstor_client_init53.4.2cstor_client_destroy53.4.3cstor_create_file63.4.4cstor_create_directory63.4.5cstor_open_file73.4.6cstor_close_file83.4.7cstor_write_by_filename83.4.8cstor_write_by_filebuff93.4.9cstor_read_by_filename103.4.10cstor_read_by_filebuff103.5.附加说明11一、 引言1.1. 编写目的 cStor通过API的方式开放一些应用接口，这篇文档用来介绍cStor目前开放的系统高速API，为应用程序的开发人员提供技术和文档服务。1.2. 更新时间 最后修订日期：2013-01-09 版本号：v1.0 二、 获取方法三、 系统高速API2.3.3.1. 总体设计 cStor系统高速 API可实现对客户端的初始化及注销，文件的创建、打开、关闭，以及文件以文件名直接读写和从文件缓冲区以一定的偏移量并行读写功能,以提高系统性能。3.2. 使用方法本API的使用说明如下：1) 添加库文件环境变量；在Linux环境下：echo export LD_LIBRARY_PATH=/opt/cstor/lib:$LD_LIBRARY_PATH /.bashrc在Windows环境下：2) 编写应用程序，编译即可。3.3. 数据结构1.2.3.3.1.3.2.3.3.33.13.23.3.1 错误类型定义#define CSTOR_SUCCESS 0 /*操作成功 /#define CSTOR_ERROR -1 /* General Error /#define CSTOR_ERROR_FILE_EXISTS -2/* 文件已存在 /#define CSTOR_ERROR_FILE_NOT_EXISTS -3/* 文件不存在 /#define CSTOR_NAME_TOO_LONG -4/* 名字太长/#define CSTOR_FILE_TOO_LONG -5/* 文件太长 /#define CSTOR_UNREG_FILE -6/* 文件未注册/#define CSTOR_FILE_INFO_ERROR -7/* 文件信息错误 /#define CSTOR_INPUT_INFO_ERROR -8/* 输入信息错误/#define CSTOR_NOT_FILE -9/* 非文件/3.3.2 文件打开类型定义enum IO_NONE,IO_READ,IO_WRITE,IO_READONLY,IO_WRITEONLY;3.4. 函数说明3.4.1 cstor_client_init函数功能：根据配置文件参数初始化客户端函数原型：int cstor_client_init(const char* conf_filename);参数说明：conf_filename:配置文件名返回值：return: 0 success, !=0 fail, return the error code （操作成功则返回0，失败时为非0值，返回具体错误类型）示例代码:3.4.2 cstor_client_destroy函数功能：客户端注销函数原型：void cstor_client_destroy();返回值：此函数不需要返回值示例代码：3.4.3 cstor_create_file函数功能：创建一个文件函数原型：int cstor_create_file(const char* filename, int overwrite);参数说明：filename：要创建文件的文件名overwrite：是否需要覆盖原文件（如已存在则覆盖，暂不支持覆盖）返回值：return: 0 success, !=0 fail, return the error code（操作成功则返回0，失败时为非0值，返回具体错误类型）示例代码：3.4.4 cstor_create_directory函数功能：创建一个目录函数原型：int cstor_create_directory(const char* dirpath);参数说明：dirpath：所要创建的目录的路径返回值：return: 0 success, !=0 fail, return the error code（操作成功则返回0，失败时为非0值，返回具体错误类型）示例代码:3.4.5 cstor_open_file函数功能：此函数实现打开一个文件函数原型：int cstor_open_file(const char* filename, int mode, cStorFileInfo* fileinfo);参数说明：filename：要打开的文件名mode：打开类型IO_NONE,IO_READ,IO_WRITE,IO_READONLY,IO_WRITEONLY中的一种fileinfo：文件句柄指针的指针，由用户创建，后续读写时传值使用返回值：return: 0 success, !=0 fail, return the error code（操作成功则返回0，失败时为非0值，返回具体错误类型）示例代码：3.4.6 cstor_close_file函数功能：关闭一个文件函数原型：int cstor_close_file(const char* filename, cStorFileInfo* fileinfo);参数说明：filename：要关闭的文件名fileinfo：文件句柄指针，由用户创建，后续读写时传值使用返回值：return: 0 success, !=0 fail, return the error code（操作成功则返回0，失败时为非0值，返回具体错误类型）示例代码：3.4.7 cstor_write_by_filename函数功能：通过文件名来写文件(从本地写入到cstor系统)函数原型：int cstor_write_by_filename(const char* srcfilename, const char* desfilename);参数说明：srcfilename：要写文件的源文件名desfilename：要写文件的目标文件名返回值：return: 0 success, !=0 fail, return the error code（操作成功则返回0，失败时为非0值，返回具体错误类型）示例代码：3.4.8 cstor_write_by_filebuff函数功能：从文件缓冲区按偏移量并行写文件函数原型：int cstor_write_by_filebuff( const char* filename,/ FileName void* buff,/ Buffer uint64_t size,/ NumberOfBytesToWrite uint64_t offset,/ Offset cStorFileInfo* cStorfileinfo);参数说明：filename：要写文件的文件名buff：缓冲区地址size：待写入的文件长度offset：偏移量cStorfileinfo：文件句柄指针，由用户创建，后续读写时传值使用返回值：return: 0 success, !=0 fail, return the error code（操作成功则返回0，失败时为非0值，返回具体错误类型）示例代码： 3.4.9 cstor_read_by_filename函数功能：实现通过文件名来读入文件（从cstor系统读到本地）函数原型：int cstor_read_by_filename(const char* srcfilename, const char* desfilename);参数说明：srcfilename：要读入文件的源文件名desfilename：要读入的目标文件名返回值：return: 0 success, !=0 fail, return the error code（操作成功则返回0，失败时为非0值，返回具体错误类型）示例代码：3.4.10 cstor_read_by_filebuff函数功能：从缓冲区按偏移量并行读文件函数原型：int cstor_read_by_filebuff( const char* filename, void* buff, uint64_t size, uint64_t offset, cStorFileInfo *cStorfileinfo);参数说明：filename：要读文件的文件名b