Couchbase C Client
2.4.0_beta
|
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 | |
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_CTX * | lcb_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_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. |
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 |
lcb_RESPCALLBACK lcb_install_callback3 | ( | lcb_t | instance, |
int | cbtype, | ||
lcb_RESPCALLBACK | cb | ||
) |
Install a new-style callback for an operation. The callback will be invoked with the relevant response structure.
instance | the handle |
cbtype | the type of operation for which this callback should be installed. The value should be one of the lcb_CALLBACKTYPE constants |
cb | the callback to install |
cbtype
to LCB_CALLBACK_DEFAULT then your 2.x
callbacks will not work. void lcb_sched_enter | ( | lcb_t | instance | ) |
Enter a scheduling context.
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.
instance | the 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.
instance | the instance |
void lcb_sched_fail | ( | lcb_t | instance | ) |
Fail all commands in the current scheduling context.
The commands placed within the current scheduling context are released and are never flushed to the network.
instance |
lcb_error_t lcb_get3 | ( | lcb_t | instance, |
const void * | cookie, | ||
const lcb_CMDGET * | cmd | ||
) |
Spool a single get operation.
instance | the handle |
cookie | a pointer to be associated with the command |
cmd | the command structure |
lcb_error_t lcb_unlock3 | ( | lcb_t | instance, |
const void * | cookie, | ||
const lcb_CMDUNLOCK * | cmd | ||
) |
Unlock a previously locked item using lcb_CMDGET::lock.
instance | the instance |
cookie | the context pointer to associate with the command |
cmd | the command containing the information about the locked key |
lcb_error_t lcb_counter3 | ( | lcb_t | instance, |
const void * | cookie, | ||
const lcb_CMDCOUNTER * | cmd | ||
) |
Spool a single counter operation.
instance | the instance |
cookie | the pointer to associate with the request |
cmd | the command to use |
lcb_error_t lcb_rget3 | ( | lcb_t | instance, |
const void * | cookie, | ||
const lcb_CMDGETREPLICA * | cmd | ||
) |
Spool a single get-with-replica request.
instance | |
cookie | |
cmd |
lcb_error_t lcb_store3 | ( | lcb_t | instance, |
const void * | cookie, | ||
const lcb_CMDSTORE * | cmd | ||
) |
Spool a single storage request.
instance | the handle |
cookie | pointer to associate with the command |
cmd | the command structure |
lcb_error_t lcb_remove3 | ( | lcb_t | instance, |
const void * | cookie, | ||
const lcb_CMDREMOVE * | cmd | ||
) |
Spool a removal of an item.
instance | the handle |
cookie | pointer to associate with the request |
cmd | the command |
lcb_error_t lcb_touch3 | ( | lcb_t | instance, |
const void * | cookie, | ||
const lcb_CMDTOUCH * | cmd | ||
) |
Spool a touch request.
instance | the handle |
cookie | the pointer to associate with the request |
cmd | the command |
lcb_error_t lcb_stats3 | ( | lcb_t | instance, |
const void * | cookie, | ||
const lcb_CMDSTATS * | cmd | ||
) |
Spool a request for statistics from the cluster.
instance | the instance |
cookie | pointer to associate with the request |
cmd | the command |
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.
lcb_MULTICMD_CTX* lcb_observe3_ctxnew | ( | lcb_t | instance | ) |
Create a new multi context for an observe operation.
instance | the instance |
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.
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.
instance | the instance | |
options | a structure containing the various criteria needed for durability requirements | |
[out] | err | Error code if a new context could not be created |
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 | ||
) |
lcb_error_t lcb_server_verbosity3 | ( | lcb_t | instance, |
const void * | cookie, | ||
const lcb_CMDVERBOSITY * | cmd | ||
) |
lcb_error_t lcb_flush3 | ( | lcb_t | instance, |
const void * | cookie, | ||
const lcb_CMDFLUSH * | cmd | ||
) |
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.
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.
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.
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.
options.exptime
and options.cas
fields are ignored for this command.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:
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. |
lcb_error_t(* addcmd)(struct lcb_MULTICMD_CTX_st *ctx, const lcb_CMDBASE *cmd) |
Add a command to the current context.
ctx | the context |
cmd | the command to add. Note that cmd may be a subclass of lcb_CMDBASE |
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.
ctx | The multi context |
cookie | The cookie for all commands |
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.
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. |
#define LCB_CMD_SET_KEY | ( | cmd, | |
keybuf, | |||
keylen | |||
) |
Set the key for the command.
cmd | A command derived from lcb_CMDBASE |
keybuf | the buffer for the key |
keylen | the 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.
scmd | an lcb_CMDSTORE pointer |
valbuf | the buffer for the value |
vallen | the length of the buffer The buffer needs to remain valid only until the command is passed to the lcb_store3() function. |
typedef void(* lcb_RESPCALLBACK)(lcb_t instance, int cbtype, const lcb_RESPBASE *resp) |
Callback invoked for responses.
instance | The handle |
cbtype | The type of callback - or in other words, the type of operation this callback has been invoked for. |
resp | The response for the operation. Depending on the operation this response structure should be casted into a more specialized type. |
typedef lcb_CMDBASE lcb_CMDUNLOCK |
Command for lcb_unlock3()
typedef lcb_RESPBASE lcb_RESPUNLOCK |
Response structure for an unlock command.
typedef lcb_CMDBASE lcb_CMDREMOVE |
Command for removing an item from the server.
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
typedef lcb_RESPBASE lcb_RESPREMOVE |
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.
typedef lcb_CMDBASE lcb_CMDTOUCH |
Command structure for a touch request.
typedef lcb_RESPBASE lcb_RESPTOUCH |
Response structure for a touch request.
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.
typedef lcb_CMDBASE lcb_CMDOBSERVE |
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
typedef lcb_CMDBASE lcb_CMDENDURE |
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
enum lcb_RESPFLAGS |
Response flags.
These provide additional 'meta' information about the response
enum lcb_CALLBACKTYPE |
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.