Zookeeper C API之接口描述

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);
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7

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;
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6

异步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);

上一篇:港股分时交易数据


下一篇:spyder中opencv代码快速补全