zookeeper C API

typedef void (*watcher_fn)(zhandle_t *zh, int type, int state, const char *path,void *watcherCtx);
watch回调函数，两种watch事件通知方式：
1.legacy：预先实现watch回调函数并将函数指针传入zookeeper_init，然后使用其他api设置watch。  （即在init函数中设置watcher，然后后边调用时，设置整型值watch来表明使用或者不使用watcher）
2.watcher object：一个函数指针和一个watcher上下文指针。watch触发时，两者结合调用。使用此类型，需使用'w'前缀api，如zoo_awexists、zoo_wget等.(直接使用回调函数)

zhandle_t *zookeeper_init(const char *host, watcher_fn fn, int recv_timeout, const clientid_t *clientid, void *context, int flags);
创建与ZooKeeper服务端通信的句柄和对应于此句柄的会话。会话的创建过程是异步的，收到ZOO_CONNECTED_STATE状态事件后，确认会话成功建立。 
 
int zookeeper_close(zhandle_t *zh);
关闭句柄，释放资源。调用函数后，会话将不可用，函数返回前会将未发送完毕的请求发送完，所以可能会引起阻塞。
对一个句柄来说，这个方法只许调用一次，调用多次将产生不确定的结果。对于调用过此方法的句柄，其他句柄操作也将产生不确定的结果。
 
const clientid_t *zoo_client_id(zhandle_t *zh);
返回客户端会话id，仅在与服务端连接正常时有效
 
int zoo_recv_timeout(zhandle_t *zh);
返回会话超时时间，仅在于服务端连接正常时有效，该值在与服务器重连后可能改变
 
const 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);
设置watch回调，返回之前的watch回调
 
struct sockaddr* zookeeper_get_connected_host(zhandle_t *zh, struct sockaddr *addr, socklen_t *addr_len);
返回服务端的网络地址（sockaddr结构），仅在与服务端连接正常是有效
 
int zookeeper_interest(zhandle_t *zh, int *fd, int *interest, struct timeval *tv);
暂时不太理解，可能是返回zookeeper在监听某个fd的读或者写
 
int zookeeper_process(zhandle_t *zh, int events);
暂时不太理解，通知zookeeper监听的事件发生了
 
typedef void (*void_completion_t)(int rc, const void *data);
函数类型定义，异步调用或连接断开或连接超时执行的回调类型
 
typedef void (*stat_completion_t)(int rc, const struct Stat *stat, const void *data);
同上，有返回值
 
typedef void (*data_completion_t)(int rc, const char *value, int value_len, const struct Stat *stat, const void *data);
同上，返回详细数据
 
typedef void (*strings_completion_t)(int rc, const struct String_vector *strings, const void *data);
同上
 
typedef void (*strings_stat_completion_t)(int rc, const struct String_vector *strings, const struct Stat *stat, const void *data);
同上
 
typedef void (*string_completion_t)(int rc, const char *value, const void *data);
同上
 
typedef void (*acl_completion_t)(int rc, struct ACL_vector *acl, struct Stat *stat, const void *data);
同上
 
int zoo_state(zhandle_t *zh);
返回句柄状态
 
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填充
 
int zoo_adelete(zhandle_t *zh, const char *path, int version, void_completion_t completion, const void *data);
删除一个节点
 
int zoo_aexists(zhandle_t *zh, const char *path, int watch, stat_completion_t completion, const void *data);
检查一个节点是否存在
 
int zoo_awexists(zhandle_t *zh, const char *path, watcher_fn watcher, void* watcherCtx, stat_completion_t completion, const void *data);
检查一个节点是否存在，它允许指定一个watcher对象（一个函数指针watcher和对应的上下文watcherCtx），在watch解除时，此函数会调用，watcherCtx作为watcher的传入参数
 
int zoo_aget(zhandle_t *zh, const char *path, int watch, data_completion_t completion, const void *data);
获取节点数据(legacy方式)。completion是回调函数，其rc参数可能是以下参数：ZOK-完成，ZNONODE-节点不存在，ZNOAUTH-客户端无权限
 
int zoo_awget(zhandle_t *zh, const char *path, watcher_fn watcher, void* watcherCtx, data_completion_t completion, const void *data);
获取节点数据（watcher object方式）。
 
int zoo_aset(zhandle_t *zh, const char *path, const char *buffer, int buflen, int version, stat_completion_t completion, const void *data);
设置节点数据
 
int zoo_aget_children(zhandle_t *zh, const char *path, int watch, strings_completion_t completion, const void *data);
获取子节点列表(legacy)
 
int zoo_awget_children(zhandle_t *zh, const char *path, watcher_fn watcher, void* watcherCtx, strings_completion_t completion, const void *data);
获取子节点列表(watcher object)
 
int zoo_aget_children2(zhandle_t *zh, const char *path, int watch, strings_stat_completion_t completion, const void *data);
获取子节点列表，3.3.0版本加入(legacy)
 
int zoo_awget_children2(zhandle_t *zh, const char *path, watcher_fn watcher, void* watcherCtx, strings_stat_completion_t completion, const void *data);
获取子节点列表，3.3.0版本加入(watcher object)
 
int zoo_async(zhandle_t *zh, const char *path, string_completion_t completion, const void *data);
Flush leader channel. 暂时不明确
 
int zoo_aget_acl(zhandle_t *zh, const char *path, acl_completion_t completion, const void *data);
获取节点的ACL。ACL描述了操作该节点所需具备的条件，即哪些人(id)具备哪些权限后才允许对节点执行哪些操作。
 
int zoo_aset_acl(zhandle_t *zh, const char *path, int version, struct ACL_vector *acl, void_completion_t, const void *data);
设置节点的ACL
 
int zoo_amulti(zhandle_t *zh, int count, const zoo_op_t *ops, zoo_op_result_t *results, void_completion_t, const void *data);
以原子方式执行一系列操作
 
const char* zerror(int c);
返回错误信息
 
int zoo_add_auth(zhandle_t *zh, const char* scheme, const char* cert, int certLen, void_completion_t completion, const void *data);
为应用程序指定证书。调用此函数用于认证的证书。服务端用scheme指定的安全服务对客户端连接进行认证。
如果认证失败，将与服务端断开连接，watcher触发，状态码是ZOO_AUTH_FAILED_STATE
 
int is_unrecoverable(zhandle_t *zh);
检查zookeeper连接是否可恢复
 
void zoo_set_debug_level(ZooLogLevel logLevel);
设置调试级别
 
void zoo_set_log_stream(FILE* logStream);
设置用于记录日志的文件流。默认使用stderr。若logStream为NULL，则使用默认值stderr。
 
void zoo_deterministic_conn_order(int yesOrNo);
用于启用或停用quarum端点的随机化排序，通常仅在测试时使用。
如果非0，使得client连接到quarum端按照被初始化的顺序。
如果是0，zookeeper_init将变更端点顺序，使得client连接分布在更优的端点上。
 
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);
同步建立节点
 
int zoo_delete(zhandle_t *zh, const char *path, int version);
同步删除节点
 
int zoo_exists(zhandle_t *zh, const char *path, int watch, struct Stat *stat);
同步检查节点是否存在
 
int zoo_wexists(zhandle_t *zh, const char *path, watcher_fn watcher, void* watcherCtx, struct Stat *stat);
同步检查节点是否存在(watcher object)
 
int zoo_get(zhandle_t *zh, const char *path, int watch, char *buffer, int* buffer_len, struct Stat *stat);
同步获取节点数据(legacy)
 
int zoo_wget(zhandle_t *zh, const char *path, watcher_fn watcher, void* watcherCtx, char *buffer, int* buffer_len, struct Stat *stat);
同步获取节点数据(watcher object)
 
int zoo_set(zhandle_t *zh, const char *path, const char *buffer, int buflen, int version);
同步设置节点数据
 
int zoo_set2(zhandle_t *zh, const char *path, const char *buffer, int buflen, int version, struct Stat *stat);
同步设置节点数据并返回当前节点的stat信息
 
int zoo_get_children(zhandle_t *zh, const char *path, int watch, struct String_vector *strings);
同步获取子节点列表(legacy)
 
int zoo_wget_children(zhandle_t *zh, const char *path, watcher_fn watcher, void* watcherCtx, struct String_vector *strings);
同步获取子节点列表(watcher object)
 
int zoo_get_children2(zhandle_t *zh, const char *path, int watch, struct String_vector *strings, struct Stat *stat);
同步获取子节点列表并返回当前节点的stat信息(legacy)，3.3.0版本加入
 
int zoo_wget_children2(zhandle_t *zh, const char *path, watcher_fn watcher, void* watcherCtx, struct String_vector *strings, struct Stat *stat);
同步获取子节点列表并返回当前节点的stat信息(watcher object)，3.3.0版本加入
 
int zoo_get_acl(zhandle_t *zh, const char *path, struct ACL_vector *acl, struct Stat *stat);
同步获取节点ACL
 
int zoo_set_acl(zhandle_t *zh, const char *path, int version, const struct ACL_vector *acl);
同步设置节点ACL
 
int zoo_multi(zhandle_t *zh, int count, const zoo_op_t *ops, zoo_op_result_t *results);
同步以原子方式执行一系列操作

说明：keeper C API 大部分接口可以根据同步和异步特性分为两类，同步接口以 zoo_* 开头，异步接口以则以 zoo_a* 开头。以w开头的函数表明使用watcher回调函数而不是整型watch和zookeeper中注册的watcher函数。

转自 ： http://www.cnblogs.com/caosiyang/archive/2012/11/09/2763190.html