Name

lcb_set_observe_callback — Set callback for observe operations

Synopsis

cc [ flag … ] file… -lcouchbase [ library … ]

#include <libcouchbase/couchbase.h>
lcb_observe_callback lcb_set_observe_callback(lcb_t instance, lcb_observe_callback callback);

DESCRIPTION

lcb_set_observe_callback() is used to set a new callback function to handle observe commands for a given libcouchbase instance.

The callback parameter is a callback function to call for each observe response. Passing NULL as the callback function may be used to query the current callback function. The lcb_observe_callback is a function with the following signature:

void function(lcb_t instance,
              const void *cookie,
              lcb_error_t error,
              lcb_observe_resp_t *resp);

instance is the libcouchbase instance that this response is called from. The cookie is cookie you passed to lcb_observe. error is the error status of this operation. If the error is LCB_SUCCESS the resp is a pointer to the result for the operation. lcb_observe_resp_t is a structure defined in <libcouchbase/arguments.h>:

typedef struct {
    int version;              /* The enty in "v" to use */
    union {
        struct {
            const void *key;      /* The key this response belongs to */
            lcb_size_t nkey;      /* The number of bytes in the key */
            lcb_cas_t cas;        /* The CAS value for the current value */
            lcb_observe_t status; /* The status of the key */
            int from_master;      /* zero if key came from replica */
            lcb_time_t ttp;       /* average time to persist */
            lcb_time_t ttr;       /* average time to replicate */
        } v0;
    } v;
} lcb_observe_resp_t;

The status field may be one of the following:

LCB_OBSERVE_FOUND       The item found in the memory, but not
                        yet on the disk
LCB_OBSERVE_PERSISTED   The item hit the disk
LCB_OBSERVE_NOT_FOUND   The item missing on the disk and the
                         memory

The callback function will be called multiple times with a final call with key set to NULL to indicate the last invocation of the callback.

RETURN VALUES

lcb_set_observe_callback() returns the previous callback function.

EXAMPLES

Example 1: Query the current callback

#include <libcouchbase/couchbase.h>
...
lcb_t instance;
...
lcb_observe_callback old;
old = lcb_set_observe_callback(instance, NULL);
...

Example 2: Install custom callback

#include <libcouchbase/couchbase.h>
...
static void callback(lcb_t instance, const void *cookie,
                     lcb_error_t error,
                     const lcb_observe_resp_t *resp)
{
   if (error == LCB_SUCCESS) {
      switch (resp->version) {
          ...
          /* handle the known formats */
          ...
      default:
          /* handle unknown formats */
      }
   } else {
      /* handle errors */
   }
}
...
lcb_t instance;
...
lcb_set_observe_callback(instance, callback);
...

ATTRIBUTES

See lcb_attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Interface Stability

Committed

MT-Level

MT-Safe

COPYRIGHT

Copyright 2010-2013 Couchbase, Inc.

SEE ALSO

Learn more at http://www.couchbase.com/communities/c.

libcouchbase(3lib), lcb_observe(3couchbase), lcb_attributes(5)