Zookeeper C API接口大部分以zoo_开头,少量接口以zookeeper_开头。 除了初始化/销毁句柄、设置日志等级/日志流以及一些辅助功能的API外,Zookeeper C API接口分为同步接口和异步接口:同步接口以zoo_开头、异步接口以zoo_a开头。
1、初始化/销毁Zookeeper句柄 初始化Zookeeper句柄(zhandle_t) 原型:
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: Watcher回调函数 clientid: 客户端尝试重连的先前的会话ID,如果不重连先前的会话,则设置为0。客户端可以通过调用zoo_client_id来访问一个已经连接上的、有效的会话ID,如果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。
销毁Zookeeper句柄
ZOOAPI int zookeeper_close(zhandle_t * zh);
2、同步API 同步API可以分为以下几类:1)创建/删除znode节点、2)可设置watch的API、3)访问/设置节点ACL的API,4)批处理API
1)创建/删除znode节点
a)创建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: 节点保存的数据。 value_len: 节点保存的数据大小。如果value为NULL(节点不包含数据),则value_len设置为-1。 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,则节点名称将会被截断,而服务器该节点的名称不会截断。
b)删除znode节点: 原型:
ZOOAPI int zoo_delete(zhandle_t * zh, const char *path, int version);
参数说明:
zk: Zookeeper_init()返回的zookeeper句柄。 path: 节点路径。 version: 节点版本号。如果version的值与znode节点的版本号不一致,则删除节点失败;如果version为-1,则不做版本检查。
2)可设置Watcher的API
a)检查节点状态 检查节点状态有两个接口,分别是zoo_exists()和zoo_wexists(),区别是后者可以指定单独的watcher_fn(监视回调函数),而前者只能用zookeeper_int()设置的全局监视器回调函数。
zoo_exists(): 原型:
ZOOAPI int zoo_exists(zhandle_t * zh, const char *path, int watch, struct Stat *stat);
参数说明:
zh: Zookeeper_init()返回的zookeeper句柄。 path: 节点路径。 watch:如果非0,则在服务器端设置监视。当节点发生变化时,客户端会得到通知,即使指定的节点不存在也会设置监视,这样该节点被创建时,客户端也可以得到通知。 stat: 返回的stat信息。
zoo_wexists(): 原型:
ZOOAPI int zoo_wexists(zhandle_t * zh, const char *path, watcher_fn watcher, void *watcherCtx, struct Stat *stat);
参数说明:
zh: Zookeeper_init()返回的zookeeper句柄。 path: 节点路径。 watcher: 如果不为NULL则在服务器断设置监视器。当节点发生变化时,客户端会得到通知,即使指定的节点不存在也会设置监视,这样该节点被创建时,客户端也可以得到通知。 watcherCtx: 用户指定的数据。监视器回调函数使用,与zookeeper_init()设置的全局监视器上下文不同,此上下文只与当前的监视器相关联。 stat: 返回的stat信息。
b)获取节点数据 与检查节点状态API类似,分为两种:zoo_get()和zoo_wget()。
zoo_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大小。如果节点数据为空,则buffer_len为-1。 stat: 返回的stat信息。
zoo_wget(): 原型:
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:节点路径。 watch: 如果非NULL,则在服务器端设置监视。节点发生变化时客户端会得到通知。 watcherCtx: 用户指定的数据。监视器回调函数使用,与zookeeper_init()设置的全局监视器上下文不同,此上下文只与当前的监视器相关联。 buffer: 保存从zookeeper服务器获取的节点数据。 buffer_len: Buffer大小。如果节点数据为空,则buffer_len为-1。 stat: 返回的stat信息。
c)获取子节点列表 获取子节点列表有四个接口,分别是:zoo_get_chiledren()、zoo_wget_children()、zoo_get_children2()和zoo_wget_children2()。后两个相比较于前两个接口,在获取子节点列表的同时返回stat信息。
zoo_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: 返回各个子节点路径。
zoo_wget_children(): 原型:
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: 节点路径。 watch: 如果非NULL,则在服务器端设置监视。节点发生变化时客户端会得到通知。 watcherCtx: 用户指定的数据。监视器回调函数使用,与zookeeper_init()设置的全局监视器上下文不同,此上下文只与当前的监视器相关联。 strings: 返回各个子节点路径。
zoo_get_chiledren2(): 原型:
ZOOAPI int zoo_get_children2(zhandle_t * zh, const char *path, int watch, struct String_vector *strings,struct Stat *stat);
参数说明:
zh: Zookeeper_init()返回的zookeeper句柄。 path: 节点路径。 watch: 如果非NULL,则在服务器端设置监视。节点发生变化时客户端会得到通知。 strings: 返回各个子节点路径。 stat: 返回的stat信息。
zoo_wget_chiledren2(): 原型:
ZOOAPI int zoo_wget_children2(zhandle_t * zh, const char *path, watcher_fn watcher, void *watcherCtx,struct String_vector *strings, struct Stat *stat);
参数说明:
zh: Zookeeper_init()返回的zookeeper句柄。 path: 节点路径。 watch: 如果非NULL,则在服务器端设置监视。节点发生变化时客户端会得到通知。 watcherCtx: 用户指定的数据。监视器回调函数使用,与zookeeper_init()设置的全局监视器上下文不同,此上下文只与当前的监视器相关联。 strings: 返回各个子节点路径。 stat: 返回的stat信息。
3)访问/设置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信息。 strings: 返回各个子节点路径。
设置ACL接口 原型:
ZOOAPI int zoo_set_acl(zhandle_t * zh, const char *path, int version, const struct ACL_vector *acl);
参数说明:
zh: Zookeeper_init()返回的zookeeper句柄。 count: 提交操作的个数。 ops: 提交操作数组。 results: 操作返回结果的数组。
4)批处理API 原型:
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_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;
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
- 11
- 12
- 13
- 14
- 15
- 16
- 17
- 18
- 19
- 20
- 21
- 22
- 23
- 24
- 25
- 26
- 27
- 28
- 29
- 30
- 31
- 32
- 33
- 34
- 35
- 36
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;
异步API 与同步API相同,异步API也分为4类。
1)创建/删除znode节点
a)创建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: 节点保存的数据。 value_len: 节点保存的数据大小。如果value为NULL(节点不包含数据),则value_len设置为-1。 acl: 节点出事ACL,不能为NULL或空。 flags: 可设置为0,或者为标识符ZOO_EPHEMERAL、ZOO_SEQUENCE的OR组合。 completion: zoo_acreate请求完成时会调用该函数。传递给completion的rc参数为:ZOK操作完成;ZNONODE父节点不存在;ZNODEEXISTS节点已存在;ZNOAUTH客户端没有权限;ZNOCHILDRENFOREPHEMERALS临时节点不能创建子节点。 data: Completion函数被调用时,传递给completion的数据。
b)删除znode节点: 原型:
ZOOAPI int zoo_adelete(zhandle_t * zh, const char *path, int version, void_completion_t completion, const void *data);
参数说明:
zk: Zookeeper_init()返回的zookeeper句柄。 path: 节点路径。 version: 节点版本号。如果version的值与znode节点的版本号不一致,则删除节点失败;如果version为-1,则不做版本检查。 completion zoo_adelete请求完成时会调用该函数。传递给completion的rc参数为:ZOK操作完成;ZNONODE节点不存在;ZNOAUTH客户端没有权限;ZBADVERSION版本号不匹配;ZNOTEMPTY存在子节点,不能删除。 data: Completion函数被调用时,传递给completion的数据。
2)可设置Watcher的API
a)检查节点状态 检查节点状态有两个接口,分别是zoo_aexists()和zoo_awexists(),区别是后者可以指定单独的watcher_fn(监视回调函数),而前者只能用zookeeper_int()设置的全局监视器回调函数。
zoo_aexists(): 原型:
ZOOAPI int zoo_aexists(zhandle_t * zh, const char *path, int watch, stat_completion_t completion, const void *data);
参数说明:
zh: Zookeeper_init()返回的zookeeper句柄。 path: 节点路径。 watch:如果非0,则在服务器端设置监视。当节点发生变化时,客户端会得到通知,即使指定的节点不存在也会设置监视,这样该节点被创建时,客户端也可以得到通知。 completion: zoo_aexists请求完成时会调用该函数。传递给completion的rc参数为:ZOK操作完成;ZNONODE节点不存在;ZNOAUTH客户端没有权限。 data: Completion函数被调用时,传递给completion的数据。
zoo_awexists(): 原型:
ZOOAPI int zoo_awexists(zhandle_t * zh, const char *path, watcher_fn watcher, void *watcherCtx, stat_completion_t completion, const void *data);
参数说明:
zh: Zookeeper_init()返回的zookeeper句柄。 path: 节点路径。 watcher: 如果不为NULL则在服务器断设置监视器。当节点发生变化时,客户端会得到通知,即使指定的节点不存在也会设置监视,这样该节点被创建时,客户端也可以得到通知。 watcherCtx: 用户指定的数据。监视器回调函数使用,与zookeeper_init()设置的全局监视器上下文不同,此上下文只与当前的监视器相关联。 completion: zoo_awexists请求完成时会调用该函数。传递给completion的rc参数为:ZOK操作完成;ZNONODE节点不存在;ZNOAUTH客户端没有权限。 data : Completion函数被调用时,传递给completion的数据。
b)获取节点数据 与检查节点状态API类似,分为两种:zoo_get()和zoo_wget()。
zoo_aget(): 原型:
ZOOAPI int zoo_aget(zhandle_t * zh, const char *path, int watch, data_completion_t completion, const void *data);
参数说明:
zh: Zookeeper_init()返回的zookeeper句柄。 path: 节点路径。 watch: 如果非0,则在服务器端设置监视。当节点发生变化时客户端会得到通知。 buffer: 保存从zookeeper服务器获取的节点数据。 completion: zoo_aget请求完成时会调用该函数。传递给completion的rc参数为:ZOK操作完成;ZNONODE节点不存在;ZNOAUTH客户端没有权限。 data : Completion函数被调用时,传递给completion的数据。
zoo_awget(): 原型:
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:节点路径。 watch: 如果非NULL,则在服务器端设置监视。节点发生变化时客户端会得到通知。 watcherCtx: 用户指定的数据。监视器回调函数使用,与zookeeper_init()设置的全局监视器上下文不同,此上下文只与当前的监视器相关联。 completion: zoo_awget请求完成时会调用该函数。传递给completion的rc参数为:ZOK操作完成;ZNONODE节点不存在;ZNOAUTH客户端没有权限。 data : Completion函数被调用时,传递给completion的数据。
c)获取子节点列表 获取子节点列表有四个接口,分别是:zoo_aget_chiledren()、zoo_awget_children()、zoo_aget_children2()和zoo_awget_children2()。后两个相比较于前两个接口,在获取子节点列表的同时返回stat信息。
zoo_aget_children(): 原型:
ZOOAPI int zoo_aget_children(zhandle_t * zh, const char *path, int watch, strings_completion_t completion, const void *data);
参数说明:
zh: Zookeeper_init()返回的zookeeper句柄。 path: 节点路径。 watch: 如果非0,则在服务器端设置监视。节点发生变化时客户端会得到通知。 completion: zoo_aget_children请求完成时会调用该函数。传递给completion的rc参数为:ZOK操作完成;ZNONODE节点不存在;ZNOAUTH客户端没有权限。 data : Completion函数被调用时,传递给completion的数据。
zoo_awget_children(): 原型:
ZOOAPI int zoo_awget_children(zhandle_t * zh, const char *path, watcher_fn watcher, void *watcherCtx, strings_completion_t completion, const void *data);
参数说明:
zh: Zookeeper_init()返回的zookeeper句柄。 path: 节点路径。 watch: 如果非NULL,则在服务器端设置监视。节点发生变化时客户端会得到通知。 watcherCtx: 用户指定的数据。监视器回调函数使用,与zookeeper_init()设置的全局监视器上下文不同,此上下文只与当前的监视器相关联。 completion: zoo_awget_children请求完成时会调用该函数。传递给completion的rc参数为:ZOK操作完成;ZNONODE节点不存在;ZNOAUTH客户端没有权限。 data : Completion函数被调用时,传递给completion的数据。
zoo_aget_chiledren2(): 原型:
ZOOAPI int zoo_aget_children2(zhandle_t * zh, const char *path, int watch, strings_stat_completion_t completion, const void *data);
参数说明:
zh: Zookeeper_init()返回的zookeeper句柄。 path: 节点路径。 watch: 如果非NULL,则在服务器端设置监视。节点发生变化时客户端会得到通知。 completion: zoo_aget_children2请求完成时会调用该函数。传递给completion的rc参数为:ZOK操作完成;ZNONODE节点不存在;ZNOAUTH客户端没有权限。 data : Completion函数被调用时,传递给completion的数据。
zoo_awget_chiledren2(): 原型:
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: 节点路径。 watch: 如果非NULL,则在服务器端设置监视。节点发生变化时客户端会得到通知。 watcherCtx: 用户指定的数据。监视器回调函数使用,与zookeeper_init()设置的全局监视器上下文不同,此上下文只与当前的监视器相关联。 completion: zoo_awget_children2请求完成时会调用该函数。传递给completion的rc参数为:ZOK操作完成;ZNONODE节点不存在;ZNOAUTH客户端没有权限。 data : Completion函数被调用时,传递给completion的数据。
3)访问/设置ACL接口
访问ACL接口 原型:
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的数据。
设置ACL接口 原型:
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的数据。
4)批处理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);
与同步批处理API借口类似,只需要额外设置一个void_completion_t回调函数。
4、辅助API 常用辅助API如下: 1)设置日志等级
ZOOAPI void zoo_set_debug_level(ZooLogLevel logLevel);
logLevel取值如下:ZOO_LOG_LEVEL_ERROR、ZOO_LOG_LEVEL_WARN,ZOO_LOG_INFO、ZOO_LOG_LEVEL_DEBUG。 只有客户端的当前连接状态有效时才可以使用。
2)设置日志流
ZOOAPI void zoo_set_log_stream(FILE * logStream);
Zookeeper C API默认的日志流是标准输出,可以通过zoo_set_stream设置zookeeper C API的日志流为文件。
3)获取客户端session id
ZOOAPI const clientid_t *zoo_client_id(zhandle_t * zh);
只有客户端的当前连接状态有效时才可以使用。
4)返回当前会话超时时间
ZOOAPI int zoo_recv_timeout(zhandle_t * zh);
5)获取Zookeeper句柄上下文
ZOOAPI const void *zoo_get_context(zhandle_t * zh);
6)设置Zookeeper句柄上下文
ZOOAPI void zoo_set_context(zhandle_t * zh, void *context);
7)设置Zookeeper句柄Watcher回调函数
ZOOAPI watcher_fn zoo_set_watcher(zhandle_t * zh, watcher_fn newFn);
接口返回旧的Watcher回调函数
8)返回当前Zookeeper链接的套接字地址
ZOOAPI struct sockaddr *zookeeper_get_connected_host(zhandle_t * zh, struct sockaddr *addr, socklen_t * addr_len);
9)获取当前Zookeeper链接状态
ZOOAPI int zoo_state(zhandle_t * zh);
10)返回错误码的字符串表示
ZOOAPI const char *zerror(int c);
11)检查当前Zookeeper链接是否为可恢复的
ZOOAPI int is_unrecoverable(zhandle_t * zh);
|
请发表评论