Main header file for Couchbase. More...

#include <stddef.h>
#include <time.h>
#include <stdarg.h>
#include <stdio.h>
#include <libcouchbase/sysdefs.h>
#include <libcouchbase/assert.h>
#include <libcouchbase/visibility.h>
#include <libcouchbase/error.h>
#include <libcouchbase/iops.h>
#include <libcouchbase/http.h>
#include <libcouchbase/configuration.h>
#include <libcouchbase/kvbuf.h>
#include <libcouchbase/_cxxwrap.h>
#include <libcouchbase/subdoc.h>
#include <libcouchbase/cntl.h>
#include <libcouchbase/deprecated.h>
#include <libcouchbase/api-legacy.h>

Data Structures
struct	lcb_create_st3
	Innser structure for lcb_create(). More...

struct	lcb_create_st
	Wrapper structure for lcb_create() More...

union	lcb_create_st::lcb_CRST_u
	This union contains the set of current and historical options. More...

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_MUTATION_TOKEN
	Structure representing a synchronization token. More...

struct	lcb_CMDGET
	Command for retrieving a single item. More...

struct	lcb_RESPGET
	Response structure when retrieving a single item. 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_RESPSTORE
	Response structure for lcb_store3() 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_DURABILITYOPTSv0
	Options for lcb_endure3_ctxnew() More...

struct	lcb_durability_opts_t
	Options for lcb_endure3_ctxnew() (wrapper) More...

struct	lcb_CMDENDURE
	Command structure for endure. More...

struct	lcb_RESPENDURE
	Response structure for endure. More...

struct	lcb_CMDSTOREDUR
	Command structure for lcb_storedur3() This is much like lcb_CMDSTORE, but also includes durability options. More...

struct	lcb_RESPSTOREDUR
	Response structure for `LCB_CALLBACK_STOREDUR. More...

struct	lcb_CMDOBSERVE
	Structure for an observe request. More...

struct	lcb_RESPOBSERVE
	Response structure for an observe command. More...

struct	lcb_CMDOBSEQNO
	Command structure for lcb_observe_seqno3(). More...

struct	lcb_RESPOBSEQNO
	Response structure for lcb_observe_seqno3() More...

struct	lcb_CMDCOUNTER
	Command for counter operations. More...

struct	lcb_RESPCOUNTER
	Response structure for counter operations. More...

struct	lcb_RESPSTATS
	Response structure for cluster statistics. More...

struct	lcb_RESPMCVERSION
	Response structure for the version command. More...

struct	lcb_CMDHTTP
	Structure for performing an HTTP request. More...

struct	lcb_RESPHTTP
	Structure for HTTP responses. More...

Macros
#define	LCB_CONFIG_MCD_PORT

#define	LCB_CONFIG_MCD_SSL_PORT

#define	LCB_CONFIG_HTTP_PORT

#define	LCB_CONFIG_HTTP_SSL_PORT

#define	LCB_CONFIG_MCCOMPAT_PORT

#define	LCB_CMDGET_F_CLEAREXP
	If this bit is set in lcb_CMDGET::cmdflags then the expiry time is cleared if lcb_CMDGET::exptime is 0. More...

#define	LCB_CMD_SET_VALUE(scmd, valbuf, vallen)
	Set the value buffer for the command. This may be used when the new value is a single contiguous buffer. More...

#define	LCB_CMD_SET_VALUEIOV(scmd, iovs, niovs)
	Set value from a series of input buffers. This may be used when the input buffer is not contiguous. Using this call eliminates the need for creating a temporary contiguous buffer in which to store the value. More...

#define	LCB_MUTATION_TOKEN_ID(p)
	Get the vBucket UUID.

#define	LCB_MUTATION_TOKEN_SEQ(p)
	Get the sequence number.

#define	LCB_MUTATION_TOKEN_VB(p)
	Get the vBucket number itself.

#define	LCB_MUTATION_TOKEN_ISVALID(p)
	Whether this mutation token has valid contents.

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

#define	LCB_CMDHTTP_F_CASTMO
	If specified, the lcb_CMDHTTP::cas field becomes the timeout for this specific request.

#define	LCB_DATATYPE_JSON

#define	LCB_GETNODE_UNAVAILABLE
	String constant returned by lcb_get_node() when the LCB_NODE_NEVERNULL flag is specified, and no node can be returned.

#define	LCB_VERSION_STRING
	libcouchbase version string

#define	LCB_VERSION
	libcouchbase hex version More...

#define	LCB_VERSION_CHANGESET
	The SCM revision ID. More...

#define	LCB_SUPPORTS_SSL
	Whether the library has SSL support.

#define	LCB_SUPPORTS_SNAPPY
	Whether the library has experimental compression support.

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)

Typedefs
typedef struct lcb_st *	lcb_t
	Library handle representing a connection to a data bucket. More...

typedef struct lcb_http_request_st *	lcb_http_request_t

typedef lcb_U8	lcb_datatype_t

typedef lcb_U32	lcb_USECS

typedef void(*	lcb_bootstrap_callback) (lcb_t instance, lcb_error_t err)
	Bootstrap callback. More...

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

typedef lcb_CMDBASE	lcb_CMDUNLOCK
	Command for lcb_unlock3() More...

typedef lcb_RESPBASE	lcb_RESPUNLOCK
	Response structure for an unlock command. More...

typedef lcb_CMDBASE	lcb_CMDTOUCH
	Command structure for a touch request. More...

typedef lcb_RESPBASE	lcb_RESPTOUCH
	Response structure for a touch request. More...

typedef lcb_CMDBASE	lcb_CMDCBFLUSH

typedef lcb_RESPBASE	lcb_RESPCBFLUSH

typedef lcb_CMDBASE	lcb_CMDFLUSH

typedef lcb_RESPSERVERBASE	lcb_RESPFLUSH

typedef void(*	lcb_destroy_callback) (const void *cookie)
	Callback received when instance is about to be destroyed. More...

typedef enum lcb_timeunit_t	lcb_timeunit_t

typedef void(*	lcb_timings_callback) (lcb_t instance, const void *cookie, lcb_timeunit_t timeunit, lcb_U32 min, lcb_U32 max, lcb_U32 total, lcb_U32 maxtotal)
	The following function is called for each bucket in the timings histogram when you call lcb_get_timings. More...

typedef struct lcb_histogram_st	lcb_HISTOGRAM

typedef void(*	lcb_HISTOGRAM_CALLBACK) (const void *cookie, lcb_timeunit_t timeunit, lcb_U32 min, lcb_U32 max, lcb_U32 total, lcb_U32 maxtotal)

Enumerations
enum	lcb_type_t
	Handle types. More...

enum	lcb_replica_t
	Select get-replica mode. More...

enum	lcb_storage_t
	Values for lcb_CMDSTORE::operation. More...

enum	lcb_http_type_t
	The type of HTTP request to execute. More...

enum	lcb_http_method_t
	HTTP Request method enumeration These just enumerate the various types of HTTP request methods supported. More...

enum	lcb_WAITFLAGS
	Flags for lcb_wait3() More...

enum	lcb_GETNODETYPE
	Type of node to retrieve for the lcb_get_node() function. More...

enum	lcb_timeunit_t
	Time units reported by lcb_get_timings() More...

enum	lcb_DUMPFLAGS

Functions
lcb_error_t	lcb_create (lcb_t instance, const struct lcb_create_st options)
	Create an instance of lcb. More...

lcb_error_t	lcb_connect (lcb_t instance)
	Schedule the initial connection This function will schedule the initial connection for the handle. More...

lcb_bootstrap_callback	lcb_set_bootstrap_callback (lcb_t instance, lcb_bootstrap_callback callback)
	Set the callback for notification of success or failure of initial connection. More...

lcb_error_t	lcb_get_bootstrap_status (lcb_t instance)
	Gets the initial bootstrap status. 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_rget3 (lcb_t instance, const void cookie, const lcb_CMDGETREPLICA cmd)
	Spool a single get-with-replica request. More...

lcb_error_t	lcb_store3 (lcb_t instance, const void cookie, const lcb_CMDSTORE cmd)
	Schedule a single storage request. More...

lcb_error_t	lcb_remove3 (lcb_t instance, const void cookie, const lcb_CMDREMOVE cmd)
	Spool a removal of an item. More...

const lcb_MUTATION_TOKEN *	lcb_resp_get_mutation_token (int cbtype, const lcb_RESPBASE *rb)
	Retrieves the mutation token from the response structure. More...

const lcb_MUTATION_TOKEN *	lcb_get_mutation_token (lcb_t instance, const lcb_KEYBUF kb, lcb_error_t errp)

lcb_error_t	lcb_counter3 (lcb_t instance, const void cookie, const lcb_CMDCOUNTER cmd)
	Schedule single counter 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...

lcb_error_t	lcb_touch3 (lcb_t instance, const void cookie, const lcb_CMDTOUCH cmd)
	Spool a touch request. More...

lcb_error_t	lcb_cbflush3 (lcb_t instance, const void cookie, const lcb_CMDCBFLUSH cmd)
	uncommitted More...

lcb_error_t	lcb_flush3 (lcb_t instance, const void cookie, const lcb_CMDFLUSH cmd)

lcb_error_t	lcb_http3 (lcb_t instance, const void cookie, const lcb_CMDHTTP cmd)

void	lcb_cancel_http_request (lcb_t instance, lcb_http_request_t request)
	Cancel ongoing HTTP request. More...

void	lcb_set_cookie (lcb_t instance, const void *cookie)
	Associate a cookie with an instance of lcb. More...

const void *	lcb_get_cookie (lcb_t instance)
	Retrieve the cookie associated with this instance. More...

lcb_error_t	lcb_wait (lcb_t instance)
	Wait for the execution of all batched requests. More...

lcb_error_t	lcb_tick_nowait (lcb_t instance)

void	lcb_wait3 (lcb_t instance, lcb_WAITFLAGS flags)
	Wait for completion of scheduled operations. More...

void	lcb_breakout (lcb_t instance)
	Forcefully break from the event loop. More...

int	lcb_is_waiting (lcb_t instance)
	Check if instance is blocked in the event loop. More...

void	lcb_refresh_config (lcb_t instance)
	Force the library to refetch the cluster configuration. More...

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

void	lcb_destroy (lcb_t instance)
	Destroy (and release all allocated resources) an instance of lcb. More...

lcb_destroy_callback	lcb_set_destroy_callback (lcb_t, lcb_destroy_callback)
	Set the callback to be invoked when the instance is destroyed asynchronously. More...

void	lcb_destroy_async (lcb_t instance, const void *arg)
	Asynchronously schedule the destruction of an instance. More...

const char *	lcb_get_node (lcb_t instance, lcb_GETNODETYPE type, unsigned index)
	Return a string of `host:port` for a node of the given type. More...

const char *	lcb_get_keynode (lcb_t instance, const void *key, size_t nkey)
	Get the target server for a given key. More...

lcb_S32	lcb_get_num_replicas (lcb_t instance)
	Get the number of the replicas in the cluster. More...

lcb_S32	lcb_get_num_nodes (lcb_t instance)
	Get the number of the nodes in the cluster. More...

const char const	lcb_get_server_list (lcb_t instance)
	Get a list of nodes in the cluster. More...

void	lcb_dump (lcb_t instance, FILE *fp, lcb_U32 flags)
	Write a textual dump to a file. More...

lcb_error_t	lcb_cntl (lcb_t instance, int mode, int cmd, void *arg)
	This function exposes an ioctl/fcntl-like interface to read and write various configuration properties to and from an lcb_t handle. More...

lcb_error_t	lcb_cntl_string (lcb_t instance, const char key, const char value)
	Alternate way to set configuration settings by passing a string key and value. More...

lcb_error_t	lcb_cntl_setu32 (lcb_t instance, int cmd, lcb_U32 arg)
	Convenience function to set a value as an lcb_U32. More...

lcb_U32	lcb_cntl_getu32 (lcb_t instance, int cmd)
	Retrieve an lcb_U32 setting. More...

int	lcb_cntl_exists (int ctl)
	Determine if a specific control code exists. More...

lcb_error_t	lcb_enable_timings (lcb_t instance)
	Start recording timing metrics for the different operations. More...

lcb_error_t	lcb_disable_timings (lcb_t instance)
	Stop recording (and release all resources from previous measurements) timing metrics. More...

lcb_error_t	lcb_get_timings (lcb_t instance, const void *cookie, lcb_timings_callback callback)
	Get the timings histogram. More...

const char *	lcb_get_version (lcb_U32 *version)
	Get the version of the library. More...

int	lcb_supports_feature (int n)

void *	lcb_mem_alloc (lcb_SIZE size)
	Functions to allocate and free memory related to libcouchbase. More...

void	lcb_mem_free (void *ptr)
	Use this to free memory allocated with lcb_mem_alloc.

LCB_INTERNAL_API void	lcb_histogram_print (lcb_HISTOGRAM hg, FILE stream)
	Print the histogram to the specified FILE. More...

Server Versions
Warning This does not return the actual Couchbase version but rather the internal version of the memcached server.
lcb_error_t	lcb_server_versions3 (lcb_t instance, const void cookie, const lcb_CMDBASE cmd)

Variables
LCB_EXTERN_VAR const lcb_U32	lcb_version_g
	Global/extern variable containing the version of the library.

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.
#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())

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)

Wait for a mutation to be persisted/replicated
#define	LCB_CMDENDURE_F_MUTATION_TOKEN
	Must specify this flag if using the 'mutation_token' field, as it was added in a later version.

#define	LCB_DURABILITY_VALIDATE_CAPMAX

enum	lcb_DURMODE
	Type of durability polling to use. 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...

lcb_error_t	lcb_storedur3 (lcb_t instance, const void cookie, const lcb_CMDSTOREDUR cmd)

lcb_error_t	lcb_durability_validate (lcb_t instance, lcb_U16 persist_to, lcb_U16 replicate_to, int options)

Retrieve current persistence/replication status
#define	LCB_CMDOBSERVE_F_MASTER_ONLY
	Set this bit in the cmdflags field to indicate that only the master node should be contacted.

enum	lcb_observe_t
	Possible statuses for keys in OBSERVE response. More...

lcb_MULTICMD_CTX *	lcb_observe3_ctxnew (lcb_t instance)
	Create a new multi context for an observe operation. More...

lcb_error_t	lcb_observe_seqno3 (lcb_t instance, const void cookie, const lcb_CMDOBSEQNO cmd)
	Get the persistence/replication status for a given mutation token. More...

Server Statistics
#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)
	Schedule a request for statistics from the cluster. More...

Server Log Verbosity
enum	lcb_verbosity_level_t
	`level` field for lcb_server_verbosity3 ()

typedef lcb_RESPSERVERBASE	lcb_RESPVERBOSITY

lcb_error_t	lcb_server_verbosity3 (lcb_t instance, const void cookie, const lcb_CMDVERBOSITY cmd)

Detailed Description

Main header file for Couchbase.

Enumeration Type Documentation

enum lcb_DUMPFLAGS

Enumerator
LCB_DUMP_VBCONFIG	Dump the raw vbucket configuration.
LCB_DUMP_PKTINFO	Dump information about each packet.
LCB_DUMP_BUFINFO	Dump memory usage/reservation information about buffers.
LCB_DUMP_ALL	Dump everything.

Function Documentation

void lcb_refresh_config ( lcb_t instance )

Force the library to refetch the cluster configuration.

Stability

Uncommitted:

The library by default employs various heuristics to determine if a new configuration is needed from the cluster. However there are some situations in which an application may wish to force a refresh of the configuration:

If a specific node has been failed over and the library has received a configuration in which there is no master node for a given key, the library will immediately return the error LCB_NO_MATCHING_SERVER for the given item and will not request a new configuration. In this state, the client will not perform any network I/O until a request has been made to it using a key that is mapped to a known active node.
The library's heuristics may have failed to detect an error warranting a configuration change, but the application either through its own heuristics, or through an out-of-band channel knows that the configuration has changed.

This function is provided as an aid to assist in such situations

If you wish for your application to block until a new configuration is received, you must call lcb_wait3() with the LCB_WAIT_NO_CHECK flag as this function call is not bound to a specific operation. Additionally there is no status notification as to whether this operation succeeded or failed (the configuration callback via lcb_set_configuration_callback() may provide hints as to whether a configuration was received or not, but by no means should be considered to be part of this function's control flow).

In general the use pattern of this function is like so:

unsigned retries = 5;
lcb_error_t err;
do {
  retries--;
  err = lcb_get(instance, cookie, ncmds, cmds);
  if (err == LCB_NO_MATCHING_SERVER) {
    lcb_refresh_config(instance);
    usleep(100000);
    lcb_wait3(instance, LCB_WAIT_NO_CHECK);
  } else {
    break;
  }
} while (retries);
if (err == LCB_SUCCESS) {
  lcb_wait3(instance, 0); // equivalent to lcb_wait(instance);
} else {
  printf("Tried multiple times to fetch the key, but its node is down\n");
}

void* lcb_mem_alloc ( lcb_SIZE size )

Functions to allocate and free memory related to libcouchbase.

This is mainly for use on Windows where it is possible that the DLL and EXE are using two different CRTs

LCB_INTERNAL_API void lcb_histogram_print	(	lcb_HISTOGRAM *	hg,
		FILE *	stream
	)

Print the histogram to the specified FILE.

This essentially outputs the same raw information as lcb_histogram_read(), except it prints in implementation-defined format. It's simpler to use than lcb_histogram_read, but less flexible.

Parameters

hg	the histogram
stream	File to print the histogram to.

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Receiving Responses

Wait for a mutation to be persisted/replicated

Retrieve current persistence/replication status

Server Statistics

Server Log Verbosity

Detailed Description

Enumeration Type Documentation

Function Documentation