api3.h File Reference

#include <libcouchbase/kvbuf.h>

Go to the source code of this file.

Data Structures
struct	lcb_CMDBASE
	Common ABI header for all commands. More...
struct	lcb_RESPBASE
	Base response structure for callbacks. More...
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. More...
struct	lcb_CMDGET
	Command for retrieving a single item. More...
struct	lcb_RESPGET
	Response structure when retrieving a single item. More...
struct	lcb_CMDCOUNTER
	Command for counter operations. More...
struct	lcb_RESPCOUNTER
	Response structure for counter operations. More...
struct	lcb_CMDGETREPLICA
	Command for requesting an item from a replica. More...
struct	lcb_CMDSTORE
	Command for storing an item to the server. More...
struct	lcb_RESPSTATS
	Response structure for cluster statistics. More...
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. More...
struct	lcb_RESPOBSERVE
	Response structure for an observe command. More...
struct	lcb_RESPENDURE
	Response structure for endure. More...
struct	lcb_RESPMCVERSION
	Response structure for the version command. More...
struct	lcb_CMDHTTP
	Structure for performing an HTTP request. More...

Macros
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. More...

Functions
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. More...
void	lcb_sched_leave (lcb_t instance)
	Leave the current scheduling context, scheduling the commands within the context to be flushed to the network. More...
void	lcb_sched_fail (lcb_t instance)
	Fail all commands in the current scheduling context. More...
void	lcb_sched_flush (lcb_t instance)
	Request commands to be flushed to the network. More...
Counter Operations
lcb_error_t	lcb_counter3 (lcb_t instance, const void *cookie, const lcb_CMDCOUNTER *cmd)
	Spool a single counter operation. More...
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. More...
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)

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.
#define	LCB_RESP_BASE
	Response specific flags. More...
#define	LCB_RESP_SERVER_FIELDS
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. More...
lcb_RESPCALLBACK	lcb_install_callback3 (lcb_t instance, int cbtype, lcb_RESPCALLBACK cb)
lcb_RESPCALLBACK	lcb_get_callback3 (lcb_t instance, int cbtype)

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

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

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

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. More...
typedef lcb_RESPBASE	lcb_RESPTOUCH
	Response structure for a touch request. More...
lcb_error_t	lcb_touch3 (lcb_t instance, const void *cookie, const lcb_CMDTOUCH *cmd)
	Spool a touch request. More...

Retrieve statistics from the cluster
#define	LCB_CMDSTATS_F_KV
	The key is a stored item for which statistics should be retrieved. More...
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. More...
lcb_error_t	lcb_stats3 (lcb_t instance, const void *cookie, const lcb_CMDSTATS *cmd)
	Spool a request for statistics from the cluster. More...

Retrieve replication and persistence status about an item
#define	LCB_CMDOBSERVE_F_MASTER_ONLY
	Set this bit in the cmdflags field to indicate that only the master node should be contacted.
typedef lcb_CMDBASE	lcb_CMDOBSERVE
	Structure for an observe request. More...
lcb_MULTICMD_CTX *	lcb_observe3_ctxnew (lcb_t instance)
	Create a new multi context for an observe operation. More...

Wait for items to be persisted or replicated to nodes
typedef lcb_CMDBASE	lcb_CMDENDURE
	Command structure for endure. More...
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. More...

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.
#define	LCB_CMDHTTP_F_STREAM
lcb_error_t	lcb_http3 (lcb_t instance, const void *cookie, const lcb_CMDHTTP *cmd)