Name

lcb_store — store a document

Synopsis

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

#include <libcouchbase/couchbase.h>
lcb_error_t lcb_store(lcb_t instance,
                      const void *command_cookie,
                      lcb_size_t num,
                      const lcb_store_cmd_t *const *commands);

DESCRIPTION

lcb_store() is used to store a document. If the library instance is using asynchronous mode (the default) this operation will return immediately and schedule the operations to be executed by the event loop, otherwise it will block until all commands are executed. command_cookie is is an opaque field that will be provided to the callback function. num is the number of entries in the commands array.

lcb_store_cmd_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 */
            const void *bytes;  /* Document body */
            lcb_size_t nbytes;  /* Size of the document body */
            lcb_uint32_t flags; /* Document flag section */
            lcb_cas_t cas;      /* The object identifier of the object */
            lcb_datatype_t datatype; /* Datatype. Set to 0 */
            lcb_time_t exptime; /* Document expiry time */
            lcb_storage_t operation; /* storage operation */
            const void *hashkey; /* hash key if != key */
            lcb_size_t nhashkey; /* number of bytes in hash key */
        } v0;
    } v;
} lcb_store_cmd_t;

Set cas to 0 unless you want to replace the document only if the cas matches.

Please note that using the another key for hashing may lead to an unbalanced cluster.

Upon completion the store callback as set by lcb_set_store_callback is called.

Storage operations

The following storage operations is defined:

LCB_ADD        Add the item to the cache, but fail if the
               object exists alread
LCB_REPLACE    Replace the existing object in the cache
LCB_SET        Unconditionally set the object in the cache
LCB_APPEND     Append this object to the existing object
LCB_PREPEND    Prepend this  object to the existing object

RETURN VALUES

lcb_store() returns the LCB_SUCCESS on success, or a specific error code upon failure. See lcb_strerror(3couchbase) for more information.

EXAMPLES

#include <libcouchbase/couchbase.h>
...
lcb_t instance;
...
lcb_store_cmd_t *store = calloc(1, sizeof(*store));
store->version = 0;
store->v.v0.key = "my-key";
store->v.v0.nkey = strlen(store->v.v0.key);
store->v.v0.bytes = "{ value:666 }"
store->v.v0.nbytes = strlen(store->v.v0.bytes);
store->v.v0.flags = 0xdeadcafe;
store->v.v0.cas = 0x0000;
store->v.v0.exptime = 0x666;
store->v.v0.datatype = LCB_JSON;
store->v.v0.operation = LCB_REPLACE;
lcb_store_cmd_st* commands[] = { store };
lcb_store(instance, NULL, 1, commands);
...

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_get_store_callback(3couchbase), lcb_set_store_callback(3couchbase), lcb_attributes(5)