1 /** 2 * Licensed to the Apache Software Foundation (ASF) under one 3 * or more contributor license agreements. See the NOTICE file 4 * distributed with this work for additional information 5 * regarding copyright ownership. The ASF licenses this file 6 * to you under the Apache License, Version 2.0 (the 7 * "License"); you may not use this file except in compliance 8 * with the License. You may obtain a copy of the License at 9 * 10 * http://www.apache.org/licenses/LICENSE-2.0 11 * 12 * Unless required by applicable law or agreed to in writing, software 13 * distributed under the License is distributed on an "AS IS" BASIS, 14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 15 * See the License for the specific language governing permissions and 16 * limitations under the License. 17 */ 18 19 #ifndef ZOOKEEPER_H_ 20 #define ZOOKEEPER_H_ 21 22 #include <stdlib.h> 23 24 /* we must not include config.h as a public header */ 25 #ifndef WIN32 26 #include <sys/socket.h> 27 #include <sys/time.h> 28 #endif 29 30 #ifdef WIN32 31 #include <winsock2.h> /* must always be included before ws2tcpip.h */ 32 #include <ws2tcpip.h> /* for struct sock_addr and socklen_t */ 33 #endif 34 35 #ifdef HAVE_OPENSSL_H 36 #include <openssl/ossl_typ.h> 37 #endif 38 39 #include <stdio.h> 40 #include <ctype.h> 41 42 #ifdef HAVE_CYRUS_SASL_H 43 #include <sasl/sasl.h> 44 #endif /* HAVE_CYRUS_SASL_H */ 45 46 #include "proto.h" 47 #include "zookeeper_version.h" 48 #include "recordio.h" 49 #include "zookeeper.jute.h" 50 51 /** 52 * \file zookeeper.h 53 * \brief ZooKeeper functions and definitions. 54 * 55 * ZooKeeper is a network service that may be backed by a cluster of 56 * synchronized servers. The data in the service is represented as a tree 57 * of data nodes. Each node has data, children, an ACL, and status information. 58 * The data for a node is read and write in its entirety. 59 * 60 * ZooKeeper clients can leave watches when they queries the data or children 61 * of a node. If a watch is left, that client will be notified of the change. 62 * The notification is a one time trigger. Subsequent chances to the node will 63 * not trigger a notification unless the client issues a query with the watch 64 * flag set. If the client is ever disconnected from the service, the watches do 65 * not need to be reset. The client automatically resets the watches. 66 * 67 * When a node is created, it may be flagged as an ephemeral node. Ephemeral 68 * nodes are automatically removed when a client session is closed or when 69 * a session times out due to inactivity (the ZooKeeper runtime fills in 70 * periods of inactivity with pings). Ephemeral nodes cannot have children. 71 * 72 * ZooKeeper clients are identified by a server assigned session id. For 73 * security reasons The server 74 * also generates a corresponding password for a session. A client may save its 75 * id and corresponding password to persistent storage in order to use the 76 * session across program invocation boundaries. 77 */ 78 79 /* Support for building on various platforms */ 80 81 // on cygwin we should take care of exporting/importing symbols properly 82 #ifdef DLL_EXPORT 83 # define ZOOAPI __declspec(dllexport) 84 #else 85 # if (defined(__CYGWIN__) || defined(WIN32)) && !defined(USE_STATIC_LIB) 86 # define ZOOAPI __declspec(dllimport) 87 # else 88 # define ZOOAPI 89 # endif 90 #endif 91 92 /** zookeeper return constants **/ 93 94 enum ZOO_ERRORS { 95 ZOK = 0, /*!< Everything is OK */ 96 97 /** System and server-side errors. 98 * This is never thrown by the server, it shouldn't be used other than 99 * to indicate a range. Specifically error codes greater than this 100 * value, but lesser than {@link #ZAPIERROR}, are system errors. */ 101 ZSYSTEMERROR = -1, 102 ZRUNTIMEINCONSISTENCY = -2, /*!< A runtime inconsistency was found */ 103 ZDATAINCONSISTENCY = -3, /*!< A data inconsistency was found */ 104 ZCONNECTIONLOSS = -4, /*!< Connection to the server has been lost */ 105 ZMARSHALLINGERROR = -5, /*!< Error while marshalling or unmarshalling data */ 106 ZUNIMPLEMENTED = -6, /*!< Operation is unimplemented */ 107 ZOPERATIONTIMEOUT = -7, /*!< Operation timeout */ 108 ZBADARGUMENTS = -8, /*!< Invalid arguments */ 109 ZINVALIDSTATE = -9, /*!< Invliad zhandle state */ 110 ZNEWCONFIGNOQUORUM = -13, /*!< No quorum of new config is connected and 111 up-to-date with the leader of last commmitted 112 config - try invoking reconfiguration after new 113 servers are connected and synced */ 114 ZRECONFIGINPROGRESS = -14, /*!< Reconfiguration requested while another 115 reconfiguration is currently in progress. This 116 is currently not supported. Please retry. */ 117 ZSSLCONNECTIONERROR = -15, /*!< The SSL connection Error */ 118 119 /** API errors. 120 * This is never thrown by the server, it shouldn't be used other than 121 * to indicate a range. Specifically error codes greater than this 122 * value are API errors (while values less than this indicate a 123 * {@link #ZSYSTEMERROR}). 124 */ 125 ZAPIERROR = -100, 126 ZNONODE = -101, /*!< Node does not exist */ 127 ZNOAUTH = -102, /*!< Not authenticated */ 128 ZBADVERSION = -103, /*!< Version conflict */ 129 ZNOCHILDRENFOREPHEMERALS = -108, /*!< Ephemeral nodes may not have children */ 130 ZNODEEXISTS = -110, /*!< The node already exists */ 131 ZNOTEMPTY = -111, /*!< The node has children */ 132 ZSESSIONEXPIRED = -112, /*!< The session has been expired by the server */ 133 ZINVALIDCALLBACK = -113, /*!< Invalid callback specified */ 134 ZINVALIDACL = -114, /*!< Invalid ACL specified */ 135 ZAUTHFAILED = -115, /*!< Client authentication failed */ 136 ZCLOSING = -116, /*!< ZooKeeper is closing */ 137 ZNOTHING = -117, /*!< (not error) no server responses to process */ 138 ZSESSIONMOVED = -118, /*!<session moved to another server, so operation is ignored */ 139 ZNOTREADONLY = -119, /*!< state-changing request is passed to read-only server */ 140 ZEPHEMERALONLOCALSESSION = -120, /*!< Attempt to create ephemeral node on a local session */ 141 ZNOWATCHER = -121, /*!< The watcher couldn't be found */ 142 ZRECONFIGDISABLED = -123, /*!< Attempts to perform a reconfiguration operation when reconfiguration feature is disabled */ 143 ZSESSIONCLOSEDREQUIRESASLAUTH = -124, /*!< The session has been closed by server because server requires client to do authentication via configured authentication scheme at server, but client is not configured with required authentication scheme or configured but failed (i.e. wrong credential used.). */ 144 ZTHROTTLEDOP = -127 /*!< Operation was throttled and not executed at all. please, retry! */ 145 146 /* when adding/changing values here also update zerror(int) to return correct error message */ 147 }; 148 149 #ifdef __cplusplus 150 extern "C" { 151 #endif 152 153 /** 154 * @name Debug levels 155 */ 156 typedef enum {ZOO_LOG_LEVEL_ERROR=1,ZOO_LOG_LEVEL_WARN=2,ZOO_LOG_LEVEL_INFO=3,ZOO_LOG_LEVEL_DEBUG=4} ZooLogLevel; 157 158 /** 159 * @name ACL Consts 160 */ 161 extern ZOOAPI const int ZOO_PERM_READ; 162 extern ZOOAPI const int ZOO_PERM_WRITE; 163 extern ZOOAPI const int ZOO_PERM_CREATE; 164 extern ZOOAPI const int ZOO_PERM_DELETE; 165 extern ZOOAPI const int ZOO_PERM_ADMIN; 166 extern ZOOAPI const int ZOO_PERM_ALL; 167 168 169 #define ZOO_CONFIG_NODE "/zookeeper/config" 170 171 /* flags for zookeeper_init{,2} */ 172 #define ZOO_READONLY 1 173 174 /** Disable logging of the client environment at initialization time. */ 175 #define ZOO_NO_LOG_CLIENTENV 2 176 177 /** This Id represents anyone. */ 178 extern ZOOAPI struct Id ZOO_ANYONE_ID_UNSAFE; 179 /** This Id is only usable to set ACLs. It will get substituted with the 180 * Id's the client authenticated with. 181 */ 182 extern ZOOAPI struct Id ZOO_AUTH_IDS; 183 184 /** This is a completely open ACL*/ 185 extern ZOOAPI struct ACL_vector ZOO_OPEN_ACL_UNSAFE; 186 /** This ACL gives the world the ability to read. */ 187 extern ZOOAPI struct ACL_vector ZOO_READ_ACL_UNSAFE; 188 /** This ACL gives the creators authentication id's all permissions. */ 189 extern ZOOAPI struct ACL_vector ZOO_CREATOR_ALL_ACL; 190 191 /** 192 * @name Interest Consts 193 * These constants are used to express interest in an event and to 194 * indicate to zookeeper which events have occurred. They can 195 * be ORed together to express multiple interests. These flags are 196 * used in the interest and event parameters of 197 * \ref zookeeper_interest and \ref zookeeper_process. 198 */ 199 // @{ 200 extern ZOOAPI const int ZOOKEEPER_WRITE; 201 extern ZOOAPI const int ZOOKEEPER_READ; 202 // @} 203 204 /** 205 * @name Create Mode 206 * 207 * These modes are used by zoo_create to affect node create. 208 */ 209 // @{ 210 extern ZOOAPI const int ZOO_PERSISTENT; 211 extern ZOOAPI const int ZOO_EPHEMERAL; 212 extern ZOOAPI const int ZOO_PERSISTENT_SEQUENTIAL; 213 extern ZOOAPI const int ZOO_EPHEMERAL_SEQUENTIAL; 214 extern ZOOAPI const int ZOO_CONTAINER; 215 extern ZOOAPI const int ZOO_PERSISTENT_WITH_TTL; 216 extern ZOOAPI const int ZOO_PERSISTENT_SEQUENTIAL_WITH_TTL; 217 218 /** 219 * \deprecated ZOO_SEQUENCE Create Flag has been deprecated. Use ZOO_PERSISTENT_SEQUENTIAL 220 * or ZOO_EPHEMERAL_SEQUENTIAL instead of it. 221 */ 222 extern ZOOAPI const int ZOO_SEQUENCE; 223 // @} 224 225 /** 226 * @name State Consts 227 * These constants represent the states of a zookeeper connection. They are 228 * possible parameters of the watcher callback. 229 */ 230 // @{ 231 extern ZOOAPI const int ZOO_EXPIRED_SESSION_STATE; 232 extern ZOOAPI const int ZOO_AUTH_FAILED_STATE; 233 extern ZOOAPI const int ZOO_CONNECTING_STATE; 234 extern ZOOAPI const int ZOO_ASSOCIATING_STATE; 235 extern ZOOAPI const int ZOO_CONNECTED_STATE; 236 extern ZOOAPI const int ZOO_READONLY_STATE; 237 extern ZOOAPI const int ZOO_NOTCONNECTED_STATE; 238 // @} 239 240 /** 241 * @name Watch Types 242 * These constants indicate the event that caused the watch event. They are 243 * possible values of the first parameter of the watcher callback. 244 */ 245 // @{ 246 /** 247 * \brief a node has been created. 248 * 249 * This is only generated by watches on non-existent nodes. These watches 250 * are set using \ref zoo_exists. 251 */ 252 extern ZOOAPI const int ZOO_CREATED_EVENT; 253 /** 254 * \brief a node has been deleted. 255 * 256 * This is only generated by watches on nodes. These watches 257 * are set using \ref zoo_exists and \ref zoo_get. 258 */ 259 extern ZOOAPI const int ZOO_DELETED_EVENT; 260 /** 261 * \brief a node has changed. 262 * 263 * This is only generated by watches on nodes. These watches 264 * are set using \ref zoo_exists and \ref zoo_get. 265 */ 266 extern ZOOAPI const int ZOO_CHANGED_EVENT; 267 /** 268 * \brief a change as occurred in the list of children. 269 * 270 * This is only generated by watches on the child list of a node. These watches 271 * are set using \ref zoo_get_children or \ref zoo_get_children2. 272 */ 273 extern ZOOAPI const int ZOO_CHILD_EVENT; 274 /** 275 * \brief a session has been lost. 276 * 277 * This is generated when a client loses contact or reconnects with a server. 278 */ 279 extern ZOOAPI const int ZOO_SESSION_EVENT; 280 281 /** 282 * \brief a watch has been removed. 283 * 284 * This is generated when the server for some reason, probably a resource 285 * constraint, will no longer watch a node for a client. 286 */ 287 extern ZOOAPI const int ZOO_NOTWATCHING_EVENT; 288 // @} 289 290 /** 291 * \brief ZooKeeper handle. 292 * 293 * This is the handle that represents a connection to the ZooKeeper service. 294 * It is needed to invoke any ZooKeeper function. A handle is obtained using 295 * \ref zookeeper_init. 296 */ 297 typedef struct _zhandle zhandle_t; 298 299 /** 300 * This structure represents the certificates to zookeeper. 301 */ 302 typedef struct _zcert { 303 char *certstr; 304 char *ca; 305 char *cert; 306 char *key; 307 char *passwd; 308 } zcert_t; 309 310 /** 311 * This structure represents the socket to zookeeper. 312 */ 313 typedef struct _zsock { 314 #ifdef WIN32 315 SOCKET sock; 316 #else 317 int sock; 318 #endif 319 zcert_t *cert; 320 #ifdef HAVE_OPENSSL_H 321 SSL *ssl_sock; 322 SSL_CTX *ssl_ctx; 323 #endif 324 } zsock_t; 325 326 327 /** 328 * \brief client id structure. 329 * 330 * This structure holds the id and password for the session. This structure 331 * should be treated as opaque. It is received from the server when a session 332 * is established and needs to be sent back as-is when reconnecting a session. 333 */ 334 typedef struct { 335 int64_t client_id; 336 char passwd[16]; 337 } clientid_t; 338 339 /** 340 * \brief zoo_op structure. 341 * 342 * This structure holds all the arguments necessary for one op as part 343 * of a containing multi_op via \ref zoo_multi or \ref zoo_amulti. 344 * This structure should be treated as opaque and initialized via 345 * \ref zoo_create_op_init, \ref zoo_delete_op_init, \ref zoo_set_op_init 346 * and \ref zoo_check_op_init. 347 */ 348 typedef struct zoo_op { 349 int type; 350 union { 351 // CREATE 352 struct { 353 const char *path; 354 const char *data; 355 int datalen; 356 char *buf; 357 int buflen; 358 const struct ACL_vector *acl; 359 int flags; 360 int64_t ttl; 361 } create_op; 362 363 // DELETE 364 struct { 365 const char *path; 366 int version; 367 } delete_op; 368 369 // SET 370 struct { 371 const char *path; 372 const char *data; 373 int datalen; 374 int version; 375 struct Stat *stat; 376 } set_op; 377 378 // CHECK 379 struct { 380 const char *path; 381 int version; 382 } check_op; 383 }; 384 } zoo_op_t; 385 386 /** 387 * \brief zoo_create_op_init. 388 * 389 * This function initializes a zoo_op_t with the arguments for a ZOO_CREATE_OP. 390 * 391 * \param op A pointer to the zoo_op_t to be initialized. 392 * \param path The name of the node. Expressed as a file name with slashes 393 * separating ancestors of the node. 394 * \param value The data to be stored in the node. 395 * \param valuelen The number of bytes in data. To set the data to be NULL use 396 * value as NULL and valuelen as -1. 397 * \param acl The initial ACL of the node. The ACL must not be null or empty. 398 * \param mode this parameter should be one of the Create Modes. 399 * \param path_buffer Buffer which will be filled with the path of the 400 * new node (this might be different than the supplied path 401 * because of the ZOO_SEQUENCE flag). The path string will always be 402 * null-terminated. This parameter may be NULL if path_buffer_len = 0. 403 * \param path_buffer_len Size of path buffer; if the path of the new 404 * node (including space for the null terminator) exceeds the buffer size, 405 * the path string will be truncated to fit. The actual path of the 406 * new node in the server will not be affected by the truncation. 407 * The path string will always be null-terminated. 408 */ 409 void zoo_create_op_init(zoo_op_t *op, const char *path, const char *value, 410 int valuelen, const struct ACL_vector *acl, int mode, 411 char *path_buffer, int path_buffer_len); 412 413 /** 414 * \brief zoo_delete_op_init. 415 * 416 * This function initializes a zoo_op_t with the arguments for a ZOO_DELETE_OP. 417 * 418 * \param op A pointer to the zoo_op_t to be initialized. 419 * \param path the name of the node. Expressed as a file name with slashes 420 * separating ancestors of the node. 421 * \param version the expected version of the node. The function will fail if the 422 * actual version of the node does not match the expected version. 423 * If -1 is used the version check will not take place. 424 */ 425 void zoo_delete_op_init(zoo_op_t *op, const char *path, int version); 426 427 /** 428 * \brief zoo_set_op_init. 429 * 430 * This function initializes an zoo_op_t with the arguments for a ZOO_SETDATA_OP. 431 * 432 * \param op A pointer to the zoo_op_t to be initialized. 433 * \param path the name of the node. Expressed as a file name with slashes 434 * separating ancestors of the node. 435 * \param buffer the buffer holding data to be written to the node. 436 * \param buflen the number of bytes from buffer to write. To set NULL as data 437 * use buffer as NULL and buflen as -1. 438 * \param version the expected version of the node. The function will fail if 439 * the actual version of the node does not match the expected version. If -1 is 440 * used the version check will not take place. 441 */ 442 void zoo_set_op_init(zoo_op_t *op, const char *path, const char *buffer, 443 int buflen, int version, struct Stat *stat); 444 445 /** 446 * \brief zoo_check_op_init. 447 * 448 * This function initializes an zoo_op_t with the arguments for a ZOO_CHECK_OP. 449 * 450 * \param op A pointer to the zoo_op_t to be initialized. 451 * \param path The name of the node. Expressed as a file name with slashes 452 * separating ancestors of the node. 453 * \param version the expected version of the node. The function will fail if the 454 * actual version of the node does not match the expected version. 455 */ 456 void zoo_check_op_init(zoo_op_t *op, const char *path, int version); 457 458 /** 459 * \brief zoo_op_result structure. 460 * 461 * This structure holds the result for an op submitted as part of a multi_op 462 * via \ref zoo_multi or \ref zoo_amulti. 463 */ 464 typedef struct zoo_op_result { 465 int err; 466 char *value; 467 int valuelen; 468 struct Stat *stat; 469 } zoo_op_result_t; 470 471 /** 472 * \brief signature of a watch function. 473 * 474 * There are two ways to receive watch notifications: legacy and watcher object. 475 * <p> 476 * The legacy style, an application wishing to receive events from ZooKeeper must 477 * first implement a function with this signature and pass a pointer to the function 478 * to \ref zookeeper_init. Next, the application sets a watch by calling one of 479 * the getter API that accept the watch integer flag (for example, \ref zoo_aexists, 480 * \ref zoo_get, etc). 481 * <p> 482 * The watcher object style uses an instance of a "watcher object" which in 483 * the C world is represented by a pair: a pointer to a function implementing this 484 * signature and a pointer to watcher context -- handback user-specific data. 485 * When a watch is triggered this function will be called along with 486 * the watcher context. An application wishing to use this style must use 487 * the getter API functions with the "w" prefix in their names (for example, \ref 488 * zoo_awexists, \ref zoo_wget, etc). 489 * 490 * \param zh zookeeper handle 491 * \param type event type. This is one of the *_EVENT constants. 492 * \param state connection state. The state value will be one of the *_STATE constants. 493 * \param path znode path for which the watcher is triggered. NULL if the event 494 * type is ZOO_SESSION_EVENT 495 * \param watcherCtx watcher context. 496 */ 497 typedef void (*watcher_fn)(zhandle_t *zh, int type, 498 int state, const char *path,void *watcherCtx); 499 500 /** 501 * \brief typedef for setting the log callback. It's a function pointer which 502 * returns void and accepts a const char* as its only argument. 503 * 504 * \param message message to be passed to the callback function. 505 */ 506 typedef void (*log_callback_fn)(const char *message); 507 508 /** 509 * \brief create a handle to used communicate with zookeeper. 510 * 511 * This method creates a new handle and a zookeeper session that corresponds 512 * to that handle. Session establishment is asynchronous, meaning that the 513 * session should not be considered established until (and unless) an 514 * event of state ZOO_CONNECTED_STATE is received. 515 * \param host comma separated host:port pairs, each corresponding to a zk 516 * server. e.g. "127.0.0.1:3000,127.0.0.1:3001,127.0.0.1:3002" 517 * \param fn the global watcher callback function. When notifications are 518 * triggered this function will be invoked. 519 * \param clientid the id of a previously established session that this 520 * client will be reconnecting to. Pass 0 if not reconnecting to a previous 521 * session. Clients can access the session id of an established, valid, 522 * connection by calling \ref zoo_client_id. If the session corresponding to 523 * the specified clientid has expired, or if the clientid is invalid for 524 * any reason, the returned zhandle_t will be invalid -- the zhandle_t 525 * state will indicate the reason for failure (typically 526 * ZOO_EXPIRED_SESSION_STATE). 527 * \param context the handback object that will be associated with this instance 528 * of zhandle_t. Application can access it (for example, in the watcher 529 * callback) using \ref zoo_get_context. The object is not used by zookeeper 530 * internally and can be null. 531 * \param flags reserved for future use. Should be set to zero. 532 * \return a pointer to the opaque zhandle structure. If it fails to create 533 * a new zhandle the function returns NULL and the errno variable 534 * indicates the reason. 535 */ 536 ZOOAPI zhandle_t *zookeeper_init(const char *host, watcher_fn fn, 537 int recv_timeout, const clientid_t *clientid, void *context, int flags); 538 539 #ifdef HAVE_OPENSSL_H 540 ZOOAPI zhandle_t *zookeeper_init_ssl(const char *host, const char *cert, watcher_fn fn, 541 int recv_timeout, const clientid_t *clientid, void *context, int flags); 542 #endif 543 544 ZOOAPI void close_zsock(zsock_t *zsock); 545 546 /** 547 * \brief create a handle to communicate with zookeeper. 548 * 549 * This function is identical to \ref zookeeper_init except it allows one 550 * to specify an additional callback to be used for all logging for that 551 * specific connection. For more details on the logging callback see 552 * \ref zoo_get_log_callback and \ref zoo_set_log_callback. 553 * 554 * This method creates a new handle and a zookeeper session that corresponds 555 * to that handle. Session establishment is asynchronous, meaning that the 556 * session should not be considered established until (and unless) an 557 * event of state ZOO_CONNECTED_STATE is received. 558 * \param host comma separated host:port pairs, each corresponding to a zk 559 * server. e.g. "127.0.0.1:3000,127.0.0.1:3001,127.0.0.1:3002" 560 * \param fn the global watcher callback function. When notifications are 561 * triggered this function will be invoked. 562 * \param clientid the id of a previously established session that this 563 * client will be reconnecting to. Pass 0 if not reconnecting to a previous 564 * session. Clients can access the session id of an established, valid, 565 * connection by calling \ref zoo_client_id. If the session corresponding to 566 * the specified clientid has expired, or if the clientid is invalid for 567 * any reason, the returned zhandle_t will be invalid -- the zhandle_t 568 * state will indicate the reason for failure (typically 569 * ZOO_EXPIRED_SESSION_STATE). 570 * \param context the handback object that will be associated with this instance 571 * of zhandle_t. Application can access it (for example, in the watcher 572 * callback) using \ref zoo_get_context. The object is not used by zookeeper 573 * internally and can be null. 574 * \param flags reserved for future use. Should be set to zero. 575 * \param log_callback All log messages will be passed to this callback function. 576 * For more details see \ref zoo_get_log_callback and \ref zoo_set_log_callback. 577 * \return a pointer to the opaque zhandle structure. If it fails to create 578 * a new zhandle the function returns NULL and the errno variable 579 * indicates the reason. 580 */ 581 ZOOAPI zhandle_t *zookeeper_init2(const char *host, watcher_fn fn, 582 int recv_timeout, const clientid_t *clientid, void *context, int flags, 583 log_callback_fn log_callback); 584 585 #ifdef HAVE_CYRUS_SASL_H 586 587 /** 588 * \brief zoo_sasl_params structure. 589 * 590 * This structure holds the SASL parameters for the connection. 591 * 592 * Its \c service, \c host and \c callbacks fields are used with Cyrus 593 * SASL's \c sasl_client_new; its \c mechlist field with \c 594 * sasl_client_start. Please refer to these functions for precise 595 * semantics. 596 * 597 * Note while "string" parameters are copied into the ZooKeeper 598 * client, the callbacks array is simply referenced: its lifetime must 599 * therefore cover that of the handle. 600 */ 601 typedef struct zoo_sasl_params { 602 const char *service; /*!< The service name, usually "zookeeper" */ 603 const char *host; /*!< The server name, e.g. "zk-sasl-md5" */ 604 const char *mechlist; /*!< Mechanisms to try, e.g. "DIGEST-MD5" */ 605 const sasl_callback_t *callbacks; /*!< List of callbacks */ 606 } zoo_sasl_params_t; 607 608 /** 609 * \brief create a handle to communicate with zookeeper. 610 * 611 * This function is identical to \ref zookeeper_init2 except that it 612 * allows specifying optional SASL connection parameters. It is only 613 * available if the client library was configured to link against the 614 * Cyrus SASL library, and only visible when \c HAVE_CYRUS_SASL_H is defined. 615 * 616 * This method creates a new handle and a zookeeper session that corresponds 617 * to that handle. Session establishment is asynchronous, meaning that the 618 * session should not be considered established until (and unless) an 619 * event of state ZOO_CONNECTED_STATE is received. 620 * \param host comma separated host:port pairs, each corresponding to a zk 621 * server. e.g. "127.0.0.1:3000,127.0.0.1:3001,127.0.0.1:3002" 622 * \param fn the global watcher callback function. When notifications are 623 * triggered this function will be invoked. 624 * \param clientid the id of a previously established session that this 625 * client will be reconnecting to. Pass 0 if not reconnecting to a previous 626 * session. Clients can access the session id of an established, valid, 627 * connection by calling \ref zoo_client_id. If the session corresponding to 628 * the specified clientid has expired, or if the clientid is invalid for 629 * any reason, the returned zhandle_t will be invalid -- the zhandle_t 630 * state will indicate the reason for failure (typically 631 * ZOO_EXPIRED_SESSION_STATE). 632 * \param context the handback object that will be associated with this instance 633 * of zhandle_t. Application can access it (for example, in the watcher 634 * callback) using \ref zoo_get_context. The object is not used by zookeeper 635 * internally and can be null. 636 * \param flags reserved for future use. Should be set to zero. 637 * \param log_callback All log messages will be passed to this callback function. 638 * For more details see \ref zoo_get_log_callback and \ref zoo_set_log_callback. 639 * \param sasl_params a pointer to a \ref zoo_sasl_params_t structure 640 * specifying SASL connection parameters, or NULL to skip SASL 641 * authentication 642 * \return a pointer to the opaque zhandle structure. If it fails to create 643 * a new zhandle the function returns NULL and the errno variable 644 * indicates the reason. 645 */ 646 ZOOAPI zhandle_t *zookeeper_init_sasl(const char *host, watcher_fn fn, 647 int recv_timeout, const clientid_t *clientid, void *context, int flags, 648 log_callback_fn log_callback, zoo_sasl_params_t *sasl_params); 649 650 /** 651 * \brief allocates and initializes a basic array of Cyrus SASL callbacks. 652 * 653 * This small helper function makes it easy to pass "static" 654 * parameters to Cyrus SASL's underlying callback-based API. Its use 655 * is not mandatory; you can still implement interactive dialogs by 656 * defining your own callbacks. 657 * 658 * \param user the "canned" response to \c SASL_CB_USER and \c SASL_CB_AUTHNAME, 659 * or NULL for none 660 * \param realm the "canned" response to \c SASL_CB_GETREALM, or NULL for none 661 * \param password_file the name of a file whose first line is read in 662 * response to \c SASL_CB_PASS, or NULL for none 663 * \return the freshly-malloc()ed callbacks array, or NULL if allocation 664 * failed. Deallocate with free(), but only after the corresponding 665 * ZooKeeper handle is closed. 666 */ 667 ZOOAPI sasl_callback_t *zoo_sasl_make_basic_callbacks(const char *user, 668 const char *realm, const char* password_file); 669 670 #endif /* HAVE_CYRUS_SASL_H */ 671 672 /** 673 * \brief update the list of servers this client will connect to. 674 * 675 * This method allows a client to update the connection string by providing 676 * a new comma separated list of host:port pairs, each corresponding to a 677 * ZooKeeper server. 678 * 679 * This function invokes a probabilistic load-balancing algorithm which may cause 680 * the client to disconnect from its current host to achieve expected uniform 681 * connections per server in the new list. In case the current host to which the 682 * client is connected is not in the new list this call will always cause the 683 * connection to be dropped. Otherwise, the decision is based on whether the 684 * number of servers has increased or decreased and by how much. 685 * 686 * If the connection is dropped, the client moves to a special "reconfig" mode 687 * where he chooses a new server to connect to using the probabilistic algorithm. 688 * After finding a server or exhaustively trying all the servers in the new list, 689 * the client moves back to the normal mode of operation where it will pick an 690 * arbitrary server from the 'host' string. 691 * 692 * See {@link https://issues.apache.org/jira/browse/ZOOKEEPER-1355} for the 693 * protocol and its evaluation, 694 * 695 * \param host comma separated host:port pairs, each corresponding to a zk 696 * server. e.g. "127.0.0.1:3000,127.0.0.1:3001,127.0.0.1:3002" 697 * \return ZOK on success or one of the following errcodes on failure: 698 * ZBADARGUMENTS - invalid input parameters 699 * ZINVALIDSTATE - zhandle state is either ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE 700 * ZSYSTEMERROR -- a system (OS) error occured; it's worth checking errno to get details 701 */ 702 ZOOAPI int zoo_set_servers(zhandle_t *zh, const char *hosts); 703 704 /** 705 * \brief sets a minimum delay to observe between "routine" host name 706 * resolutions. 707 * 708 * The client performs regular resolutions of the list of servers 709 * passed to \ref zookeeper_init or set with \ref zoo_set_servers in 710 * order to detect changes at the DNS level. 711 * 712 * By default, it does so every time it checks for socket readiness. 713 * This results in low latency in the detection of changes, but can 714 * lead to heavy DNS traffic when the local cache is not effective. 715 * 716 * This method allows an application to influence the rate of polling. 717 * When delay_ms is set to a value greater than zero, the client skips 718 * most "routine" resolutions which would have happened in a window of 719 * that many milliseconds since the last succesful one. 720 * 721 * Setting delay_ms to 0 disables this logic, reverting to the default 722 * behavior. Setting it to -1 disables network resolutions during 723 * normal operation (but not, e.g., on connection loss). 724 * 725 * \param delay_ms 0, -1, or the window size in milliseconds 726 * \return ZOK on success or ZBADARGUMENTS for invalid input parameters 727 */ 728 ZOOAPI int zoo_set_servers_resolution_delay(zhandle_t *zh, int delay_ms); 729 730 /** 731 * \brief cycle to the next server on the next connection attempt. 732 * 733 * Note: typically this method should NOT be used outside of testing. 734 * 735 * This method allows a client to cycle through the list of servers in it's 736 * connection pool to be used on the next connection attempt. This function does 737 * not actually trigger a connection or state change in any way. Its purpose is 738 * to allow testing changing servers on the fly and the probabilistic load 739 * balancing algorithm. 740 */ 741 ZOOAPI void zoo_cycle_next_server(zhandle_t *zh); 742 743 /** 744 * \brief get current host:port this client is connecting/connected to. 745 * 746 * Note: typically this method should NOT be used outside of testing. 747 * 748 * This method allows a client to get the current host:port that this client 749 * is either in the process of connecting to or is currently connected to. This 750 * is mainly used for testing purposes but might also come in handy as a general 751 * purpose tool to be used by other clients. 752 */ 753 ZOOAPI const char* zoo_get_current_server(zhandle_t* zh); 754 755 /** 756 * \brief close the zookeeper handle and free up any resources. 757 * 758 * After this call, the client session will no longer be valid. The function 759 * will flush any outstanding send requests before return. As a result it may 760 * block. 761 * 762 * This method should only be called only once on a zookeeper handle. Calling 763 * twice will cause undefined (and probably undesirable behavior). Calling any other 764 * zookeeper method after calling close is undefined behaviour and should be avoided. 765 * 766 * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init 767 * \return a result code. Regardless of the error code returned, the zhandle 768 * will be destroyed and all resources freed. 769 * 770 * ZOK - success 771 * ZBADARGUMENTS - invalid input parameters 772 * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory 773 * ZOPERATIONTIMEOUT - failed to flush the buffers within the specified timeout. 774 * ZCONNECTIONLOSS - a network error occurred while attempting to send request to server 775 * ZSYSTEMERROR -- a system (OS) error occurred; it's worth checking errno to get details 776 */ 777 ZOOAPI int zookeeper_close(zhandle_t *zh); 778 779 /** 780 * \brief return the client session id, only valid if the connections 781 * is currently connected (ie. last watcher state is ZOO_CONNECTED_STATE) 782 */ 783 ZOOAPI const clientid_t *zoo_client_id(zhandle_t *zh); 784 785 /** 786 * \brief return the timeout for this session, only valid if the connections 787 * is currently connected (ie. last watcher state is ZOO_CONNECTED_STATE). This 788 * value may change after a server re-connect. 789 */ 790 ZOOAPI int zoo_recv_timeout(zhandle_t *zh); 791 792 /** 793 * \brief return the context for this handle. 794 */ 795 ZOOAPI const void *zoo_get_context(zhandle_t *zh); 796 797 /** 798 * \brief set the context for this handle. 799 */ 800 ZOOAPI void zoo_set_context(zhandle_t *zh, void *context); 801 802 /** 803 * \brief set a watcher function 804 * \return previous watcher function 805 */ 806 ZOOAPI watcher_fn zoo_set_watcher(zhandle_t *zh,watcher_fn newFn); 807 808 /** 809 * \brief returns the socket address for the current connection 810 * \return socket address of the connected host or NULL on failure, only valid if the 811 * connection is current connected 812 */ 813 ZOOAPI struct sockaddr* zookeeper_get_connected_host(zhandle_t *zh, 814 struct sockaddr *addr, socklen_t *addr_len); 815 816 #ifndef THREADED 817 /** 818 * \brief Returns the events that zookeeper is interested in. 819 * 820 * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init 821 * \param fd is the file descriptor of interest 822 * \param interest is an or of the ZOOKEEPER_WRITE and ZOOKEEPER_READ flags to 823 * indicate the I/O of interest on fd. 824 * \param tv a timeout value to be used with select/poll system call 825 * \return a result code. 826 * ZOK - success 827 * ZBADARGUMENTS - invalid input parameters 828 * ZINVALIDSTATE - zhandle state is either ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE 829 * ZCONNECTIONLOSS - a network error occurred while attempting to establish 830 * a connection to the server 831 * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory 832 * ZOPERATIONTIMEOUT - hasn't received anything from the server for 2/3 of the 833 * timeout value specified in zookeeper_init() 834 * ZSYSTEMERROR -- a system (OS) error occurred; it's worth checking errno to get details 835 */ 836 #ifdef WIN32 837 ZOOAPI int zookeeper_interest(zhandle_t *zh, SOCKET *fd, int *interest, 838 struct timeval *tv); 839 #else 840 ZOOAPI int zookeeper_interest(zhandle_t *zh, int *fd, int *interest, 841 struct timeval *tv); 842 #endif 843 844 /** 845 * \brief Notifies zookeeper that an event of interest has happened. 846 * 847 * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init 848 * \param events will be an OR of the ZOOKEEPER_WRITE and ZOOKEEPER_READ flags. 849 * \return a result code. 850 * ZOK - success 851 * ZBADARGUMENTS - invalid input parameters 852 * ZINVALIDSTATE - zhandle state is either ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE 853 * ZCONNECTIONLOSS - a network error occurred while attempting to send request to server 854 * ZSESSIONEXPIRED - connection attempt failed -- the session's expired 855 * ZAUTHFAILED - authentication request failed, e.i. invalid credentials 856 * ZRUNTIMEINCONSISTENCY - a server response came out of order 857 * ZSYSTEMERROR -- a system (OS) error occurred; it's worth checking errno to get details 858 * ZNOTHING -- not an error; simply indicates that there no more data from the server 859 * to be processed (when called with ZOOKEEPER_READ flag). 860 */ 861 ZOOAPI int zookeeper_process(zhandle_t *zh, int events); 862 #endif 863 864 /** 865 * \brief signature of a completion function for a call that returns void. 866 * 867 * This method will be invoked at the end of a asynchronous call and also as 868 * a result of connection loss or timeout. 869 * \param rc the error code of the call. Connection loss/timeout triggers 870 * the completion with one of the following error codes: 871 * ZCONNECTIONLOSS -- lost connection to the server 872 * ZOPERATIONTIMEOUT -- connection timed out 873 * Data related events trigger the completion with error codes listed the 874 * Exceptions section of the documentation of the function that initiated the 875 * call. (Zero indicates call was successful.) 876 * \param data the pointer that was passed by the caller when the function 877 * that this completion corresponds to was invoked. The programmer 878 * is responsible for any memory freeing associated with the data 879 * pointer. 880 */ 881 typedef void (*void_completion_t)(int rc, const void *data); 882 883 /** 884 * \brief signature of a completion function that returns a Stat structure. 885 * 886 * This method will be invoked at the end of a asynchronous call and also as 887 * a result of connection loss or timeout. 888 * \param rc the error code of the call. Connection loss/timeout triggers 889 * the completion with one of the following error codes: 890 * ZCONNECTIONLOSS -- lost connection to the server 891 * ZOPERATIONTIMEOUT -- connection timed out 892 * Data related events trigger the completion with error codes listed the 893 * Exceptions section of the documentation of the function that initiated the 894 * call. (Zero indicates call was successful.) 895 * \param stat a pointer to the stat information for the node involved in 896 * this function. If a non zero error code is returned, the content of 897 * stat is undefined. The programmer is NOT responsible for freeing stat. 898 * \param data the pointer that was passed by the caller when the function 899 * that this completion corresponds to was invoked. The programmer 900 * is responsible for any memory freeing associated with the data 901 * pointer. 902 */ 903 typedef void (*stat_completion_t)(int rc, const struct Stat *stat, 904 const void *data); 905 906 /** 907 * \brief signature of a completion function that returns data. 908 * 909 * This method will be invoked at the end of a asynchronous call and also as 910 * a result of connection loss or timeout. 911 * \param rc the error code of the call. Connection loss/timeout triggers 912 * the completion with one of the following error codes: 913 * ZCONNECTIONLOSS -- lost connection to the server 914 * ZOPERATIONTIMEOUT -- connection timed out 915 * Data related events trigger the completion with error codes listed the 916 * Exceptions section of the documentation of the function that initiated the 917 * call. (Zero indicates call was successful.) 918 * \param value the value of the information returned by the asynchronous call. 919 * If a non zero error code is returned, the content of value is undefined. 920 * The programmer is NOT responsible for freeing value. 921 * \param value_len the number of bytes in value. 922 * \param stat a pointer to the stat information for the node involved in 923 * this function. If a non zero error code is returned, the content of 924 * stat is undefined. The programmer is NOT responsible for freeing stat. 925 * \param data the pointer that was passed by the caller when the function 926 * that this completion corresponds to was invoked. The programmer 927 * is responsible for any memory freeing associated with the data 928 * pointer. 929 */ 930 typedef void (*data_completion_t)(int rc, const char *value, int value_len, 931 const struct Stat *stat, const void *data); 932 933 /** 934 * \brief signature of a completion function that returns a list of strings. 935 * 936 * This method will be invoked at the end of a asynchronous call and also as 937 * a result of connection loss or timeout. 938 * \param rc the error code of the call. Connection loss/timeout triggers 939 * the completion with one of the following error codes: 940 * ZCONNECTIONLOSS -- lost connection to the server 941 * ZOPERATIONTIMEOUT -- connection timed out 942 * Data related events trigger the completion with error codes listed the 943 * Exceptions section of the documentation of the function that initiated the 944 * call. (Zero indicates call was successful.) 945 * \param strings a pointer to the structure containng the list of strings of the 946 * names of the children of a node. If a non zero error code is returned, 947 * the content of strings is undefined. The programmer is NOT responsible 948 * for freeing strings. 949 * \param data the pointer that was passed by the caller when the function 950 * that this completion corresponds to was invoked. The programmer 951 * is responsible for any memory freeing associated with the data 952 * pointer. 953 */ 954 typedef void (*strings_completion_t)(int rc, 955 const struct String_vector *strings, const void *data); 956 957 /** 958 * \brief signature of a completion function that returns a string and stat. 959 * . 960 * 961 * This method will be invoked at the end of a asynchronous call and also as 962 * a result of connection loss or timeout. 963 * \param rc the error code of the call. Connection loss/timeout triggers 964 * the completion with one of the following error codes: 965 * ZCONNECTIONLOSS -- lost connection to the server 966 * ZOPERATIONTIMEOUT -- connection timed out 967 * Data related events trigger the completion with error codes listed the 968 * Exceptions section of the documentation of the function that initiated the 969 * call. (Zero indicates call was successful.) 970 * \param value the value of the string returned. 971 * \param stat a pointer to the stat information for the node involved in 972 * this function. If a non zero error code is returned, the content of 973 * stat is undefined. The programmer is NOT responsible for freeing stat. 974 * \param data the pointer that was passed by the caller when the function 975 * that this completion corresponds to was invoked. The programmer 976 * is responsible for any memory freeing associated with the data 977 * pointer. 978 */ 979 typedef void (*string_stat_completion_t)(int rc, 980 const char *string, const struct Stat *stat, const void *data); 981 982 /** 983 * \brief signature of a completion function that returns a list of strings and stat. 984 * . 985 * 986 * This method will be invoked at the end of a asynchronous call and also as 987 * a result of connection loss or timeout. 988 * \param rc the error code of the call. Connection loss/timeout triggers 989 * the completion with one of the following error codes: 990 * ZCONNECTIONLOSS -- lost connection to the server 991 * ZOPERATIONTIMEOUT -- connection timed out 992 * Data related events trigger the completion with error codes listed the 993 * Exceptions section of the documentation of the function that initiated the 994 * call. (Zero indicates call was successful.) 995 * \param strings a pointer to the structure containng the list of strings of the 996 * names of the children of a node. If a non zero error code is returned, 997 * the content of strings is undefined. The programmer is NOT responsible 998 * for freeing strings. 999 * \param stat a pointer to the stat information for the node involved in 1000 * this function. If a non zero error code is returned, the content of 1001 * stat is undefined. The programmer is NOT responsible for freeing stat. 1002 * \param data the pointer that was passed by the caller when the function 1003 * that this completion corresponds to was invoked. The programmer 1004 * is responsible for any memory freeing associated with the data 1005 * pointer. 1006 */ 1007 typedef void (*strings_stat_completion_t)(int rc, 1008 const struct String_vector *strings, const struct Stat *stat, 1009 const void *data); 1010 1011 /** 1012 * \brief signature of a completion function that returns a list of strings. 1013 * 1014 * This method will be invoked at the end of a asynchronous call and also as 1015 * a result of connection loss or timeout. 1016 * \param rc the error code of the call. Connection loss/timeout triggers 1017 * the completion with one of the following error codes: 1018 * ZCONNECTIONLOSS -- lost connection to the server 1019 * ZOPERATIONTIMEOUT -- connection timed out 1020 * Data related events trigger the completion with error codes listed the 1021 * Exceptions section of the documentation of the function that initiated the 1022 * call. (Zero indicates call was successful.) 1023 * \param value the value of the string returned. 1024 * \param data the pointer that was passed by the caller when the function 1025 * that this completion corresponds to was invoked. The programmer 1026 * is responsible for any memory freeing associated with the data 1027 * pointer. 1028 */ 1029 typedef void 1030 (*string_completion_t)(int rc, const char *value, const void *data); 1031 1032 /** 1033 * \brief signature of a completion function that returns an ACL. 1034 * 1035 * This method will be invoked at the end of a asynchronous call and also as 1036 * a result of connection loss or timeout. 1037 * \param rc the error code of the call. Connection loss/timeout triggers 1038 * the completion with one of the following error codes: 1039 * ZCONNECTIONLOSS -- lost connection to the server 1040 * ZOPERATIONTIMEOUT -- connection timed out 1041 * Data related events trigger the completion with error codes listed the 1042 * Exceptions section of the documentation of the function that initiated the 1043 * call. (Zero indicates call was successful.) 1044 * \param acl a pointer to the structure containng the ACL of a node. If a non 1045 * zero error code is returned, the content of strings is undefined. The 1046 * programmer is NOT responsible for freeing acl. 1047 * \param stat a pointer to the stat information for the node involved in 1048 * this function. If a non zero error code is returned, the content of 1049 * stat is undefined. The programmer is NOT responsible for freeing stat. 1050 * \param data the pointer that was passed by the caller when the function 1051 * that this completion corresponds to was invoked. The programmer 1052 * is responsible for any memory freeing associated with the data 1053 * pointer. 1054 */ 1055 typedef void (*acl_completion_t)(int rc, struct ACL_vector *acl, 1056 struct Stat *stat, const void *data); 1057 1058 /** 1059 * \brief get the state of the zookeeper connection. 1060 * 1061 * The return value will be one of the \ref State Consts. 1062 */ 1063 ZOOAPI int zoo_state(zhandle_t *zh); 1064 1065 /** 1066 * \brief create a node. 1067 * 1068 * This method will create a node in ZooKeeper. A node can only be created if 1069 * it does not already exist. The Create Mode affects the creation of nodes. 1070 * If ZOO_EPHEMERAL mode is chosen, the node will automatically get removed if the 1071 * client session goes away. If ZOO_CONTAINER flag is set, a container node will be 1072 * created. For ZOO_*_SEQUENTIAL modes, a unique monotonically increasing 1073 * sequence number is appended to the path name. The sequence number is always fixed 1074 * length of 10 digits, 0 padded. 1075 * 1076 * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init 1077 * \param path The name of the node. Expressed as a file name with slashes 1078 * separating ancestors of the node. 1079 * \param value The data to be stored in the node. 1080 * \param valuelen The number of bytes in data. 1081 * \param acl The initial ACL of the node. The ACL must not be null or empty. 1082 * \param mode this parameter should be one of the Create Modes. 1083 * \param completion the routine to invoke when the request completes. The completion 1084 * will be triggered with one of the following codes passed in as the rc argument: 1085 * ZOK operation completed successfully 1086 * ZNONODE the parent node does not exist. 1087 * ZNODEEXISTS the node already exists 1088 * ZNOAUTH the client does not have permission. 1089 * ZNOCHILDRENFOREPHEMERALS cannot create children of ephemeral nodes. 1090 * \param data The data that will be passed to the completion routine when the 1091 * function completes. 1092 * \return ZOK on success or one of the following errcodes on failure: 1093 * ZBADARGUMENTS - invalid input parameters 1094 * ZINVALIDSTATE - zhandle state is either ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE 1095 * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory 1096 */ 1097 ZOOAPI int zoo_acreate(zhandle_t *zh, const char *path, const char *value, 1098 int valuelen, const struct ACL_vector *acl, int mode, 1099 string_completion_t completion, const void *data); 1100 1101 /** 1102 * \brief create a node. 1103 * 1104 * This method will create a node in ZooKeeper. A node can only be created if 1105 * it does not already exist. The Create Mode affects the creation of nodes. 1106 * If ZOO_EPHEMERAL mode is chosen, the node will automatically get removed if the 1107 * client session goes away. If ZOO_CONTAINER flag is set, a container node will be 1108 * created. For ZOO_*_SEQUENTIAL modes, a unique monotonically increasing 1109 * sequence number is appended to the path name. The sequence number is always fixed 1110 * length of 10 digits, 0 padded. When ZOO_*_WITH_TTL is selected, a ttl node will be 1111 * created. 1112 * 1113 * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init 1114 * \param path The name of the node. Expressed as a file name with slashes 1115 * separating ancestors of the node. 1116 * \param value The data to be stored in the node. 1117 * \param valuelen The number of bytes in data. 1118 * \param acl The initial ACL of the node. The ACL must not be null or empty. 1119 * \param mode this parameter should be one of the Create Modes. 1120 * \param ttl the value of ttl in milliseconds. It must be positive for ZOO_*_WITH_TTL 1121 * Create modes, otherwise it must be -1. 1122 * \param completion the routine to invoke when the request completes. The completion 1123 * will be triggered with one of the following codes passed in as the rc argument: 1124 * ZOK operation completed successfully 1125 * ZNONODE the parent node does not exist. 1126 * ZNODEEXISTS the node already exists 1127 * ZNOAUTH the client does not have permission. 1128 * ZNOCHILDRENFOREPHEMERALS cannot create children of ephemeral nodes. 1129 * \param data The data that will be passed to the completion routine when the 1130 * function completes. 1131 * \return ZOK on success or one of the following errcodes on failure: 1132 * ZBADARGUMENTS - invalid input parameters 1133 * ZINVALIDSTATE - zhandle state is either ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE 1134 * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory 1135 */ 1136 ZOOAPI int zoo_acreate_ttl(zhandle_t *zh, const char *path, const char *value, 1137 int valuelen, const struct ACL_vector *acl, int mode, int64_t ttl, 1138 string_completion_t completion, const void *data); 1139 1140 /** 1141 * \brief create a node asynchronously and returns stat details. 1142 * 1143 * This method will create a node in ZooKeeper. A node can only be created if 1144 * it does not already exist. The Create Mode affects the creation of nodes. 1145 * If ZOO_EPHEMERAL mode is chosen, the node will automatically get removed if the 1146 * client session goes away. If ZOO_CONTAINER flag is set, a container node will be 1147 * created. For ZOO_*_SEQUENTIAL modes, a unique monotonically increasing 1148 * sequence number is appended to the path name. The sequence number is always fixed 1149 * length of 10 digits, 0 padded. 1150 * 1151 * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init 1152 * \param path The name of the node. Expressed as a file name with slashes 1153 * separating ancestors of the node. 1154 * \param value The data to be stored in the node. 1155 * \param valuelen The number of bytes in data. 1156 * \param acl The initial ACL of the node. The ACL must not be null or empty. 1157 * \param mode this parameter should be one of the Create Modes. 1158 * \param completion the routine to invoke when the request completes. The completion 1159 * will be triggered with one of the following codes passed in as the rc argument: 1160 * ZOK operation completed successfully 1161 * ZNONODE the parent node does not exist. 1162 * ZNODEEXISTS the node already exists 1163 * ZNOAUTH the client does not have permission. 1164 * ZNOCHILDRENFOREPHEMERALS cannot create children of ephemeral nodes. 1165 * \param data The data that will be passed to the completion routine when the 1166 * function completes. 1167 * \return ZOK on success or one of the following errcodes on failure: 1168 * ZBADARGUMENTS - invalid input parameters 1169 * ZINVALIDSTATE - zhandle state is either ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE 1170 * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory 1171 */ 1172 ZOOAPI int zoo_acreate2(zhandle_t *zh, const char *path, const char *value, 1173 int valuelen, const struct ACL_vector *acl, int mode, 1174 string_stat_completion_t completion, const void *data); 1175 1176 /** 1177 * \brief create a node asynchronously and returns stat details. 1178 * 1179 * This method will create a node in ZooKeeper. A node can only be created if 1180 * it does not already exist. The Create Mode affects the creation of nodes. 1181 * If ZOO_EPHEMERAL mode is chosen, the node will automatically get removed if the 1182 * client session goes away. If ZOO_CONTAINER flag is set, a container node will be 1183 * created. For ZOO_*_SEQUENTIAL modes, a unique monotonically increasing 1184 * sequence number is appended to the path name. The sequence number is always fixed 1185 * length of 10 digits, 0 padded. When ZOO_*_WITH_TTL is selected, a ttl node will be 1186 * created. 1187 * 1188 * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init 1189 * \param path The name of the node. Expressed as a file name with slashes 1190 * separating ancestors of the node. 1191 * \param value The data to be stored in the node. 1192 * \param valuelen The number of bytes in data. 1193 * \param acl The initial ACL of the node. The ACL must not be null or empty. 1194 * \param mode this parameter should be one of the Create Modes. 1195 * \param ttl the value of ttl in milliseconds. It must be positive for ZOO_*_WITH_TTL 1196 * Create modes, otherwise it must be -1. 1197 * \param completion the routine to invoke when the request completes. The completion 1198 * will be triggered with one of the following codes passed in as the rc argument: 1199 * ZOK operation completed successfully 1200 * ZNONODE the parent node does not exist. 1201 * ZNODEEXISTS the node already exists 1202 * ZNOAUTH the client does not have permission. 1203 * ZNOCHILDRENFOREPHEMERALS cannot create children of ephemeral nodes. 1204 * \param data The data that will be passed to the completion routine when the 1205 * function completes. 1206 * \return ZOK on success or one of the following errcodes on failure: 1207 * ZBADARGUMENTS - invalid input parameters 1208 * ZINVALIDSTATE - zhandle state is either ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE 1209 * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory 1210 */ 1211 ZOOAPI int zoo_acreate2_ttl(zhandle_t *zh, const char *path, const char *value, 1212 int valuelen, const struct ACL_vector *acl, int mode, int64_t ttl, 1213 string_stat_completion_t completion, const void *data); 1214 1215 /** 1216 * \brief delete a node in zookeeper. 1217 * 1218 * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init 1219 * \param path the name of the node. Expressed as a file name with slashes 1220 * separating ancestors of the node. 1221 * \param version the expected version of the node. The function will fail if the 1222 * actual version of the node does not match the expected version. 1223 * If -1 is used the version check will not take place. 1224 * \param completion the routine to invoke when the request completes. The completion 1225 * will be triggered with one of the following codes passed in as the rc argument: 1226 * ZOK operation completed successfully 1227 * ZNONODE the node does not exist. 1228 * ZNOAUTH the client does not have permission. 1229 * ZBADVERSION expected version does not match actual version. 1230 * ZNOTEMPTY children are present; node cannot be deleted. 1231 * \param data the data that will be passed to the completion routine when 1232 * the function completes. 1233 * \return ZOK on success or one of the following errcodes on failure: 1234 * ZBADARGUMENTS - invalid input parameters 1235 * ZINVALIDSTATE - zhandle state is either ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE 1236 * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory 1237 */ 1238 ZOOAPI int zoo_adelete(zhandle_t *zh, const char *path, int version, 1239 void_completion_t completion, const void *data); 1240 1241 /** 1242 * \brief checks the existence of a node in zookeeper. 1243 * 1244 * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init 1245 * \param path the name of the node. Expressed as a file name with slashes 1246 * separating ancestors of the node. 1247 * \param watch if nonzero, a watch will be set at the server to notify the 1248 * client if the node changes. The watch will be set even if the node does not 1249 * exist. This allows clients to watch for nodes to appear. 1250 * \param completion the routine to invoke when the request completes. The completion 1251 * will be triggered with one of the following codes passed in as the rc argument: 1252 * ZOK operation completed successfully 1253 * ZNONODE the node does not exist. 1254 * ZNOAUTH the client does not have permission. 1255 * \param data the data that will be passed to the completion routine when the 1256 * function completes. 1257 * \return ZOK on success or one of the following errcodes on failure: 1258 * ZBADARGUMENTS - invalid input parameters 1259 * ZINVALIDSTATE - zhandle state is either ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE 1260 * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory 1261 */ 1262 ZOOAPI int zoo_aexists(zhandle_t *zh, const char *path, int watch, 1263 stat_completion_t completion, const void *data); 1264 1265 /** 1266 * \brief checks the existence of a node in zookeeper. 1267 * 1268 * This function is similar to \ref zoo_axists except it allows one specify 1269 * a watcher object - a function pointer and associated context. The function 1270 * will be called once the watch has fired. The associated context data will be 1271 * passed to the function as the watcher context parameter. 1272 * 1273 * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init 1274 * \param path the name of the node. Expressed as a file name with slashes 1275 * separating ancestors of the node. 1276 * \param watcher if non-null a watch will set on the specified znode on the server. 1277 * The watch will be set even if the node does not exist. This allows clients 1278 * to watch for nodes to appear. 1279 * \param watcherCtx user specific data, will be passed to the watcher callback. 1280 * Unlike the global context set by \ref zookeeper_init, this watcher context 1281 * is associated with the given instance of the watcher only. 1282 * \param completion the routine to invoke when the request completes. The completion 1283 * will be triggered with one of the following codes passed in as the rc argument: 1284 * ZOK operation completed successfully 1285 * ZNONODE the node does not exist. 1286 * ZNOAUTH the client does not have permission. 1287 * \param data the data that will be passed to the completion routine when the 1288 * function completes. 1289 * \return ZOK on success or one of the following errcodes on failure: 1290 * ZBADARGUMENTS - invalid input parameters 1291 * ZINVALIDSTATE - zhandle state is either ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE 1292 * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory 1293 */ 1294 ZOOAPI int zoo_awexists(zhandle_t *zh, const char *path, 1295 watcher_fn watcher, void* watcherCtx, 1296 stat_completion_t completion, const void *data); 1297 1298 /** 1299 * \brief gets the data associated with a node. 1300 * 1301 * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init 1302 * \param path the name of the node. Expressed as a file name with slashes 1303 * separating ancestors of the node. 1304 * \param watch if nonzero, a watch will be set at the server to notify 1305 * the client if the node changes. 1306 * \param completion the routine to invoke when the request completes. The completion 1307 * will be triggered with one of the following codes passed in as the rc argument: 1308 * ZOK operation completed successfully 1309 * ZNONODE the node does not exist. 1310 * ZNOAUTH the client does not have permission. 1311 * \param data the data that will be passed to the completion routine when 1312 * the function completes. 1313 * \return ZOK on success or one of the following errcodes on failure: 1314 * ZBADARGUMENTS - invalid input parameters 1315 * ZINVALIDSTATE - zhandle state is either in ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE 1316 * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory 1317 */ 1318 ZOOAPI int zoo_aget(zhandle_t *zh, const char *path, int watch, 1319 data_completion_t completion, const void *data); 1320 1321 /** 1322 * \brief gets the data associated with a node. 1323 * 1324 * This function is similar to \ref zoo_aget except it allows one specify 1325 * a watcher object rather than a boolean watch flag. 1326 * 1327 * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init 1328 * \param path the name of the node. Expressed as a file name with slashes 1329 * separating ancestors of the node. 1330 * \param watcher if non-null, a watch will be set at the server to notify 1331 * the client if the node changes. 1332 * \param watcherCtx user specific data, will be passed to the watcher callback. 1333 * Unlike the global context set by \ref zookeeper_init, this watcher context 1334 * is associated with the given instance of the watcher only. 1335 * \param completion the routine to invoke when the request completes. The completion 1336 * will be triggered with one of the following codes passed in as the rc argument: 1337 * ZOK operation completed successfully 1338 * ZNONODE the node does not exist. 1339 * ZNOAUTH the client does not have permission. 1340 * \param data the data that will be passed to the completion routine when 1341 * the function completes. 1342 * \return ZOK on success or one of the following errcodes on failure: 1343 * ZBADARGUMENTS - invalid input parameters 1344 * ZINVALIDSTATE - zhandle state is either in ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE 1345 * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory 1346 */ 1347 ZOOAPI int zoo_awget(zhandle_t *zh, const char *path, 1348 watcher_fn watcher, void* watcherCtx, 1349 data_completion_t completion, const void *data); 1350 1351 /** 1352 * \brief gets the last committed configuration of the ZooKeeper cluster as it is known to 1353 * the server to which the client is connected. 1354 * 1355 * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init 1356 * \param watch if nonzero, a watch will be set at the server to notify 1357 * the client if the configuration changes. 1358 * \param completion the routine to invoke when the request completes. The completion 1359 * will be triggered with one of the following codes passed in as the rc argument: 1360 * ZOK operation completed successfully 1361 * ZNONODE the configuration node (/zookeeper/config) does not exist. 1362 * ZNOAUTH the client does not have permission to access the configuration node. 1363 * \param data the configuration data that will be passed to the completion routine when 1364 * the function completes. 1365 * \return ZOK on success or one of the following errcodes on failure: 1366 * ZBADARGUMENTS - invalid input parameters 1367 * ZINVALIDSTATE - zhandle state is either in ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE 1368 * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory 1369 */ 1370 ZOOAPI int zoo_agetconfig(zhandle_t *zh, int watch, 1371 data_completion_t completion, const void *data); 1372 1373 /** 1374 * \brief gets the last committed configuration of the ZooKeeper cluster as it is known to 1375 * the server to which the client is connected. 1376 * 1377 * This function is similar to \ref zoo_agetconfig except it allows one specify 1378 * a watcher object rather than a boolean watch flag. 1379 * 1380 * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init 1381 * \param watcher if non-null, a watch will be set at the server to notify 1382 * the client if the node changes. 1383 * \param watcherCtx user specific data, will be passed to the watcher callback. 1384 * Unlike the global context set by \ref zookeeper_init, this watcher context 1385 * is associated with the given instance of the watcher only. 1386 * \param completion the routine to invoke when the request completes. The completion 1387 * will be triggered with one of the following codes passed in as the rc argument: 1388 * ZOK operation completed successfully 1389 * ZNONODE the configuration node (/zookeeper/config) does not exist. 1390 * ZNOAUTH the client does not have permission to access the configuration node. 1391 * \param data the configuration data that will be passed to the completion routine when 1392 * the function completes. 1393 * \return ZOK on success or one of the following errcodes on failure: 1394 * ZBADARGUMENTS - invalid input parameters 1395 * ZINVALIDSTATE - zhandle state is either in ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE 1396 * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory 1397 */ 1398 ZOOAPI int zoo_awgetconfig(zhandle_t *zh, watcher_fn watcher, void* watcherCtx, 1399 data_completion_t completion, const void *data); 1400 1401 /** 1402 * \brief asynchronous reconfiguration interface - allows changing ZK cluster 1403 * ensemble membership and roles of ensemble peers. 1404 * 1405 * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init 1406 * \param joining - comma separated list of servers to be added to the ensemble. 1407 * Each has a configuration line for a server to be added (as would appear in a 1408 * configuration file), only for maj. quorums. NULL for non-incremental reconfiguration. 1409 * \param leaving - comma separated list of server IDs to be removed from the ensemble. 1410 * Each has an id of a server to be removed, only for maj. quorums. NULL for 1411 * non-incremental reconfiguration. 1412 * \param members - comma separated list of new membership (e.g., contents of a 1413 * membership configuration file) - for use only with a non-incremental 1414 * reconfiguration. NULL for incremental reconfiguration. 1415 * \param version - version of config from which we want to reconfigure - if 1416 * current config is different reconfiguration will fail. Should be -1 to disable 1417 * this option. 1418 * \param completion - the routine to invoke when the request completes. The 1419 * completion will be triggered with one of the following codes passed in as the 1420 * rc argument: 1421 * ZOK operation completed successfully 1422 * \param data the configuration data that will be passed to the completion routine 1423 * when the function completes. 1424 * \return return value of the function call. 1425 * ZOK operation completed successfully 1426 * ZBADARGUMENTS - invalid input parameters (one case when this is returned is 1427 * when the new config has less than 2 servers) 1428 * ZINVALIDSTATE - zhandle state is either in ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE 1429 * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory 1430 * ZNEWCONFIGNOQUORUM - no quorum of new config is connected and up-to-date with 1431 * the leader of last committed config - try invoking reconfiguration after new servers are connected and synced 1432 * ZRECONFIGINPROGRESS - another reconfig is currently in progress 1433 */ 1434 ZOOAPI int zoo_areconfig(zhandle_t *zh, const char *joining, const char *leaving, 1435 const char *members, int64_t version, data_completion_t dc, const void *data); 1436 1437 /** 1438 * \brief sets the data associated with a node. 1439 * 1440 * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init 1441 * \param path the name of the node. Expressed as a file name with slashes 1442 * separating ancestors of the node. 1443 * \param buffer the buffer holding data to be written to the node. 1444 * \param buflen the number of bytes from buffer to write. 1445 * \param version the expected version of the node. The function will fail if 1446 * the actual version of the node does not match the expected version. If -1 is 1447 * used the version check will not take place. * completion: If null, 1448 * the function will execute synchronously. Otherwise, the function will return 1449 * immediately and invoke the completion routine when the request completes. 1450 * \param completion the routine to invoke when the request completes. The completion 1451 * will be triggered with one of the following codes passed in as the rc argument: 1452 * ZOK operation completed successfully 1453 * ZNONODE the node does not exist. 1454 * ZNOAUTH the client does not have permission. 1455 * ZBADVERSION expected version does not match actual version. 1456 * \param data the data that will be passed to the completion routine when 1457 * the function completes. 1458 * \return ZOK on success or one of the following errcodes on failure: 1459 * ZBADARGUMENTS - invalid input parameters 1460 * ZINVALIDSTATE - zhandle state is either ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE 1461 * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory 1462 */ 1463 ZOOAPI int zoo_aset(zhandle_t *zh, const char *path, const char *buffer, int buflen, 1464 int version, stat_completion_t completion, const void *data); 1465 1466 /** 1467 * \brief lists the children of a node. 1468 * 1469 * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init 1470 * \param path the name of the node. Expressed as a file name with slashes 1471 * separating ancestors of the node. 1472 * \param watch if nonzero, a watch will be set at the server to notify 1473 * the client if the node changes. 1474 * \param completion the routine to invoke when the request completes. The completion 1475 * will be triggered with one of the following codes passed in as the rc argument: 1476 * ZOK operation completed successfully 1477 * ZNONODE the node does not exist. 1478 * ZNOAUTH the client does not have permission. 1479 * \param data the data that will be passed to the completion routine when 1480 * the function completes. 1481 * \return ZOK on success or one of the following errcodes on failure: 1482 * ZBADARGUMENTS - invalid input parameters 1483 * ZINVALIDSTATE - zhandle state is either ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE 1484 * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory 1485 */ 1486 ZOOAPI int zoo_aget_children(zhandle_t *zh, const char *path, int watch, 1487 strings_completion_t completion, const void *data); 1488 1489 /** 1490 * \brief lists the children of a node. 1491 * 1492 * This function is similar to \ref zoo_aget_children except it allows one specify 1493 * a watcher object rather than a boolean watch flag. 1494 * 1495 * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init 1496 * \param path the name of the node. Expressed as a file name with slashes 1497 * separating ancestors of the node. 1498 * \param watcher if non-null, a watch will be set at the server to notify 1499 * the client if the node changes. 1500 * \param watcherCtx user specific data, will be passed to the watcher callback. 1501 * Unlike the global context set by \ref zookeeper_init, this watcher context 1502 * is associated with the given instance of the watcher only. 1503 * \param completion the routine to invoke when the request completes. The completion 1504 * will be triggered with one of the following codes passed in as the rc argument: 1505 * ZOK operation completed successfully 1506 * ZNONODE the node does not exist. 1507 * ZNOAUTH the client does not have permission. 1508 * \param data the data that will be passed to the completion routine when 1509 * the function completes. 1510 * \return ZOK on success or one of the following errcodes on failure: 1511 * ZBADARGUMENTS - invalid input parameters 1512 * ZINVALIDSTATE - zhandle state is either ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE 1513 * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory 1514 */ 1515 ZOOAPI int zoo_awget_children(zhandle_t *zh, const char *path, 1516 watcher_fn watcher, void* watcherCtx, 1517 strings_completion_t completion, const void *data); 1518 1519 /** 1520 * \brief lists the children of a node, and get the parent stat. 1521 * 1522 * This function is new in version 3.3.0 1523 * 1524 * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init 1525 * \param path the name of the node. Expressed as a file name with slashes 1526 * separating ancestors of the node. 1527 * \param watch if nonzero, a watch will be set at the server to notify 1528 * the client if the node changes. 1529 * \param completion the routine to invoke when the request completes. The completion 1530 * will be triggered with one of the following codes passed in as the rc argument: 1531 * ZOK operation completed successfully 1532 * ZNONODE the node does not exist. 1533 * ZNOAUTH the client does not have permission. 1534 * \param data the data that will be passed to the completion routine when 1535 * the function completes. 1536 * \return ZOK on success or one of the following errcodes on failure: 1537 * ZBADARGUMENTS - invalid input parameters 1538 * ZINVALIDSTATE - zhandle state is either ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE 1539 * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory 1540 */ 1541 ZOOAPI int zoo_aget_children2(zhandle_t *zh, const char *path, int watch, 1542 strings_stat_completion_t completion, const void *data); 1543 1544 /** 1545 * \brief lists the children of a node, and get the parent stat. 1546 * 1547 * This function is similar to \ref zoo_aget_children2 except it allows one specify 1548 * a watcher object rather than a boolean watch flag. 1549 * 1550 * This function is new in version 3.3.0 1551 * 1552 * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init 1553 * \param path the name of the node. Expressed as a file name with slashes 1554 * separating ancestors of the node. 1555 * \param watcher if non-null, a watch will be set at the server to notify 1556 * the client if the node changes. 1557 * \param watcherCtx user specific data, will be passed to the watcher callback. 1558 * Unlike the global context set by \ref zookeeper_init, this watcher context 1559 * is associated with the given instance of the watcher only. 1560 * \param completion the routine to invoke when the request completes. The completion 1561 * will be triggered with one of the following codes passed in as the rc argument: 1562 * ZOK operation completed successfully 1563 * ZNONODE the node does not exist. 1564 * ZNOAUTH the client does not have permission. 1565 * \param data the data that will be passed to the completion routine when 1566 * the function completes. 1567 * \return ZOK on success or one of the following errcodes on failure: 1568 * ZBADARGUMENTS - invalid input parameters 1569 * ZINVALIDSTATE - zhandle state is either ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE 1570 * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory 1571 */ 1572 ZOOAPI int zoo_awget_children2(zhandle_t *zh, const char *path, 1573 watcher_fn watcher, void* watcherCtx, 1574 strings_stat_completion_t completion, const void *data); 1575 1576 /** 1577 * \brief Flush leader channel. 1578 * 1579 * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init 1580 * \param path the name of the node. Expressed as a file name with slashes 1581 * separating ancestors of the node. 1582 * \param completion the routine to invoke when the request completes. The completion 1583 * will be triggered with one of the following codes passed in as the rc argument: 1584 * ZOK operation completed successfully 1585 * ZNONODE the node does not exist. 1586 * ZNOAUTH the client does not have permission. 1587 * \param data the data that will be passed to the completion routine when 1588 * the function completes. 1589 * \return ZOK on success or one of the following errcodes on failure: 1590 * ZBADARGUMENTS - invalid input parameters 1591 * ZINVALIDSTATE - zhandle state is either ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE 1592 * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory 1593 */ 1594 1595 ZOOAPI int zoo_async(zhandle_t *zh, const char *path, 1596 string_completion_t completion, const void *data); 1597 1598 1599 /** 1600 * \brief gets the acl associated with a node. 1601 * 1602 * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init 1603 * \param path the name of the node. Expressed as a file name with slashes 1604 * separating ancestors of the node. 1605 * \param completion the routine to invoke when the request completes. The completion 1606 * will be triggered with one of the following codes passed in as the rc argument: 1607 * ZOK operation completed successfully 1608 * ZNONODE the node does not exist. 1609 * ZNOAUTH the client does not have permission. 1610 * \param data the data that will be passed to the completion routine when 1611 * the function completes. 1612 * \return ZOK on success or one of the following errcodes on failure: 1613 * ZBADARGUMENTS - invalid input parameters 1614 * ZINVALIDSTATE - zhandle state is either ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE 1615 * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory 1616 */ 1617 ZOOAPI int zoo_aget_acl(zhandle_t *zh, const char *path, acl_completion_t completion, 1618 const void *data); 1619 1620 /** 1621 * \brief sets the acl associated with a node. 1622 * 1623 * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init 1624 * \param path the name of the node. Expressed as a file name with slashes 1625 * separating ancestors of the node. 1626 * \param buffer the buffer holding the acls to be written to the node. 1627 * \param buflen the number of bytes from buffer to write. 1628 * \param completion the routine to invoke when the request completes. The completion 1629 * will be triggered with one of the following codes passed in as the rc argument: 1630 * ZOK operation completed successfully 1631 * ZNONODE the node does not exist. 1632 * ZNOAUTH the client does not have permission. 1633 * ZINVALIDACL invalid ACL specified 1634 * ZBADVERSION expected version does not match actual version. 1635 * \param data the data that will be passed to the completion routine when 1636 * the function completes. 1637 * \return ZOK on success or one of the following errcodes on failure: 1638 * ZBADARGUMENTS - invalid input parameters 1639 * ZINVALIDSTATE - zhandle state is either ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE 1640 * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory 1641 */ 1642 ZOOAPI int zoo_aset_acl(zhandle_t *zh, const char *path, int version, 1643 struct ACL_vector *acl, void_completion_t, const void *data); 1644 1645 /** 1646 * \brief atomically commits multiple zookeeper operations. 1647 * 1648 * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init 1649 * \param count the number of operations 1650 * \param ops an array of operations to commit 1651 * \param results an array to hold the results of the operations 1652 * \param completion the routine to invoke when the request completes. The completion 1653 * will be triggered with any of the error codes that can that can be returned by the 1654 * ops supported by a multi op (see \ref zoo_acreate, \ref zoo_adelete, \ref zoo_aset). 1655 * \param data the data that will be passed to the completion routine when 1656 * the function completes. 1657 * \return the return code for the function call. This can be any of the 1658 * values that can be returned by the ops supported by a multi op (see 1659 * \ref zoo_acreate, \ref zoo_adelete, \ref zoo_aset). 1660 */ 1661 ZOOAPI int zoo_amulti(zhandle_t *zh, int count, const zoo_op_t *ops, 1662 zoo_op_result_t *results, void_completion_t, const void *data); 1663 1664 /** 1665 * \brief return an error string. 1666 * 1667 * \param return code 1668 * \return string corresponding to the return code 1669 */ 1670 ZOOAPI const char* zerror(int c); 1671 1672 /** 1673 * \brief specify application credentials. 1674 * 1675 * The application calls this function to specify its credentials for purposes 1676 * of authentication. The server will use the security provider specified by 1677 * the scheme parameter to authenticate the client connection. If the 1678 * authentication request has failed: 1679 * - the server connection is dropped 1680 * - the watcher is called with the ZOO_AUTH_FAILED_STATE value as the state 1681 * parameter. 1682 * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init 1683 * \param scheme the id of authentication scheme. Natively supported: 1684 * "digest" password-based authentication 1685 * \param cert application credentials. The actual value depends on the scheme. 1686 * \param certLen the length of the data parameter 1687 * \param completion the routine to invoke when the request completes. One of 1688 * the following result codes may be passed into the completion callback: 1689 * ZOK operation completed successfully 1690 * ZAUTHFAILED authentication failed 1691 * \param data the data that will be passed to the completion routine when the 1692 * function completes. 1693 * \return ZOK on success or one of the following errcodes on failure: 1694 * ZBADARGUMENTS - invalid input parameters 1695 * ZINVALIDSTATE - zhandle state is either ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE 1696 * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory 1697 * ZSYSTEMERROR - a system error occurred 1698 */ 1699 ZOOAPI int zoo_add_auth(zhandle_t *zh,const char* scheme,const char* cert, 1700 int certLen, void_completion_t completion, const void *data); 1701 1702 /** 1703 * \brief checks if the current zookeeper connection state can't be recovered. 1704 * 1705 * The application must close the zhandle and try to reconnect. 1706 * 1707 * \param zh the zookeeper handle (see \ref zookeeper_init) 1708 * \return ZINVALIDSTATE if connection is unrecoverable 1709 */ 1710 ZOOAPI int is_unrecoverable(zhandle_t *zh); 1711 1712 /** 1713 * \brief sets the debugging level for the library 1714 */ 1715 ZOOAPI void zoo_set_debug_level(ZooLogLevel logLevel); 1716 1717 /** 1718 * \brief sets the stream to be used by the library for logging 1719 * 1720 * The zookeeper library uses stderr as its default log stream. Application 1721 * must make sure the stream is writable. Passing in NULL resets the stream 1722 * to its default value (stderr). 1723 */ 1724 ZOOAPI void zoo_set_log_stream(FILE* logStream); 1725 1726 /** 1727 * \brief gets the callback to be used by this connection for logging. 1728 * 1729 * This is a per-connection logging mechanism that will take priority over 1730 * the library-wide default log stream. That is, zookeeper library will first 1731 * try to use a per-connection callback if available and if not, will fallback 1732 * to using the logging stream. Passing in NULL resets the callback and will 1733 * cause it to then fallback to using the logging stream as described in \ref 1734 * zoo_set_log_stream. 1735 */ 1736 ZOOAPI log_callback_fn zoo_get_log_callback(const zhandle_t *zh); 1737 1738 /** 1739 * \brief sets the callback to be used by the library for logging 1740 * 1741 * Setting this callback has the effect of overriding the default log stream. 1742 * Zookeeper will first try to use a per-connection callback if available 1743 * and if not, will fallback to using the logging stream. Passing in NULL 1744 * resets the callback and will cause it to then fallback to using the logging 1745 * stream as described in \ref zoo_set_log_stream. 1746 * 1747 * Note: The provided callback will be invoked by multiple threads and therefore 1748 * it needs to be thread-safe. 1749 */ 1750 ZOOAPI void zoo_set_log_callback(zhandle_t *zh, log_callback_fn callback); 1751 1752 /** 1753 * \brief enable/disable quorum endpoint order randomization 1754 * 1755 * Note: typically this method should NOT be used outside of testing. 1756 * 1757 * If passed a non-zero value, will make the client connect to quorum peers 1758 * in the order as specified in the zookeeper_init() call. 1759 * A zero value causes zookeeper_init() to permute the peer endpoints 1760 * which is good for more even client connection distribution among the 1761 * quorum peers. 1762 */ 1763 ZOOAPI void zoo_deterministic_conn_order(int yesOrNo); 1764 1765 /** 1766 * Type of watches: used to select which type of watches should be removed 1767 */ 1768 typedef enum { 1769 ZWATCHTYPE_CHILD = 1, 1770 ZWATCHTYPE_DATA = 2, 1771 ZWATCHTYPE_ANY = 3 1772 } ZooWatcherType; 1773 1774 /** 1775 * \brief removes the watches for the given path and watcher type. 1776 * 1777 * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init 1778 * \param path the path for which watches will be removed 1779 * \param wtype the watcher type to be removed 1780 * \param watcher the watcher to be removed, if null all watches for that 1781 * path (and watcher type) will be removed 1782 * \param watcherCtx the contex associated with the watcher to be removed 1783 * \param local whether the watches will be removed locally even if there is 1784 * no server connection 1785 * \return the return code for the function call. 1786 * ZOK - operation completed successfully 1787 * ZNOWATCHER - the watcher couldn't be found. 1788 * ZINVALIDSTATE - if !local, zhandle state is either ZOO_SESSION_EXPIRED_STATE 1789 * or ZOO_AUTH_FAILED_STATE 1790 * ZBADARGUMENTS - invalid input parameters 1791 * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory 1792 * ZSYSTEMERROR - a system error occured 1793 */ 1794 ZOOAPI int zoo_aremove_watches(zhandle_t *zh, const char *path, 1795 ZooWatcherType wtype, watcher_fn watcher, void *watcherCtx, int local, 1796 void_completion_t *completion, const void *data); 1797 1798 /** 1799 * \brief removes all the watches for the given path and watcher type. 1800 * 1801 * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init 1802 * \param path the path for which watches will be removed 1803 * \param wtype the watcher type to be removed 1804 * \param local whether the watches will be removed locally even if there is 1805 * no server connection 1806 * \return the return code for the function call. 1807 * ZOK - operation completed successfully 1808 * ZNOWATCHER - the watcher couldn't be found. 1809 * ZINVALIDSTATE - if !local, zhandle state is either ZOO_SESSION_EXPIRED_STATE 1810 * or ZOO_AUTH_FAILED_STATE 1811 * ZBADARGUMENTS - invalid input parameters 1812 * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory 1813 * ZSYSTEMERROR - a system error occured 1814 */ 1815 ZOOAPI int zoo_remove_all_watches(zhandle_t *zh, const char *path, 1816 ZooWatcherType wtype, int local); 1817 1818 /** 1819 * \brief removes all the watches for the given path and watcher type. 1820 * 1821 * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init 1822 * \param path the path for which watches will be removed 1823 * \param wtype the watcher type to be removed 1824 * \param local whether the watches will be removed locally even if there is 1825 * no server connection 1826 * \return the return code for the function call. 1827 * ZOK - operation completed successfully 1828 * ZNOWATCHER - the watcher couldn't be found. 1829 * ZINVALIDSTATE - if !local, zhandle state is either ZOO_SESSION_EXPIRED_STATE 1830 * or ZOO_AUTH_FAILED_STATE 1831 * ZBADARGUMENTS - invalid input parameters 1832 * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory 1833 * ZSYSTEMERROR - a system error occured 1834 */ 1835 ZOOAPI int zoo_aremove_all_watches(zhandle_t *zh, const char *path, 1836 ZooWatcherType wtype, int local, void_completion_t *completion, 1837 const void *data); 1838 1839 #ifdef THREADED 1840 /** 1841 * \brief create a node synchronously. 1842 * 1843 * This method will create a node in ZooKeeper. A node can only be created if 1844 * it does not already exist. The Create Mode affects the creation of nodes. 1845 * If ZOO_EPHEMERAL mode is chosen, the node will automatically get removed if the 1846 * client session goes away. If ZOO_CONTAINER flag is set, a container node will be 1847 * created. For ZOO_*_SEQUENTIAL modes, a unique monotonically increasing 1848 * sequence number is appended to the path name. The sequence number is always fixed 1849 * length of 10 digits, 0 padded. 1850 * 1851 * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init 1852 * \param path The name of the node. Expressed as a file name with slashes 1853 * separating ancestors of the node. 1854 * \param value The data to be stored in the node. 1855 * \param valuelen The number of bytes in data. To set the data to be NULL use 1856 * value as NULL and valuelen as -1. 1857 * \param acl The initial ACL of the node. The ACL must not be null or empty. 1858 * \param mode this parameter should be one of the Create Modes. 1859 * \param path_buffer Buffer which will be filled with the path of the 1860 * new node (this might be different than the supplied path 1861 * because of the ZOO_SEQUENCE flag). The path string will always be 1862 * null-terminated. This parameter may be NULL if path_buffer_len = 0. 1863 * \param path_buffer_len Size of path buffer; if the path of the new 1864 * node (including space for the null terminator) exceeds the buffer size, 1865 * the path string will be truncated to fit. The actual path of the 1866 * new node in the server will not be affected by the truncation. 1867 * The path string will always be null-terminated. 1868 * \return one of the following codes are returned: 1869 * ZOK operation completed successfully 1870 * ZNONODE the parent node does not exist. 1871 * ZNODEEXISTS the node already exists 1872 * ZNOAUTH the client does not have permission. 1873 * ZNOCHILDRENFOREPHEMERALS cannot create children of ephemeral nodes. 1874 * ZBADARGUMENTS - invalid input parameters 1875 * ZINVALIDSTATE - zhandle state is either ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE 1876 * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory 1877 */ 1878 ZOOAPI int zoo_create(zhandle_t *zh, const char *path, const char *value, 1879 int valuelen, const struct ACL_vector *acl, int mode, 1880 char *path_buffer, int path_buffer_len); 1881 1882 /** 1883 * \brief create a node synchronously. 1884 * 1885 * This method will create a node in ZooKeeper. A node can only be created if 1886 * it does not already exist. The Create Mode affects the creation of nodes. 1887 * If ZOO_EPHEMERAL mode is chosen, the node will automatically get removed if the 1888 * client session goes away. If ZOO_CONTAINER flag is set, a container node will be 1889 * created. For ZOO_*_SEQUENTIAL modes, a unique monotonically increasing 1890 * sequence number is appended to the path name. The sequence number is always fixed 1891 * length of 10 digits, 0 padded. When ZOO_*_WITH_TTL is selected, a ttl node will be 1892 * created. 1893 * 1894 * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init 1895 * \param path The name of the node. Expressed as a file name with slashes 1896 * separating ancestors of the node. 1897 * \param value The data to be stored in the node. 1898 * \param valuelen The number of bytes in data. To set the data to be NULL use 1899 * value as NULL and valuelen as -1. 1900 * \param acl The initial ACL of the node. The ACL must not be null or empty. 1901 * \param mode this parameter should be one of the Create Modes. 1902 * \param ttl the value of ttl in milliseconds. It must be positive for ZOO_*_WITH_TTL 1903 * Create modes, otherwise it must be -1. 1904 * \param path_buffer Buffer which will be filled with the path of the 1905 * new node (this might be different than the supplied path 1906 * because of the ZOO_SEQUENCE flag). The path string will always be 1907 * null-terminated. This parameter may be NULL if path_buffer_len = 0. 1908 * \param path_buffer_len Size of path buffer; if the path of the new 1909 * node (including space for the null terminator) exceeds the buffer size, 1910 * the path string will be truncated to fit. The actual path of the 1911 * new node in the server will not be affected by the truncation. 1912 * The path string will always be null-terminated. 1913 * \return one of the following codes are returned: 1914 * ZOK operation completed successfully 1915 * ZNONODE the parent node does not exist. 1916 * ZNODEEXISTS the node already exists 1917 * ZNOAUTH the client does not have permission. 1918 * ZNOCHILDRENFOREPHEMERALS cannot create children of ephemeral nodes. 1919 * ZBADARGUMENTS - invalid input parameters 1920 * ZINVALIDSTATE - zhandle state is either ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE 1921 * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory 1922 */ 1923 ZOOAPI int zoo_create_ttl(zhandle_t *zh, const char *path, const char *value, 1924 int valuelen, const struct ACL_vector *acl, int mode, int64_t ttl, 1925 char *path_buffer, int path_buffer_len); 1926 1927 /** 1928 * \brief create a node synchronously and collect stat details. 1929 * 1930 * This method will create a node in ZooKeeper. A node can only be created if 1931 * it does not already exist. The Create Mode affects the creation of nodes. 1932 * If ZOO_EPHEMERAL mode is chosen, the node will automatically get removed if the 1933 * client session goes away. If ZOO_CONTAINER flag is set, a container node will be 1934 * created. For ZOO_*_SEQUENTIAL modes, a unique monotonically increasing 1935 * sequence number is appended to the path name. The sequence number is always fixed 1936 * length of 10 digits, 0 padded. 1937 * 1938 * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init 1939 * \param path The name of the node. Expressed as a file name with slashes 1940 * separating ancestors of the node. 1941 * \param value The data to be stored in the node. 1942 * \param valuelen The number of bytes in data. To set the data to be NULL use 1943 * value as NULL and valuelen as -1. 1944 * \param acl The initial ACL of the node. The ACL must not be null or empty. 1945 * \param mode this parameter should be one of the Create Modes. 1946 * \param path_buffer Buffer which will be filled with the path of the 1947 * new node (this might be different than the supplied path 1948 * because of the ZOO_SEQUENCE flag). The path string will always be 1949 * null-terminated. This parameter may be NULL if path_buffer_len = 0. 1950 * \param path_buffer_len Size of path buffer; if the path of the new 1951 * node (including space for the null terminator) exceeds the buffer size, 1952 * the path string will be truncated to fit. The actual path of the 1953 * new node in the server will not be affected by the truncation. 1954 * The path string will always be null-terminated. 1955 * \param stat The Stat struct to store Stat info into. 1956 * \return one of the following codes are returned: 1957 * ZOK operation completed successfully 1958 * ZNONODE the parent node does not exist. 1959 * ZNODEEXISTS the node already exists 1960 * ZNOAUTH the client does not have permission. 1961 * ZNOCHILDRENFOREPHEMERALS cannot create children of ephemeral nodes. 1962 * ZBADARGUMENTS - invalid input parameters 1963 * ZINVALIDSTATE - zhandle state is either ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE 1964 * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory 1965 */ 1966 ZOOAPI int zoo_create2(zhandle_t *zh, const char *path, const char *value, 1967 int valuelen, const struct ACL_vector *acl, int mode, 1968 char *path_buffer, int path_buffer_len, struct Stat *stat); 1969 1970 /** 1971 * \brief create a node synchronously and collect stat details. 1972 * 1973 * This method will create a node in ZooKeeper. A node can only be created if 1974 * it does not already exist. The Create Mode affects the creation of nodes. 1975 * If ZOO_EPHEMERAL mode is chosen, the node will automatically get removed if the 1976 * client session goes away. If ZOO_CONTAINER flag is set, a container node will be 1977 * created. For ZOO_*_SEQUENTIAL modes, a unique monotonically increasing 1978 * sequence number is appended to the path name. The sequence number is always fixed 1979 * length of 10 digits, 0 padded. When ZOO_*_WITH_TTL is selected, a ttl node will be 1980 * created. 1981 * 1982 * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init 1983 * \param path The name of the node. Expressed as a file name with slashes 1984 * separating ancestors of the node. 1985 * \param value The data to be stored in the node. 1986 * \param valuelen The number of bytes in data. To set the data to be NULL use 1987 * value as NULL and valuelen as -1. 1988 * \param acl The initial ACL of the node. The ACL must not be null or empty. 1989 * \param mode this parameter should be one of the Create Modes. 1990 * \param ttl the value of ttl in milliseconds. It must be positive for ZOO_*_WITH_TTL 1991 * Create modes, otherwise it must be -1. 1992 * \param path_buffer Buffer which will be filled with the path of the 1993 * new node (this might be different than the supplied path 1994 * because of the ZOO_SEQUENCE flag). The path string will always be 1995 * null-terminated. This parameter may be NULL if path_buffer_len = 0. 1996 * \param path_buffer_len Size of path buffer; if the path of the new 1997 * node (including space for the null terminator) exceeds the buffer size, 1998 * the path string will be truncated to fit. The actual path of the 1999 * new node in the server will not be affected by the truncation. 2000 * The path string will always be null-terminated. 2001 * \param stat The Stat struct to store Stat info into. 2002 * \return one of the following codes are returned: 2003 * ZOK operation completed successfully 2004 * ZNONODE the parent node does not exist. 2005 * ZNODEEXISTS the node already exists 2006 * ZNOAUTH the client does not have permission. 2007 * ZNOCHILDRENFOREPHEMERALS cannot create children of ephemeral nodes. 2008 * ZBADARGUMENTS - invalid input parameters 2009 * ZINVALIDSTATE - zhandle state is either ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE 2010 * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory 2011 */ 2012 ZOOAPI int zoo_create2_ttl(zhandle_t *zh, const char *path, const char *value, 2013 int valuelen, const struct ACL_vector *acl, int mode, int64_t ttl, 2014 char *path_buffer, int path_buffer_len, struct Stat *stat); 2015 2016 /** 2017 * \brief delete a node in zookeeper synchronously. 2018 * 2019 * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init 2020 * \param path the name of the node. Expressed as a file name with slashes 2021 * separating ancestors of the node. 2022 * \param version the expected version of the node. The function will fail if the 2023 * actual version of the node does not match the expected version. 2024 * If -1 is used the version check will not take place. 2025 * \return one of the following values is returned. 2026 * ZOK operation completed successfully 2027 * ZNONODE the node does not exist. 2028 * ZNOAUTH the client does not have permission. 2029 * ZBADVERSION expected version does not match actual version. 2030 * ZNOTEMPTY children are present; node cannot be deleted. 2031 * ZBADARGUMENTS - invalid input parameters 2032 * ZINVALIDSTATE - zhandle state is either ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE 2033 * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory 2034 */ 2035 ZOOAPI int zoo_delete(zhandle_t *zh, const char *path, int version); 2036 2037 /** 2038 * \brief checks the existence of a node in zookeeper synchronously. 2039 * 2040 * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init 2041 * \param path the name of the node. Expressed as a file name with slashes 2042 * separating ancestors of the node. 2043 * \param watch if nonzero, a watch will be set at the server to notify the 2044 * client if the node changes. The watch will be set even if the node does not 2045 * exist. This allows clients to watch for nodes to appear. 2046 * \param the return stat value of the node. 2047 * \return return code of the function call. 2048 * ZOK operation completed successfully 2049 * ZNONODE the node does not exist. 2050 * ZNOAUTH the client does not have permission. 2051 * ZBADARGUMENTS - invalid input parameters 2052 * ZINVALIDSTATE - zhandle state is either ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE 2053 * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory 2054 */ 2055 ZOOAPI int zoo_exists(zhandle_t *zh, const char *path, int watch, struct Stat *stat); 2056 2057 /** 2058 * \brief checks the existence of a node in zookeeper synchronously. 2059 * 2060 * This function is similar to \ref zoo_exists except it allows one specify 2061 * a watcher object rather than a boolean watch flag. 2062 * 2063 * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init 2064 * \param path the name of the node. Expressed as a file name with slashes 2065 * separating ancestors of the node. 2066 * \param watcher if non-null a watch will set on the specified znode on the server. 2067 * The watch will be set even if the node does not exist. This allows clients 2068 * to watch for nodes to appear. 2069 * \param watcherCtx user specific data, will be passed to the watcher callback. 2070 * Unlike the global context set by \ref zookeeper_init, this watcher context 2071 * is associated with the given instance of the watcher only. 2072 * \param the return stat value of the node. 2073 * \return return code of the function call. 2074 * ZOK operation completed successfully 2075 * ZNONODE the node does not exist. 2076 * ZNOAUTH the client does not have permission. 2077 * ZBADARGUMENTS - invalid input parameters 2078 * ZINVALIDSTATE - zhandle state is either ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE 2079 * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory 2080 */ 2081 ZOOAPI int zoo_wexists(zhandle_t *zh, const char *path, 2082 watcher_fn watcher, void* watcherCtx, struct Stat *stat); 2083 2084 /** 2085 * \brief gets the data associated with a node synchronously. 2086 * 2087 * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init 2088 * \param path the name of the node. Expressed as a file name with slashes 2089 * separating ancestors of the node. 2090 * \param watch if nonzero, a watch will be set at the server to notify 2091 * the client if the node changes. 2092 * \param buffer the buffer holding the node data returned by the server 2093 * \param buffer_len is the size of the buffer pointed to by the buffer parameter. 2094 * It'll be set to the actual data length upon return. If the data is NULL, length is -1. 2095 * \param stat if not NULL, will hold the value of stat for the path on return. 2096 * \return return value of the function call. 2097 * ZOK operation completed successfully 2098 * ZNONODE the node does not exist. 2099 * ZNOAUTH the client does not have permission. 2100 * ZBADARGUMENTS - invalid input parameters 2101 * ZINVALIDSTATE - zhandle state is either in ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE 2102 * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory 2103 */ 2104 ZOOAPI int zoo_get(zhandle_t *zh, const char *path, int watch, char *buffer, 2105 int* buffer_len, struct Stat *stat); 2106 /** 2107 * \brief gets the data associated with a node synchronously. 2108 * 2109 * This function is similar to \ref zoo_get except it allows one specify 2110 * a watcher object rather than a boolean watch flag. 2111 * 2112 * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init 2113 * \param path the name of the node. Expressed as a file name with slashes 2114 * separating ancestors of the node. 2115 * \param watcher if non-null, a watch will be set at the server to notify 2116 * the client if the node changes. 2117 * \param watcherCtx user specific data, will be passed to the watcher callback. 2118 * Unlike the global context set by \ref zookeeper_init, this watcher context 2119 * is associated with the given instance of the watcher only. 2120 * \param buffer the buffer holding the node data returned by the server 2121 * \param buffer_len is the size of the buffer pointed to by the buffer parameter. 2122 * It'll be set to the actual data length upon return. If the data is NULL, length is -1. 2123 * \param stat if not NULL, will hold the value of stat for the path on return. 2124 * \return return value of the function call. 2125 * ZOK operation completed successfully 2126 * ZNONODE the node does not exist. 2127 * ZNOAUTH the client does not have permission. 2128 * ZBADARGUMENTS - invalid input parameters 2129 * ZINVALIDSTATE - zhandle state is either in ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE 2130 * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory 2131 */ 2132 ZOOAPI int zoo_wget(zhandle_t *zh, const char *path, 2133 watcher_fn watcher, void* watcherCtx, 2134 char *buffer, int* buffer_len, struct Stat *stat); 2135 2136 /** 2137 * \brief gets the last committed configuration of the ZooKeeper cluster as it is known to 2138 * the server to which the client is connected, synchronously. 2139 * 2140 * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init 2141 * \param watch if nonzero, a watch will be set at the server to notify 2142 * the client if the node changes. 2143 * \param buffer the buffer holding the configuration data returned by the server 2144 * \param buffer_len is the size of the buffer pointed to by the buffer parameter. 2145 * It'll be set to the actual data length upon return. If the data is NULL, length is -1. 2146 * \param stat if not NULL, will hold the value of stat for the path on return. 2147 * \return return value of the function call. 2148 * ZOK operation completed successfully 2149 * ZNONODE the configuration node (/zookeeper/config) does not exist. 2150 * ZNOAUTH the client does not have permission to access the configuration node. 2151 * ZBADARGUMENTS - invalid input parameters 2152 * ZINVALIDSTATE - zhandle state is either in ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE 2153 * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory 2154 */ 2155 ZOOAPI int zoo_getconfig(zhandle_t *zh, int watch, char *buffer, 2156 int* buffer_len, struct Stat *stat); 2157 2158 /** 2159 * \brief gets the last committed configuration of the ZooKeeper cluster as it is known to 2160 * the server to which the client is connected, synchronously. 2161 * 2162 * This function is similar to \ref zoo_getconfig except it allows one specify 2163 * a watcher object rather than a boolean watch flag. 2164 * 2165 * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init 2166 * \param watcher if non-null, a watch will be set at the server to notify 2167 * the client if the node changes. 2168 * \param watcherCtx user specific data, will be passed to the watcher callback. 2169 * Unlike the global context set by \ref zookeeper_init, this watcher context 2170 * is associated with the given instance of the watcher only. 2171 * \param buffer the buffer holding the configuration data returned by the server 2172 * \param buffer_len is the size of the buffer pointed to by the buffer parameter. 2173 * It'll be set to the actual data length upon return. If the data is NULL, length is -1. 2174 * \param stat if not NULL, will hold the value of stat for the path on return. 2175 * \return return value of the function call. 2176 * ZOK operation completed successfully 2177 * ZNONODE the configuration node (/zookeeper/config) does not exist. 2178 * ZNOAUTH the client does not have permission to access the configuration node. 2179 * ZBADARGUMENTS - invalid input parameters 2180 * ZINVALIDSTATE - zhandle state is either in ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE 2181 * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory 2182 */ 2183 ZOOAPI int zoo_wgetconfig(zhandle_t *zh, watcher_fn watcher, void* watcherCtx, 2184 char *buffer, int* buffer_len, struct Stat *stat); 2185 2186 /** 2187 * \brief synchronous reconfiguration interface - allows changing ZK cluster 2188 * ensemble membership and roles of ensemble peers. 2189 * 2190 * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init 2191 * \param joining - comma separated list of servers to be added to the ensemble. 2192 * Each has a configuration line for a server to be added (as would appear in a 2193 * configuration file), only for maj. quorums. NULL for non-incremental reconfiguration. 2194 * \param leaving - comma separated list of server IDs to be removed from the ensemble. 2195 * Each has an id of a server to be removed, only for maj. quorums. NULL for 2196 * non-incremental reconfiguration. 2197 * \param members - comma separated list of new membership (e.g., contents of a 2198 * membership configuration file) - for use only with a non-incremental 2199 * reconfiguration. NULL for incremental reconfiguration. 2200 * \param version - zxid of config from which we want to reconfigure - if 2201 * current config is different reconfiguration will fail. Should be -1 to 2202 * disable this option. 2203 * \param buffer the buffer holding the configuration data returned by the server 2204 * \param buffer_len is the size of the buffer pointed to by the buffer parameter. 2205 * It'll be set to the actual data length upon return. If the data is NULL, length 2206 * is -1. 2207 * \param stat if not NULL, will hold the value of stat for the path on return. 2208 * \return return value of the function call. 2209 * ZOK operation completed successfully 2210 * ZBADARGUMENTS - invalid input parameters (one case when this is returned is 2211 * when the new config has less than 2 servers) 2212 * ZINVALIDSTATE - zhandle state is either in ZOO_SESSION_EXPIRED_STATE or 2213 * ZOO_AUTH_FAILED_STATE 2214 * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory 2215 * ZNEWCONFIGNOQUORUM - no quorum of new config is connected and up-to-date with 2216 * the leader of last committed config - try invoking reconfiguration after new 2217 * servers are connected and synced 2218 * ZRECONFIGINPROGRESS - another reconfig is currently in progress 2219 */ 2220 ZOOAPI int zoo_reconfig(zhandle_t *zh, const char *joining, const char *leaving, 2221 const char *members, int64_t version, char *buffer, int* buffer_len, 2222 struct Stat *stat); 2223 2224 /** 2225 * \brief sets the data associated with a node. See zoo_set2 function if 2226 * you require access to the stat information associated with the znode. 2227 * 2228 * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init 2229 * \param path the name of the node. Expressed as a file name with slashes 2230 * separating ancestors of the node. 2231 * \param buffer the buffer holding data to be written to the node. 2232 * \param buflen the number of bytes from buffer to write. To set NULL as data 2233 * use buffer as NULL and buflen as -1. 2234 * \param version the expected version of the node. The function will fail if 2235 * the actual version of the node does not match the expected version. If -1 is 2236 * used the version check will not take place. 2237 * \return the return code for the function call. 2238 * ZOK operation completed successfully 2239 * ZNONODE the node does not exist. 2240 * ZNOAUTH the client does not have permission. 2241 * ZBADVERSION expected version does not match actual version. 2242 * ZBADARGUMENTS - invalid input parameters 2243 * ZINVALIDSTATE - zhandle state is either ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE 2244 * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory 2245 */ 2246 ZOOAPI int zoo_set(zhandle_t *zh, const char *path, const char *buffer, 2247 int buflen, int version); 2248 2249 /** 2250 * \brief sets the data associated with a node. This function is the same 2251 * as zoo_set except that it also provides access to stat information 2252 * associated with the znode. 2253 * 2254 * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init 2255 * \param path the name of the node. Expressed as a file name with slashes 2256 * separating ancestors of the node. 2257 * \param buffer the buffer holding data to be written to the node. 2258 * \param buflen the number of bytes from buffer to write. To set NULL as data 2259 * use buffer as NULL and buflen as -1. 2260 * \param version the expected version of the node. The function will fail if 2261 * the actual version of the node does not match the expected version. If -1 is 2262 * used the version check will not take place. 2263 * \param stat if not NULL, will hold the value of stat for the path on return. 2264 * \return the return code for the function call. 2265 * ZOK operation completed successfully 2266 * ZNONODE the node does not exist. 2267 * ZNOAUTH the client does not have permission. 2268 * ZBADVERSION expected version does not match actual version. 2269 * ZBADARGUMENTS - invalid input parameters 2270 * ZINVALIDSTATE - zhandle state is either ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE 2271 * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory 2272 */ 2273 ZOOAPI int zoo_set2(zhandle_t *zh, const char *path, const char *buffer, 2274 int buflen, int version, struct Stat *stat); 2275 2276 /** 2277 * \brief lists the children of a node synchronously. 2278 * 2279 * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init 2280 * \param path the name of the node. Expressed as a file name with slashes 2281 * separating ancestors of the node. 2282 * \param watch if nonzero, a watch will be set at the server to notify 2283 * the client if the node changes. 2284 * \param strings return value of children paths. 2285 * \return the return code of the function. 2286 * ZOK operation completed successfully 2287 * ZNONODE the node does not exist. 2288 * ZNOAUTH the client does not have permission. 2289 * ZBADARGUMENTS - invalid input parameters 2290 * ZINVALIDSTATE - zhandle state is either ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE 2291 * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory 2292 */ 2293 ZOOAPI int zoo_get_children(zhandle_t *zh, const char *path, int watch, 2294 struct String_vector *strings); 2295 2296 /** 2297 * \brief lists the children of a node synchronously. 2298 * 2299 * This function is similar to \ref zoo_get_children except it allows one specify 2300 * a watcher object rather than a boolean watch flag. 2301 * 2302 * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init 2303 * \param path the name of the node. Expressed as a file name with slashes 2304 * separating ancestors of the node. 2305 * \param watcher if non-null, a watch will be set at the server to notify 2306 * the client if the node changes. 2307 * \param watcherCtx user specific data, will be passed to the watcher callback. 2308 * Unlike the global context set by \ref zookeeper_init, this watcher context 2309 * is associated with the given instance of the watcher only. 2310 * \param strings return value of children paths. 2311 * \return the return code of the function. 2312 * ZOK operation completed successfully 2313 * ZNONODE the node does not exist. 2314 * ZNOAUTH the client does not have permission. 2315 * ZBADARGUMENTS - invalid input parameters 2316 * ZINVALIDSTATE - zhandle state is either ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE 2317 * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory 2318 */ 2319 ZOOAPI int zoo_wget_children(zhandle_t *zh, const char *path, 2320 watcher_fn watcher, void* watcherCtx, 2321 struct String_vector *strings); 2322 2323 /** 2324 * \brief lists the children of a node and get its stat synchronously. 2325 * 2326 * This function is new in version 3.3.0 2327 * 2328 * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init 2329 * \param path the name of the node. Expressed as a file name with slashes 2330 * separating ancestors of the node. 2331 * \param watch if nonzero, a watch will be set at the server to notify 2332 * the client if the node changes. 2333 * \param strings return value of children paths. 2334 * \param stat return value of node stat. 2335 * \return the return code of the function. 2336 * ZOK operation completed successfully 2337 * ZNONODE the node does not exist. 2338 * ZNOAUTH the client does not have permission. 2339 * ZBADARGUMENTS - invalid input parameters 2340 * ZINVALIDSTATE - zhandle state is either ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE 2341 * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory 2342 */ 2343 ZOOAPI int zoo_get_children2(zhandle_t *zh, const char *path, int watch, 2344 struct String_vector *strings, struct Stat *stat); 2345 2346 /** 2347 * \brief lists the children of a node and get its stat synchronously. 2348 * 2349 * This function is similar to \ref zoo_get_children except it allows one specify 2350 * a watcher object rather than a boolean watch flag. 2351 * 2352 * This function is new in version 3.3.0 2353 * 2354 * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init 2355 * \param path the name of the node. Expressed as a file name with slashes 2356 * separating ancestors of the node. 2357 * \param watcher if non-null, a watch will be set at the server to notify 2358 * the client if the node changes. 2359 * \param watcherCtx user specific data, will be passed to the watcher callback. 2360 * Unlike the global context set by \ref zookeeper_init, this watcher context 2361 * is associated with the given instance of the watcher only. 2362 * \param strings return value of children paths. 2363 * \param stat return value of node stat. 2364 * \return the return code of the function. 2365 * ZOK operation completed successfully 2366 * ZNONODE the node does not exist. 2367 * ZNOAUTH the client does not have permission. 2368 * ZBADARGUMENTS - invalid input parameters 2369 * ZINVALIDSTATE - zhandle state is either ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE 2370 * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory 2371 */ 2372 ZOOAPI int zoo_wget_children2(zhandle_t *zh, const char *path, 2373 watcher_fn watcher, void* watcherCtx, 2374 struct String_vector *strings, struct Stat *stat); 2375 2376 /** 2377 * \brief gets the acl associated with a node synchronously. 2378 * 2379 * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init 2380 * \param path the name of the node. Expressed as a file name with slashes 2381 * separating ancestors of the node. 2382 * \param acl the return value of acls on the path. 2383 * \param stat returns the stat of the path specified. 2384 * \return the return code for the function call. 2385 * ZOK operation completed successfully 2386 * ZNONODE the node does not exist. 2387 * ZNOAUTH the client does not have permission. 2388 * ZBADARGUMENTS - invalid input parameters 2389 * ZINVALIDSTATE - zhandle state is either ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE 2390 * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory 2391 */ 2392 ZOOAPI int zoo_get_acl(zhandle_t *zh, const char *path, struct ACL_vector *acl, 2393 struct Stat *stat); 2394 2395 /** 2396 * \brief sets the acl associated with a node synchronously. 2397 * 2398 * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init 2399 * \param path the name of the node. Expressed as a file name with slashes 2400 * separating ancestors of the node. 2401 * \param version the expected version of the path. 2402 * \param acl the acl to be set on the path. 2403 * \return the return code for the function call. 2404 * ZOK operation completed successfully 2405 * ZNONODE the node does not exist. 2406 * ZNOAUTH the client does not have permission. 2407 * ZINVALIDACL invalid ACL specified 2408 * ZBADVERSION expected version does not match actual version. 2409 * ZBADARGUMENTS - invalid input parameters 2410 * ZINVALIDSTATE - zhandle state is either ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE 2411 * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory 2412 */ 2413 ZOOAPI int zoo_set_acl(zhandle_t *zh, const char *path, int version, 2414 const struct ACL_vector *acl); 2415 2416 /** 2417 * \brief atomically commits multiple zookeeper operations synchronously. 2418 * 2419 * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init 2420 * \param count the number of operations 2421 * \param ops an array of operations to commit 2422 * \param results an array to hold the results of the operations 2423 * \return the return code for the function call. This can be any of the 2424 * values that can be returned by the ops supported by a multi op (see 2425 * \ref zoo_acreate, \ref zoo_adelete, \ref zoo_aset). 2426 */ 2427 ZOOAPI int zoo_multi(zhandle_t *zh, int count, const zoo_op_t *ops, zoo_op_result_t *results); 2428 2429 /** 2430 * \brief removes the watches for the given path and watcher type. 2431 * 2432 * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init 2433 * \param path the path for which watches will be removed 2434 * \param wtype the watcher type to be removed 2435 * \param watcher the watcher to be removed, if null all watches for that 2436 * path (and watcher type) will be removed 2437 * \param watcherCtx the contex associated with the watcher to be removed 2438 * \param local whether the watches will be removed locally even if there is 2439 * no server connection 2440 * \return the return code for the function call. 2441 * ZOK - operation completed successfully 2442 * ZNOWATCHER - the watcher couldn't be found. 2443 * ZINVALIDSTATE - if !local, zhandle state is either ZOO_SESSION_EXPIRED_STATE 2444 * or ZOO_AUTH_FAILED_STATE 2445 * ZBADARGUMENTS - invalid input parameters 2446 * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory 2447 * ZSYSTEMERROR - a system error occured 2448 */ 2449 ZOOAPI int zoo_remove_watches(zhandle_t *zh, const char *path, 2450 ZooWatcherType wtype, watcher_fn watcher, void *watcherCtx, int local); 2451 #endif 2452 #ifdef __cplusplus 2453 } 2454 #endif 2455 2456 #endif /*ZOOKEEPER_H_*/ 2457