Couchbase C Client  2.10.7
Asynchronous C Client for Couchbase
Legacy Key-Value API

Detailed Description

Operate on one or more key values.

The key-value APIs are high performance APIs utilizing the memcached protocol. Use these APIs to access data by its unique key.

These APIs are designed so that each function is passed in one or more "Command Structures". A command structure is a small structure detailing a specific key and contains options and modifiers for the operation as it relates to that key.

All the command structures are currently layed out like so:

{
int version;
union {
struct CMDv0 v0;
struct CMDv1 v1;
} v;
}

These top level structures are wrapper structures and are present to ensure portability between different versions of the library. To employ these structures within the command, you may do:

lcb_get_cmd_t gcmd_wrap = { 0 }, *cmdp_wrap = &gcmd_wrap;
lcb_GETCMDv0 *gcmd = &gcmd_wrap->v.v0;
gcmd->key = key;
gcmd->nkey = strlen(key);
lcb_get(instance, cookie, 1, &gcmd_wrap);

Functions

lcb_get_callback lcb_set_get_callback (lcb_t, lcb_get_callback callback)
 Set the callback to be invoked when an item is received as a result of an lcb_get() operation. More...
 
lcb_error_t lcb_get (lcb_t instance, const void *command_cookie, lcb_SIZE num, const lcb_get_cmd_t *const *commands)
 Get a number of values from the cache. More...
 

Typedefs

typedef void(* lcb_get_callback) (lcb_t instance, const void *cookie, lcb_error_t error, const lcb_get_resp_t *resp)
 The callback function for a "get-style" request. More...
 

Function Documentation

◆ lcb_set_get_callback()

lcb_get_callback lcb_set_get_callback ( lcb_t  ,
lcb_get_callback  callback 
)

Set the callback to be invoked when an item is received as a result of an lcb_get() operation.

Parameters
callbackthe new callback to install. Pass NULL to only query the current callback
Returns
the previous callback
See also
lcb_get()
Stability
Committed:

◆ lcb_get()

lcb_error_t lcb_get ( lcb_t  instance,
const void *  command_cookie,
lcb_SIZE  num,
const lcb_get_cmd_t *const *  commands 
)

Get a number of values from the cache.

If you specify a non-zero value for expiration, the server will update the expiration value on the item (refer to the documentation on lcb_store to see the meaning of the expiration). All other members should be set to zero.

lcb_get_cmd_t *get = calloc(1, sizeof(*get));
get->version = 0;
get->v.v0.key = "my-key";
get->v.v0.nkey = strlen(get->v.v0.key);
// Set an expiration of 60 (optional)
get->v.v0.exptime = 60;
lcb_get_cmd_t* commands[] = { get };
lcb_get(instance, NULL, 1, commands);

It is possible to get an item with a lock that has a timeout. It can then be unlocked with either a CAS operation or with an explicit unlock command.

You may specify the expiration value for the lock in the expiration (setting it to 0 cause the server to use the default value).

Get and lock the key:

lcb_get_cmd_t *get = calloc(1, sizeof(*get));
get->version = 0;
get->v.v0.key = "my-key";
get->v.v0.nkey = strlen(get->v.v0.key);
// Set a lock expiration of 5 (optional)
get->v.v0.lock = 1;
get->v.v0.exptime = 5;
lcb_get_cmd_t* commands[] = { get };
lcb_get(instance, NULL, 1, commands);
Parameters
instancethe instance used to batch the requests from
command_cookieA cookie passed to all of the notifications from this command
numthe total number of elements in the commands array
commandsthe array containing the items to get
Returns
Status code indicating whether the operation was scheduled or not. See 'exceptions' section for errors received in callbacks

Operation-specific errors received in callbacks include:

  • LCB_KEY_ENOENT if the key does not exist
  • LCB_ETMPFAIL if the lock option was set in the command and the item was already locked.
Stability
Committed:

Data Structure Documentation

◆ lcb_GETCMDv0

struct lcb_GETCMDv0

Get Command Structure.

Data Fields
const void * key Key to retrieve.
lcb_SIZE nkey Key length.
lcb_time_t exptime If this parameter is specified and lock is not set then the server will also update the object's expiration time while retrieving the key.

If lock is set then this is the maximum amount of time the lock may be held (before an unlock) before the server will forecfully unlock the key.

int lock If this parameter is set then the server will in addition to retrieving the item also lock the item, making it so that subsequent attempts to lock and/or modify the same item will fail with an error (either LCB_KEY_EEXISTS or LCB_ETMPFAIL).

The lock will be released when one of the following happens:

  1. The item is explicitly unlocked (see lcb_unlock())
  2. The lock expires (See the exptime parameter)
  3. The item is modified using lcb_store(), and being provided with the correct CAS.

◆ lcb_get_cmd_st

struct lcb_get_cmd_st

lcb_get() Command Wrapper Structure

See also
lcb_GETCMDv0
Data Fields
int version
union lcb_get_cmd_st v

◆ lcb_GETRESPv0

struct lcb_GETRESPv0

Inner response structure for a get operation.

Data Fields

const void * key
 
lcb_SIZE nkey
 
const void * bytes
 
lcb_SIZE nbytes
 
lcb_U32 flags
 Server side flags stored with the item.
 
lcb_cas_t cas
 CAS representing current mutation state of the item.
 

◆ lcb_get_resp_t

struct lcb_get_resp_t

lcb_get() response wrapper structure

See also
lcb_GETRESPv0
Data Fields
int version
union lcb_get_resp_t v

Typedef Documentation

◆ lcb_get_callback

typedef void(* lcb_get_callback) (lcb_t instance, const void *cookie, lcb_error_t error, const lcb_get_resp_t *resp)

The callback function for a "get-style" request.

Parameters
instancethe instance performing the operation
cookiethe cookie associated with with the command
errorThe status of the operation
respMore information about the actual item (only key and nkey is valid if error != LCB_SUCCESS)
Stability
Committed:
lcb_GETCMDv0
Get Command Structure.
Definition: api-legacy.h:87
lcb_get
lcb_error_t lcb_get(lcb_t instance, const void *command_cookie, lcb_SIZE num, const lcb_get_cmd_t *const *commands)
Get a number of values from the cache.
lcb_GETCMDv0::key
const void * key
Key to retrieve.
Definition: api-legacy.h:88
lcb_GETCMDv0::nkey
lcb_SIZE nkey
Key length.
Definition: api-legacy.h:89