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.
	Open Bucket
	Open bucket in cluster.
	Remove
	Remove documents.
	Counters
	Manipulate the numeric content of a document.

Functions
int	lcb_mutation_token_is_valid (const lcb_MUTATION_TOKEN *token)
lcb_RESPCALLBACK	lcb_install_callback (lcb_INSTANCE *instance, int cbtype, lcb_RESPCALLBACK cb)
lcb_RESPCALLBACK	lcb_get_callback (lcb_INSTANCE *instance, int cbtype)
const char *	lcb_strcbtype (int cbtype)
	Returns the type of the callback as a string.
lcb_STATUS	lcb_respexists_status (const lcb_RESPEXISTS *resp)
int	lcb_respexists_is_found (const lcb_RESPEXISTS *resp)
lcb_STATUS	lcb_respexists_error_context (const lcb_RESPEXISTS *resp, const lcb_KEY_VALUE_ERROR_CONTEXT **ctx)
lcb_STATUS	lcb_respexists_cookie (const lcb_RESPEXISTS *resp, void **cookie)
lcb_STATUS	lcb_respexists_cas (const lcb_RESPEXISTS *resp, uint64_t *cas)
lcb_STATUS	lcb_respexists_key (const lcb_RESPEXISTS *resp, const char **key, size_t *key_len)
lcb_STATUS	lcb_cmdexists_create (lcb_CMDEXISTS **cmd)
lcb_STATUS	lcb_cmdexists_destroy (lcb_CMDEXISTS *cmd)
lcb_STATUS	lcb_cmdexists_parent_span (lcb_CMDEXISTS *cmd, lcbtrace_SPAN *span)
lcb_STATUS	lcb_cmdexists_collection (lcb_CMDEXISTS *cmd, const char *scope, size_t scope_len, const char *collection, size_t collection_len)
lcb_STATUS	lcb_cmdexists_key (lcb_CMDEXISTS *cmd, const char *key, size_t key_len)
lcb_STATUS	lcb_cmdexists_timeout (lcb_CMDEXISTS *cmd, uint32_t timeout)
lcb_STATUS	lcb_cmdexists_on_behalf_of (lcb_CMDEXISTS *cmd, const char *data, size_t data_len)
lcb_STATUS	lcb_cmdexists_on_behalf_of_extra_privilege (lcb_CMDEXISTS *cmd, const char *privilege, size_t privilege_len)
lcb_STATUS	lcb_exists (lcb_INSTANCE *instance, void *cookie, const lcb_CMDEXISTS *cmd)
lcb_STATUS	lcb_respunlock_status (const lcb_RESPUNLOCK *resp)
lcb_STATUS	lcb_respunlock_error_context (const lcb_RESPUNLOCK *resp, const lcb_KEY_VALUE_ERROR_CONTEXT **ctx)
lcb_STATUS	lcb_respunlock_cookie (const lcb_RESPUNLOCK *resp, void **cookie)
lcb_STATUS	lcb_respunlock_cas (const lcb_RESPUNLOCK *resp, uint64_t *cas)
lcb_STATUS	lcb_respunlock_key (const lcb_RESPUNLOCK *resp, const char **key, size_t *key_len)
lcb_STATUS	lcb_cmdunlock_create (lcb_CMDUNLOCK **cmd)
lcb_STATUS	lcb_cmdunlock_destroy (lcb_CMDUNLOCK *cmd)
lcb_STATUS	lcb_cmdunlock_parent_span (lcb_CMDUNLOCK *cmd, lcbtrace_SPAN *span)
lcb_STATUS	lcb_cmdunlock_collection (lcb_CMDUNLOCK *cmd, const char *scope, size_t scope_len, const char *collection, size_t collection_len)
lcb_STATUS	lcb_cmdunlock_key (lcb_CMDUNLOCK *cmd, const char *key, size_t key_len)
lcb_STATUS	lcb_cmdunlock_cas (lcb_CMDUNLOCK *cmd, uint64_t cas)
lcb_STATUS	lcb_cmdunlock_timeout (lcb_CMDUNLOCK *cmd, uint32_t timeout)
lcb_STATUS	lcb_cmdunlock_on_behalf_of (lcb_CMDUNLOCK *cmd, const char *data, size_t data_len)
lcb_STATUS	lcb_cmdunlock_on_behalf_of_extra_privilege (lcb_CMDUNLOCK *cmd, const char *privilege, size_t privilege_len)
lcb_STATUS	lcb_unlock (lcb_INSTANCE *instance, void *cookie, const lcb_CMDUNLOCK *cmd)

Macros
#define	LCB_CALLBACK_VIEWQUERY
	Callback type for views (cannot be used for lcb_install_callback3())
#define	LCB_CALLBACK_QUERY
	Callback type for N1QL (cannot be used for lcb_install_callback3())
#define	LCB_CALLBACK_IXMGMT
	Callback type for N1QL index management (cannot be used for lcb_install_callback3())
#define	LCB_CALLBACK_ANALYTICS
	Callback type for Analytics (cannot be used for lcb_install_callback3())
#define	LCB_CALLBACK_SEARCH
	Callback type for Search (cannot be used for lcb_install_callback3())
#define	LCB_CALLBACK_OPEN

Typedefs
typedef void	lcb_CMDBASE
typedef void	lcb_RESPBASE
typedef void(*	lcb_RESPCALLBACK) (lcb_INSTANCE *instance, int cbtype, const lcb_RESPBASE *resp)
	Callback invoked for responses.
typedef struct lcb_RESPEXISTS_	lcb_RESPEXISTS
typedef struct lcb_CMDEXISTS_	lcb_CMDEXISTS
typedef struct lcb_RESPUNLOCK_	lcb_RESPUNLOCK
	Unlock a previously locked item using lcb_cmdunlock.
typedef struct lcb_CMDUNLOCK_	lcb_CMDUNLOCK

Enumerations
enum	lcb_RESPFLAGS
	Response flags. More...
enum	lcb_CALLBACK_TYPE
	The type of response passed to the callback. More...
enum	lcb_DURABILITY_LEVEL

Function Documentation

lcb_install_callback()

lcb_RESPCALLBACK lcb_install_callback	(	lcb_INSTANCE *	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_CALLBACK_TYPE 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, example/minimal/minimal.c, example/minimal/query.c, example/subdoc/subdoc-xattrs.c, and example/tracing/tracing.c.

lcb_get_callback()

lcb_RESPCALLBACK lcb_get_callback	(	lcb_INSTANCE *	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.

lcb_strcbtype()

const char * lcb_strcbtype

(

int

cbtype

)

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/crypto/openssl_symmetric_decrypt.c, example/crypto/openssl_symmetric_encrypt.c, example/minimal/minimal.c, example/minimal/query.c, and example/tracing/tracing.c.

lcb_cmdexists_on_behalf_of()

lcb_STATUS lcb_cmdexists_on_behalf_of	(	lcb_CMDEXISTS *	cmd,
		const char *	data,
		size_t	data_len
	)

Stability

Internal:

Internal: This should never be used and is not supported.

lcb_cmdexists_on_behalf_of_extra_privilege()

lcb_STATUS lcb_cmdexists_on_behalf_of_extra_privilege	(	lcb_CMDEXISTS *	cmd,
		const char *	privilege,
		size_t	privilege_len
	)

Stability

Internal:

Internal: This should never be used and is not supported.

lcb_cmdunlock_on_behalf_of()

lcb_STATUS lcb_cmdunlock_on_behalf_of	(	lcb_CMDUNLOCK *	cmd,
		const char *	data,
		size_t	data_len
	)

Stability

Internal:

Internal: This should never be used and is not supported.

lcb_cmdunlock_on_behalf_of_extra_privilege()

lcb_STATUS lcb_cmdunlock_on_behalf_of_extra_privilege	(	lcb_CMDUNLOCK *	cmd,
		const char *	privilege,
		size_t	privilege_len
	)

Stability

Internal:

Internal: This should never be used and is not supported.

Typedef Documentation

lcb_RESPCALLBACK

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

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.

Examples

example/libeventdirect/main.c, example/minimal/minimal.c, example/minimal/query.c, example/subdoc/subdoc-xattrs.c, and example/tracing/tracing.c.

lcb_RESPUNLOCK

typedef struct lcb_RESPUNLOCK_ lcb_RESPUNLOCK

Unlock a previously locked item using lcb_cmdunlock.

Stability

Committed:

Parameters

instance	the instance
cookie	the context pointer to associate with the command
cmd	the command containing the information about the locked key

Returns

LCB_SUCCESS if successful, an error code otherwise Note that you must specify the cas of the item to unlock it, and the only way to get that cas is in the callback of the lock call. Outside that, the server will respond with a dummy cas if, for instance, you do a lcb_get.

See also

lcb_get()

void locked_callback(lcb_INSTANCE, lcb_CALLBACK_TYPE, const lcb_RESPBASE *rb) {
  const lcb_RESPGET* resp = (const lcb_RESPLOCK*)rb;
  lcb_CMDUNLOCK* cmd;
  char* key;
  size_t key_len;
  unit64_t cas;
  lcb_respget_cas(resp, &cas);
  lcb_respget_key(resp, &key, &key_len);
  lcb_cmdunlock_create(&cmd);
  lcb_cmdunlock_key(cmd, key, key_len);
  lcb_cmdunlock_cas(cmd, cas);
  lcb_unlock(instance, cookie, cmd);
}

Enumeration Type Documentation

lcb_RESPFLAGS

enum lcb_RESPFLAGS

Response flags.

These provide additional 'meta' information about the response They can be read from the response object with a call like lcb_respXXX_flags, where the XXX is the operation – like get, exists, store, etc... There is also a lcb_respXXX_is_final method which reads the LCB_RESP_F_FINAL flag for those operations that execute the callback multiple times.

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.
LCB_RESP_F_ERRINFO	The response has extra error information as value (see SDK-RFC-28).

lcb_CALLBACK_TYPE

enum lcb_CALLBACK_TYPE

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_get()
LCB_CALLBACK_STORE	lcb_store()
LCB_CALLBACK_COUNTER	lcb_counter()
LCB_CALLBACK_TOUCH	lcb_touch()
LCB_CALLBACK_REMOVE	lcb_remove()
LCB_CALLBACK_UNLOCK	lcb_unlock()
LCB_CALLBACK_STATS	lcb_stats3()
LCB_CALLBACK_VERSIONS	lcb_server_versions()
LCB_CALLBACK_VERBOSITY	lcb_server_verbosity()
LCB_CALLBACK_OBSERVE	lcb_observe3_ctxnew()
LCB_CALLBACK_GETREPLICA	lcb_getreplica()
LCB_CALLBACK_ENDURE	lcb_endure3_ctxnew()
LCB_CALLBACK_HTTP	lcb_http()
LCB_CALLBACK_CBFLUSH	lcb_cbflush3()
LCB_CALLBACK_OBSEQNO	For lcb_observe_seqno3()
LCB_CALLBACK_SDLOOKUP	<for lcb_storedur3()
LCB_CALLBACK_NOOP	lcb_noop3()
LCB_CALLBACK_PING	lcb_ping3()
LCB_CALLBACK_DIAG	lcb_diag()
LCB_CALLBACK_COLLECTIONS_GET_MANIFEST	lcb_getmanifest()
LCB_CALLBACK_GETCID	lcb_getcid()
LCB_CALLBACK_EXISTS	lcb_exists()

lcb_DURABILITY_LEVEL

enum lcb_DURABILITY_LEVEL

Stability

Uncommitted:

Durability levels

Enumerator
LCB_DURABILITYLEVEL_MAJORITY	Mutation must be replicated to (i.e. held in memory of that node) a majority ((configured_nodes / 2) + 1) of the configured nodes of the bucket.
LCB_DURABILITYLEVEL_MAJORITY_AND_PERSIST_TO_ACTIVE	As majority, but additionally persisted to the active node.
LCB_DURABILITYLEVEL_PERSIST_TO_MAJORITY	Mutation must be persisted to (i.e. written and fsync'd to disk) a majority of the configured nodes of the bucket.