Couchbase C Client  2.4.0_beta
Experimental V3 API

Detailed Description

Preview APIs for performing commands.

Basic command and structure definitions for public API. This represents the "V3" API of libcouchbase. All of the APIs in this group are considered to be volatile, however you are encouraged to try them out and provide feedback on them.

Creating Commands

Issuing a command to the Cluster involves selecting the correct command structure, populating it with the data relevant for the command, optionally associating the command with your own application data, issuing the command to a spooling function, and finally receiving the response.

Command structures all derive from the common lcb_CMDBASE structure. This structure defines the common fields for all commands.

Almost all commands need to contain a key, which should be assigned using the LCB_CMD_SET_KEY() macro.

#define LCB_CMD_BASE
#define LCB_CMD_SET_KEY(cmd, keybuf, keylen)
 Set the key for the command.

Receiving Responses

This section describes the structures used for receiving responses to commands.

Each command will have a callback invoked (typically once, for some commands this may be more than once) with a response structure. The response structure will be of a type that extends lcb_RESPBASE. The response structure should not be modified and any of its fields should be considered to point to memory which will be released after the callback exits.

The common response header contains the lcb_RESPBASE::cookie field which is the pointer to your application context (passed as the second argument to the spooling function) and allows you to associate a specific command with a specific response.

The header will also contain the key (lcb_RESPBASE::key) field which can also help identify the specific command. This is useful if you maintain a single cookie for multiple commands, and have per-item specific data you wish to associate within the cookie itself.

Success or failure of the operation is signalled through the lcb_RESPBASE::rc field. Note that even in the case of failure, the lcb_RESPBASE::cookie and lcb_RESPBASE::key fields will always be populated.

Most commands also return the CAS of the item (as it exists on the server) and this is placed inside the lcb_RESPBASE::cas field, however it is only valid in the case where lcb_RESPBASE::rc is LCB_SUCCESS.

enum  lcb_RESPFLAGS
 Response flags. More...
enum  lcb_CALLBACKTYPE
 The type of response passed to the callback. More...
typedef void(* lcb_RESPCALLBACK )(lcb_t instance, int cbtype, const lcb_RESPBASE *resp)
 Callback invoked for responses.
lcb_RESPCALLBACK lcb_install_callback3 (lcb_t instance, int cbtype, lcb_RESPCALLBACK cb)
#define LCB_RESP_BASE
 Response specific flags.
#define LCB_RESP_SERVER_FIELDS

General Spooling API

The following operation APIs are low level entry points which create a single operation. To use these operation APIs you should call the lcb_sched_enter() which creates a virtual scope in which to create operations.

For each of these operation APIs, the actual API call will insert the created packet into a "Scheduling Queue" (this is done through mcreq_sched_add() which is in mcreq.h). You may add as many items to this scheduling queue as you would like.

Note that an operation is only added to the queue if it was able to be scheduled properly. If a scheduling failure occurred (for example, if a configuration is missing, the command had invalid input, or memory allocation failed) then the command will not be placed into the queue.

Once all operations have been scheduled you can call lcb_sched_leave() which will place all commands scheduled into the I/O queue.

If you wish to discard all scheduled operations (for example, if one of them errored, and your application cannot handle partial scheduling failures) then you may call lcb_sched_fail() which will release all the resources of the packets placed into the temporary queue.

void lcb_sched_enter (lcb_t instance)
 Enter a scheduling context.
void lcb_sched_leave (lcb_t instance)
 Leave the current scheduling context, scheduling the commands within the context to be flushed to the network.
void lcb_sched_fail (lcb_t instance)
 Fail all commands in the current scheduling context.

Simple Retrievals

Request and response structure for retrieving items

typedef lcb_CMDBASE lcb_CMDUNLOCK
 Command for lcb_unlock3()
typedef lcb_RESPBASE lcb_RESPUNLOCK
 Response structure for an unlock command.
lcb_error_t lcb_get3 (lcb_t instance, const void *cookie, const lcb_CMDGET *cmd)
 Spool a single get operation.
lcb_error_t lcb_unlock3 (lcb_t instance, const void *cookie, const lcb_CMDUNLOCK *cmd)
 Unlock a previously locked item using lcb_CMDGET::lock.

Counter Operations

lcb_error_t lcb_counter3 (lcb_t instance, const void *cookie, const lcb_CMDCOUNTER *cmd)
 Spool a single counter operation.

Replica Reads

Replica reads are done in cases where the master node is unavailable (i.e. an lcb_get3() call returns LCB_NO_MATCHING_SERVER).

lcb_error_t lcb_rget3 (lcb_t instance, const void *cookie, const lcb_CMDGETREPLICA *cmd)
 Spool a single get-with-replica request.

Storing and Mutating Items

lcb_error_t lcb_store3 (lcb_t instance, const void *cookie, const lcb_CMDSTORE *cmd)
 Spool a single storage request.
#define LCB_CMD_SET_VALUE(scmd, valbuf, vallen)
 Set the value buffer for the command.

Removing Items

typedef lcb_CMDBASE lcb_CMDREMOVE
 Command for removing an item from the server.
typedef lcb_RESPBASE lcb_RESPREMOVE
 Response structure for removal operation.
lcb_error_t lcb_remove3 (lcb_t instance, const void *cookie, const lcb_CMDREMOVE *cmd)
 Spool a removal of an item.

Modify an item's expiration time

The lcb_touch3() command may be used to modify an items operation time, either to make it expire at a given time, or to clear its pending expiration. This command may be used in case you wish to only ensure the item is not deleted but no actually modify (lcb_store3()) or retrieve (lcb_get3()) the item.

typedef lcb_CMDBASE lcb_CMDTOUCH
 Command structure for a touch request.
typedef lcb_RESPBASE lcb_RESPTOUCH
 Response structure for a touch request.
lcb_error_t lcb_touch3 (lcb_t instance, const void *cookie, const lcb_CMDTOUCH *cmd)
 Spool a touch request.

Retrieve statistics from the cluster

typedef lcb_CMDBASE lcb_CMDSTATS
 Command structure for stats request The lcb_CMDSTATS::key field should contain the statistics key, or be empty if the default statistics are desired.
lcb_error_t lcb_stats3 (lcb_t instance, const void *cookie, const lcb_CMDSTATS *cmd)
 Spool a request for statistics from the cluster.

Retrieve replication and persistence status about an item

typedef lcb_CMDBASE lcb_CMDOBSERVE
 Structure for an observe request.
lcb_MULTICMD_CTXlcb_observe3_ctxnew (lcb_t instance)
 Create a new multi context for an observe operation.
#define LCB_CMDOBSERVE_F_MASTER_ONLY
 Set this bit in the cmdflags field to indicate that only the master node should be contacted.

Wait for items to be persisted or replicated to nodes

typedef lcb_CMDBASE lcb_CMDENDURE
 Command structure for endure.
lcb_MULTICMD_CTXlcb_endure3_ctxnew (lcb_t instance, const lcb_durability_opts_t *options, lcb_error_t *err)
 Return a new command context for scheduling endure operations.

Check the memcached server versions

Return the memcached version (not Couchbase version) for all servers.

May also be used as a simple way to check that all nodes are responding.

lcb_error_t lcb_server_versions3 (lcb_t instance, const void *cookie, const lcb_CMDBASE *cmd)

Set the memcached Logging Level

typedef lcb_RESPSERVERBASE lcb_RESPVERBOSITY
lcb_error_t lcb_server_verbosity3 (lcb_t instance, const void *cookie, const lcb_CMDVERBOSITY *cmd)

Flush a memcached Bucket

Clear a memcached bucket of all items. Note that this will not work on a Couchbase bucket. To flush a couchbase bucket, use the REST API

typedef lcb_CMDBASE lcb_CMDFLUSH
typedef lcb_RESPSERVERBASE lcb_RESPFLUSH
lcb_error_t lcb_flush3 (lcb_t instance, const void *cookie, const lcb_CMDFLUSH *cmd)

Perform an HTTP operation

Command flag for HTTP to indicate that the callback is to be invoked multiple times for each new chunk of incoming data.

Once all the chunks have been received, the callback will be invoked once more with the LCB_RESP_F_FINAL flag and an empty content.

lcb_error_t lcb_http3 (lcb_t instance, const void *cookie, const lcb_CMDHTTP *cmd)
#define LCB_CMDHTTP_F_STREAM

Function Documentation

lcb_RESPCALLBACK lcb_install_callback3 ( lcb_t  instance,
int  cbtype,
lcb_RESPCALLBACK  cb 
)
Stability
Volatile:

Install a new-style callback for an operation. The callback will be invoked with the relevant response structure.

Parameters
instancethe handle
cbtypethe type of operation for which this callback should be installed. The value should be one of the lcb_CALLBACKTYPE constants
cbthe callback to install
Returns
the old callback
Note
LCB_CALLBACK_DEFAULT is initialized to the default handler which proxies back to the older 2.x callbacks. If you set cbtype to LCB_CALLBACK_DEFAULT then your 2.x callbacks will not work.
void lcb_sched_enter ( lcb_t  instance)

Enter a scheduling context.

Stability
Volatile:

A scheduling context is an ephemeral list of commands issued to various servers. Operations (like lcb_get3(), lcb_store3()) place packets into the current context.

The context mechanism allows you to efficiently pipeline and schedule multiple operations of different types and quantities. The network is not touched and nothing is scheduled until the context is exited.

Parameters
instancethe instance
lcb_sched_enter(instance);
lcb_get3(...);
lcb_sched_leave(instance);
void lcb_sched_leave ( lcb_t  instance)

Leave the current scheduling context, scheduling the commands within the context to be flushed to the network.

Stability
Volatile:
Parameters
instancethe instance
void lcb_sched_fail ( lcb_t  instance)

Fail all commands in the current scheduling context.

Stability
Volatile:

The commands placed within the current scheduling context are released and are never flushed to the network.

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

Spool a single get operation.

Stability
Volatile:
Parameters
instancethe handle
cookiea pointer to be associated with the command
cmdthe command structure
Returns
LCB_SUCCESS if successful, an error code otherwise
See Also
lcb_sched_enter(), lcb_sched_leave()
lcb_sched_enter(instance);
lcb_CMDGET cmd = { 0 };
LCB_CMD_SET_KEY(&cmd, "Hello", 5);
lcb_install_callback3(instance, LCB_CALLBACK_GET, a_callback);
lcb_get3(instance, cookie, &cmd);
lcb_sched_leave(instance);
lcb_error_t lcb_unlock3 ( lcb_t  instance,
const void *  cookie,
const lcb_CMDUNLOCK cmd 
)

Unlock a previously locked item using lcb_CMDGET::lock.

Stability
Volatile:
Parameters
instancethe instance
cookiethe context pointer to associate with the command
cmdthe command containing the information about the locked key
Returns
LCB_SUCCESS if successful, an error code otherwise
See Also
lcb_get3(), lcb_sched_enter(), lcb_sched_leave()
static void locked_callback(lcb_t, lcb_CALLBACKTYPE, const lcb_RESPBASE *resp) {
lcb_CMDUNLOCK cmd = { 0 };
LCB_CMD_SET_KEY(&cmd, resp->key, resp->nkey);
cmd.cas = resp->cas;
lcb_sched_enter(instance);
lcb_unlock3(instance, cookie, &cmd);
lcb_sched_leave(instance);
}
lcb_error_t lcb_counter3 ( lcb_t  instance,
const void *  cookie,
const lcb_CMDCOUNTER cmd 
)

Spool a single counter operation.

Stability
Volatile:
Parameters
instancethe instance
cookiethe pointer to associate with the request
cmdthe command to use
Returns
LCB_SUCCESS on success, other error on failure
lcb_CMDCOUNTER cmd = { 0 };
LCB_CMD_SET_KEY(&cmd, "counter", strlen("counter"));
cmd.delta = 1; // Increment by one
cmd.initial = 42; // Default value is 42 if it does not exist
cmd.exptime = 300; // Expire in 5 minutes
lcb_sched_enter(instance);
lcb_counter3(instance, NULL, &cmd);
lcb_sched_leave(instance);
lcb_install_callback3(instance, LCB_CALLBACKTYPE_COUNTER, cb);
lcb_error_t lcb_rget3 ( lcb_t  instance,
const void *  cookie,
const lcb_CMDGETREPLICA cmd 
)

Spool a single get-with-replica request.

Stability
Volatile:
Parameters
instance
cookie
cmd
Returns
LCB_SUCCESS on success, error code otherwise
lcb_error_t lcb_store3 ( lcb_t  instance,
const void *  cookie,
const lcb_CMDSTORE cmd 
)

Spool a single storage request.

Stability
Volatile:
Parameters
instancethe handle
cookiepointer to associate with the command
cmdthe command structure
Returns
LCB_SUCCESS on success, error code on failure
lcb_CMDSTORE cmd = { 0 };
LCB_CMD_SET_KEY(&cmd, "Key", 3);
LCB_CMD_SET_VALUE(&cmd, "value", 5);
cmd.operation = LCB_ADD; // Only create if it does not exist
cmd.exptime = 60; // expire in a minute
lcb_sched_enter(instance);
lcb_store3(instance, cookie, &cmd);
lcb_sched_leave(instance);
lcb_error_t lcb_remove3 ( lcb_t  instance,
const void *  cookie,
const lcb_CMDREMOVE cmd 
)

Spool a removal of an item.

Stability
Volatile:
Parameters
instancethe handle
cookiepointer to associate with the request
cmdthe command
Returns
LCB_SUCCESS on success, other code on failure
lcb_CMDREMOVE cmd = { 0 };
LCB_CMD_SET_KEY(cmd, "deleteme", strlen("deleteme"));
lcb_sched_enter(instance);
lcb_remove3(instance, cookie, &cmd);
lcb_sched_leave(instance);
lcb_error_t lcb_touch3 ( lcb_t  instance,
const void *  cookie,
const lcb_CMDTOUCH cmd 
)

Spool a touch request.

Stability
Volatile:
Parameters
instancethe handle
cookiethe pointer to associate with the request
cmdthe command
Returns
LCB_SUCCESS on success, other error code on failure
lcb_CMDTOUCH cmd = { 0 };
LCB_CMD_SET_KEY(&cmd, "keep_me", strlen("keep_me"));
cmd.exptime = 0; // Clear the expiration
lcb_sched_enter(instance);
lcb_touch3(instance, cookie, &cmd);
lcb_sched_leave(instance);
lcb_error_t lcb_stats3 ( lcb_t  instance,
const void *  cookie,
const lcb_CMDSTATS cmd 
)

Spool a request for statistics from the cluster.

Stability
Volatile:
Parameters
instancethe instance
cookiepointer to associate with the request
cmdthe command
Returns
LCB_SUCCESS on success, other error code on failure.

Note that the callback for this command is invoked an indeterminate amount of times. The callback is invoked once for each statistic for each server. When all the servers have responded with their statistics, a final callback is delivered to the application with the LCB_RESP_F_FINAL flag set in the lcb_RESPSTATS::rflags field. When this response is received no more callbacks for this command shall be invoked.

void stats_callback(lcb_t, lcb_CALLBACKTYPE, const lcb_RESPSTATS *resp)
{
if (resp->key) {
FILE *fp = (FILE *)resp->cookie;
fprintf(fp, "Server %s: %.*s = %.*s\n", resp->server,
(int)resp->nkey, resp->key,
(int)resp->nvalue, resp->value);
}
if (resp->rflags & LCB_RESP_F_FINAL) {
fclose(cookie);
}
}
void printStatsToFile(const char *path) {
FILE *fp = fopen(path, "w");
// .. initialize your instance
lcb_install_callback3(instance, LCB_CALLBACK_STATS, (lcb_RESP_cb)stats_callback);
lcb_CMDSTATS cmd = { 0 };
// Using default stats, no further initialization
lcb_sched_enter(instance);
lcb_stats3(instance, fp, &cmd);
lcb_sched_leave(instance);
}
lcb_MULTICMD_CTX* lcb_observe3_ctxnew ( lcb_t  instance)

Create a new multi context for an observe operation.

Stability
Volatile:
Parameters
instancethe instance
Returns
a new multi command context, or NULL on allocation failure.

Note that the callback for this command will be invoked multiple times, one for each node. To determine when no more callbacks will be invoked, check for the LCB_RESP_F_FINAL flag inside the lcb_RESPOBSERVE::rflags field.

void callback(lcb_t, lcb_CALLBACKTYPE, const lcb_RESPOBSERVE *resp)
{
if (resp->rflags & LCB_RESP_F_FINAL) {
return;
}
printf("Got status for key %.*s\n", (int)resp->nkey, resp->key);
printf(" Node Type: %s\n", resp->ismaster ? "MASTER" : "REPLICA");
printf(" Status: 0x%x\n", resp->status);
printf(" Current CAS: 0x%"PRIx64"\n", resp->cas);
}
lcb_CMDOBSERVE cmd = { 0 };
LCB_CMD_SET_KEY(&cmd, "key", 3);
mctx->addcmd(mctx, (lcb_CMDBASE *)&cmd);
lcb_sched_enter(instance);
mctx->done(mctx, cookie);
lcb_sched_leave(instance);
lcb_install_callback3(instance, LCB_CALLBACK_OBSERVE, (lcb_RESP_cb)callback);
lcb_MULTICMD_CTX* lcb_endure3_ctxnew ( lcb_t  instance,
const lcb_durability_opts_t options,
lcb_error_t err 
)

Return a new command context for scheduling endure operations.

Stability
Volatile:
Parameters
instancethe instance
optionsa structure containing the various criteria needed for durability requirements
[out]errError code if a new context could not be created
Returns
the new context, or NULL on error. Note that in addition to memory allocation failure, this function might also return NULL because the options structure contained bad values. Always check the err result.
lcb_error_t lcb_server_versions3 ( lcb_t  instance,
const void *  cookie,
const lcb_CMDBASE cmd 
)
Stability
Volatile:
lcb_error_t lcb_server_verbosity3 ( lcb_t  instance,
const void *  cookie,
const lcb_CMDVERBOSITY *  cmd 
)
Stability
Volatile:
lcb_error_t lcb_flush3 ( lcb_t  instance,
const void *  cookie,
const lcb_CMDFLUSH cmd 
)
Stability
Volatile:

Data Structure Documentation

struct lcb_CMDBASE

Common ABI header for all commands.

Any command may be safely casted to this type.

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_RESPGET::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 command. Every command has a key. Generally you will be initializing this field using LCB_CMD_SET_KEY()
lcb_KEYBUF hashkey
struct lcb_RESPBASE

Base response structure for callbacks.

All responses structures derive from this ABI.

Data Fields
void * cookie User data associated with request.
const void * key Key for request.
lcb_SIZE nkey Size of key.
lcb_cas_t 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
struct lcb_RESPSERVERBASE

Base structure for informational commands from servers This contains an additional lcb_RESPSERVERBASE::server field containing the server which emitted this response.

Data Fields
void * cookie User data associated with request.
const void * key Key for request.
lcb_SIZE nkey Size of key.
lcb_cas_t 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 char * server String containing the host:port of the server which sent this response.
struct lcb_CMDGET

Command for retrieving a single item.

See Also
lcb_get3()
lcb_RESPGET
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_RESPGET::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 command. Every command has a key. Generally you will be initializing this field using LCB_CMD_SET_KEY()
lcb_KEYBUF hashkey
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
struct lcb_RESPGET

Response structure when retrieving a single item.

Data Fields
void * cookie User data associated with request.
const void * key Key for request.
lcb_SIZE nkey Size of key.
lcb_cas_t 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
lcb_U32 itmflags User-defined flags for the item.
struct lcb_CMDCOUNTER

Command for counter operations.

See Also
lcb_counter3(), lcb_RESPCOUNTER
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_RESPGET::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 command. Every command has a key. Generally you will be initializing this field using LCB_CMD_SET_KEY()
lcb_KEYBUF hashkey
lcb_int64_t delta Delta value. If this number is negative the item on the server is decremented. If this number is positive then the item on the server is incremented
lcb_U64 initial If the item does not exist on the server (and create is true) then this will be the initial value for the item.
int create Boolean value. Create the item and set it to initial if it does not already exist
struct lcb_RESPCOUNTER

Response structure for counter operations.

See Also
lcb_counter3()
Data Fields
void * cookie User data associated with request.
const void * key Key for request.
lcb_SIZE nkey Size of key.
lcb_cas_t 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
lcb_U64 value Contains the current value after the operation was performed.
struct lcb_CMDGETREPLICA

Command for requesting an item from a replica.

Note
The options.exptime and options.cas fields are ignored for this command.
See Also
lcb_rget3(), lcb_RESPGET
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_RESPGET::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 command. Every command has a key. Generally you will be initializing this field using LCB_CMD_SET_KEY()
lcb_KEYBUF hashkey
lcb_replica_t strategy Strategy to use for selecting a replica.
int index
struct lcb_CMDSTORE

Command for storing an item to the server.

This command must contain the key to mutate, the value which should be set (or appended/prepended) in the lcb_CMDSTORE::value field (see LCB_CMD_SET_VALUE()) and the operation indicating the mutation type (lcb_CMDSTORE::operation).

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_RESPGET::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 command. Every command has a key. Generally you will be initializing this field using LCB_CMD_SET_KEY()
lcb_KEYBUF hashkey
lcb_VALBUF value Value to store on the server.
lcb_U32 flags These flags are stored alongside the item on the server. They are typically used by higher level clients to store format/type information
lcb_datatype_t datatype Ignored for now.
lcb_storage_t operation Must be assigned.
struct lcb_RESPSTATS

Response structure for cluster statistics.

The lcb_RESPSTATS::key field contains the statistic name (not the same as was passed in lcb_CMDSTATS::key which is the name of the statistical group).

Data Fields
void * cookie User data associated with request.
const void * key Key for request.
lcb_SIZE nkey Size of key.
lcb_cas_t 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 char * server String containing the host:port of the server which sent this response.
const char * value The value, if any, for the given statistic.
lcb_SIZE nvalue Length of value.
struct lcb_MULTICMD_CTX

Multi Command Context API Some commands (notably, OBSERVE and its higher level equivalent, endue) are handled more efficiently at the cluster side by stuffing multiple items into a single packet.

This structure defines three function pointers to invoke. The addcmd() function will add a new command to the current packet, the done() function will schedule the packet(s) into the current scheduling context and the fail() function will destroy the context without progressing further.

Some commands will return an lcb_MULTICMD_CTX object to be used for this purpose:

lcb_MUTLICMD_CTX *ctx = lcb_observe3_ctxnew(instance);
lcb_CMDOBSERVE cmd = { 0 };
LCB_CMD_SET_KEY(&cmd, "key1", strlen("key1"));
ctx->addcmd(ctx, &cmd);
LCB_CMD_SET_KEY(&cmd.key, "key2", strlen("key2"));
ctx->addcmd(ctx, &cmd);
LCB_CMD_SET_KEY(&cmd.key, "key3", strlen("key3"));
ctx->addcmd(ctx, &cmd);
lcb_sched_enter(instance);
ctx->done(ctx);
lcb_sched_leave(instance);
lcb_wait(instance);

Data Fields

lcb_error_t(* addcmd )(struct lcb_MULTICMD_CTX_st *ctx, const lcb_CMDBASE *cmd)
 Add a command to the current context.
lcb_error_t(* done )(struct lcb_MULTICMD_CTX_st *ctx, const void *cookie)
 Indicate that no more commands are added to this context, and that the context should assemble the packets and place them in the current scheduling context.
void(* fail )(struct lcb_MULTICMD_CTX_st *ctx)
 Indicate that no more commands should be added to this context, and that the context should not add its contents to the packet queues, but rather release its resources.

Field Documentation

lcb_error_t(* addcmd)(struct lcb_MULTICMD_CTX_st *ctx, const lcb_CMDBASE *cmd)

Add a command to the current context.

Parameters
ctxthe context
cmdthe command to add. Note that cmd may be a subclass of lcb_CMDBASE
Returns
LCB_SUCCESS, or failure if a command could not be added.
lcb_error_t(* done)(struct lcb_MULTICMD_CTX_st *ctx, const void *cookie)

Indicate that no more commands are added to this context, and that the context should assemble the packets and place them in the current scheduling context.

Parameters
ctxThe multi context
cookieThe cookie for all commands
Returns
LCB_SUCCESS if scheduled successfully, or an error code if there was a problem constructing the packet(s).
void(* fail)(struct lcb_MULTICMD_CTX_st *ctx)

Indicate that no more commands should be added to this context, and that the context should not add its contents to the packet queues, but rather release its resources.

Called if you don't want to actually perform the operations.

Parameters
ctx
struct lcb_RESPOBSERVE

Response structure for an observe command.

Note that the lcb_RESPOBSERVE::cas contains the CAS of the item as it is stored within that specific server. The CAS may be incorrect or stale unless lcb_RESPOBSERVE::ismaster is true.

Data Fields
void * cookie User data associated with request.
const void * key Key for request.
lcb_SIZE nkey Size of key.
lcb_cas_t 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
lcb_U8 status Bit set of flags.
lcb_U8 ismaster Set to true if this response came from the master node.
lcb_U32 ttp Unused.
lcb_U32 ttr Unused.
struct lcb_RESPENDURE

Response structure for endure.

Data Fields
void * cookie User data associated with request.
const void * key Key for request.
lcb_SIZE nkey Size of key.
lcb_cas_t 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
lcb_U16 nresponses Total number of polls needed for this item.
lcb_U8 exists_master True if the item exists in master's cache.
lcb_U8 persisted_master True if item exists in master's disk.
lcb_U8 npersisted How many nodes was this item persisted to.
lcb_U8 nreplicated How many nodes was this item replicated to.
struct lcb_RESPMCVERSION

Response structure for the version command.

Data Fields
void * cookie User data associated with request.
const void * key Key for request.
lcb_SIZE nkey Size of key.
lcb_cas_t 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 char * server String containing the host:port of the server which sent this response.
const char * mcversion The version string.
lcb_SIZE nversion Length of the version string.
struct lcb_CMDHTTP

Structure for performing an HTTP request.

Note that the key and nkey fields indicate the path for the API

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_RESPGET::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 command. Every command has a key. Generally you will be initializing this field using LCB_CMD_SET_KEY()
lcb_KEYBUF hashkey
lcb_http_type_t type Type of request to issue. LCB_HTTP_TYPE_VIEW will issue a request against a random node's view API. LCB_HTTP_TYPE_MANAGEMENT will issue a request against a random node's administrative API, and LCB_HTTP_TYPE_RAW will issue a request against an arbitrary host.
lcb_http_method_t method HTTP Method to use.
const char * body If the request requires a body (e.g. PUT or POST) then it will go here. Be sure to indicate the length of the body too.
lcb_SIZE nbody Length of the body for the request.
lcb_http_request_t * reqhandle If non-NULL, will be assigned a handle which may be used to subsequently cancel the request.
const char * content_type For views, set this to application/json
const char * username Username to authenticate with, if left empty, will use the credentials passed to lcb_create()
const char * password Password to authenticate with, if left empty, will use the credentials passed to lcb_create()
const char * host If set, this must be a string in the form of http://host:port. Should only be used for raw requests.

Macro Definition Documentation

#define LCB_CMD_SET_KEY (   cmd,
  keybuf,
  keylen 
)

Set the key for the command.

Parameters
cmdA command derived from lcb_CMDBASE
keybufthe buffer for the key
keylenthe length of the key.

The storage for keybuf may be released or modified after the command has been spooled.

#define LCB_RESP_BASE

Response specific flags.

see lcb_RESPFLAGS

#define LCB_CMD_SET_VALUE (   scmd,
  valbuf,
  vallen 
)

Set the value buffer for the command.

Parameters
scmdan lcb_CMDSTORE pointer
valbufthe buffer for the value
vallenthe length of the buffer The buffer needs to remain valid only until the command is passed to the lcb_store3() function.

Typedef Documentation

typedef void(* lcb_RESPCALLBACK)(lcb_t instance, int cbtype, const lcb_RESPBASE *resp)

Callback invoked for responses.

Parameters
instanceThe handle
cbtypeThe type of callback - or in other words, the type of operation this callback has been invoked for.
respThe response for the operation. Depending on the operation this response structure should be casted into a more specialized type.

Command for lcb_unlock3()

Attention
lcb_CMDBASE::cas must be specified, or the operation will fail on the server

Response structure for an unlock command.

Note
the lcb_RESPBASE::cas field does not contain the CAS of the item

Command for removing an item from the server.

Note
The lcb_CMDREMOVE::exptime field here does nothing.

The lcb_CMDREMOVE::cas field may be set to the last CAS received from a previous operation if you wish to ensure the item is removed only if it has not been mutated since the last retrieval

Response structure for removal operation.

The lcb_RESPREMOVE::cas field contains the CAS of the item which may be used to check that it no longer exists on any node's storage using the lcb_endure3_ctxnew() function.

The lcb_RESPREMOVE::rc field may be set to LCB_KEY_ENOENT if the item does not exist, or LCB_KEY_EEXISTS if a CAS was specified and the item has since been mutated.

Command structure for a touch request.

Note
The lcb_CMDTOUCH::cas field is ignored. The item's modification time is always updated regardless if the CAS on the server differs

Response structure for a touch request.

Note
the lcb_RESPTOUCH::cas field contains the current CAS of the item

Command structure for stats request The lcb_CMDSTATS::key field should contain the statistics key, or be empty if the default statistics are desired.

Structure for an observe request.

To request the status from only the master node of the key, set the LCB_CMDOBSERVE_F_MASTERONLY bit inside the lcb_CMDOBSERVE::cmdflags field

Command structure for endure.

If the lcb_CMDENDURE::cas field is specified, the operation will check and verify that the CAS found on each of the nodes matches the CAS specified and only then consider the item to be replicated and/or persisted to the nodes. If the item exists on the master's cache with a different CAS then the operation will fail

Enumeration Type Documentation

Response flags.

These provide additional 'meta' information about the response

Enumerator:
LCB_RESP_F_FINAL 

No more responses are to be received for this request.

LCB_RESP_F_CLIENTGEN 

The response was artificially generated inside the client.

This does not contain reply data from the server for the command, but rather contains the basic fields to indicate success or failure and is otherwise empty.

LCB_RESP_F_NMVGEN 

The response was a result of a not-my-vbucket error.

The type of response passed to the callback.

This is used to install callbacks for the library and to distinguish between responses if a single callback is used for multiple response types.

Note
These callbacks may conflict with the older version 2 callbacks. The rules are as follows:
  • If a callback has been installed using lcb_install_callback3(), then the older version 2 callback will not be invoked for that operation. The order of installation does not matter.
  • If the LCB_CALLBACK_DEFAULT callback is installed, none of the version 2 callbacks are invoked.
Enumerator:
LCB_CALLBACK_DEFAULT 

Default callback invoked as a fallback.

LCB_CALLBACK_GET 

lcb_get3()

LCB_CALLBACK_STORE 

lcb_store3()

LCB_CALLBACK_COUNTER 

lcb_counter3()

LCB_CALLBACK_TOUCH 

lcb_touch3()

LCB_CALLBACK_REMOVE 

lcb_remove3()

LCB_CALLBACK_UNLOCK 

lcb_unlock3()

LCB_CALLBACK_STATS 

lcb_stats3()

LCB_CALLBACK_VERSIONS 

lcb_server_versions3()

LCB_CALLBACK_VERBOSITY 

lcb_server_verbosity3()

LCB_CALLBACK_FLUSH 

lcb_flush3()

LCB_CALLBACK_OBSERVE 

lcb_observe3_ctxnew()

LCB_CALLBACK_GETREPLICA 

lcb_rget3()

LCB_CALLBACK_ENDURE 

lcb_endure3_ctxnew()

LCB_CALLBACK_HTTP 

lcb_http3()