Key/Value

Detailed Description

Preview APIs for performing commands.

Basic command and structure definitions for public API. This represents the "V3" API of libcouchbase. This API replaces the legacy API (which now wraps this one). It contains common definitions for scheduling, response structures and callback signatures.

Modules
	Read
	Retrieve a document from the cluster.
	Read (Replica)
	Retrieve a document from a replica if it cannot be fetched from the primary.
	Create/Update
	Set the value of a document.
	Delete
	Remove documents from the cluster.
	MULTICMD API
	Durability
	Ensure persistence and mutation of documents.
	Mutation Tokens
	Counters
	Manipulate the numeric content of a document.
	Lock/Unlock
	Touch/Expiry
	Modify or clear a document's expiration time.

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_F_INTERNAL_CALLBACK
	Flag for lcb_CMDBASE::cmdflags which indicates that the lcb_CMDBASE::cookie is a special callback object. More...
#define	LCB_CMD_SET_KEY(cmd, keybuf, keylen)
#define	LCB_CMD__SETVBID(cmd, vbid)

Receiving Responses
This section describes the APIs used in receiving responses. 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)
lcb_RESPCALLBACK	lcb_install_callback3 (lcb_t instance, int cbtype, lcb_RESPCALLBACK cb)
lcb_RESPCALLBACK	lcb_get_callback3 (lcb_t instance, int cbtype)
const char *	lcb_strcbtype (int cbtype)
#define	LCB_RESP_BASE
	Response specific flags. More...
#define	LCB_RESP_SERVER_FIELDS
#define	LCB_CALLBACK_VIEWQUERY
	Callback type for views (cannot be used for lcb_install_callback3())
#define	LCB_CALLBACK_N1QL
	Callback type for N1QL (cannot be used for lcb_install_callback3())

Function Documentation

lcb_RESPCALLBACK lcb_install_callback3	(	lcb_t	instance,
		int	cbtype,
		lcb_RESPCALLBACK	cb
	)

Stability

Committed:

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

Parameters

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

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.

The old callback may be NULL. It is usually not an error to have a NULL callback installed. If the callback is NULL, then the default callback invocation pattern will take place (as desribed above). However it is an error to set the default callback to NULL.

Examples:

example/libeventdirect/main.c, and example/minimal/minimal.c.

lcb_RESPCALLBACK lcb_get_callback3	(	lcb_t	instance,
		int	cbtype
	)

Stability

Committed:

Get the current callback installed as cbtype. Note that this does not perform any kind of resolution (as described in lcb_install_callback3) and will only return a non-NULL value if a callback had specifically been installed via lcb_install_callback3() with the given cbtype.

Parameters

instance	the handle
cbtype	the type of callback to retrieve

Returns

the installed callback for the type.

const char* lcb_strcbtype

(

int

cbtype

)

Stability

Committed:

Returns the type of the callback as a string. This function is helpful for debugging and demonstrative processes.

Parameters

cbtype

the type of the callback (the second argument to the callback)

Returns

a string describing the callback type

Examples:

example/minimal/minimal.c.

---

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_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:

struct lcb_RESPBASE

Base response structure for callbacks.

All responses structures derive from this ABI.

Examples:

example/libeventdirect/main.c, and example/minimal/minimal.c.

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

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	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 char *	server	String containing the host:port of the server which sent this response.

struct lcb_MUTATION_TOKEN

Structure representing a synchronization token.

This token may be used for durability operations and N1QL queries. The contents of this structure should be considered opaque, and accessed via the various macros

Data Fields
lcb_U64	uuid_	Use LCB_MUTATION_TOKEN_ID()
lcb_U64	seqno_	Use LCB_MUTATION_TOKEN_SEQ()
lcb_U16	vbid_	Use LCB_MUTATION_TOKEN_VB()

Macro Definition Documentation

#define LCB_CMD_F_INTERNAL_CALLBACK

Flag for lcb_CMDBASE::cmdflags which indicates that the lcb_CMDBASE::cookie is a special callback object.

This flag is used internally within the library.

#define LCB_CMD_SET_KEY	(		cmd,
			keybuf,
			keylen
	)

Stability

Committed:

Set the key for the command.

Parameters

cmd	A command derived from lcb_CMDBASE
keybuf	the buffer for the key
keylen	the length of the key.

lcb_CMDGET cmd = { 0 };
LCB_CMD_SET_KEY(&cmd, "key", strlen("key"));

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

Examples:

example/libeventdirect/main.c, and example/minimal/minimal.c.

#define LCB_CMD__SETVBID	(		cmd,
			vbid
	)

Stability

Volatile:

Sets the vBucket ID for the item. This accomplishes the same effect as hashkey except that this assumes the vBucket has already been obtained.

The intent of this API is to override the default vBucket hashing/calculation.

Parameters

cmd	the command structure
vbid	the vBucket ID for the key.

#define LCB_RESP_BASE

Response specific flags.

see lcb_RESPFLAGS

Typedef Documentation

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

Stability

Committed:

Callback invoked for responses.

Parameters

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.

Enumeration Type Documentation

enum lcb_RESPFLAGS

Response flags.

These provide additional 'meta' information about the response One of more of these values can be set in lcb_RESPBASE::rflags

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.
LCB_RESP_F_EXTDATA	The response has additional internal data. Used by lcb_resp_get_mutation_token()
LCB_RESP_F_SDSINGLE	Flag, only valid for subdoc responses, indicates that the response was processed using the single-operation protocol.

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.

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()
LCB_CALLBACK_CBFLUSH	lcb_cbflush3()
LCB_CALLBACK_OBSEQNO	For lcb_observe_seqno3()
LCB_CALLBACK_SDLOOKUP	<for lcb_storedur3()