上一講《Zookeeper C API 指南四(C API 概覽)》講了Zookeeper C API 的分類和幾個基本函數的用法，相信大家對 Zookeeper C API 也有了一個大致的了解，本文我會給大家介紹 Zookeeper C API 中的同步調用的函數(即以 zoo_* 開頭的函數)。
Zookeeper C API 中與訪問 Zookeeper 服務相關(比如創建、刪除 znode 節點，獲取子節點，設置 znode 數據等)的同步 API 如下：
ZOOAPI int zoo_add_auth(zhandle_t * zh, const char *scheme, const char *cert, int certLen, void_completion_t completion, const void *data); 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); ZOOAPI int zoo_delete(zhandle_t * zh, const char *path, int version); ZOOAPI int zoo_exists(zhandle_t * zh, const char *path, int watch, struct Stat *stat); ZOOAPI int zoo_wexists(zhandle_t * zh, const char *path, watcher_fn watcher, void *watcherCtx, struct Stat *stat); ZOOAPI int zoo_get(zhandle_t * zh, const char *path, int watch, char *buffer, int *buffer_len, struct Stat *stat); ZOOAPI int zoo_wget(zhandle_t * zh, const char *path, watcher_fn watcher, void *watcherCtx, char *buffer, int *buffer_len, struct Stat *stat); ZOOAPI int zoo_set(zhandle_t * zh, const char *path, const char *buffer, int buflen, int version); ZOOAPI int zoo_set2(zhandle_t * zh, const char *path, const char *buffer, int buflen, int version, struct Stat *stat); ZOOAPI int zoo_get_children(zhandle_t * zh, const char *path, int watch, struct String_vector *strings); ZOOAPI int zoo_wget_children(zhandle_t * zh, const char *path, watcher_fn watcher, void *watcherCtx, struct String_vector *strings); ZOOAPI int zoo_get_children2(zhandle_t * zh, const char *path, int watch, struct String_vector *strings, struct Stat *stat); ZOOAPI int zoo_wget_children2(zhandle_t * zh, const char *path, watcher_fn watcher, void *watcherCtx, struct String_vector *strings, struct Stat *stat); ZOOAPI int zoo_get_acl(zhandle_t * zh, const char *path, struct ACL_vector *acl, struct Stat *stat); ZOOAPI int zoo_set_acl(zhandle_t * zh, const char *path, int version, const struct ACL_vector *acl); ZOOAPI int zoo_multi(zhandle_t * zh, int count, const zoo_op_t * ops, zoo_op_result_t * results);
本文將以上同步 API 在此細分為一下幾類：(1). 創建、刪除 znode 節點，(2). 可設置 watch 的 API，(3). 訪問、設置節點 ACL 的 API，(4). 批處理 API
- 創建、刪除 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); ZOOAPI int zoo_delete(zhandle_t * zh, const char *path, int version);
- 創建 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 | 該節點保存的數據。 |
| valuelen | 該節點保存數據的大小。如果 value 被設置為 NULL(該 znode 節點不包含數據)，則 valuelen 應該設置為 -1。 |
| acl | 該節點初始 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，則節點名稱將會被截斷，而服務器端該節點的名稱不會截斷。 |
- 刪除 znode 節點：
ZOOAPI int zoo_delete(zhandle_t * zh, const char *path, int version);
| zh | zookeeper_init() 返回的 zookeeper 句柄。 |
| path | 節點路徑。 |
| version | 節點的版本號，如果該 znode 節點的實際版本號與該參數提供的版本號不一值，則刪除節點失敗，如果 version 為 -1，則不作版本檢查。 |
- 可設置 watch 的 API(exists(兩個) + get(兩個) + get_children(四個) = 八個)
ZOOAPI int zoo_exists(zhandle_t * zh, const char *path, int watch, struct Stat *stat); ZOOAPI int zoo_wexists(zhandle_t * zh, const char *path, watcher_fn watcher, void *watcherCtx, struct Stat *stat); ZOOAPI int zoo_get(zhandle_t * zh, const char *path, int watch, char *buffer, int *buffer_len, struct Stat *stat); ZOOAPI int zoo_wget(zhandle_t * zh, const char *path, watcher_fn watcher, void *watcherCtx, char *buffer, int *buffer_len, struct Stat *stat); ZOOAPI int zoo_get_children(zhandle_t * zh, const char *path, int watch, struct String_vector *strings); ZOOAPI int zoo_wget_children(zhandle_t * zh, const char *path, watcher_fn watcher, void *watcherCtx, struct String_vector *strings); ZOOAPI int zoo_get_children2(zhandle_t * zh, const char *path, int watch, struct String_vector *strings, struct Stat *stat); ZOOAPI int zoo_wget_children2(zhandle_t * zh, const char *path, watcher_fn watcher, void *watcherCtx, struct String_vector *strings, struct Stat *stat);
- 檢查節點狀態 exists(兩個，分別是 zoo_exists() 和 zoo_wexists()，區別是后者可以指定單獨的 watcher_fn(監視器回調函數)，而前者只能用 zookeeper_init() 設置的全局監視器回調函數，同時 get 和 get_children兩族函數也一樣，帶有zoo_w* 的函數可以指定單獨的 watcher_fn)。
ZOOAPI int zoo_exists(zhandle_t * zh, const char *path, int watch, struct Stat *stat);
| zh | zookeeper_init() 返回的 zookeeper 句柄。 |
| path | 節點路徑。 |
| watch | 如果非 0，則在服務器端設置監視，當節點發生變化時客戶端會得到通知，即使當前指定的節點不存在也會設置監視，這樣該節點被創建時，客戶端也可以得到通知。 |
| stat | 返回的 Stat 信息。 |
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 信息。 |
- 獲取節點數據 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 大小，一旦成功返回該值將會被設置為節點數據的實際大小，如果節點的數據為空，則數據大小為 -1，buffer_len 也為 -1。 |
| stat | 如果非空，stat 指向的結構將會保存該節點的 Stat 信息。 |
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 | 節點路徑。 |
| watcher | 如果不為 NULL 則會在服務器端設置監視，當節點發生變化時客戶端會得到通知。 |
| watcherCtx | 用戶指定的數據，將被傳入到監視器回調函數中，與由 zookeeper_init() 設置的全局監視器上下文不同，該函數設置的監視器上下文只與當前的監視器相關聯。 |
| buffer | 用於保存從 zookeeper 服務器獲取的節點數據。 |
| buffer_len | buffer 大小，一旦成功返回該值將會被設置為節點數據的實際大小，如果節點的數據為空，則數據大小為 -1，buffer_len 也為 -1。 |
| stat | 如果非空，stat 指向的結構將會保存該節點的 Stat 信息。 |
- 獲取子節點列表 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 | 返回各個子節點路徑 |
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 | 節點路徑。 |
| watcher | 如果不為 NULL 則會在服務器端設置監視，當節點發生變化時客戶端會得到通知。 |
| watcherCtx | 用戶指定的數據，將被傳入到監視器回調函數中，與由 zookeeper_init() 設置的全局監視器上下文不同，該函數設置的監視器上下文只與當前的監視器相關聯。 |
| strings | 回各個子節點路徑 |
ZOOAPI int zoo_get_children2(zhandle_t * zh, const char *path, int watch, struct String_vector *strings, struct Stat *stat);
該函數最早出現在 Zookeeper 3.3.0中，該函數功能與 zoo_get_children() 基本一致，但同時還會返回指定節點的 Stat 信息。
| zh | zookeeper_init() 返回的 zookeeper 句柄。 |
| path | 節點路徑。 |
| watch | 如果非0，則在服務器端設置監視，當節點發生變化時客戶端會得到通知。 |
| strings | 返回各個子節點路徑。 |
| stat | 返回指定節點的 Stat 信息。 |
ZOOAPI int zoo_wget_children2(zhandle_t * zh, const char *path, watcher_fn watcher, void *watcherCtx, struct String_vector *strings, struct Stat *stat);
該函數最早出現在 Zookeeper 3.3.0中，該函數功能與 zoo_wget_children() 基本一致，但同時還會返回指定節點的 Stat 信息。
| zh | zookeeper_init() 返回的 zookeeper 句柄。 |
| path | 節點路徑。 |
| watcher | 如果不為 NULL 則會在服務器端設置監視，當節點發生變化時客戶端會得到通知。 |
| watcherCtx | 用戶指定的數據，將被傳入到監視器回調函數中，與由 zookeeper_init() 設置的全局監視器上下文不同，該函數設置的監視器上下文只與當前的監視器相關聯。 |
| strings | 返回各個子節點路徑。 |
| stat | 返回指定節點的 Stat 信息。 |
- 訪問、設置節點 ACL (兩個)
ZOOAPI int zoo_get_acl(zhandle_t * zh, const char *path, struct ACL_vector *acl, struct Stat *stat); ZOOAPI int zoo_set_acl(zhandle_t * zh, const char *path, int version, const struct ACL_vector *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 信息。 |
| stat | 返回指定節點的 Stat 信息。 |
- 設置節點 ACL
ZOOAPI int zoo_set_acl(zhandle_t * zh, const char *path, int version, const struct ACL_vector *acl);
| zh | zookeeper_init() 返回的 zookeeper 句柄。 |
| path | 節點路徑。 |
| version | 節點的版本號。 |
| acl | 需要設置的 ACL 信息。 |
- 批處理，即原子性地一次提交多個 Zookeeper 操作。
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;
以上內容是 Zookeeper C API 中同步 API 的介紹，如有錯誤請留下您的想法和意見，本人會盡快更正；同時，我也將在后面的文章中列舉一些示例來說明上述 API 的用法，如有興趣請繼續關注，如果您需要了解 Zookeeper 異步 API，請移步第六講《Zookeeper C API 指南六(異步 API 介紹)》。