Detailed Description

To communicate with a Couchbase cluster, a new library handle instance is created in the form of an lcb_t. To create such an object, the lcb_create() function is called, passing it a structure of type lcb_create_st. The structure acts as a container for a union of other structures which are extended as more features are added. This container is forwards and backwards compatible, meaning that if the structure is extended, you code and application will still function if using an older version of the structure. The current sub-field of the lcb_create_st structure is the v3 field.

Connecting to the cluster involes the client knowing the necessary information needed to actually locate its services and connect to it.

A connection specification consists of:

One or more hosts which comprise the cluster
The name of the bucket to access and perform operations on
The credentials of the bucket

All these options are specified within the form of a URI in the form of

couchbase://$HOSTS/$BUCKET?$OPTIONS

Note: If any of the fields (hosts, bucket, options) contain the / character then it must be url-encoded; thus a bucket named foo/bar would be specified as couchbase:///foo%2Fbar

Hosts

In the most typical use case, you would specify a list of several hostnames delimited by a comma (,); each host specified should be a member of the cluster. The library will use this list to initially connect to the cluster.

Note that it is not necessary to specify all the nodes of the cluster as in a normal situation the library will only initially connect to one of the nodes. Passing multiple nodes increases the chance of a connection succeeding even if some of the nodes are currently down. Once connected to the cluster, the client will update itself with the other nodes actually found within the cluster and discard the list passed to it

You can specify multiple hosts like so:

couchbase://foo.com,bar.com,baz.com

Or a single host:

couchbase://localhost

Specifying Ports and Protocol Options

The default couchbase:// scheme will assume all hosts and/or ports specify the memcached port. If no port is specified, it is assumed that the port is _11210). For more extended options there are additional schemes available:

couchbases:// - Will assume all ports refer to the SSL-enabled memcached ports. This setting implicitly enables SSL on the instance as well. If no ports are provided for the hosts, the implicit port for each host will be 11207.
http:// - Will assume all ports refer to the HTTP REST API ports used by Couchbase 2.2 and lower. These are also used when connecting to a memcached bucket. If no port is specified it will be assumed the port is 8091.

Bucket

A bucket may be specified by using the optional path component of the URI For protected buckets a password will still need to be supplied out of band.

couchbase://1.1.1.1,2.2.2.2,3.3.3.3/users - Connect to the users bucket.

Options

Warning: The key-value options here are considered to be a volatile interface as their names may change.

Options can be specified as the query part of the connection string, for example:

couchbase://cbnode.net/beer?operation_timeout=10000000.

Options may either be appropriate key parameters for lcb_cntl_string() or one of the following:

boostrap_on - specify bootstrap protocols. Values can be http to force old-style bootstrap mode for legacy clusters, cccp to force bootstrap over the memcached port (For clusters 2.5 and above), or all to try with cccp and revert to http
certpath - Specify the path (on the local filesystem) to the server's SSL certificate. Only applicable if SSL is being used (i.e. the scheme is couchbases)

Bucket Identification and Credentials

The most common settings you will wish to modify are the bucket name and the credentials field (user and passwd). If a bucket is not specified it will revert to the default bucket (i.e. the bucket which is created when Couchbase Server is installed).

The user and passwd fields authenticate for the bucket. This is only needed if you have configured your bucket to employ SASL auth. You can tell if the bucket has been configured with SASL auth by

Logging into the Couchbase Administration Console
Going to the Data Buckets tab
Locate the row for your bucket
Expand the row into the detailed view (by clicking on the arrow at the left of the row)
Click on Edit
Inspect the Access Control section in the pop-up

The bucket name is specified as the path portion of the URI.

For security purposes, the user and passwd cannot be specified within the URI

Note: You may not change the bucket or credentials after initializing the handle.

Bootstrap Options

The default configuration process will attempt to bootstrap first from the new memcached configuration protocol (CCCP) and if that fails, use the "HTTP" protocol via the REST API.

The CCCP configuration will by default attempt to connect to one of the nodes specified on the port 11201. While normally the memcached port is determined by the configuration itself, this is not possible when the configuration has not been attained. You may specify a list of alternate memcached servers by using the 'mchosts' field.

If you wish to modify the default bootstrap protocol selection, you can use the bootstrap_on option to specify the desired bootstrap specification to use for configuration (note that the ordering of this array is ignored). Using this mechanism, you can disable CCCP or HTTP.

To force only "new-style" bootstrap, you may use bootstrap_on=cccp. To force only "old-style" bootstrap, use bootstrap_on=http. To force the default behavior, use bootstrap_on=all

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

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

lcb_configuration_callback	lcb_set_configuration_callback (lcb_t, lcb_configuration_callback)

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)
	Destory io ops instance. More...

Macros
#define	LCB_IOCREATE_T_BUILTIN

#define	LCB_IOCREATE_T_DSO

#define	LCB_IOCREATE_T_FUNCTIONPOINTER

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

typedef void(*	lcb_configuration_callback) (lcb_t instance, lcb_configuration_t config)
	Receive notification upon cluster configuration. More...

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

Enumerations
enum	lcb_type_t
	Handle types. More...

enum	lcb_WAITFLAGS
	Flags for lcb_wait3() More...

enum	lcb_configuration_t
	Argument indicating configuration change type. More...

enum	lcb_io_ops_type_t
	Built-in I/O plugins. More...

Function Documentation

lcb_error_t lcb_create	(	lcb_t *	instance,
		const struct lcb_create_st *	options
	)

Create an instance of lcb.

Parameters

instance	Where the instance should be returned
options	How to create the libcouchbase instance

Returns: LCB_SUCCESS on success

Examples

Create an instance using the default values:

lcb_t instance;
lcb_error_t err = lcb_create(&instance, NULL);
if (err != LCB_SUCCESS) {
   fprintf(stderr, "Failed to create instance: %s\n", lcb_strerror(NULL, err));
   exit(EXIT_FAILURE);
}

Specify server list

struct lcb_create_st options;
memset(&options, 0, sizeof(options));
options.version = 3;
options.v.v3.connstr = "couchbase://host1,host2,host3";
err = lcb_create(&instance, &options);

Create a handle for data requests to protected bucket

struct lcb_create_st options;
memset(&options, 0, sizeof(options));
options.version = 3;
options.v.v3.host = "couchbase://example.com,example.org/protected"
options.v.v3.passwd = "secret";
err = lcb_create(&instance, &options);

Stability

Committed:

See also: lcb_create_st3

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

lcb_error_t lcb_connect ( lcb_t instance )

Schedule the initial connection This function will schedule the initial connection for the handle.

This function must be called before any operations can be performed.

lcb_set_bootstrap_callback() or lcb_get_bootstrap_status() can be used to determine if the scheduled connection completed successfully.

lcb_wait() should be called after this function.

Stability

Committed:

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

void lcb_set_cookie	(	lcb_t	instance,
		const void *	cookie
	)

Associate a cookie with an instance of lcb.

The cookie is a user defined pointer which will remain attached to the specified lcb_t for its duration. This is the way to associate user data with the lcb_t.

Parameters

instance	the instance to associate the cookie to
cookie	the cookie to associate with this instance.

Attention: There is no destructor for the specified cookie stored with the instance; thus you must ensure to manually free resources to the pointer (if it was dynamically allocated) when it is no longer required.

Stability

Committed:

typedef struct {
  const char *status;
  // ....
} instance_info;
static void bootstrap_callback(lcb_t instance, lcb_error_t err) {
  instance_info *info = (instance_info *)lcb_get_cookie(instance);
  if (err == LCB_SUCCESS) {
    info->status = "Connected";
  } else {
    info->status = "Error";
  }
}
static void do_create(void) {
  instance_info *info = calloc(1, sizeof(*info));
  // info->status is currently NULL
  // .. create the instance here
  lcb_set_cookie(instance, info);
  lcb_set_bootstrap_callback(instance, bootstrap_callback);
  lcb_connect(instance);
  lcb_wait(instance);
  printf("Status of instance is %s\n", info->status);
}

Examples:: example/libeventdirect/main.c.

const void* lcb_get_cookie ( lcb_t instance )

Retrieve the cookie associated with this instance.

Parameters

instance the instance of lcb

Returns: The cookie associated with this instance or NULL

See also: lcb_set_cookie()

Stability

Committed:

Examples:: example/libeventdirect/main.c.

lcb_error_t lcb_wait ( lcb_t instance )

Wait for the execution of all batched requests.

A batched request is any request which requires network I/O. This includes most of the APIs. You should not use this API if you are integrating with an asynchronous event loop (i.e. one where your application code is invoked asynchronously via event loops).

This function will block the calling thread until either

All operations have been completed
lcb_breakout() is explicitly called

Parameters

instance the instance containing the requests

Returns: whether the wait operation failed, or LCB_SUCCESS

Stability

Committed:

Examples:: example/minimal/minimal.c.

void lcb_wait3	(	lcb_t	instance,
		lcb_WAITFLAGS	flags
	)

Wait for completion of scheduled operations.

Stability

Committed:

Parameters

instance	the instance
flags	flags to modify the behavior of lcb_wait(). Pass 0 to obtain behavior identical to lcb_wait().

void lcb_breakout ( lcb_t instance )

Forcefully break from the event loop.

You may call this function from within any callback to signal to the library that it return control to the function calling lcb_wait() as soon as possible. Note that if there are pending functions which have not been processed, you are responsible for calling lcb_wait() a second time.

Parameters

instance the instance to run the event loop for.

Stability

Committed:

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.

Parameters

instance	the instance
callback	the callback to set. If `NULL`, return the existing callback

Returns: The existing (and previous) callback.

See also: lcb_connect(); lcb_get_bootstrap_status()

Examples:: example/libeventdirect/main.c.

lcb_error_t lcb_get_bootstrap_status ( lcb_t instance )

Gets the initial bootstrap status.

This is an alternative to using the lcb_bootstrap_callback() and may be used after the initial lcb_connect() and lcb_wait() sequence.

Parameters

instance

Returns: LCB_SUCCESS if properly bootstrapped or an error code otherwise.

Attention: Calling this function only makes sense during instantiation.

Stability

Committed:

Examples:: example/minimal/minimal.c.

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");
}

lcb_configuration_callback lcb_set_configuration_callback	(	lcb_t	,
		lcb_configuration_callback
	)

Stability

Uncommitted:

void lcb_destroy ( lcb_t instance )

Destroy (and release all allocated resources) an instance of lcb.

Using instance after calling destroy will most likely cause your application to crash.

Note that any pending operations will not have their callbacks invoked.

Parameters

instance the instance to destroy.

Stability

Committed:

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

lcb_destroy_callback lcb_set_destroy_callback	(	lcb_t	,
		lcb_destroy_callback
	)

Set the callback to be invoked when the instance is destroyed asynchronously.

Returns: the previous callback.

void lcb_destroy_async	(	lcb_t	instance,
		const void *	arg
	)

Asynchronously schedule the destruction of an instance.

This function provides a safe way for asynchronous environments to destroy the lcb_t handle without worrying about reentrancy issues.

Parameters

instance
arg	a pointer passed to the callback.

While the callback and cookie are optional, they are very much recommended for testing scenarios where you wish to ensure that all resources allocated by the instance have been closed. Specifically when the callback is invoked, all timers (save for the one actually triggering the destruction) and sockets will have been closed.

As with lcb_destroy() you may call this function only once. You may not call this function together with lcb_destroy as the two are mutually exclusive.

If for whatever reason this function is being called in a synchronous flow, lcb_wait() must be invoked in order for the destruction to take effect

See also: lcb_set_destroy_callback

Stability

Committed:

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.

Parameters

op	Where to store the io ops structure
options	How to create the io ops structure

Returns: LCB_SUCCESS on success

Stability

Uncommitted:

Examples:: example/libeventdirect/main.c.

lcb_error_t lcb_destroy_io_ops ( lcb_io_opt_t op )

Destory io ops instance.

Parameters

op	ops structure

Returns: LCB_SUCCESS on success

Stability

Uncommitted:

Data Structure Documentation

struct lcb_create_st3

Structure for lcb_create().

See also: Basic Library Routines

Data Fields
const char *	connstr	Connection string.
const char *	username	Username for bucket. Unused as of Server 2.5
const char *	passwd	Password for bucket.
void *	_pad_bucket
struct lcb_io_opt_st *	io	IO Options.
lcb_type_t	type

struct lcb_create_st

Wrapper structure for lcb_create()

See also: lcb_create_st3

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

Data Fields
int	version	Set this to `3`
union lcb_create_st	v

struct lcb_IOCREATEOPTS_BUILTIN

IO Creation for builtin plugins.

Data Fields
lcb_io_ops_type_t	type	The predefined type you want to create.
void *	cookie	Plugin-specific argument.

struct lcb_IOCREATEOPS_FUNCTIONPOINTER

I/O Creation for function pointers.

Data Fields
lcb_io_create_fn	create	Function used to create the IO ops.
void *	cookie	`cookie` parameter passed to function

struct lcb_create_io_ops_st

uncommitted

Examples:: example/libeventdirect/main.c.

Data Fields
int	version
union lcb_create_io_ops_st	v

Typedef Documentation

typedef void(* lcb_bootstrap_callback) (lcb_t instance, lcb_error_t err)

Bootstrap callback.

Invoked once the instance is ready to perform operations

Parameters

instance	The instance which was bootstrapped
err	The error code received. If this is not LCB_SUCCESS then the instance is not bootstrapped and must be recreated

Attention: This callback only receives information during instantiation.

Stability

Committed:

typedef void(* lcb_configuration_callback) (lcb_t instance, lcb_configuration_t config)

Receive notification upon cluster configuration.

This callback may be used as a hook for the application to notify it that operations may start being scheduled.

Parameters

instance	The instance who received the new configuration
config	The kind of configuration received

Stability

Uncommitted:

typedef void(* lcb_destroy_callback) (const void *cookie)

Callback received when instance is about to be destroyed.

Parameters

cookie cookie passed to lcb_destroy_async()

Enumeration Type Documentation

enum lcb_type_t

Handle types.

See also: lcb_create_st3::type

Enumerator
LCB_TYPE_BUCKET	Handle for data access (default)
LCB_TYPE_CLUSTER	Handle for administrative access.

enum lcb_WAITFLAGS

Flags for lcb_wait3()

Enumerator

LCB_WAIT_DEFAULT

Behave like the old lcb_wait()

LCB_WAIT_NOCHECK

Do not check pending operations before running the event loop.

By default lcb_wait() will traverse the server list to check if any operations are pending, and if nothing is pending the function will return without running the event loop. This is usually not necessary for applications which already only call lcb_wait() when they know they have scheduled at least one command.

enum lcb_configuration_t

Argument indicating configuration change type.

See also: lcb_set_configuration_callback() uncommitted

Enumerator

LCB_CONFIGURATION_NEW

New configuration (initial bootstrap).

This status code is received only once per instance

LCB_CONFIGURATION_CHANGED

Configuration updated.

LCB_CONFIGURATION_UNCHANGED

Configuration propagated from cluster, but matches our current one.

enum lcb_io_ops_type_t

Built-in I/O plugins.

Stability

Committed:

Enumerator

LCB_IO_OPS_LIBEVENT

Integrate with the libevent loop.

See lcb_create_libevent_io_opts()

Detailed Description

Hosts

Specifying Ports and Protocol Options

Bucket

Options

Bucket Identification and Credentials

Bootstrap Options

Functions

Macros

Typedefs

Enumerations

Function Documentation

Examples

Data Structure Documentation

Typedef Documentation

Enumeration Type Documentation