Zookeeper C API之介面描述

阿新 • • 發佈：2018-11-17

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

Zookeeper C API之介面描述

Zookeeper C API之介面描述

Zookeeper C API之回撥函式

Zookeeper C API之監視（Watch）、常量和結構體

Zookeeper C API之監視（Watch）、常量和結構體

Zookeeper C API之回撥函式

Zookeeper C API應用示例（3）——配置管理（非同步API）

Zookeeper C API應用示例（1）——配置管理（同步API）

Zookeeper C API應用準備工作

Zookeeper C API開發環境配置

Zookeeper C API開發環境配置

Zookeeper C API應用準備工作

MYSQL的C API之mysql_query

c# WebApi之介面返回型別詳解

zookeeper c api連線管理問題

C學習之介面和實現

zookeeper C API 編譯

C#基礎之介面（6）

sqlite之我見--C/C++ API介面示例 .

zookeeper的c API 單線程與多線程問題 cli_st和cli_mt

我的C#跨平臺之旅（二）：開發一組標準的Restful API

Zookeeper C API之介面描述

相關推薦