include/zookeeper/zookeeper.h

   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 <sys/time.h>
  23 #include <stdio.h>
  24
  25 #include "zookeeper_version.h"
  26 #include "recordio.h"
  27 #include "zookeeper.jute.h"
  28
  29 /**
  30  * \file zookeeper.h
  31  * \brief ZooKeeper functions and definitions.
  32  *
  33  * ZooKeeper is a network service that may be backed by a cluster of
  34  * synchronized servers. The data in the service is represented as a tree
  35  * of data nodes. Each node has data, children, an ACL, and status information.
  36  * The data for a node is read and write in its entirety.
  37  *
  38  * ZooKeeper clients can leave watches when they queries the data or children
  39  * of a node. If a watch is left, that client will be notified of the change.
  40  * The notification is a one time trigger. Subsequent chances to the node will
  41  * not trigger a notification unless the client issues a querity with the watch
  42  * flag set. If the client is ever disconnected from the service, even if the
  43  * disconnection is temporary, the watches of the client will be removed from
  44  * the service, so a client must treat a disconnect notification as an implicit
  45  * trigger of all outstanding watches.
  46  *
  47  * When a node is created, it may be flagged as an ephemeral node. Ephemeral
  48  * nodes are automatically removed when a client session is closed or when
  49  * a session times out due to inactivity (the ZooKeeper runtime fills in
  50  * periods of inactivity with pings). Ephemeral nodes cannot have children.
  51  *
  52  * ZooKeeper clients are identified by a server assigned session id. For
  53  * security reasons The server
  54  * also generates a corresponding password for a session. A client may save its
  55  * id and corresponding password to persistent storage in order to use the
  56  * session across program invocation boundaries.
  57  */
  58
  59 /* Support for building on various platforms */
  60
  61 // on cygwin we should take care of exporting/importing symbols properly
  62 #ifdef DLL_EXPORT
  63 #    define ZOOAPI __declspec(dllexport)
  64 #else
  65 #  if defined(__CYGWIN__) && !defined(USE_STATIC_LIB)
  66 #    define ZOOAPI __declspec(dllimport)
  67 #  else
  68 #    define ZOOAPI
  69 #  endif
  70 #endif
  71
  72 /** zookeeper return constants **/
  73
  74 enum ZOO_ERRORS {
  75   ZOK = 0, /*!< Everything is OK */
  76
  77   /** System and server-side errors.
  78    * This is never thrown by the server, it shouldn't be used other than
  79    * to indicate a range. Specifically error codes greater than this
  80    * value, but lesser than {@link #ZAPIERROR}, are system errors. */
  81   ZSYSTEMERROR = -1,
  82   ZRUNTIMEINCONSISTENCY = -2, /*!< A runtime inconsistency was found */
  83   ZDATAINCONSISTENCY = -3, /*!< A data inconsistency was found */
  84   ZCONNECTIONLOSS = -4, /*!< Connection to the server has been lost */
  85   ZMARSHALLINGERROR = -5, /*!< Error while marshalling or unmarshalling data */
  86   ZUNIMPLEMENTED = -6, /*!< Operation is unimplemented */
  87   ZOPERATIONTIMEOUT = -7, /*!< Operation timeout */
  88   ZBADARGUMENTS = -8, /*!< Invalid arguments */
  89   ZINVALIDSTATE = -9, /*!< Invliad zhandle state */
  90
  91   /** API errors.
  92    * This is never thrown by the server, it shouldn't be used other than
  93    * to indicate a range. Specifically error codes greater than this
  94    * value are API errors (while values less than this indicate a
  95    * {@link #ZSYSTEMERROR}).
  96    */
  97   ZAPIERROR = -100,
  98   ZNONODE = -101, /*!< Node does not exist */
  99   ZNOAUTH = -102, /*!< Not authenticated */
 100   ZBADVERSION = -103, /*!< Version conflict */
 101   ZNOCHILDRENFOREPHEMERALS = -108, /*!< Ephemeral nodes may not have children */
 102   ZNODEEXISTS = -110, /*!< The node already exists */
 103   ZNOTEMPTY = -111, /*!< The node has children */
 104   ZSESSIONEXPIRED = -112, /*!< The session has been expired by the server */
 105   ZINVALIDCALLBACK = -113, /*!< Invalid callback specified */
 106   ZINVALIDACL = -114, /*!< Invalid ACL specified */
 107   ZAUTHFAILED = -115, /*!< Client authentication failed */
 108   ZCLOSING = -116, /*!< ZooKeeper is closing */
 109   ZNOTHING = -117, /*!< (not error) no server responses to process */
 110   ZSESSIONMOVED = -118 /*!<session moved to another server, so operation is ignored */
 111 };
 112
 113 #ifdef __cplusplus
 114 extern "C" {
 115 #endif
 116
 117 /**
 118 *  @name Debug levels
 119 */
 120 typedef enum {ZOO_LOG_LEVEL_ERROR=1,ZOO_LOG_LEVEL_WARN=2,ZOO_LOG_LEVEL_INFO=3,ZOO_LOG_LEVEL_DEBUG=4} ZooLogLevel;
 121
 122 /**
 123  * @name ACL Consts
 124  */
 125 extern ZOOAPI const int ZOO_PERM_READ;
 126 extern ZOOAPI const int ZOO_PERM_WRITE;
 127 extern ZOOAPI const int ZOO_PERM_CREATE;
 128 extern ZOOAPI const int ZOO_PERM_DELETE;
 129 extern ZOOAPI const int ZOO_PERM_ADMIN;
 130 extern ZOOAPI const int ZOO_PERM_ALL;
 131
 132 /** This Id represents anyone. */
 133 extern ZOOAPI struct Id ZOO_ANYONE_ID_UNSAFE;
 134 /** This Id is only usable to set ACLs. It will get substituted with the
 135  * Id's the client authenticated with.
 136  */
 137 extern ZOOAPI struct Id ZOO_AUTH_IDS;
 138
 139 /** This is a completely open ACL*/
 140 extern ZOOAPI struct ACL_vector ZOO_OPEN_ACL_UNSAFE;
 141 /** This ACL gives the world the ability to read. */
 142 extern ZOOAPI struct ACL_vector ZOO_READ_ACL_UNSAFE;
 143 /** This ACL gives the creators authentication id's all permissions. */
 144 extern ZOOAPI struct ACL_vector ZOO_CREATOR_ALL_ACL;
 145
 146 /**
 147  * @name Interest Consts
 148  * These constants are used to express interest in an event and to
 149  * indicate to zookeeper which events have occurred. They can
 150  * be ORed together to express multiple interests. These flags are
 151  * used in the interest and event parameters of
 152  * \ref zookeeper_interest and \ref zookeeper_process.
 153  */
 154 // @{
 155 extern ZOOAPI const int ZOOKEEPER_WRITE;
 156 extern ZOOAPI const int ZOOKEEPER_READ;
 157 // @}
 158
 159 /**
 160  * @name Create Flags
 161  *
 162  * These flags are used by zoo_create to affect node create. They may
 163  * be ORed together to combine effects.
 164  */
 165 // @{
 166 extern ZOOAPI const int ZOO_EPHEMERAL;
 167 extern ZOOAPI const int ZOO_SEQUENCE;
 168 // @}
 169
 170 /**
 171  * @name State Consts
 172  * These constants represent the states of a zookeeper connection. They are
 173  * possible parameters of the watcher callback.
 174  */
 175 // @{
 176 extern ZOOAPI const int ZOO_EXPIRED_SESSION_STATE;
 177 extern ZOOAPI const int ZOO_AUTH_FAILED_STATE;
 178 extern ZOOAPI const int ZOO_CONNECTING_STATE;
 179 extern ZOOAPI const int ZOO_ASSOCIATING_STATE;
 180 extern ZOOAPI const int ZOO_CONNECTED_STATE;
 181 // @}
 182
 183 /**
 184  * @name Watch Types
 185  * These constants indicate the event that caused the watch event. They are
 186  * possible values of the first parameter of the watcher callback.
 187  */
 188 // @{
 189 /**
 190  * \brief a node has been created.
 191  *
 192  * This is only generated by watches on non-existent nodes. These watches
 193  * are set using \ref zoo_exists.
 194  */
 195 extern ZOOAPI const int ZOO_CREATED_EVENT;
 196 /**
 197  * \brief a node has been deleted.
 198  *
 199  * This is only generated by watches on nodes. These watches
 200  * are set using \ref zoo_exists and \ref zoo_get.
 201  */
 202 extern ZOOAPI const int ZOO_DELETED_EVENT;
 203 /**
 204  * \brief a node has changed.
 205  *
 206  * This is only generated by watches on nodes. These watches
 207  * are set using \ref zoo_exists and \ref zoo_get.
 208  */
 209 extern ZOOAPI const int ZOO_CHANGED_EVENT;
 210 /**
 211  * \brief a change as occurred in the list of children.
 212  *
 213  * This is only generated by watches on the child list of a node. These watches
 214  * are set using \ref zoo_get_children.
 215  */
 216 extern ZOOAPI const int ZOO_CHILD_EVENT;
 217 /**
 218  * \brief a session has been lost.
 219  *
 220  * This is generated when a client loses contact or reconnects with a server.
 221  */
 222 extern ZOOAPI const int ZOO_SESSION_EVENT;
 223
 224 /**
 225  * \brief a watch has been removed.
 226  *
 227  * This is generated when the server for some reason, probably a resource
 228  * constraint, will no longer watch a node for a client.
 229  */
 230 extern ZOOAPI const int ZOO_NOTWATCHING_EVENT;
 231 // @}
 232
 233 /**
 234  * \brief ZooKeeper handle.
 235  *
 236  * This is the handle that represents a connection to the ZooKeeper service.
 237  * It is needed to invoke any ZooKeeper function. A handle is obtained using
 238  * \ref zookeeper_init.
 239  */
 240 typedef struct _zhandle zhandle_t;
 241
 242 /**
 243  * \brief client id structure.
 244  *
 245  * This structure holds the id and password for the session. This structure
 246  * should be treated as opaque. It is received from the server when a session
 247  * is established and needs to be sent back as-is when reconnecting a session.
 248  */
 249 typedef struct {
 250     int64_t client_id;
 251     char passwd[16];
 252 } clientid_t;
 253
 254 /**
 255  * \brief signature of a watch function.
 256  *
 257  * There are two ways to receive watch notifications: legacy and watcher object.
 258  * <p>
 259  * The legacy style, an application wishing to receive events from ZooKeeper must
 260  * first implement a function with this signature and pass a pointer to the function
 261  * to \ref zookeeper_init. Next, the application sets a watch by calling one of
 262  * the getter API that accept the watch integer flag (for example, \ref zoo_aexists,
 263  * \ref zoo_get, etc).
 264  * <p>
 265  * The watcher object style uses an instance of a "watcher object" which in
 266  * the C world is represented by a pair: a pointer to a function implementing this
 267  * signature and a pointer to watcher context -- handback user-specific data.
 268  * When a watch is triggered this function will be called along with
 269  * the watcher context. An application wishing to use this style must use
 270  * the getter API functions with the "w" prefix in their names (for example, \ref
 271  * zoo_awexists, \ref zoo_wget, etc).
 272  *
 273  * \param zh zookeeper handle
 274  * \param type event type. This is one of the *_EVENT constants.
 275  * \param state connection state. The state value will be one of the *_STATE constants.
 276  * \param path znode path for which the watcher is triggered. NULL if the event
 277  * type is ZOO_SESSION_EVENT
 278  * \param watcherCtx watcher context.
 279  */
 280 typedef void (*watcher_fn)(zhandle_t *zh, int type,
 281         int state, const char *path,void *watcherCtx);
 282
 283 /**
 284  * \brief create a handle to used communicate with zookeeper.
 285  *
 286  * This method creates a new handle and a zookeeper session that corresponds
 287  * to that handle. Session establishment is asynchronous, meaning that the
 288  * session should not be considered established until (and unless) an
 289  * event of state ZOO_CONNECTED_STATE is received.
 290  * \param host comma separated host:port pairs, each corresponding to a zk
 291  *   server. e.g. "127.0.0.1:3000,127.0.0.1:3001,127.0.0.1:3002"
 292  * \param fn the global watcher callback function. When notifications are
 293  *   triggered this function will be invoked.
 294  * \param clientid the id of a previously established session that this
 295  *   client will be reconnecting to. Pass 0 if not reconnecting to a previous
 296  *   session. Clients can access the session id of an established, valid,
 297  *   connection by calling \ref zoo_client_id. If the session corresponding to
 298  *   the specified clientid has expired, or if the clientid is invalid for
 299  *   any reason, the returned zhandle_t will be invalid -- the zhandle_t
 300  *   state will indicate the reason for failure (typically
 301  *   ZOO_EXPIRED_SESSION_STATE).
 302  * \param context the handback object that will be associated with this instance
 303  *   of zhandle_t. Application can access it (for example, in the watcher
 304  *   callback) using \ref zoo_get_context. The object is not used by zookeeper
 305  *   internally and can be null.
 306  * \param flags reserved for future use. Should be set to zero.
 307  * \return a pointer to the opaque zhandle structure. If it fails to create
 308  * a new zhandle the function returns NULL and the errno variable
 309  * indicates the reason.
 310  */
 311 ZOOAPI zhandle_t *zookeeper_init(const char *host, watcher_fn fn,
 312   int recv_timeout, const clientid_t *clientid, void *context, int flags);
 313
 314 /**
 315  * \brief close the zookeeper handle and free up any resources.
 316  *
 317  * After this call, the client session will no longer be valid. The function
 318  * will flush any outstanding send requests before return. As a result it may
 319  * block.
 320  *
 321  * This method should only be called only once on a zookeeper handle. Calling
 322  * twice will cause undefined (and probably undesirable behavior). Calling any other
 323  * zookeeper method after calling close is undefined behaviour and should be avoided.
 324  *
 325  * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init
 326  * \return a result code. Regardless of the error code returned, the zhandle
 327  * will be destroyed and all resources freed.
 328  *
 329  * ZOK - success
 330  * ZBADARGUMENTS - invalid input parameters
 331  * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory
 332  * ZOPERATIONTIMEOUT - failed to flush the buffers within the specified timeout.
 333  * ZCONNECTIONLOSS - a network error occured while attempting to send request to server
 334  * ZSYSTEMERROR -- a system (OS) error occured; it's worth checking errno to get details
 335  */
 336 ZOOAPI int zookeeper_close(zhandle_t *zh);
 337
 338 /**
 339  * \brief return the client session id, only valid if the connections
 340  * is currently connected (ie. last watcher state is ZOO_CONNECTED_STATE)
 341  */
 342 ZOOAPI const clientid_t *zoo_client_id(zhandle_t *zh);
 343
 344 ZOOAPI int zoo_recv_timeout(zhandle_t *zh);
 345
 346 ZOOAPI const void *zoo_get_context(zhandle_t *zh);
 347
 348 ZOOAPI void zoo_set_context(zhandle_t *zh, void *context);
 349
 350 /**
 351  * \brief set a watcher function
 352  * \return previous watcher function
 353  */
 354 ZOOAPI watcher_fn zoo_set_watcher(zhandle_t *zh,watcher_fn newFn);
 355
 356 #ifndef THREADED
 357 /**
 358  * \brief Returns the events that zookeeper is interested in.
 359  *
 360  * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init
 361  * \param fd is the file descriptor of interest
 362  * \param interest is an or of the ZOOKEEPER_WRITE and ZOOKEEPER_READ flags to
 363  *    indicate the I/O of interest on fd.
 364  * \param tv a timeout value to be used with select/poll system call
 365  * \return a result code.
 366  * ZOK - success
 367  * ZBADARGUMENTS - invalid input parameters
 368  * ZINVALIDSTATE - zhandle state is either ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE
 369  * ZCONNECTIONLOSS - a network error occured while attempting to establish
 370  * a connection to the server
 371  * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory
 372  * ZOPERATIONTIMEOUT - hasn't received anything from the server for 2/3 of the
 373  * timeout value specified in zookeeper_init()
 374  * ZSYSTEMERROR -- a system (OS) error occured; it's worth checking errno to get details
 375  */
 376 ZOOAPI int zookeeper_interest(zhandle_t *zh, int *fd, int *interest,
 377         struct timeval *tv);
 378
 379 /**
 380  * \brief Notifies zookeeper that an event of interest has happened.
 381  *
 382  * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init
 383  * \param events will be an OR of the ZOOKEEPER_WRITE and ZOOKEEPER_READ flags.
 384  * \return a result code.
 385  * ZOK - success
 386  * ZBADARGUMENTS - invalid input parameters
 387  * ZINVALIDSTATE - zhandle state is either ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE
 388  * ZCONNECTIONLOSS - a network error occured while attempting to send request to server
 389  * ZSESSIONEXPIRED - connection attempt failed -- the session's expired
 390  * ZAUTHFAILED - authentication request failed, e.i. invalid credentials
 391  * ZRUNTIMEINCONSISTENCY - a server response came out of order
 392  * ZSYSTEMERROR -- a system (OS) error occured; it's worth checking errno to get details
 393  * ZNOTHING -- not an error; simply indicates that there no more data from the server
 394  *              to be processed (when called with ZOOKEEPER_READ flag).
 395  */
 396 ZOOAPI int zookeeper_process(zhandle_t *zh, int events);
 397 #endif
 398
 399 /**
 400  * \brief signature of a completion function for a call that returns void.
 401  *
 402  * This method will be invoked at the end of a asynchronous call and also as
 403  * a result of connection loss or timeout.
 404  * \param rc the error code of the call. Connection loss/timeout triggers
 405  * the completion with one of the following error codes:
 406  * ZCONNECTIONLOSS -- lost connection to the server
 407  * ZOPERATIONTIMEOUT -- connection timed out
 408  * Data related events trigger the completion with error codes listed the
 409  * Exceptions section of the documentation of the function that initiated the
 410  * call. (Zero indicates call was successful.)
 411  * \param data the pointer that was passed by the caller when the function
 412  *   that this completion corresponds to was invoked. The programmer
 413  *   is responsible for any memory freeing associated with the data
 414  *   pointer.
 415  */
 416 typedef void (*void_completion_t)(int rc, const void *data);
 417
 418 /**
 419  * \brief signature of a completion function that returns a Stat structure.
 420  *
 421  * This method will be invoked at the end of a asynchronous call and also as
 422  * a result of connection loss or timeout.
 423  * \param rc the error code of the call. Connection loss/timeout triggers
 424  * the completion with one of the following error codes:
 425  * ZCONNECTIONLOSS -- lost connection to the server
 426  * ZOPERATIONTIMEOUT -- connection timed out
 427  * Data related events trigger the completion with error codes listed the
 428  * Exceptions section of the documentation of the function that initiated the
 429  * call. (Zero indicates call was successful.)
 430  * \param stat a pointer to the stat information for the node involved in
 431  *   this function. If a non zero error code is returned, the content of
 432  *   stat is undefined. The programmer is NOT responsible for freeing stat.
 433  * \param data the pointer that was passed by the caller when the function
 434  *   that this completion corresponds to was invoked. The programmer
 435  *   is responsible for any memory freeing associated with the data
 436  *   pointer.
 437  */
 438 typedef void (*stat_completion_t)(int rc, const struct Stat *stat,
 439         const void *data);
 440
 441 /**
 442  * \brief signature of a completion function that returns data.
 443  *
 444  * This method will be invoked at the end of a asynchronous call and also as
 445  * a result of connection loss or timeout.
 446  * \param rc the error code of the call. Connection loss/timeout triggers
 447  * the completion with one of the following error codes:
 448  * ZCONNECTIONLOSS -- lost connection to the server
 449  * ZOPERATIONTIMEOUT -- connection timed out
 450  * Data related events trigger the completion with error codes listed the
 451  * Exceptions section of the documentation of the function that initiated the
 452  * call. (Zero indicates call was successful.)
 453  * \param value the value of the information returned by the asynchronous call.
 454  *   If a non zero error code is returned, the content of value is undefined.
 455  *   The programmer is NOT responsible for freeing value.
 456  * \param value_len the number of bytes in value.
 457  * \param stat a pointer to the stat information for the node involved in
 458  *   this function. If a non zero error code is returned, the content of
 459  *   stat is undefined. The programmer is NOT responsible for freeing stat.
 460  * \param data the pointer that was passed by the caller when the function
 461  *   that this completion corresponds to was invoked. The programmer
 462  *   is responsible for any memory freeing associated with the data
 463  *   pointer.
 464  */
 465 typedef void (*data_completion_t)(int rc, const char *value, int value_len,
 466         const struct Stat *stat, const void *data);
 467
 468 /**
 469  * \brief signature of a completion function that returns a list of strings.
 470  *
 471  * This method will be invoked at the end of a asynchronous call and also as
 472  * a result of connection loss or timeout.
 473  * \param rc the error code of the call. Connection loss/timeout triggers
 474  * the completion with one of the following error codes:
 475  * ZCONNECTIONLOSS -- lost connection to the server
 476  * ZOPERATIONTIMEOUT -- connection timed out
 477  * Data related events trigger the completion with error codes listed the
 478  * Exceptions section of the documentation of the function that initiated the
 479  * call. (Zero indicates call was successful.)
 480  * \param strings a pointer to the structure containng the list of strings of the
 481  *   names of the children of a node. If a non zero error code is returned,
 482  *   the content of strings is undefined. The programmer is NOT responsible
 483  *   for freeing strings.
 484  * \param data the pointer that was passed by the caller when the function
 485  *   that this completion corresponds to was invoked. The programmer
 486  *   is responsible for any memory freeing associated with the data
 487  *   pointer.
 488  */
 489 typedef void (*strings_completion_t)(int rc,
 490         const struct String_vector *strings, const void *data);
 491
 492 /**
 493  * \brief signature of a completion function that returns a list of strings.
 494  *
 495  * This method will be invoked at the end of a asynchronous call and also as
 496  * a result of connection loss or timeout.
 497  * \param rc the error code of the call. Connection loss/timeout triggers
 498  * the completion with one of the following error codes:
 499  * ZCONNECTIONLOSS -- lost connection to the server
 500  * ZOPERATIONTIMEOUT -- connection timed out
 501  * Data related events trigger the completion with error codes listed the
 502  * Exceptions section of the documentation of the function that initiated the
 503  * call. (Zero indicates call was successful.)
 504  * \param value the value of the string returned.
 505  * \param data the pointer that was passed by the caller when the function
 506  *   that this completion corresponds to was invoked. The programmer
 507  *   is responsible for any memory freeing associated with the data
 508  *   pointer.
 509  */
 510 typedef void
 511         (*string_completion_t)(int rc, const char *value, const void *data);
 512
 513 /**
 514  * \brief signature of a completion function that returns an ACL.
 515  *
 516  * This method will be invoked at the end of a asynchronous call and also as
 517  * a result of connection loss or timeout.
 518  * \param rc the error code of the call. Connection loss/timeout triggers
 519  * the completion with one of the following error codes:
 520  * ZCONNECTIONLOSS -- lost connection to the server
 521  * ZOPERATIONTIMEOUT -- connection timed out
 522  * Data related events trigger the completion with error codes listed the
 523  * Exceptions section of the documentation of the function that initiated the
 524  * call. (Zero indicates call was successful.)
 525  * \param acl a pointer to the structure containng the ACL of a node. If a non
 526  *   zero error code is returned, the content of strings is undefined. The
 527  *   programmer is NOT responsible for freeing acl.
 528  * \param stat a pointer to the stat information for the node involved in
 529  *   this function. If a non zero error code is returned, the content of
 530  *   stat is undefined. The programmer is NOT responsible for freeing stat.
 531  * \param data the pointer that was passed by the caller when the function
 532  *   that this completion corresponds to was invoked. The programmer
 533  *   is responsible for any memory freeing associated with the data
 534  *   pointer.
 535  */
 536 typedef void (*acl_completion_t)(int rc, struct ACL_vector *acl,
 537         struct Stat *stat, const void *data);
 538
 539 /**
 540  * \brief get the state of the zookeeper connection.
 541  *
 542  * The return value will be one of the \ref State Consts.
 543  */
 544 ZOOAPI int zoo_state(zhandle_t *zh);
 545
 546 /**
 547  * \brief create a node.
 548  *
 549  * This method will create a node in ZooKeeper. A node can only be created if
 550  * it does not already exists. The Create Flags affect the creation of nodes.
 551  * If ZOO_EPHEMERAL flag is set, the node will automatically get removed if the
 552  * client session goes away. If the ZOO_SEQUENCE flag is set, a unique
 553  * monotonically increasing sequence number is appended to the path name.
 554  *
 555  * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init
 556  * \param path The name of the node. Expressed as a file name with slashes
 557  * separating ancestors of the node.
 558  * \param value The data to be stored in the node.
 559  * \param valuelen The number of bytes in data.
 560  * \param acl The initial ACL of the node. If null, the ACL of the parent will be
 561  *    used.
 562  * \param flags this parameter can be set to 0 for normal create or an OR
 563  *    of the Create Flags
 564  * \param completion the routine to invoke when the request completes. The completion
 565  * will be triggered with one of the following codes passed in as the rc argument:
 566  * ZOK operation completed succesfully
 567  * ZNONODE the parent node does not exist.
 568  * ZNODEEXISTS the node already exists
 569  * ZNOAUTH the client does not have permission.
 570  * ZNOCHILDRENFOREPHEMERALS cannot create children of ephemeral nodes.
 571  * \param data The data that will be passed to the completion routine when the
 572  * function completes.
 573  * \return ZOK on success or one of the following errcodes on failure:
 574  * ZBADARGUMENTS - invalid input parameters
 575  * ZINVALIDSTATE - zhandle state is either ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE
 576  * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory
 577  */
 578 ZOOAPI int zoo_acreate(zhandle_t *zh, const char *path, const char *value,
 579         int valuelen, const struct ACL_vector *acl, int flags,
 580         string_completion_t completion, const void *data);
 581
 582 /**
 583  * \brief delete a node in zookeeper.
 584  *
 585  * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init
 586  * \param path the name of the node. Expressed as a file name with slashes
 587  * separating ancestors of the node.
 588  * \param version the expected version of the node. The function will fail if the
 589  *    actual version of the node does not match the expected version.
 590  *  If -1 is used the version check will not take place.
 591  * \param completion the routine to invoke when the request completes. The completion
 592  * will be triggered with one of the following codes passed in as the rc argument:
 593  * ZOK operation completed succesfully
 594  * ZNONODE the node does not exist.
 595  * ZNOAUTH the client does not have permission.
 596  * ZBADVERSION expected version does not match actual version.
 597  * ZNOTEMPTY children are present; node cannot be deleted.
 598  * \param data the data that will be passed to the completion routine when
 599  * the function completes.
 600  * \return ZOK on success or one of the following errcodes on failure:
 601  * ZBADARGUMENTS - invalid input parameters
 602  * ZINVALIDSTATE - zhandle state is either ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE
 603  * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory
 604  */
 605 ZOOAPI int zoo_adelete(zhandle_t *zh, const char *path, int version,
 606         void_completion_t completion, const void *data);
 607
 608 /**
 609  * \brief checks the existence of a node in zookeeper.
 610  *
 611  * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init
 612  * \param path the name of the node. Expressed as a file name with slashes
 613  * separating ancestors of the node.
 614  * \param watch if nonzero, a watch will be set at the server to notify the
 615  * client if the node changes. The watch will be set even if the node does not
 616  * exist. This allows clients to watch for nodes to appear.
 617  * \param completion the routine to invoke when the request completes. The completion
 618  * will be triggered with one of the following codes passed in as the rc argument:
 619  * ZOK operation completed succesfully
 620  * ZNONODE the node does not exist.
 621  * ZNOAUTH the client does not have permission.
 622  * \param data the data that will be passed to the completion routine when the
 623  * function completes.
 624  * \return ZOK on success or one of the following errcodes on failure:
 625  * ZBADARGUMENTS - invalid input parameters
 626  * ZINVALIDSTATE - zhandle state is either ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE
 627  * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory
 628  */
 629 ZOOAPI int zoo_aexists(zhandle_t *zh, const char *path, int watch,
 630         stat_completion_t completion, const void *data);
 631
 632 /**
 633  * \brief checks the existence of a node in zookeeper.
 634  *
 635  * This function is similar to \ref zoo_axists except it allows one specify
 636  * a watcher object - a function pointer and associated context. The function
 637  * will be called once the watch has fired. The associated context data will be
 638  * passed to the function as the watcher context parameter.
 639  *
 640  * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init
 641  * \param path the name of the node. Expressed as a file name with slashes
 642  * separating ancestors of the node.
 643  * \param watcher if non-null a watch will set on the specified znode on the server.
 644  * The watch will be set even if the node does not exist. This allows clients
 645  * to watch for nodes to appear.
 646  * \param watcherCtx user specific data, will be passed to the watcher callback.
 647  * Unlike the global context set by \ref zookeeper_init, this watcher context
 648  * is associated with the given instance of the watcher only.
 649  * \param completion the routine to invoke when the request completes. The completion
 650  * will be triggered with one of the following codes passed in as the rc argument:
 651  * ZOK operation completed succesfully
 652  * ZNONODE the node does not exist.
 653  * ZNOAUTH the client does not have permission.
 654  * \param data the data that will be passed to the completion routine when the
 655  * function completes.
 656  * \return ZOK on success or one of the following errcodes on failure:
 657  * ZBADARGUMENTS - invalid input parameters
 658  * ZINVALIDSTATE - zhandle state is either ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE
 659  * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory
 660  */
 661 ZOOAPI int zoo_awexists(zhandle_t *zh, const char *path,
 662         watcher_fn watcher, void* watcherCtx,
 663         stat_completion_t completion, const void *data);
 664
 665 /**
 666  * \brief gets the data associated with a node.
 667  *
 668  * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init
 669  * \param path the name of the node. Expressed as a file name with slashes
 670  * separating ancestors of the node.
 671  * \param watch if nonzero, a watch will be set at the server to notify
 672  * the client if the node changes.
 673  * \param completion the routine to invoke when the request completes. The completion
 674  * will be triggered with one of the following codes passed in as the rc argument:
 675  * ZOK operation completed succesfully
 676  * ZNONODE the node does not exist.
 677  * ZNOAUTH the client does not have permission.
 678  * \param data the data that will be passed to the completion routine when
 679  * the function completes.
 680  * \return ZOK on success or one of the following errcodes on failure:
 681  * ZBADARGUMENTS - invalid input parameters
 682  * ZINVALIDSTATE - zhandle state is either in ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE
 683  * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory
 684  */
 685 ZOOAPI int zoo_aget(zhandle_t *zh, const char *path, int watch,
 686         data_completion_t completion, const void *data);
 687
 688 /**
 689  * \brief gets the data associated with a node.
 690  *
 691  * This function is similar to \ref zoo_aget except it allows one specify
 692  * a watcher object rather than a boolean watch flag.
 693  *
 694  * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init
 695  * \param path the name of the node. Expressed as a file name with slashes
 696  * separating ancestors of the node.
 697  * \param watcher if non-null, a watch will be set at the server to notify
 698  * the client if the node changes.
 699  * \param watcherCtx user specific data, will be passed to the watcher callback.
 700  * Unlike the global context set by \ref zookeeper_init, this watcher context
 701  * is associated with the given instance of the watcher only.
 702  * \param completion the routine to invoke when the request completes. The completion
 703  * will be triggered with one of the following codes passed in as the rc argument:
 704  * ZOK operation completed succesfully
 705  * ZNONODE the node does not exist.
 706  * ZNOAUTH the client does not have permission.
 707  * \param data the data that will be passed to the completion routine when
 708  * the function completes.
 709  * \return ZOK on success or one of the following errcodes on failure:
 710  * ZBADARGUMENTS - invalid input parameters
 711  * ZINVALIDSTATE - zhandle state is either in ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE
 712  * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory
 713  */
 714 ZOOAPI int zoo_awget(zhandle_t *zh, const char *path,
 715         watcher_fn watcher, void* watcherCtx,
 716         data_completion_t completion, const void *data);
 717
 718 /**
 719  * \brief sets the data associated with a node.
 720  *
 721  * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init
 722  * \param path the name of the node. Expressed as a file name with slashes
 723  * separating ancestors of the node.
 724  * \param buffer the buffer holding data to be written to the node.
 725  * \param buflen the number of bytes from buffer to write.
 726  * \param version the expected version of the node. The function will fail if
 727  * the actual version of the node does not match the expected version. If -1 is
 728  * used the version check will not take place. * completion: If null,
 729  * the function will execute synchronously. Otherwise, the function will return
 730  * immediately and invoke the completion routine when the request completes.
 731  * \param completion the routine to invoke when the request completes. The completion
 732  * will be triggered with one of the following codes passed in as the rc argument:
 733  * ZOK operation completed succesfully
 734  * ZNONODE the node does not exist.
 735  * ZNOAUTH the client does not have permission.
 736  * ZBADVERSION expected version does not match actual version.
 737  * \param data the data that will be passed to the completion routine when
 738  * the function completes.
 739  * \return ZOK on success or one of the following errcodes on failure:
 740  * ZBADARGUMENTS - invalid input parameters
 741  * ZINVALIDSTATE - zhandle state is either ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE
 742  * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory
 743  */
 744 ZOOAPI int zoo_aset(zhandle_t *zh, const char *path, const char *buffer, int buflen,
 745         int version, stat_completion_t completion, const void *data);
 746
 747 /**
 748  * \brief lists the children of a node.
 749  *
 750  * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init
 751  * \param path the name of the node. Expressed as a file name with slashes
 752  * separating ancestors of the node.
 753  * \param watch if nonzero, a watch will be set at the server to notify
 754  * the client if the node changes.
 755  * \param completion the routine to invoke when the request completes. The completion
 756  * will be triggered with one of the following codes passed in as the rc argument:
 757  * ZOK operation completed succesfully
 758  * ZNONODE the node does not exist.
 759  * ZNOAUTH the client does not have permission.
 760  * \param data the data that will be passed to the completion routine when
 761  * the function completes.
 762  * \return ZOK on success or one of the following errcodes on failure:
 763  * ZBADARGUMENTS - invalid input parameters
 764  * ZINVALIDSTATE - zhandle state is either ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE
 765  * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory
 766  */
 767 ZOOAPI int zoo_aget_children(zhandle_t *zh, const char *path, int watch,
 768         strings_completion_t completion, const void *data);
 769
 770 /**
 771  * \brief lists the children of a node.
 772  *
 773  * This function is similar to \ref zoo_aget_children except it allows one specify
 774  * a watcher object rather than a boolean watch flag.
 775  *
 776  * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init
 777  * \param path the name of the node. Expressed as a file name with slashes
 778  * separating ancestors of the node.
 779  * \param watcher if non-null, a watch will be set at the server to notify
 780  * the client if the node changes.
 781  * \param watcherCtx user specific data, will be passed to the watcher callback.
 782  * Unlike the global context set by \ref zookeeper_init, this watcher context
 783  * is associated with the given instance of the watcher only.
 784  * \param completion the routine to invoke when the request completes. The completion
 785  * will be triggered with one of the following codes passed in as the rc argument:
 786  * ZOK operation completed succesfully
 787  * ZNONODE the node does not exist.
 788  * ZNOAUTH the client does not have permission.
 789  * \param data the data that will be passed to the completion routine when
 790  * the function completes.
 791  * \return ZOK on success or one of the following errcodes on failure:
 792  * ZBADARGUMENTS - invalid input parameters
 793  * ZINVALIDSTATE - zhandle state is either ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE
 794  * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory
 795  */
 796 ZOOAPI int zoo_awget_children(zhandle_t *zh, const char *path,
 797         watcher_fn watcher, void* watcherCtx,
 798         strings_completion_t completion, const void *data);
 799
 800 /**
 801  * \brief Flush leader channel.
 802  *
 803  * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init
 804  * \param path the name of the node. Expressed as a file name with slashes
 805  * separating ancestors of the node.
 806  * \param completion the routine to invoke when the request completes. The completion
 807  * will be triggered with one of the following codes passed in as the rc argument:
 808  * ZOK operation completed succesfully
 809  * ZNONODE the node does not exist.
 810  * ZNOAUTH the client does not have permission.
 811  * \param data the data that will be passed to the completion routine when
 812  * the function completes.
 813  * \return ZOK on success or one of the following errcodes on failure:
 814  * ZBADARGUMENTS - invalid input parameters
 815  * ZINVALIDSTATE - zhandle state is either ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE
 816  * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory
 817  */
 818
 819 ZOOAPI int zoo_async(zhandle_t *zh, const char *path,
 820         string_completion_t completion, const void *data);
 821
 822
 823 /**
 824  * \brief gets the acl associated with a node.
 825  *
 826  * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init
 827  * \param path the name of the node. Expressed as a file name with slashes
 828  * separating ancestors of the node.
 829  * \param completion the routine to invoke when the request completes. The completion
 830  * will be triggered with one of the following codes passed in as the rc argument:
 831  * ZOK operation completed succesfully
 832  * ZNONODE the node does not exist.
 833  * ZNOAUTH the client does not have permission.
 834  * \param data the data that will be passed to the completion routine when
 835  * the function completes.
 836  * \return ZOK on success or one of the following errcodes on failure:
 837  * ZBADARGUMENTS - invalid input parameters
 838  * ZINVALIDSTATE - zhandle state is either ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE
 839  * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory
 840  */
 841 ZOOAPI int zoo_aget_acl(zhandle_t *zh, const char *path, acl_completion_t completion,
 842         const void *data);
 843
 844 /**
 845  * \brief sets the acl associated with a node.
 846  *
 847  * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init
 848  * \param path the name of the node. Expressed as a file name with slashes
 849  * separating ancestors of the node.
 850  * \param buffer the buffer holding the acls to be written to the node.
 851  * \param buflen the number of bytes from buffer to write.
 852  * \param completion the routine to invoke when the request completes. The completion
 853  * will be triggered with one of the following codes passed in as the rc argument:
 854  * ZOK operation completed succesfully
 855  * ZNONODE the node does not exist.
 856  * ZNOAUTH the client does not have permission.
 857  * ZINVALIDACL invalid ACL specified
 858  * ZBADVERSION expected version does not match actual version.
 859  * \param data the data that will be passed to the completion routine when
 860  * the function completes.
 861  * \return ZOK on success or one of the following errcodes on failure:
 862  * ZBADARGUMENTS - invalid input parameters
 863  * ZINVALIDSTATE - zhandle state is either ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE
 864  * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory
 865  */
 866 ZOOAPI int zoo_aset_acl(zhandle_t *zh, const char *path, int version,
 867         struct ACL_vector *acl, void_completion_t, const void *data);
 868
 869 /**
 870  * \brief return an error string.
 871  *
 872  * \param return code
 873  * \return string corresponding to the return code
 874  */
 875 ZOOAPI const char* zerror(int c);
 876
 877 /**
 878  * \brief specify application credentials.
 879  *
 880  * The application calls this function to specify its credentials for purposes
 881  * of authentication. The server will use the security provider specified by
 882  * the scheme parameter to authenticate the client connection. If the
 883  * authentication request has failed:
 884  * - the server connection is dropped
 885  * - the watcher is called with the ZOO_AUTH_FAILED_STATE value as the state
 886  * parameter.
 887  * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init
 888  * \param scheme the id of authentication scheme. Natively supported:
 889  * "digest" password-based authentication
 890  * \param cert application credentials. The actual value depends on the scheme.
 891  * \param certLen the length of the data parameter
 892  * \param completion the routine to invoke when the request completes. One of
 893  * the following result codes may be passed into the completion callback:
 894  * ZOK operation completed successfully
 895  * ZAUTHFAILED authentication failed
 896  * \param data the data that will be passed to the completion routine when the
 897  * function completes.
 898  * \return ZOK on success or one of the following errcodes on failure:
 899  * ZBADARGUMENTS - invalid input parameters
 900  * ZINVALIDSTATE - zhandle state is either ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE
 901  * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory
 902  * ZSYSTEMERROR - a system error occured
 903  */
 904 ZOOAPI int zoo_add_auth(zhandle_t *zh,const char* scheme,const char* cert,
 905         int certLen, void_completion_t completion, const void *data);
 906
 907 /**
 908  * \brief checks if the current zookeeper connection state can't be recovered.
 909  *
 910  *  The application must close the zhandle and try to reconnect.
 911  *
 912  * \param zh the zookeeper handle (see \ref zookeeper_init)
 913  * \return ZINVALIDSTATE if connection is unrecoverable
 914  */
 915 ZOOAPI int is_unrecoverable(zhandle_t *zh);
 916
 917 /**
 918  * \brief sets the debugging level for the library
 919  */
 920 ZOOAPI void zoo_set_debug_level(ZooLogLevel logLevel);
 921
 922 /**
 923  * \brief sets the stream to be used by the library for logging
 924  *
 925  * The zookeeper library uses stderr as its default log stream. Application
 926  * must make sure the stream is writable. Passing in NULL resets the stream
 927  * to its default value (stderr).
 928  */
 929 ZOOAPI void zoo_set_log_stream(FILE* logStream);
 930
 931 /**
 932  * \brief enable/disable quorum endpoint order randomization
 933  *
 934  * If passed a non-zero value, will make the client connect to quorum peers
 935  * in the order as specified in the zookeeper_init() call.
 936  * A zero value causes zookeeper_init() to permute the peer endpoints
 937  * which is good for more even client connection distribution among the
 938  * quorum peers.
 939  */
 940 ZOOAPI void zoo_deterministic_conn_order(int yesOrNo);
 941
 942 /**
 943  * \brief create a node synchronously.
 944  *
 945  * This method will create a node in ZooKeeper. A node can only be created if
 946  * it does not already exists. The Create Flags affect the creation of nodes.
 947  * If ZOO_EPHEMERAL flag is set, the node will automatically get removed if the
 948  * client session goes away. If the ZOO_SEQUENCE flag is set, a unique
 949  * monotonically increasing sequence number is appended to the path name.
 950  *
 951  * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init
 952  * \param path The name of the node. Expressed as a file name with slashes
 953  * separating ancestors of the node.
 954  * \param value The data to be stored in the node.
 955  * \param valuelen The number of bytes in data. To set the data to be NULL use
 956   * value as NULL and valuelen as -1.
 957  * \param acl The initial ACL of the node. If null, the ACL of the parent will be
 958  *    used.
 959  * \param flags this parameter can be set to 0 for normal create or an OR
 960  *    of the Create Flags
 961  * \param path_buffer Buffer which will be filled with the path of the
 962  *    new node (this might be different than the supplied path
 963  *    because of the ZOO_SEQUENCE flag).  The path string will always be
 964  *    null-terminated.
 965  * \param path_buffer_len Size of path buffer; if the path of the new
 966  *    node (including space for the null terminator) exceeds the buffer size,
 967  *    the path string will be truncated to fit.  The actual path of the
 968  *    new node in the server will not be affected by the truncation.
 969  *    The path string will always be null-terminated.
 970  * \return  one of the following codes are returned:
 971  * ZOK operation completed succesfully
 972  * ZNONODE the parent node does not exist.
 973  * ZNODEEXISTS the node already exists
 974  * ZNOAUTH the client does not have permission.
 975  * ZNOCHILDRENFOREPHEMERALS cannot create children of ephemeral nodes.
 976  * ZBADARGUMENTS - invalid input parameters
 977  * ZINVALIDSTATE - zhandle state is either ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE
 978  * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory
 979  */
 980 ZOOAPI int zoo_create(zhandle_t *zh, const char *path, const char *value,
 981         int valuelen, const struct ACL_vector *acl, int flags,
 982         char *path_buffer, int path_buffer_len);
 983
 984 /**
 985  * \brief delete a node in zookeeper synchronously.
 986  *
 987  * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init
 988  * \param path the name of the node. Expressed as a file name with slashes
 989  * separating ancestors of the node.
 990  * \param version the expected version of the node. The function will fail if the
 991  *    actual version of the node does not match the expected version.
 992  *  If -1 is used the version check will not take place.
 993  * \return one of the following values is returned.
 994  * ZOK operation completed succesfully
 995  * ZNONODE the node does not exist.
 996  * ZNOAUTH the client does not have permission.
 997  * ZBADVERSION expected version does not match actual version.
 998  * ZNOTEMPTY children are present; node cannot be deleted.
 999  * ZBADARGUMENTS - invalid input parameters
1000  * ZINVALIDSTATE - zhandle state is either ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE
1001  * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory
1002  */
1003 ZOOAPI int zoo_delete(zhandle_t *zh, const char *path, int version);
1004
1005
1006 /**
1007  * \brief checks the existence of a node in zookeeper synchronously.
1008  *
1009  * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init
1010  * \param path the name of the node. Expressed as a file name with slashes
1011  * separating ancestors of the node.
1012  * \param watch if nonzero, a watch will be set at the server to notify the
1013  * client if the node changes. The watch will be set even if the node does not
1014  * exist. This allows clients to watch for nodes to appear.
1015  * \param the return stat value of the node.
1016  * \return  return code of the function call.
1017  * ZOK operation completed succesfully
1018  * ZNONODE the node does not exist.
1019  * ZNOAUTH the client does not have permission.
1020  * ZBADARGUMENTS - invalid input parameters
1021  * ZINVALIDSTATE - zhandle state is either ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE
1022  * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory
1023  */
1024 ZOOAPI int zoo_exists(zhandle_t *zh, const char *path, int watch, struct Stat *stat);
1025
1026 /**
1027  * \brief checks the existence of a node in zookeeper synchronously.
1028  *
1029  * This function is similar to \ref zoo_exists except it allows one specify
1030  * a watcher object rather than a boolean watch flag.
1031  *
1032  * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init
1033  * \param path the name of the node. Expressed as a file name with slashes
1034  * separating ancestors of the node.
1035  * \param watcher if non-null a watch will set on the specified znode on the server.
1036  * The watch will be set even if the node does not exist. This allows clients
1037  * to watch for nodes to appear.
1038  * \param watcherCtx user specific data, will be passed to the watcher callback.
1039  * Unlike the global context set by \ref zookeeper_init, this watcher context
1040  * is associated with the given instance of the watcher only.
1041  * \param the return stat value of the node.
1042  * \return  return code of the function call.
1043  * ZOK operation completed succesfully
1044  * ZNONODE the node does not exist.
1045  * ZNOAUTH the client does not have permission.
1046  * ZBADARGUMENTS - invalid input parameters
1047  * ZINVALIDSTATE - zhandle state is either ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE
1048  * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory
1049  */
1050 ZOOAPI int zoo_wexists(zhandle_t *zh, const char *path,
1051         watcher_fn watcher, void* watcherCtx, struct Stat *stat);
1052
1053 /**
1054  * \brief gets the data associated with a node synchronously.
1055  *
1056  * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init
1057  * \param path the name of the node. Expressed as a file name with slashes
1058  * separating ancestors of the node.
1059  * \param watch if nonzero, a watch will be set at the server to notify
1060  * the client if the node changes.
1061  * \param buffer the buffer holding the node data returned by the server
1062  * \param buffer_len is the size of the buffer pointed to by the buffer parameter.
1063  * It'll be set to the actual data length upon return. If the data is NULL, length is -1.
1064  * \param stat if not NULL, will hold the value of stat for the path on return.
1065  * \return return value of the function call.
1066  * ZOK operation completed succesfully
1067  * ZNONODE the node does not exist.
1068  * ZNOAUTH the client does not have permission.
1069  * ZBADARGUMENTS - invalid input parameters
1070  * ZINVALIDSTATE - zhandle state is either in ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE
1071  * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory
1072  */
1073 ZOOAPI int zoo_get(zhandle_t *zh, const char *path, int watch, char *buffer,
1074                    int* buffer_len, struct Stat *stat);
1075
1076 /**
1077  * \brief gets the data associated with a node synchronously.
1078  *
1079  * This function is similar to \ref zoo_get except it allows one specify
1080  * a watcher object rather than a boolean watch flag.
1081  *
1082  * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init
1083  * \param path the name of the node. Expressed as a file name with slashes
1084  * separating ancestors of the node.
1085  * \param watcher if non-null, a watch will be set at the server to notify
1086  * the client if the node changes.
1087  * \param watcherCtx user specific data, will be passed to the watcher callback.
1088  * Unlike the global context set by \ref zookeeper_init, this watcher context
1089  * is associated with the given instance of the watcher only.
1090  * \param buffer the buffer holding the node data returned by the server
1091  * \param buffer_len is the size of the buffer pointed to by the buffer parameter.
1092  * It'll be set to the actual data length upon return. If the data is NULL, length is -1.
1093  * \param stat if not NULL, will hold the value of stat for the path on return.
1094  * \return return value of the function call.
1095  * ZOK operation completed succesfully
1096  * ZNONODE the node does not exist.
1097  * ZNOAUTH the client does not have permission.
1098  * ZBADARGUMENTS - invalid input parameters
1099  * ZINVALIDSTATE - zhandle state is either in ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE
1100  * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory
1101  */
1102 ZOOAPI int zoo_wget(zhandle_t *zh, const char *path,
1103         watcher_fn watcher, void* watcherCtx,
1104         char *buffer, int* buffer_len, struct Stat *stat);
1105
1106 /**
1107  * \brief sets the data associated with a node. See zoo_set2 function if
1108  * you require access to the stat information associated with the znode.
1109  *
1110  * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init
1111  * \param path the name of the node. Expressed as a file name with slashes
1112  * separating ancestors of the node.
1113  * \param buffer the buffer holding data to be written to the node.
1114  * \param buflen the number of bytes from buffer to write. To set NULL as data
1115  * use buffer as NULL and buflen as -1.
1116  * \param version the expected version of the node. The function will fail if
1117  * the actual version of the node does not match the expected version. If -1 is
1118  * used the version check will not take place.
1119  * \return the return code for the function call.
1120  * ZOK operation completed succesfully
1121  * ZNONODE the node does not exist.
1122  * ZNOAUTH the client does not have permission.
1123  * ZBADVERSION expected version does not match actual version.
1124  * ZBADARGUMENTS - invalid input parameters
1125  * ZINVALIDSTATE - zhandle state is either ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE
1126  * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory
1127  */
1128 ZOOAPI int zoo_set(zhandle_t *zh, const char *path, const char *buffer,
1129                    int buflen, int version);
1130
1131 /**
1132  * \brief sets the data associated with a node. This function is the same
1133  * as zoo_set except that it also provides access to stat information
1134  * associated with the znode.
1135  *
1136  * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init
1137  * \param path the name of the node. Expressed as a file name with slashes
1138  * separating ancestors of the node.
1139  * \param buffer the buffer holding data to be written to the node.
1140  * \param buflen the number of bytes from buffer to write. To set NULL as data
1141  * use buffer as NULL and buflen as -1.
1142  * \param version the expected version of the node. The function will fail if
1143  * the actual version of the node does not match the expected version. If -1 is
1144  * used the version check will not take place.
1145  * \param stat if not NULL, will hold the value of stat for the path on return.
1146  * \return the return code for the function call.
1147  * ZOK operation completed succesfully
1148  * ZNONODE the node does not exist.
1149  * ZNOAUTH the client does not have permission.
1150  * ZBADVERSION expected version does not match actual version.
1151  * ZBADARGUMENTS - invalid input parameters
1152  * ZINVALIDSTATE - zhandle state is either ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE
1153  * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory
1154  */
1155 ZOOAPI int zoo_set2(zhandle_t *zh, const char *path, const char *buffer,
1156                    int buflen, int version, struct Stat *stat);
1157
1158 /**
1159  * \brief lists the children of a node synchronously.
1160  *
1161  * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init
1162  * \param path the name of the node. Expressed as a file name with slashes
1163  * separating ancestors of the node.
1164  * \param watch if nonzero, a watch will be set at the server to notify
1165  * the client if the node changes.
1166  * \param strings return value of children paths.
1167  * \return the return code of the function.
1168  * ZOK operation completed succesfully
1169  * ZNONODE the node does not exist.
1170  * ZNOAUTH the client does not have permission.
1171  * ZBADARGUMENTS - invalid input parameters
1172  * ZINVALIDSTATE - zhandle state is either ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE
1173  * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory
1174  */
1175 ZOOAPI int zoo_get_children(zhandle_t *zh, const char *path, int watch,
1176                             struct String_vector *strings);
1177
1178 /**
1179  * \brief lists the children of a node synchronously.
1180  *
1181  * This function is similar to \ref zoo_get_children except it allows one specify
1182  * a watcher object rather than a boolean watch flag.
1183  *
1184  * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init
1185  * \param path the name of the node. Expressed as a file name with slashes
1186  * separating ancestors of the node.
1187  * \param watcher if non-null, a watch will be set at the server to notify
1188  * the client if the node changes.
1189  * \param watcherCtx user specific data, will be passed to the watcher callback.
1190  * Unlike the global context set by \ref zookeeper_init, this watcher context
1191  * is associated with the given instance of the watcher only.
1192  * \param strings return value of children paths.
1193  * \return the return code of the function.
1194  * ZOK operation completed succesfully
1195  * ZNONODE the node does not exist.
1196  * ZNOAUTH the client does not have permission.
1197  * ZBADARGUMENTS - invalid input parameters
1198  * ZINVALIDSTATE - zhandle state is either ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE
1199  * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory
1200  */
1201 ZOOAPI int zoo_wget_children(zhandle_t *zh, const char *path,
1202         watcher_fn watcher, void* watcherCtx,
1203         struct String_vector *strings);
1204
1205 /**
1206  * \brief gets the acl associated with a node synchronously.
1207  *
1208  * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init
1209  * \param path the name of the node. Expressed as a file name with slashes
1210  * separating ancestors of the node.
1211  * \param acl the return value of acls on the path.
1212  * \param stat returns the stat of the path specified.
1213  * \return the return code for the function call.
1214  * ZOK operation completed succesfully
1215  * ZNONODE the node does not exist.
1216  * ZNOAUTH the client does not have permission.
1217  * ZBADARGUMENTS - invalid input parameters
1218  * ZINVALIDSTATE - zhandle state is either ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE
1219  * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory
1220  */
1221 ZOOAPI int zoo_get_acl(zhandle_t *zh, const char *path, struct ACL_vector *acl,
1222                        struct Stat *stat);
1223
1224 /**
1225  * \brief sets the acl associated with a node synchronously.
1226  *
1227  * \param zh the zookeeper handle obtained by a call to \ref zookeeper_init
1228  * \param path the name of the node. Expressed as a file name with slashes
1229  * separating ancestors of the node.
1230  * \param version the expected version of the path.
1231  * \param acl the acl to be set on the path.
1232  * \return the return code for the function call.
1233  * ZOK operation completed succesfully
1234  * ZNONODE the node does not exist.
1235  * ZNOAUTH the client does not have permission.
1236  * ZINVALIDACL invalid ACL specified
1237  * ZBADVERSION expected version does not match actual version.
1238  * ZBADARGUMENTS - invalid input parameters
1239  * ZINVALIDSTATE - zhandle state is either ZOO_SESSION_EXPIRED_STATE or ZOO_AUTH_FAILED_STATE
1240  * ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory
1241  */
1242 ZOOAPI int zoo_set_acl(zhandle_t *zh, const char *path, int version,
1243                            const struct ACL_vector *acl);
1244
1245 #ifdef __cplusplus
1246 }
1247 #endif
1248
1249 #endif /*ZOOKEEPER_H_*/