Zookeeper C API之接口描述

2023-10-08 11:35:52

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;

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

码农公寓

相关文章