Couchbase C Client  2.5.6
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/kvbuf.h>
#include <libcouchbase/_cxxwrap.h>
#include <libcouchbase/subdoc.h>
#include <libcouchbase/cntl.h>
#include <libcouchbase/deprecated.h>
#include <libcouchbase/api-legacy.h>

Go to the source code of this file.

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_TOKENlcb_resp_get_mutation_token (int cbtype, const lcb_RESPBASE *rb)
 Retrieves the mutation token from the response structure. More...
 
const lcb_MUTATION_TOKENlcb_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_CTXlcb_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_CTXlcb_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

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;
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
hgthe histogram
streamFile to print the histogram to.