Storing items

Detailed Description

Mutate an item within the cluster.

Here you can create a new item, replace an existing item, and append or prepend to an existing value

Functions
lcb_store_callback	lcb_set_store_callback (lcb_t, lcb_store_callback callback)
	Set the callback to be received when an item has been stored. More...
lcb_error_t	lcb_store (lcb_t instance, const void *command_cookie, lcb_SIZE num, const lcb_store_cmd_t *const *commands)
	Store an item in the cluster. More...

Typedefs
typedef void(*	lcb_store_callback) (lcb_t instance, const void *cookie, lcb_storage_t operation, lcb_error_t error, const lcb_store_resp_t *resp)
	The callback function for a storage request. More...

Enumerations
enum	lcb_storage_t
	operation parameter for lcb_store() More...

Function Documentation

lcb_store_callback lcb_set_store_callback	(	lcb_t	,
		lcb_store_callback	callback
	)

Set the callback to be received when an item has been stored.

Parameters

callback

the new callback to install, or NULL to just query the current callback

Returns

the previous callback

See also

lcb_store()

Stability

Committed:

Examples:

example/libeventdirect/main.c, and example/minimal/minimal.c.

lcb_error_t lcb_store	(	lcb_t	instance,
		const void *	command_cookie,
		lcb_SIZE	num,
		const lcb_store_cmd_t *const *	commands
	)

Store an item in the cluster.

You may initialize all of the members in the the lcb_item_st structure with the values you want. Values larger than 30*24*60*60 seconds (30 days) are interpreted as absolute times (from the epoch). Unused members should be set to zero.

lcb_store_cmd_st *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 = 0x1234;
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);

Parameters

instance	the instance used to batch the requests from
command_cookie	A cookie passed to all of the notifications from this command
num	the total number of elements in the commands array
commands	the array containing the items to store

Returns

Status code indicating whether the operation was scheduled or not. See 'exceptions' section for errors received in callbacks

Operation-specific error codes include:

• LCB_KEY_ENOENT if LCB_REPLACE was used and the key does not exist
• LCB_KEY_EEXISTS if LCB_ADD was used and the key already exists
• LCB_KEY_EEXISTS if the CAS was specified (for an operation other than LCB_ADD) and the item exists on the server with a different CAS
• LCB_KEY_EEXISTS if the item was locked and the CAS supplied did not match the locked item's CAS (or if no CAS was supplied)
• LCB_NOT_STORED if an LCB_APPEND or LCB_PREPEND operation was performed and the item did not exist on the server.
• LCB_E2BIG if the size of the value exceeds the cluster per-item value limit (currently 20MB).

Stability

Committed:

Examples:

example/libeventdirect/main.c, and example/minimal/minimal.c.

---

Data Structure Documentation

struct lcb_STORECMDv0

lcb_store() Command structure

This structure is used to define an item to be stored on the server.

Data Fields
const void *	key
lcb_SIZE	nkey
const void *	bytes	Value to store.
lcb_SIZE	nbytes	Length of value to store.
lcb_U32	flags	User-defined flags stored along with the item.
lcb_cas_t	cas	If present, the server will check that the item's current CAS matches the value specified here. If this check fails the command will fail with an LCB_KEY_EEXISTS error. Warning For LCB_APPEND and LCB_PREPEND, this field should be 0.
lcb_U8	datatype	See lcb_VALUEFLAGS.
lcb_time_t	exptime	Expiration for the item. 0 means never expire. Warning for LCB_APPEND and LCB_PREPEND, this field should be 0.
lcb_storage_t	operation	Mandatory. Mutation type

struct lcb_store_cmd_t

Wrapper structure for lcb_STORECMDv0.

Examples:

example/libeventdirect/main.c, and example/minimal/minimal.c.

Data Fields
int	version
union lcb_store_cmd_t	v

struct lcb_store_resp_t

Wrapper structure for lcb_STORERESPv0.

Examples:

example/libeventdirect/main.c, and example/minimal/minimal.c.

Data Fields
int	version
union lcb_store_resp_t	v

Typedef Documentation

typedef void(* lcb_store_callback) (lcb_t instance, const void *cookie, lcb_storage_t operation, lcb_error_t error, const lcb_store_resp_t *resp)

The callback function for a storage request.

Parameters

instance	the instance performing the operation
operation	the operation performed
cookie	the cookie associated with with the command
error	The status of the operation
resp	More information about the item related to the store operation. (only key and nkey is valid if error != LCB_SUCCESS)

Stability

Committed:

Enumeration Type Documentation

enum lcb_storage_t

operation parameter for lcb_store()

Storing an item in couchbase is only one operation with a different set of attributes / constraints.

Enumerator
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.