一、初始化、销毁 Zookeeper 句柄

1）初始化zookeeper句柄

ZOOAPI zhandle_t *zookeeper_init(const char *host, watcher_fn fn,int recv_timeout,const clientid_t * clientid,void *context, int flags);
---------------------------
参数说明-》》》
host		逗号隔开的 host:port 对, 每个代表一个 zk server, 例如: "127.0.0.1:3000,127.0.0.1:3001,127.0.0.1:3002"fn			全局的监视器回调函数，当发生事件通知时，该函数会被调用。clientid	客户端尝试重连的先前会话的ID，如果不需要重连先前的会话，则设置为 0。客户端可以通过调用 zoo_client_id来访
问一个已经连接上的并且有效的会话ID，如果clientid对应的会话超时，或者由于某种原因 clientid变为无效了，那么
zookeeper_init 将返回一个非法的 zhandle_t， 通过 zhandle_t 的状态可以获知 zookeeper_init 调用失败的原因。 (通常为 
ZOO_EXPIRED_SESSION_STATE).context		与 zhandle_t 实例相关联的“上下文对象”（可以通过该参数为 zhandle_t 传入自定义类型的数据），应用程序可以
通过 zoo_get_context 访问它（例如在监视器回调函数中），当然 zookeeper 内部没有用到该参数，所以 context 可以设置为 
NULL。flags		目前为保留参数，设置为 0。

2）销毁zookeeper句柄

ZOOAPI int zookeeper_close(zhandle_t * zh);

二、辅助函数

1）设置日志等级

ZOOAPI void zoo_set_debug_level(ZooLogLevel logLevel);
其中 logLevel 可以是ZOO_LOG_LEVEL_ERROR, ZOO_LOG_LEVEL_WARN, ZOO_LOG_LEVEL_INFO, ZOO_LOG_LEVEL_DEBUG四个取值。

2）获取客户端的 session id，只有在客户端的当前连接状态有效时才可以。

ZOOAPI void zoo_set_log_stream(FILE * logStream);
Zookeeper C API 默认的日志流是标准输出，可以通过该函数设置 Zookeeper C API的日志流为文件。

3）返回当前会话的超时时间，只有在客户端的当前连接状态有效时才可以。

ZOOAPI const clientid_t *zoo_client_id(zhandle_t * zh);

4）获取 Zookeeper 句柄的上下文。

ZOOAPI const void *zoo_get_context(zhandle_t * zh);

5）设置 Zookeeper 句柄的上下文。

ZOOAPI void zoo_set_context(zhandle_t * zh, void *context);

6）设置 Zookeeper 句柄的全局监视器回调函数，该函数返回全局监视器的旧回调函数。

ZOOAPI watcher_fn zoo_set_watcher(zhandle_t * zh, watcher_fn newFn);

7）返回当前 Zookeeper 连接的套接字地址。

ZOOAPI struct sockaddr *zookeeper_get_connected_host(zhandle_t * zh, struct sockaddr*addr,socklen_t * addr_len);

8）获取当前 Zookeeper 连接状态。

ZOOAPI int zoo_state(zhandle_t * zh);

9）返回某一错误码的字符串表示。

ZOOAPI const char *zerror(int c);

10）检查当前 Zookeeper 连接是否为不可恢复的，如果不可恢复，则客户端需要关闭连接，然后重连。

ZOOAPI int is_unrecoverable(zhandle_t * zh);

// 设置日志等级、日志流
ZOOAPI void zoo_set_debug_level(ZooLogLevel logLevel);
ZOOAPI void zoo_set_log_stream(FILE * logStream);ZOOAPI const clientid_t *zoo_client_id(zhandle_t * zh);ZOOAPI int zoo_recv_timeout(zhandle_t * zh);ZOOAPI const void *zoo_get_context(zhandle_t * zh);ZOOAPI void zoo_set_context(zhandle_t * zh, void *context);ZOOAPI watcher_fn zoo_set_watcher(zhandle_t * zh, watcher_fn newFn);ZOOAPI struct sockaddr *zookeeper_get_connected_host(zhandle_t * zh, struct sockaddr*addr,socklen_t * addr_len);ZOOAPI int zookeeper_interest(zhandle_t * zh, int *fd, int *interest,struct timeval *tv);ZOOAPI int zookeeper_process(zhandle_t * zh, int events);ZOOAPI int zoo_state(zhandle_t * zh);ZOOAPI const char *zerror(int c);ZOOAPI int is_unrecoverable(zhandle_t * zh);ZOOAPI void zoo_deterministic_conn_order(int yesOrNo);

三、与 zoo_multi() 和 zoo_amulti() 批量操作相关的 zoo_op_t 初始化

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);void zoo_delete_op_init(zoo_op_t * op, const char *path, int version);void zoo_set_op_init(zoo_op_t * op, const char *path,const char *buffer, int buflen, int version,struct Stat *stat);void zoo_check_op_init(zoo_op_t * op, const char *path, int version);

四、Zookeeper C API 同步接口

1）创建znode节点

ZOOAPI int zoo_create(zhandle_t * zh, const char *path,const char *value, int valuelen,const struct ACL_vector *acl, int flags,char *path_buffer, int path_buffer_len);

zh				zookeeper_init() 返回的 zookeeper 句柄。
path			节点路径。
value			该节点保存的数据。
valuelen		该节点保存数据的大小。如果 value 被设置为 NULL(该 znode 节点不包含数据)，则 valuelen 应该设置为 -1。
acl				该节点初始 ACL,ACL 不能为null 或空。
flags			该参数可以设置为 0，或者创建标识符 ZOO_EPHEMERAL, ZOO_SEQUENCE 的组合或(OR)。
path_buffer		用于保存返回节点新路径（因为设置了 ZOO_SEQUENCE 后 zoo_create 所创建的节点名称与参数 path 提供的名称不同，新的节点名称后面填充了序号），path 字符串以 NULL 结束。path_buffer 可以设置为 NULL，此时 path_buffer_len 等于 0。
path_buffer_len	path_buffer 的长度，如果新节点名称的长度大于path_buffer_len，则节点名称将会被截断，而服务器端该节点的名称不会截断。

2）删除znode节点

ZOOAPI int zoo_delete(zhandle_t * zh, const char *path, int version);

zh		zookeeper_init() 返回的 zookeeper 句柄。
path	节点路径。
version	节点的版本号，如果该 znode 节点的实际版本号与该参数提供的版本号不一值，则删除节点失败，如果 version 为 -1，则不作版本检查。

3）可设置 watch 的 API(exists(两个) + get(两个) + get_children(四个) = 八个)

exists

• zoo_exists() 和 zoo_wexists()的区别

检查节点状态 exists(两个，分别是 zoo_exists() 和 zoo_wexists()，区别是后者可以指定单独的 watcher_fn(监视器回调函数)，而前者只能用 zookeeper_init() 设置的全局监视器回调函数，同时 get 和 get_children两族函数也一样，带有zoo_w* 的函数可以指定单独的 watcher_fn)。

ZOOAPI int zoo_exists(zhandle_t * zh, const char *path, int watch,struct Stat *stat);ZOOAPI int zoo_wexists(zhandle_t * zh, const char *path,watcher_fn watcher, void *watcherCtx,struct Stat *stat);

• 参数说明

zh			zookeeper_init() 返回的 zookeeper 句柄。
path		节点路径。
watch		如果非 0，则在服务器端设置监视，当节点发生变化时客户端会得到通知，即使当前指定的节点不存在也会设置监视，这样该节点被创建时，客户端也可以得到通知。
stat		返回的 Stat 信息。
watcherCtx	用户指定的数据，将被传入到监视器回调函数中，与由 zookeeper_init() 设置的全局监视器上下文不同，该函数设置的监视器上下文只与当前的监视器相关联。

get获取节点数据

ZOOAPI int zoo_get(zhandle_t * zh, const char *path, int watch,char *buffer, int *buffer_len, struct Stat *stat);
--------------------
zh		zookeeper_init() 返回的 zookeeper 句柄。
path	节点路径。
watch	如果非0，则在服务器端设置监视，当节点发生变化时客户端会得到通知。
buffer	用于保存从 zookeeper 服务器获取的节点数据。
buffer_len	buffer 大小，一旦成功返回该值将会被设置为节点数据的实际大小，如果节点的数据为空，则数据大小为 -1，buffer_len 也为 -1。
stat	如果非空，stat 指向的结构将会保存该节点的 Stat 信息。ZOOAPI int zoo_wget(zhandle_t * zh, const char *path,watcher_fn watcher, void *watcherCtx,char *buffer, int *buffer_len, struct Stat *stat);
-----------------------
zh		zookeeper_init() 返回的 zookeeper 句柄。
path	节点路径。
watcher	如果不为 NULL 则会在服务器端设置监视，当节点发生变化时客户端会得到通知。
watcherCtx	用户指定的数据，将被传入到监视器回调函数中，与由 zookeeper_init() 设置的全局监视器上下文不同，该函数设置的监视器上下文只与当前的监视器相关联。
buffer	用于保存从 zookeeper 服务器获取的节点数据。
buffer_len	buffer 大小，一旦成功返回该值将会被设置为节点数据的实际大小，如果节点的数据为空，则数据大小为 -1，buffer_len 也为 -1。
stat	如果非空，stat 指向的结构将会保存该节点的 Stat 信息。

get_children获取子节点列表

ZOOAPI int zoo_get_children(zhandle_t * zh, const char *path,int watch, struct String_vector *strings);
--------------------
zh		zookeeper_init() 返回的 zookeeper 句柄。
path	节点路径。
watch	如果非0，则在服务器端设置监视，当节点发生变化时客户端会得到通知。
strings	返回各个子节点路径ZOOAPI int zoo_wget_children(zhandle_t * zh, const char *path,watcher_fn watcher, void *watcherCtx,struct String_vector *strings);
---------------------
zh		zookeeper_init() 返回的 zookeeper 句柄。
path	节点路径。
watcher	如果不为 NULL 则会在服务器端设置监视，当节点发生变化时客户端会得到通知。
watcherCtx	用户指定的数据，将被传入到监视器回调函数中，与由 zookeeper_init() 设置的全局监视器上下文不同，该函数设置的监视器上下文只与当前的监视器相关联。
strings	回各个子节点路径ZOOAPI int zoo_get_children2(zhandle_t * zh, const char *path,int watch, struct String_vector *strings,struct Stat *stat);
-----------------------------
该函数最早出现在 Zookeeper 3.3.0中，该函数功能与 zoo_get_children() 基本一致，但同时还会返回指定节点的 Stat 信息。zh		zookeeper_init() 返回的 zookeeper 句柄。
path	节点路径。
watch	如果非0，则在服务器端设置监视，当节点发生变化时客户端会得到通知。
strings	返回各个子节点路径。
stat	返回指定节点的 Stat 信息。ZOOAPI int zoo_wget_children2(zhandle_t * zh, const char *path,watcher_fn watcher, void *watcherCtx,struct String_vector *strings,struct Stat *stat);
------------------------
ZOOAPI int zoo_wget_children2(zhandle_t * zh, const char *path,watcher_fn watcher, void *watcherCtx,struct String_vector *strings,struct Stat *stat);
该函数最早出现在 Zookeeper 3.3.0中，该函数功能与 zoo_wget_children() 基本一致，但同时还会返回指定节点的 Stat 信息。zh		zookeeper_init() 返回的 zookeeper 句柄。
path	节点路径。
watcher	如果不为 NULL 则会在服务器端设置监视，当节点发生变化时客户端会得到通知。
watcherCtx	用户指定的数据，将被传入到监视器回调函数中，与由 zookeeper_init() 设置的全局监视器上下文不同，该函数设置的监视器上下文只与当前的监视器相关联。
strings	返回各个子节点路径。
stat	返回指定节点的 Stat 信息。

4）访问、设置节点 ACL (两个)

获取节点 ACL 信息

ZOOAPI int zoo_get_acl(zhandle_t * zh, const char *path, struct ACL_vector *acl, struct Stat *stat);
zh		zookeeper_init() 返回的 zookeeper 句柄。
path	节点路径。
acl		该函数所返回的指定节点的 ACL 信息。
stat	返回指定节点的 Stat 信息。

设置节点 ACL

ZOOAPI int zoo_set_acl(zhandle_t * zh, const char *path, int version, const struct ACL_vector *acl);
zh		zookeeper_init() 返回的 zookeeper 句柄。
path	节点路径。
version	节点的版本号。
acl		需要设置的 ACL 信息。

5）批处理，即原子性地一次提交多个 Zookeeper 操作。

ZOOAPI int zoo_multi(zhandle_t * zh, int count, const zoo_op_t * ops,zoo_op_result_t * results);
zh		zookeeper_init() 返回的 zookeeper 句柄。
count	提交操作的个数。
ops		包含所提交操作数组。
results	包含操作所返回结果的数组。

zoo_opt_t结构体（其中 zoo_op_t 是各种操作(创建、删除节点，设置节点数据和检查节点状态四种操作)一个封装(联合体)，定义如下：）

typedef struct zoo_op {int type;union {// CREATEstruct {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;// SETstruct {const char *path;const char *data;int datalen;int version;struct Stat *stat;} set_op;// CHECKstruct {const char *path;int version;} check_op;};
} zoo_op_t;

zoo_op_t一般由以下四个函数初始化

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);void zoo_delete_op_init(zoo_op_t * op, const char *path, int version);void zoo_set_op_init(zoo_op_t * op, const char *path,const char *buffer, int buflen, int version,struct Stat *stat);void zoo_check_op_init(zoo_op_t * op, const char *path, int version);

zoo_op_result_t 用于保存 zoo_multi 或者 zoo_amulti 返回的其中一个结果，定义如下：

typedef struct zoo_op_result {int err;char *value;int valuelen;struct Stat *stat;
} zoo_op_result_t;

6）其他接口

ZOOAPI int zoo_add_auth(zhandle_t * zh, const char *scheme,const char *cert, int certLen,void_completion_t completion, const void *data);ZOOAPI int zoo_set(zhandle_t * zh, const char *path,const char *buffer, int buflen, int version);ZOOAPI int zoo_set2(zhandle_t * zh, const char *path,const char *buffer, int buflen, int version,struct Stat *stat);

五、Zookeeper C API 异步接口

1）异步创建znode节点

//异步方式创建znode节点
ZOOAPI 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);
---------------
参数说明：
zh			zookeeper_init() 返回的 zookeeper 句柄。
path		节点路径。
value		该节点保存的数据。
valuelen	该节点保存数据的大小。
acl			该节点初始 ACL,ACL 不能为null 或空。
flags		该参数可以设置为 0，或者创建标识符 ZOO_EPHEMERAL, ZOO_SEQUENCE 的组合或(OR)。
completion	当创建节点请求完成时会调用该函数，该函数原型详见第三讲《回调函数》一节。同时传递给completion的 rc参
数为: ZOK 操作完成；ZNONODE 父节点不存在；ZNODEEXISTS 节点已存在；ZNOAUTH 客户端没有权限创建节点。
ZNOCHILDRENFOREPHEMERALS 临时节点不能创建子节点。
data		completino函数被调用时，传递给 completion 的数据。

• 使用举例

// struct ACL ALL_ACL[] = {{ZOO_PERM_ALL, ZOO_ANYONE_ID_UNSAFE}};// struct ACL_vector ALL_PERMS = {1, ALL_ACL};int ret = zoo_acreate(zkhandle, "/xyz", "hello", 5,&ZOO_OPEN_ACL_UNSAFE, 0 /* ZOO_SEQUENCE */,zktest_string_completion, "acreate");if (ret) {fprintf(stderr, "Error %d for %s\n", ret, "acreate");exit(EXIT_FAILURE);}

2）调用 exists() 和zoo_aexists()函数，设置监视器。

• 代码举例

void zktest_stat_completion(int rc, const struct Stat *stat, const void *data)
{fprintf(stderr, "%s: rc = %d Stat:\n", (char*)data, rc);zktest_dump_stat(stat);
}
//main
ret = zoo_aexists(zkhandle, "/xyz", 1, zktest_stat_completion, "aexists");if (ret) {fprintf(stderr, "Error %d for %s\n", ret, "aexists");exit(EXIT_FAILURE);}

• 函数原型

ZOOAPI int zoo_aexists(zhandle_t * zh, const char *path, int watch,stat_completion_t completion, const void *data);
zh			zookeeper_init() 返回的 zookeeper 句柄。
path		节点路径。
watcher		如果非 0，则在服务器端设置监视，当节点发生变化时客户端会得到通知，即使当前指定的节点不存在也会设置监视，这样该节点被创建时，客户端也可以得到通知。
watcherCtx	用户指定的数据，将被传入到监视器回调函数中，与由 zookeeper_init() 设置的全局监视器上下文不同，该函数设置的监视器上下文只与当前的监视器相关联。
completion	当 zoo_awexists 请求完成时会调用该函数，该函数原型详见第三讲《回调函数》一节。同时传递给completion的 rc参数为: ZOK 操作完成；ZNONODE 节点不存在；ZNOAUTH 客户端没有权限删除节点。
data		completion 函数被调用时，传递给 completion 的数据。

3）调用 delete 函数，删除 znode 节点。

• 代码举例

void zktest_void_completion(int rc, const void *data)
{fprintf(stderr, "[%s]: rc = %d\n", (char*)(data==0?"null":data), rc);
}
//main
ret = zoo_adelete(zkhandle, "/xyz", -1, zktest_void_completion, "adelete");if (ret) {fprintf(stderr, "Error %d for %s\n", ret, "adelete");exit(EXIT_FAILURE);}

• 原型

ZOOAPI int zoo_adelete(zhandle_t * zh, const char *path, int version,void_completion_t completion, const void *data);
//其中 zoo_op_t 是各种操作(创建、删除节点，设置节点数据和检查节点状态四种操作)一个封装(联合体)，定义如下：

zh			zookeeper_init() 返回的 zookeeper 句柄。
path		节点路径。
version		期望的节点版本号，如果真实的版本号与期望的版本号不同则 zoo_delete() 调用失败，-1 表示不不检查版本号。
completion	当删除节点请求完成时会调用该函数，该函数原型详见第三讲《回调函数》一节。同时传递给completion的 rc参数为: ZOK 操作完成；ZNONODE 节点不存在；ZNOAUTH 客户端没有权限删除节点；ZBADVERSION 版包号不匹配；ZNOTEMPTY 当前节点存在子节点，不能被删除。
data		completion 函数被调用时，传递给 completion 的数据。

4）获得节点数据(两个API)

ZOOAPI int zoo_aget(zhandle_t * zh, const char *path, int watch,data_completion_t completion, const void *data);
ZOOAPI int zoo_awget(zhandle_t * zh, const char *path,watcher_fn watcher, void *watcherCtx,data_completion_t completion, const void *data);
zh		zookeeper_init() 返回的 zookeeper 句柄。
path	节点路径。
watcher	如果非 0，则在服务器端设置监视，当节点发生变化时客户端会得到通知，即使当前指定的节点不存在也会设置监视，这样该节点被创建时，客户端也可以得到通知。
watcherCtx	用户指定的数据，将被传入到监视器回调函数中，与由 zookeeper_init() 设置的全局监视器上下文不同，该函数设置的监视器上下文只与当前的监视器相关联。
completion	当 zoo_awget 请求完成时会调用该函数，该函数原型详见第三讲《回调函数》一节。同时传递给completion的 rc参数为: ZOK 操作完成；ZNONODE 节点不存在；ZNOAUTH 客户端没有权限删除节点。
data	completion 函数被调用时，传递给 completion 的数据。

5）获取子节点列表 aget_children (四个)

ZOOAPI int zoo_aget_children(zhandle_t * zh, const char *path,int watch,strings_completion_t completion,const void *data);
ZOOAPI int zoo_awget_children(zhandle_t * zh, const char *path,watcher_fn watcher, void *watcherCtx,strings_completion_t completion,const void *data);
ZOOAPI int zoo_aget_children2(zhandle_t * zh, const char *path,int watch,strings_stat_completion_t completion,const void *data);
ZOOAPI int zoo_awget_children2(zhandle_t * zh, const char *path,watcher_fn watcher, void *watcherCtx,strings_stat_completion_t completion,const void *data);
zh			zookeeper_init() 返回的 zookeeper 句柄。
path		节点路径。
watcher		如果非 0，则在服务器端设置监视，当节点发生变化时客户端会得到通知，即使当前指定的节点不存在也会设置监视，这样该节点被创建时，客户端也可以得到通知。
watcherCtx	用户指定的数据，将被传入到监视器回调函数中，与由 zookeeper_init() 设置的全局监视器上下文不同，该函数设置的监视器上下文只与当前的监视器相关联。
completion	当zoo_awget_children2 请求完成时会调用该函数，该函数原型详见第三讲《回调函数》一节。同时传递给completion的 rc参数为: ZOK 操作完成；ZNONODE 节点不存在；ZNOAUTH 客户端没有权限删除节点。
data		completion 函数被调用时，传递给 completion 的数据。

6）访问、设置节点 ACL 的 API

ZOOAPI int zoo_aget_acl(zhandle_t * zh, const char *path,acl_completion_t completion, const void *data);
----------------
zh			zookeeper_init() 返回的 zookeeper 句柄。
path		节点路径。
completion	当 zoo_aget_acl 请求完成时会调用该函数，该函数原型详见第三讲《回调函数》一节。同时传递给completion的 rc参数为: ZOK 操作完成；ZNONODE 节点不存在；ZNOAUTH 客户端没有权限删除节点。
data		completion 函数被调用时，传递给 completion 的数据。ZOOAPI int zoo_aset_acl(zhandle_t * zh, const char *path, int version,struct ACL_vector *acl, void_completion_t,const void *data);
---------------
zh		zookeeper_init() 返回的 zookeeper 句柄。
path	节点路径。
buffer	保存需要设置的 ACL。
buflen	buffer 的长度。
completion	当 zoo_aset_acl 请求完成时会调用该函数，该函数原型详见第三讲《回调函数》一节。同时传递给completion的 rc参数为: ZOK 操作完成；ZNONODE 节点不存在；ZNOAUTH 客户端没有权限删除节点;ZINVALIDACL 非法 ACL；ZBADVERSION 版本号不匹配。
data	completion 函数被调用时，传递给 completion 的数据。

7）异步批处理 API

ZOOAPI int zoo_amulti(zhandle_t * zh, int count, const zoo_op_t * ops,zoo_op_result_t * results, void_completion_t,const void *data);
异步批处理与同步批处理方式类似见《Zookeeper C API 指南五(同步 API 介绍)》，只是需要额外设置一个 void_completion_t 回调函数，在此不再赘述。

8）其他API

ZOOAPI int zoo_async(zhandle_t * zh, const char *path,string_completion_t completion, const void *data);ZOOAPI int zoo_aget_acl(zhandle_t * zh, const char *path,acl_completion_t completion, const void *data);ZOOAPI int zoo_aset_acl(zhandle_t * zh, const char *path, int version,struct ACL_vector *acl, void_completion_t,const void *data);ZOOAPI int zoo_amulti(zhandle_t * zh, int count, const zoo_op_t * ops,zoo_op_result_t * results, void_completion_t,const void *data);

六、编译测试程序

1）头文件包含 #include <zookeeper/zookeeper.h>
2）如果你需要编译多线程版本客户端程序，请添加编译选项 -DTHREADED，同时链接时应链接 zookeeper_mt 库；如果你需要编译单线程客户端程序，请不要添加编译选项 -DTHREADED，同时链接时应链接 zookeeper_st 库。

七、其他接口

1）zookeeper_process

• 作用
  通知zookeeper注册的事件已经发生

• 参数：

• events：ZOOKEEPER_WRITE、ZOOKEEPER_READ标志

• 表达式

ZOOAPI int zookeeper_process(zhandle_t * zh, int events);

2) zookeeper_interest

• 函数作用
  返回向zookeeper中注册的事件列表

• 参数：
  -fd：文件描述列表
  -interest：事件类型，ZOOKEEPER_WRITE、ZOOKEEPER_READ标志
  -select或是poll超时时间

• 表达式

ZOOAPI int zookeeper_interest(zhandle_t * zh, int *fd, int *interest,struct timeval *tv);