zookeeperCAPI中文翻译.doc

1、错误码ZOO_ERRORS
ZOK 
正常返回
ZSYSTEMERROR 
系统或服务器端错误(System and server-side errors)，服务器不会抛出该错误，该错误也只是用来标识错误范围的，即大于该错误值，且小于 ZAPIERROR 都是系统错误。
ZRUNTIMEINCONSISTENCY 
运行时非一致性错误。
ZDATAINCONSISTENCY 
数据非一致性错误。
ZCONNECTIONLOSS 
Zookeeper 客户端与服务器端失去连接
ZMARSHALLINGERROR 
在编码和解码数据时出现错误
ZUNIMPLEMENTED 
该操作未实现/未执行
ZOPERATIONTIMEOUT 
该操作超时
ZBADARGUMENTS 
非法参数错误
ZINVALIDSTATE 
非法句柄状态
ZAPIERROR 
API 错误(API errors)，服务器不会抛出该错误，该错误也只是用来标识错误范围的，错误值大于该值的标识 API 错误，而小于该值的标识 ZSYSTEMERROR。
ZNONODE 
节点不存在(Node does not exist)
ZNOAUTH 
没有经过授权(Not authenticated)
ZBADVERSION 
版本冲突(Version conflict)
ZNOCHILDRENFOREPHEMERALS 
临时节点不能拥有子节点(Ephemeral nodes may not have children)
ZNODEEXISTS 
节点已经存在(The node already exists)
ZNOTEMPTY 
该节点具有自身的子节点(The node has children)
ZSESSIONEXPIRED 
会话过期(The session has been expired by the server)
ZINVALIDCALLBACK 
非法的回调函数(Invalid callback specified)
ZINVALIDACL 
非法的ACL(Invalid ACL specified)
ZAUTHFAILED 
客户端授权失败(Client authentication failed)
ZCLOSING 
Zookeeper 连接关闭(ZooKeeper is closing)
ZNOTHING 
并非错误，客户端不需要处理服务器的响应(not error, no server responses to process)
ZSESSIONMOVED 
会话转移至其他服务器，所以操作被忽略(session moved to another server, so operation is ignored)
2、日志级别
enum ZooLogLevel {
ZOO_LOG_LEVEL_ERROR=1,
ZOO_LOG_LEVEL_WARN=2,
ZOO_LOG_LEVEL_INFO=3,
ZOO_LOG_LEVEL_DEBUG=4}
3、常量
3.1、与ZNODE访问权限相关的常量
ZOO_PERM_READ; //允许客户端读取znode节点的值以及子节点列表
ZOO_PERM_WRITE; //允许客户端设置znode节点的值
ZOO_PERM_CREATE; //允许客户端在该znode节点下创建子节点
ZOO_PERM_DELETE; //允许客户端删除子节点
ZOO_PERM_ADMIN; //允许客户端执行set_acl()
ZOO_PERM_ALL; //允许客户端执行所有操作，等价上述所有标识的或
3.2、ACL IDs相关的常量
struct Id ZOO_ANYONE_ID_UNSAFE; //表示所有人（’world’,’anyone’）
struct Id ZOO_AUTH_IDS; //仅仅用于设置ACLs(‘auth’,’’)

3.3、三种标准的ACL
struct ACL_vector ZOO_OPEN_ACL_UNSAFE; //全开放权限
struct ACL_vector ZOO_READ_ACL_UNSAFE; //所有人可读权限
struct ACL_vector ZOO_CREATOR_ALL_ACL; //授予创建者ID所有权限

3.4、与 Interest 相关的常量
ZOOKEEPER_WRITE, ZOOKEEPER_READ
这两个常量用于标识感兴趣的事件并通知 zookeeper 发生了哪些事件。Interest 常量可以进行组合或（OR）来标识多种兴趣(multiple interests: write, read)，这两个常量一般用于 zookeeper_interest() 和 zookeeper_process()两个函数中。
3.5、与节点创建相关的常量
ZOO_EPHEMERAL, ZOO_SEQUENCE
zoo_create 函数标志，ZOO_EPHEMERAL 用来标识创建临时节点，ZOO_SEQUENCE 用来标识节点命名具有递增的后缀序号(一般是节点名称后填充 10 位字符的序号，如 /xyz0000000000, /xyz0000000001, /xyz0000000002, ...)，同样地，ZOO_EPHEMERAL, ZOO_SEQUENCE 可以组合。
3.6、与连接状态 Stat 相关的常量
以下常量均与 Zookeeper 连接状态有关，他们通常用作监视器回调函数的参数。
ZOOAPI const int 
ZOO_EXPIRED_SESSION_STATE
ZOOAPI const int 
ZOO_AUTH_FAILED_STATE
ZOOAPI const int 
ZOO_CONNECTING_STATE
ZOOAPI const int 
ZOO_ASSOCIATING_STATE
ZOOAPI const int 
ZOO_CONNECTED_STATE
3.7、与监视类型(Watch Types)相关的常量
以下常量标识监视事件的类型，他们通常用作监视器回调函数的第一个参数。
ZOO_CREATED_EVENT; //节点被创建(此前该节点不存在)，通过 zoo_exists() 设置监视
ZOO_DELETED_EVENT; //节点被删除，通过 zoo_exists() 和 zoo_get() 设置监视
ZOO_CHANGED_EVENT; //节点发生变化，通过 zoo_exists() 和 zoo_get() 设置监视。
ZOO_CHILD_EVENT; //子节点事件，通过zoo_get_children() 和 zoo_get_children2()设置监视。
ZOO_SESSION_EVENT; // 会话丢失
ZOO_NOTWATCHING_EVENT; //监视被移除。
4、结构体
4.1、clientid_t
typedef struct {
int64_t client_id; //ID
char passwd[16]; //密码
} clientid_t;
说明：保存回话ID和密码。当回话建立时从服务端接收到，如果需要保持连接，需要回返该结构体
4.2、zoo_op_t
typedef struct zoo_op {
int type;
union {
// CREATE
struct {
const char *path;
const char *data;
int datalen;
char *buf;
int buflen;
const struct ACL_vector *acl;
int flags;
} create_op;

// DELETE
struct {
const char *path;
int version;
} delete_op;

// SET
struct {
const char *path;
const char *data;
int datalen;
int version;
struct Stat *stat;
} set_op;

// CHECK
struct {
const char *path;
int version;
} check_op;
};
} zoo_op_t;
说明：该结构体包含一次操作相关的所有必须参数，可被zoo_multi()和zoo_amulti()函数调用。它的值可通过zoo_create_op_init(),zoo_delete_op_init(),zoo_set_op_init()和zoo_check_op_init() 函数设置。
4.3、zoo_op_result_t
typedef struct zoo_op_result {
int err;
char *value;
int valuelen;
struct Stat *stat;
} zoo_op_result_t;
说明：保存一次操作的结果信息，被zoo_multi()和zoo_amulti()函数调用。
5、函数
5.1、zoo_op_t结构体初始化函数
5.1.1 zoo_create_op_init
void zoo_create_op_init(zoo_op_t *op, const char *path, const char *value,
int valuelen, const struct ACL_vector *acl, int flags,
char *path_buffer, int path_buffer_len);
/**@brief 初始化zoo_op_t结构体，用于ZOO_CREATE_OP
* @param[in/out] op: 需要被初始化的结构体指针
* @param[in] path : 节点名,以/与上层目录分割
* @param[in] value: 节点需要存储的数据
* @param[in] valuelen: 需要存储的字节数，无数据时value=NULL,valuelen=-1
* @param[in] acl: 节点的初始权限，不能为空
* @param[in] flags: 普通创建可设为0，或者与创建标识的或操作
* @param[in/out] path_buffer: 存储新节点路径，以NULL结束
* @param[in] path_buffer_len: 新路径缓冲区长度
* @remark：path_buffer的值可能因ZOO_SEQUENCE标识设置与输入的路径不一致，当path_buffer_len = 0时，该值为NULL。当path_buffer_len 的值小于新节点的实际路径长度，新节点路径将被截断，并以NULL结束。
*/
5.1.2 zoo_delete_op_init
void zoo_delete_op_init(zoo_op_t *op, const char *path, int version);
/**@ brief 初始化zoo_op_t结构体，用于ZOO_DELETE_OP
* @param[in/out] op: 需要被初始化的结构体指针
* @param[in] path: 节点名,以/与上层目录分割
* @param[in] version: 节点的版本号，-1时进行全匹配（不检测版本）
* @remark：如果实际版本号与期望版本号不匹配，函数将失败
*/
5.1.3 zoo_set_op_init
void zoo_set_op_init(zoo_op_t *op, const char *path, const char *buffer,
int buflen, int version, struct Stat *stat);
/**@brief 初始化zoo_op_t结构体，用于ZOO_SETDATA_OP
* @param[in/out] op: 需要被初始化的结构体指针
* @param[in] path: 节点名,以/与上层目录分割
* @param[in] buffer: 写入节点的数据
* @param[in] buflen: 写入节点的数据长度,数据为空时buffer=NULL,buflen=-1
* @param[in] version: 节点的版本号，-1时进行全匹配（不检测版本）
* @remark：如果实际版本号与期望版本号不匹配，函数将失败
*/
void zoo_set_op_init(zoo_op_t *op, const char *path, const char *buffer,
int buflen, int version, struct Stat *stat);
5.1.4 zoo_check_op_init
void zoo_check_op_init(zoo_op_t *op, const char *path, int version);
/**@brief 初始化zoo_op_t结构体，用于ZOO_CHECK_OP
* @param[in/out] op: 需要被初始化的结构体指针
* @param[in] path: 节点名,以/与上层目录分割
* @param[in] version: 节点的版本号，-1时进行全匹配（不检测版本）
* @remark：如果实际版本号与期望版本号不匹配，函数将失败
*/
5.2、回调函数原型
5.2.1 监视函数
typedef void (*watcher_fn)(zhandle_t *zh, int type,
int state, const char *path,void *watcherCtx);
/**@brief 监视函数签名
* @param[in] zh: zookeeper 句柄
* @param[in] type: 事件类型 ，*_EVENT常量中的一个值
* @param[in] state: 连接状态 ，*_STATE常量中的一个值
* @param[in] path: 被监视的znode路径，如果事件类型=ZOO_SESSION_EVENT时为空
* @param[in] watcherCtx: 监视器上下文
*/
备注：有两种获取监视通知的方式：legacy和watcher object.
Legacy方式下，应用如果想接收到ZooKeeper的事件，必须先调用使用该签名的一个方法，并传递一个指针给该方法，比如zookeeper_init()函数。然后应用通过调用一个接收到一个监视整型标识的回调函数（比如zoo_aexists()/ref zoo_get()等）设置一个监视。
示例：
void watcher(zhandle_t *zzh, int type, int state, const char *path,
void* context){/**/}
clientid_t myid;
zhandle_t *zh = zookeeper_init(hostPort, watcher, 30000, &myid, 0, 0);

watcher object方式使用一个watcher object实例传回用户特定数据。watcher object在C语言中代表了一个对：一个执行该签名的指针和一个监视器上下文指针。当监视被触发，该函数即被调用，使用这种方式的应用必须使用名称中带w前缀的回调函数（比如zoo_awexists(),zoo_wget()等）。
5.2.2 其他回调函数的原型
Zookeeper 中还有几种在异步 API(一般以 zoo_a*开头的函数) 中使用的回调函数，根据回调函数处理异步函数返回值类型的不同分为以下几类：处理返回 void 类型的回调函数，处理返回 Stat 结构的回调函数，处理返回字符串的回调函数，处理返回数据的回调函数，处理返回字符串列表(a list of string)的回调函数，同时处理返回字符串列表(a list of string)和 Stat 结构的回调函数，以及处理返回 ACL 信息的回调函数，它们分别如下：
typedef void(* void_completion_t)(int rc, const void *data);
/**@brief 处理返回 void 类型的回调函数,也可以响应连接丢失或超时
* @param[in] rc: 调用的错误码，0表示成功
* @param[in] data: 函数运行所需的参数指针
* @ramark连接丢失/超时时的rc值：
* ZCONNECTIONLOSS – 与服务器的连接丢失
* ZOPERATIONTIMEOUT – 连接超时
*/

typedef void(* stat_completion_t)(int rc, const struct Stat *stat, const void *data);
/**@brief 处理返回 Stat 结构的回调函数,也可以响应连接丢失或超时
* @param[in] rc: 调用的错误码，0表示成功
* @param[in] stat: 函数调用所需的Stat结构体指针,如果rc非0，该值无意义
* @param[in] data: 调用者传入参数指针
* @remark 连接丢失或超时rc值参考void返回类型回调函数
*/

typedef void(* string_completion_t)(int rc, const char *value, const void *data);
/**@brief 处理返回字符串的回调函数,也可以响应连接丢失或超时
* @param[in] rc: 调用的错误码，0表示成功
* @param[in] value: 返回的字符串值
* @param[in] data: 调用者传入参数指针
* @remark 连接丢失或超时rc值参考void返回类型回调函数
*/

typedef void(* data_completion_t)(int rc, const char *value, int value_len, const struct Stat *stat, const void *data);
/**@brief处理返回数据的回调函数,也可以响应连接丢失或超时
* @param[in] rc: 调用的错误码，0表示成功
* @param[in] value: 异步调用的返回信息
* @param[in] value_len: value的字节数
* @param[in] stat：指向该函数调用的节点的stat信息结构体指针
* @param[in] data: 调用者传入参数指针
* @remark 连接丢失或超时rc值参考void返回类型回调函数
*/

typedef void(* strings_completion_t)(int rc, const struct String_vector *strings, const void *data);
/**@brief处理返回字符串列表的回调函数,也可以响应连接丢失或超时
* @param[in] rc: 调用的错误码，0表示成功
* @param[in] strings: 指向一个节点的所有子节点名称列表的指针
* @param[in] data: 调用者传入参数指针
* @remark 连接丢失或超时rc值参考void返回类型回调函数
*/

typedef void(* strings_stat_completion_t)(int rc, const struct String_vector *strings, const struct Stat *stat, const void *data);
/**@brief同时处理返回字符串列表和 Stat 结构的回调函数,也可以响应连接丢失或超时
* @param[in] rc: 调用的错误码，0表示成功
* @param[in] strings: 指向一个节点的所有子节点名称列表的指针
* @param[in] stat: 指向该函数调用的节点的stat信息结构体指针
* @param[in] data: 调用者传入参数指针
* @remark 连接丢失或超时rc值参考void返回类型回调函数
*/

typedef void(* acl_completion_t)(int rc, struct ACL_vector *acl, struct Stat *stat, const void *data);
/**@brief 处理返回 ACL信息的回调函数,也可以响应连接丢失或超时
* @param[in] rc: 调用的错误码，0表示成功
* @param[in] acl: 指向包含节点ACL信息结构的指针
* @param[in] stat: 指向该函数调用的节点的stat信息结构体指针
* @param[in] data: 调用者传入参数指针
* @remark 连接丢失或超时rc值参考void返回类型回调函数
*/

5.3、初始化/销毁函数
zhandle_t *zookeeper_init(const char *host, watcher_fn fn,
int recv_timeout, const clientid_t *clientid, void *context, int flags);
/**@brief 创建一个与ZooKeeper通信的句柄，由于会话采用异步方式建立，因此在收到ZOO_CONNECTED_STATE事件前不能认为连接建立。
* @param[in] host: 逗号分隔的 host:port ZooKeeper服务器对
* @param[in] fn: 监视回调函数
* @param[in] recv_timeout： 等待接收事件最长时间
* @param[in] clientid: 先前建立的会话ID，用于客户端重新连接。如果不重新连接* 先前的会话则传入0.客户端可通过调用zoo_client_id()函数接入一个先前建立的、* 有效的会话。如果该值表示的会话过期或者失效，返回的zhandle_t将是无效的， * 其状态将表明失败的原因（典型的一个原因如ZOO_EXPIRED_SESSION_STATE）。
* @param[in] context: 关联该实例的回调对象，实际不被使用，可设为NULL
* @param[in] flags: 预留，设为0
* @return 成功返回一个结构体指针，否则返回NULL，可通过errno查看失败原因。
*/

int zookeeper_close(zhandle_t *zh);
/**@brief 关闭zookeeper句柄并释放所有资源，调用该函数后，客户端会话将不再有效，函数在返回之前将清除未发送的请求，因此，可能引起阻塞。该函数对一个zookeeper句柄只能调用一次。
* @param[in] zh: 需要关闭的zookeeper句柄
* @return
* ZOK – 成功
* ZBADARGUMENTS – 无效的输入参数
* ZMARSHALLINGERROR – 请求入队失败，可能是因为内存溢出
* ZOPERATIONTIMEOUT - 未在特定的时间内清除缓冲区
* ZCONNECTIONLOSS – 尝试向服务器发送请求是出现网络错误
* ZSYSTEMERROR – 系统错误; it's worth checking errno to get details
*/

5.4、辅助函数
/*返回客户端会话ID，仅当连接建立后（收到监视状态ZOO_CONNECTED_STATE）有效。 */
clientid_t *zoo_client_id(zhandle_t *zh);

/*返回会话的超时时间，仅当连接建立后（收到监视状态ZOO_CONNECTED_STATE）有效，*服务器重新连接后该值可能改变。 */
int zoo_recv_timeout(zhandle_t *zh);

/*返回句柄的上下文 */
void *zoo_get_context(zhandle_t *zh);

/*设置句柄的上下文 */
void zoo_set_context(zhandle_t *zh, void *context);

/*设置句柄的监视函数，返回当前监视函数*/
watcher_fn zoo_set_watcher(zhandle_t *zh,watcher_fn newFn);

/*返回当前连接的socket地址，失败返回NULL，仅当连接建立后有效 */
struct sockaddr* zookeeper_get_connected_host(zhandle_t *zh,
struct sockaddr *addr, socklen_t *addr_len);

/*获取zookeeper连接状态*/
int zoo_state(zhandle_t *zh);

/*返回错误码对应的错误信息*/
const char* zerror(int c);

/*如果当前连接无法恢复进行监测，如果连接无法恢复，返回ZINVALIDSTATE */
int is_unrecoverable(zhandle_t *zh);

/*设置日志级别为DEBUG级别*/
void zoo_set_debug_level(ZooLogLevel logLevel);

/*设置日志流模式，默认采用stderr模式，必须保证流是可写的，NULL默认采用默认值*/
void zoo_set_log_stream(FILE* logStream);

/*启用/禁用顺序接入端口
* 注意: 一般该方法不应该在测试之外使用
* 传入非0值，客户端将根据顺序连接端口，0值使得客户端随机接入（分布式应用中较好）
*/
void zoo_deterministic_conn_order(int yesOrNo);

5.5、单线程函数
#ifdef WIN32
int zookeeper_interest(zhandle_t *zh, SOCKET *fd, int *interest,
struct timeval *tv);
#else
int zookeeper_interest(zhandle_t *zh, int *fd, int *interest,
struct timeval *tv);
#endif
/**@brief 返回zookeeper感兴趣的事件
* @param[in] zh: zookeeper句柄
* @param[in] fd: 文件描述符
* @param[in] interest: fd的I/O标识（ZOOKEEPER_WRITE |ZOOKEEPER_READ ）
* @param[in] tv: 超时值，在select/poll系统调用时使用
* @return
* ZOK – 成功
* ZBADARGUMENTS – 无效的输入参数
* ZINVALIDSTATE – 句柄状态既不是ZOO_SESSION_EXPIRED_STATE 也不是ZOO_AUTH_FAILED_STATE
* ZCONNECTIONLOSS – 与服务器建立连接时出现网络错误
* ZMARSHALLINGERROR -请求入队失败，可能是因为内存溢出
* ZOPERATIONTIMEOUT –超过2/3在zookeeper_init()中定义的超时时间未收到事件
* ZSYSTEMERROR – 系统错误; it's worth checking errno to get details
*/

int zookeeper_process(zhandle_t *zh, int events);
/**@brief 通知zookeeper一个感兴趣的事件发生
* @param[in] zh: zookeeper句柄
* @param[in] events: 可能是ZOOKEEPER_WRITE与ZOOKEEPER_READ的或.
* @return
* ZOK - success
* ZBADARGUMENTS – 无效的输入参数
* ZINVALIDSTATE – 句柄状态既不是ZOO_SESSION_EXPIRED_STATE也不是 ZOO_AUTH_FAILED_STATE
* ZCONNECTIONLOSS – 尝试向服务器发送请求是出现网络错误
* ZSESSIONEXPIRED – 连接失败-会话超时
* ZAUTHFAILED – 身份认证失败,可能原因：无效证书
* ZRUNTIMEINCONSISTENCY - a server response came out of order
* ZSYSTEMERROR – 系统错误; it's worth checking errno to get details
* ZNOTHING – 不是错误，只是表明服务器上没有更多的数据去处理
*/

5.6、函数
除了基本的初始化、销毁 Zookeeper 句柄(zhandle)，设置日志等级、日志流以及一些具有辅助功能 API(zerror(), zoo_state()等) 外，Zookeeper C API 大部分接口可以根据同步和异步特性分为两类，同步接口以 zoo_* 开头，异步接口以则以 zoo_a* 开头。并且除了 zookeeper_init() 以及与 zoo_multi() 或 zoo_amulti() 批量操作相关的 zoo_op_t 初始化外，其他的 API 的第一个参数均为 zhandle_t * zh, 即 Zookeeper 句柄的指针。
5.6.1 异步函数
5.6.1.1 创建节点
int zoo_acreate(zhandle_t *zh, const char *path, const char *value, int valuelen, const struct ACL_vector *acl, int flags, string_completion_t completion, const void *data);
/**@ 创建一个节点。只有当节点不存在时才被创建，创建标识影响节点的创建。
* ZOO_EPHEMERAL标识，当连接失效时，节点自动删除
* ZOO_SEQUENCE标识，路径名后追加一个10进制自增序列码，用0补齐
* @param[in] zh: zookeeper 句柄
* @param[in] path: 节点名，以斜线分割
* @param[in] value: 节点的绑定数据
* @param[in] valuelen： 绑定数据长度
* @param[in] acl: 节点的初始ACL. 不能为null 或者空.
* @param[in] flags:普通创建可设为0，或者创建标识的或操作
* @param[in]completion: 创建请求执行后的处理函数，根据以下rc的值进行触发
* ZOK 操作成功
* ZNONODE 父节点不存在
* ZNODEEXISTS 节点已经存在
* ZNOAUTH 客户端节点没有权限
* ZNOCHILDRENFOREPHEMERALS 不能创建临时节点的子节点
* @param[in] data:传递给completion的值
* @return 成功返回ZOK，否则返回以下值：
* ZBADARGUMENTS – 无效的输入参数
* ZINVALIDSTATE - zhandle状态既不是ZOO_SESSION_EXPIRED_STATE也不是ZOO_AUTH_FAILED_STATE
* ZMARSHALLINGERROR –请求失败，可能是内存溢出
*/
5.6.1.2 删除节点
int zoo_adelete(zhandle_t *zh, const char *path, int version, void_completion_t completion, const void *data);
/**@brief 删除节点
* @param[in] zh: zookeeper 句柄
* @param[in] path: 节点名称，以斜线分割
* @param[in] version: 期望的节点版本号.版本号不匹配时函数失败，-1时表示不检查版本号
* @param[in] completion: 请求执行后的处理，根据以下rc值触发：
* ZOK 操作成功
* ZNONODE 节点不存在
* ZNOAUTH 客户端没有权限
* ZBADVERSION 期望版本与现有版本不匹配
* ZNOTEMPTY 存在子节点，节点不能被删除
* @param[in] data:传递给completion的值
* @return 成功返回ZOK，否则返回以下值：
* ZBADARGUMENTS – 无效的输入参数
* ZINVALIDSTATE –zhandle状态既不是ZOO_SESSION_EXPIRED_STATE也不是ZOO_AUTH_FAILED_STATE
* ZMARSHALLINGERROR –请求失败，可能原因：内存溢出
*/
5.6.1.3