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