couchbase.h File Reference

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/_cxxwrap.h>
#include <libcouchbase/cntl.h>
#include <libcouchbase/deprecated.h>

Go to the source code of this file.

Data Structures
struct	lcb_create_st3
	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_IOCREATEOPTS_BUILTIN
	IO Creation for builtin plugins. More...
struct	lcb_create_io_ops_st
	uncommitted More...
struct	lcb_GETCMDv0
	Get Command Structure. More...
struct	lcb_get_cmd_t
	lcb_get() Command Wrapper Structure More...
struct	lcb_GETRESPv0
	Inner response structure for a get operation. More...
struct	lcb_get_resp_t
	lcb_get() response wrapper structure More...
struct	lcb_GETREPLICACMDv1
	Command for lcb_get_replica() More...
struct	lcb_get_replica_cmd_t
	wrapper structure for lcb_get_replica() More...
struct	lcb_UNLOCKCMDv0
	lcb_unlock() Command structure More...
struct	lcb_unlock_cmd_t
	lcb_unlock() Wrapper structure More...
struct	lcb_UNLOCKRESPv0
	lcb_unlock() response structure More...
struct	lcb_unlock_resp_t
	lcb_unlock() wrapper response structure More...
struct	lcb_STORECMDv0
	lcb_store() Command structure More...
struct	lcb_store_cmd_t
	Wrapper structure for lcb_STORECMDv0. More...
struct	lcb_store_resp_t
	Wrapper structure for lcb_STORERESPv0. More...
struct	lcb_ARITHCMDv0
	Command structure for arithmetic operations This is contained within the lcb_arithmetic_cmd_t structure. More...
struct	lcb_arithmetic_cmd_t
	Wrapper structure for lcb_ARITHCMDv0. More...
struct	lcb_OBSERVECMDv1
	lcb_observe() Command structure More...
struct	lcb_observe_cmd_t
	lcb_observe() Command wrapper structure More...
struct	lcb_OBSERVERESPv0
	Response Structure for lcb_observe() More...
struct	lcb_DURABILITYCMDv0
	Single-key command structure for lcb_durability_poll() More...
struct	lcb_durability_cmd_t
	lcb_durability_poll() Command wrapper More...
struct	lcb_DURABILITYOPTSv0
	Options for lcb_durability_poll() More...
struct	lcb_durability_opts_t
	Options for lcb_durability_poll() (wrapper) More...
struct	lcb_DURABILITYRESPv0
	Response structure for lcb_durability_poll() More...
struct	lcb_STATSRESPv0
	Per-server, per-stat response structure for lcb_server_stats() More...
struct	lcb_server_stat_resp_t
	Wrapper structure for lcb_STATSRESPv0. More...
struct	lcb_server_version_resp_t
	Response structure for lcb_server_versions() More...
struct	lcb_HTTPCMDv0
	Structure for lcb_make_http_request() More...
struct	lcb_HTTPCMDv1
	v1 is used by the raw http requests. More...
struct	lcb_http_cmd_t
	Wrapper structure for lcb_make_http_request. More...
struct	lcb_HTTPRESPv0
	Response structure received for HTTP requests. More...
union	lcb_arithmetic_cmd_t.v
	Wrapper union for lcb_ARITHCMDv0. 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_CREATEOPT_INIT(cropt, s, iops)
#define	LCB__HKFIELDS
	Note that hashkey/groupid is not a supported feature of Couchbase Server and this client. More...
#define	LCB_DATATYPE_JSON
	Value is JSON.
#define	LCB_OBSERVE_FIELDS_COMMON
#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.

Typedefs
typedef struct lcb_st *	lcb_t
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 void(*	lcb_destroy_callback )(const void *cookie)
	Callback received when instance is about to be destroyed. More...
typedef void(*	lcb_get_callback )(lcb_t instance, const void *cookie, lcb_error_t error, const lcb_get_resp_t *resp)
	The callback function for a "get-style" request. More...
typedef void(*	lcb_unlock_callback )(lcb_t instance, const void *cookie, lcb_error_t error, const lcb_unlock_resp_t *resp)
	The callback function for an unlock request. More...
typedef void(*	lcb_store_callback )(lcb_t instance, const void *cookie, lcb_storage_t operation, lcb_error_t error, const lcb_store_resp_t *resp)
	The callback function for a storage request. More...
typedef void(*	lcb_arithmetic_callback )(lcb_t instance, const void *cookie, lcb_error_t error, const lcb_arithmetic_resp_t *resp)
	The callback function for an arithmetic request. More...
typedef void(*	lcb_observe_callback )(lcb_t instance, const void *cookie, lcb_error_t error, const lcb_observe_resp_t *resp)
	The callback function for an observe request. More...
typedef void(*	lcb_remove_callback )(lcb_t instance, const void *cookie, lcb_error_t error, const lcb_remove_resp_t *resp)
	The callback function for a remove request. More...
typedef lcb_get_cmd_t	lcb_touch_cmd_t
typedef void(*	lcb_touch_callback )(lcb_t instance, const void *cookie, lcb_error_t error, const lcb_touch_resp_t *resp)
	The callback function for a touch request. More...
typedef void(*	lcb_durability_callback )(lcb_t instance, const void *cookie, lcb_error_t err, const lcb_durability_resp_t *res)
	Callback for durability status. More...
typedef void(*	lcb_stat_callback )(lcb_t instance, const void *cookie, lcb_error_t error, const lcb_server_stat_resp_t *resp)
	The callback function for a stat request. More...
typedef void(*	lcb_version_callback )(lcb_t instance, const void *cookie, lcb_error_t error, const lcb_server_version_resp_t *resp)
	The callback function for a version request. More...
typedef void(*	lcb_verbosity_callback )(lcb_t instance, const void *cookie, lcb_error_t error, const lcb_verbosity_resp_t *resp)
	The callback function for a verbosity command. More...
typedef void(*	lcb_flush_callback )(lcb_t instance, const void *cookie, lcb_error_t error, const lcb_flush_resp_t *resp)
	The callback function for a flush request. More...
typedef void(*	lcb_http_res_callback )(lcb_http_request_t request, lcb_t instance, const void *cookie, lcb_error_t error, const lcb_http_resp_t *resp)
	Callback invoked for HTTP requests. More...
typedef lcb_http_res_callback	lcb_http_data_callback
typedef lcb_http_res_callback	lcb_http_complete_callback
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 lcb_error_t(*	lcb_errmap_callback )(lcb_t instance, lcb_U16 bincode)
	Callback for error mappings. More...

Enumerations
enum	lcb_WAITFLAGS
	Flags for lcb_wait3() More...
enum	lcb_io_ops_type_t
	Built-in I/O plugins. More...
enum	lcb_VALUEFLAGS
	Flags which can be returned int the the lcb_GETRESPv0::datatype field. More...
enum	lcb_replica_t
	Select get-replica mode. More...
enum	lcb_storage_t
	operation parameter for lcb_store() More...
enum	lcb_observe_options_t
enum	lcb_observe_t
	Possible statuses for keys in OBSERVE response. More...
enum	lcb_verbosity_level_t
	level field for lcb_set_verbosity() 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_timeunit_t
	Time units reported by lcb_get_timings() More...
enum	lcb_DUMPFLAGS

Functions
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...
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...
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...
void	lcb_refresh_config (lcb_t instance)
	Force the library to refetch the cluster configuration. 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...
lcb_error_t	lcb_create_io_ops (lcb_io_opt_t *op, const struct lcb_create_io_ops_st *options)
	Create a new instance of one of the library-supplied io ops types. More...
lcb_error_t	lcb_destroy_io_ops (lcb_io_opt_t op)
	Destroy the plugin handle created by lcb_create_io_ops() More...
lcb_get_callback	lcb_set_get_callback (lcb_t, lcb_get_callback callback)
	Set the callback to be invoked when an item is received as a result of an lcb_get() operation. More...
lcb_error_t	lcb_get (lcb_t instance, const void *command_cookie, lcb_SIZE num, const lcb_get_cmd_t *const *commands)
	Get a number of values from the cache. More...
lcb_error_t	lcb_get_replica (lcb_t instance, const void *command_cookie, lcb_SIZE num, const lcb_get_replica_cmd_t *const *commands)
	Get a number of replca values from the cache. More...
lcb_unlock_callback	lcb_set_unlock_callback (lcb_t, lcb_unlock_callback)
lcb_error_t	lcb_unlock (lcb_t instance, const void *command_cookie, lcb_SIZE num, const lcb_unlock_cmd_t *const *commands)
	Unlock the key locked with lcb_get() with the lcb_GETCMDv0::lock option. More...
lcb_store_callback	lcb_set_store_callback (lcb_t, lcb_store_callback callback)
	Set the callback to be received when an item has been stored. More...
lcb_error_t	lcb_store (lcb_t instance, const void *command_cookie, lcb_SIZE num, const lcb_store_cmd_t *const *commands)
	Store an item in the cluster. More...
lcb_arithmetic_callback	lcb_set_arithmetic_callback (lcb_t, lcb_arithmetic_callback)
lcb_error_t	lcb_arithmetic (lcb_t instance, const void *command_cookie, lcb_SIZE num, const lcb_arithmetic_cmd_t *const *commands)
	Perform arithmetic operation on a keys value. More...
lcb_observe_callback	lcb_set_observe_callback (lcb_t, lcb_observe_callback)
lcb_error_t	lcb_observe (lcb_t instance, const void *command_cookie, lcb_SIZE num, const lcb_observe_cmd_t *const *commands)
	Observe key. More...
lcb_remove_callback	lcb_set_remove_callback (lcb_t, lcb_remove_callback)
lcb_error_t	lcb_remove (lcb_t instance, const void *command_cookie, lcb_SIZE num, const lcb_remove_cmd_t *const *commands)
	Remove a key from the cluster. More...
lcb_touch_callback	lcb_set_touch_callback (lcb_t, lcb_touch_callback)
lcb_error_t	lcb_touch (lcb_t instance, const void *cookie, lcb_SIZE num, const lcb_touch_cmd_t *const *commands)
	Touch (set expiration time) on a number of values in the cache. More...
lcb_error_t	lcb_durability_poll (lcb_t instance, const void *cookie, const lcb_durability_opts_t *options, lcb_SIZE ncmds, const lcb_durability_cmd_t *const *cmds)
	Schedule a durability check on a set of keys. More...
lcb_durability_callback	lcb_set_durability_callback (lcb_t, lcb_durability_callback)
lcb_stat_callback	lcb_set_stat_callback (lcb_t, lcb_stat_callback)
lcb_error_t	lcb_server_stats (lcb_t instance, const void *command_cookie, lcb_SIZE num, const lcb_server_stats_cmd_t *const *commands)
	Request server statistics. More...
lcb_error_t	lcb_server_versions (lcb_t instance, const void *command_cookie, lcb_SIZE num, const lcb_server_version_cmd_t *const *commands)
	Request server versions. More...
lcb_version_callback	lcb_set_version_callback (lcb_t, lcb_version_callback)
lcb_error_t	lcb_set_verbosity (lcb_t instance, const void *command_cookie, lcb_SIZE num, const lcb_verbosity_cmd_t *const *commands)
	Set the loglevel on the servers. More...
lcb_verbosity_callback	lcb_set_verbosity_callback (lcb_t, lcb_verbosity_callback)
lcb_error_t	lcb_flush (lcb_t instance, const void *cookie, lcb_SIZE num, const lcb_flush_cmd_t *const *commands)
	Flush the entire couchbase cluster! More...
lcb_flush_callback	lcb_set_flush_callback (lcb_t, lcb_flush_callback)
lcb_http_complete_callback	lcb_set_http_complete_callback (lcb_t, lcb_http_complete_callback)
	Set the HTTP completion callback for HTTP request completion. More...
lcb_http_data_callback	lcb_set_http_data_callback (lcb_t, lcb_http_data_callback)
	Set the HTTP data stream callback for streaming responses. More...
lcb_error_t	lcb_make_http_request (lcb_t instance, const void *command_cookie, lcb_http_type_t type, const lcb_http_cmd_t *cmd, lcb_http_request_t *request)
	Execute HTTP request matching given path and yield JSON result object. More...
void	lcb_cancel_http_request (lcb_t instance, lcb_http_request_t request)
	Cancel ongoing HTTP request. More...
int	lcb_is_waiting (lcb_t instance)
	Check if instance is blocked in the event loop. 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)
lcb_error_t	lcb_errmap_default (lcb_t instance, lcb_U16 code)
	This may be used in conjunction with the errmap callback if it wishes to fallback for default behavior for the given code. More...
lcb_errmap_callback	lcb_set_errmap_callback (lcb_t, lcb_errmap_callback)
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_run_loop (lcb_t instance)
	These two functions unconditionally start and stop the event loop. More...
LCB_INTERNAL_API void	lcb_stop_loop (lcb_t instance)
void	lcb_dump (lcb_t instance, FILE *fp, lcb_U32 flags)
	Write a textual dump to a file. More...
Modifying Settings
The lcb_cntl() function and its various helpers are the means by which to modify settings within the library
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...

Creating A Library Handle
These structures contain the various options passed to the lcb_create() function.
enum	lcb_type_t
	Handle types. More...
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...

Information about Nodes
#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.
enum	lcb_GETNODETYPE
	Type of node to retrieve for the lcb_get_node() function. 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...
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...

Detailed Description

Main header file for Couchbase.

Macro Definition Documentation

#define LCB__HKFIELDS

Note that hashkey/groupid is not a supported feature of Couchbase Server and this client.

It should be considered volatile and experimental. Using this could lead to an unbalanced cluster, inability to interoperate with the data from other languages, not being able to use the Couchbase Server UI to look up documents and other possible future upgrade/migration concerns.

Typedef Documentation

typedef lcb_error_t(* lcb_errmap_callback)(lcb_t instance, lcb_U16 bincode)

Callback for error mappings.

This will be invoked when requesting whether the user has a possible mapping for this error code.

This will be called for response codes which may be ambiguous in most use cases, or in cases where detailed response codes may be mapped to more generic ones.

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

lcb_error_t lcb_errmap_default	(	lcb_t	instance,
		lcb_U16	code
	)

This may be used in conjunction with the errmap callback if it wishes to fallback for default behavior for the given code.

uncommitted

lcb_errmap_callback lcb_set_errmap_callback	(	lcb_t	,
		lcb_errmap_callback
	)

Stability

Uncommitted:

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_run_loop

(

lcb_t

instance

)

These two functions unconditionally start and stop the event loop.

These should be used only when necessary. Use lcb_wait and lcb_breakout for safer variants.

Internally these proxy to the run_event_loop/stop_event_loop calls

void lcb_dump	(	lcb_t	instance,
		FILE *	fp,
		lcb_U32	flags
	)

Write a textual dump to a file.

Stability

Volatile:

This function will inspect the various internal structures of the current client handle (indicated by instance) and write the state information to the file indicated by fp.

Parameters

instance	the handle to dump
fp	the file to which the dump should be written
flags	a set of modifiers (of lcb_DUMPFLAGS) indicating what information to dump. Note that a standard set of information is always dumped, but by default more verbose information is hidden, and may be enabled with these flags.