Couchbase C Client  2.10.2
Asynchronous C Client for Couchbase

Detailed Description

Retrieve a document from the cluster.

Functions

lcb_error_t lcb_get3 (lcb_t instance, const void *cookie, const lcb_CMDGET *cmd)
 
Spool a single get operation More...
 

Macros

#define LCB_CMDGET_F_CLEAREXP
 If this bit is set in lcb_CMDGET::cmdflags then the expiry time is cleared if lcb_CMDGET::exptime is 0. More...
 

Function Documentation

◆ lcb_get3()

lcb_error_t lcb_get3 ( lcb_t  instance,
const void *  cookie,
const lcb_CMDGET cmd 
)


Spool a single get operation

Stability
Committed:
Parameters
instancethe handle
cookiea pointer to be associated with the command
cmdthe command structure
Returns
LCB_SUCCESS if successful, an error code otherwise
Request
lcb_CMDGET cmd = { 0 };
LCB_CMD_SET_KEY(&cmd, "Hello", 5);
lcb_get3(instance, cookie, &cmd);
Response
lcb_install_callback3(instance, LCB_CALLBACK_GET, get_callback);
static void get_callback(lcb_t instance, int cbtype, const lcb_RESPBASE *rb) {
const lcb_RESPGET *resp = (const lcb_RESPGET*)rb;
printf("Got response for key: %.*s\n", (int)resp->key, resp->nkey);
if (resp->rc != LCB_SUCCESS) {
printf("Couldn't get item: %s\n", lcb_strerror(NULL, resp->rc));
} else {
printf("Got value: %.*s\n", (int)resp->nvalue, resp->value);
printf("Got CAS: 0x%llx\n", resp->cas);
printf("Got item/formatting flags: 0x%x\n", resp->itmflags);
}
}
Errors
  • LCB_KEY_ENOENT if the item does not exist in the cluster
  • LCB_ETMPFAIL if the lcb_CMDGET::lock option was set but the item was already locked. Note that this error may also be returned (as a generic error) if there is a resource constraint within the server itself.
Examples:
example/crypto/openssl_symmetric_decrypt.c, example/libeventdirect/main.c, example/minimal/minimal.c, example/minimal/query.c, and example/tracing/tracing.c.

Data Structure Documentation

◆ lcb_CMDGET

struct lcb_CMDGET

Command for retrieving a single item.

See also
lcb_get3()
lcb_RESPGET
Note
The cas member should be set to 0 for this operation. If the cas is not 0, lcb_get3() will fail with LCB_OPTIONS_CONFLICT.

Use of the exptime field

  • Get And Touch:

    It is possible to retrieve an item and concurrently modify its expiration time (thus keeping it "alive"). The item's expiry time can be set using the exptime field.

  • Lock If the lock field is set to non-zero, the exptime field indicates the amount of time the lock should be held for
Examples:
example/crypto/openssl_symmetric_decrypt.c, example/libeventdirect/main.c, example/minimal/minimal.c, example/minimal/query.c, example/tracing/tracing.c, and example/tracing/views.c.
Data Fields
lcb_U32 cmdflags Common flags for the command.

These modify the command itself. Currently the lower 16 bits of this field are reserved, and the higher 16 bits are used for individual commands.

lcb_U32 exptime Specify the expiration time.

This is either an absolute Unix time stamp or a relative offset from now, in seconds. If the value of this number is greater than the value of thirty days in seconds, then it is a Unix timestamp. This field is used in mutation operations (lcb_store3()) to indicate the lifetime of the item. It is used in lcb_get3() with the lcb_CMDGET::lock option to indicate the lock expiration itself.

lcb_U64 cas The known CAS of the item.

This is passed to mutation to commands to ensure the item is only changed if the server-side CAS value matches the one specified here. For other operations (such as lcb_CMDENDURE) this is used to ensure that the item has been persisted/replicated to a number of servers with the value specified here.

lcb_KEYBUF key The key for the document itself.

This should be set via LCB_CMD_SET_KEY()

lcb_KEYBUF _hashkey
Stability
Volatile:
int lock If set to true, the exptime field inside options will take to mean the time the lock should be held.

While the lock is held, other operations trying to access the key will fail with an LCB_ETMPFAIL error. The item may be unlocked either via lcb_unlock3() or via a mutation operation with a supplied CAS

◆ lcb_RESPGET

struct lcb_RESPGET
Data Fields
void * cookie Application-defined pointer passed as the cookie parameter when scheduling the command.
const void * key Key for request.
lcb_SIZE nkey Size of key.
lcb_CAS cas CAS for response (if applicable)
lcb_error_t rc Status code.
lcb_U16 version ABI version for response.
lcb_U16 rflags Response specific flags.

see lcb_RESPFLAGS

const void * value Value buffer for the item.
lcb_SIZE nvalue Length of value.
void * bufh
lcb_datatype_t datatype
Stability
Internal:
lcb_U32 itmflags User-defined flags for the item.

Macro Definition Documentation

◆ LCB_CMDGET_F_CLEAREXP

#define LCB_CMDGET_F_CLEAREXP

If this bit is set in lcb_CMDGET::cmdflags then the expiry time is cleared if lcb_CMDGET::exptime is 0.

This allows get-and-touch with an expiry of 0.