Couchbase C Client  2.10.0
Asynchronous C Client for Couchbase
Initialization

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:

  1. One or more hosts which comprise the cluster
  2. The name of the bucket to access and perform operations on
  3. 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:

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.

Options

Warning
The key-value options here are considered to be an uncommitted 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:

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

  1. Logging into the Couchbase Administration Console
  2. Going to the Data Buckets tab
  3. Locate the row for your bucket
  4. Expand the row into the detailed view (by clicking on the arrow at the left of the row)
  5. Click on Edit
  6. 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...
 
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_set_auth (lcb_t instance, lcb_AUTHENTICATOR *auth)
 Sets the authenticator object for the instance. More...
 

Typedefs

typedef struct lcb_st * lcb_t
 Library handle representing a connection to a cluster and its data buckets. More...
 
typedef void(* lcb_bootstrap_callback) (lcb_t instance, lcb_error_t err)
 
Bootstrap callback. More...
 

Enumerations

enum  lcb_type_t
 Handle types. More...
 
enum  lcb_BTYPE
 Type of the bucket. More...
 

Function Documentation

◆ lcb_create()

lcb_error_t lcb_create ( lcb_t instance,
const struct lcb_create_st options 
)


Create an instance of lcb.

Parameters
instanceWhere the instance should be returned
optionsHow 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/analytics/analytics.c, example/crypto/openssl_symmetric_decrypt.c, example/crypto/openssl_symmetric_encrypt.c, example/fts/fts.c, example/libeventdirect/main.c, example/minimal/minimal.c, example/minimal/query.c, example/observe/durability.c, example/observe/observe.c, example/subdoc/subdoc-xattrs.c, example/tracing/tracing.c, and example/tracing/views.c.

◆ lcb_connect()

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.

Synchronous Usage
lcb_error_t rc = lcb_connect(instance);
if (rc != LCB_SUCCESS) {
your_error_handling(rc);
}
lcb_wait(instance);
rc = lcb_get_bootstrap_status(instance);
if (rc != LCB_SUCCESS) {
your_error_handler(rc);
}
Stability
Committed:
Examples:
example/analytics/analytics.c, example/crypto/openssl_symmetric_decrypt.c, example/crypto/openssl_symmetric_encrypt.c, example/fts/fts.c, example/libeventdirect/main.c, example/minimal/minimal.c, example/minimal/query.c, example/observe/durability.c, example/observe/observe.c, example/subdoc/subdoc-xattrs.c, example/tracing/tracing.c, and example/tracing/views.c.

◆ lcb_set_bootstrap_callback()

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
instancethe instance
callbackthe 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_get_bootstrap_status()

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/analytics/analytics.c, example/crypto/openssl_symmetric_decrypt.c, example/crypto/openssl_symmetric_encrypt.c, example/fts/fts.c, example/minimal/minimal.c, example/minimal/query.c, example/observe/durability.c, example/observe/observe.c, example/subdoc/subdoc-xattrs.c, example/tracing/tracing.c, and example/tracing/views.c.

◆ lcb_set_auth()

void lcb_set_auth ( lcb_t  instance,
lcb_AUTHENTICATOR auth 
)

Sets the authenticator object for the instance.

This may be done anytime, but should probably be done before calling lcb_connect() for best effect.

Parameters
instancethe handle
auththe authenticator object used. The library will increase the refcount on the authenticator object.

Data Structure Documentation

◆ lcb_create_st3

struct lcb_create_st3

Inner structure V3 for lcb_create().

Data Fields

const char * connstr
 Connection string.
 
const char * username
 Username to use for authentication. More...
 
const char * passwd
 Password for bucket. More...
 
struct lcb_io_opt_st * io
 IO Options.
 
lcb_type_t type
 

Field Documentation

◆ username

◆ passwd

◆ lcb_create_st4

struct lcb_create_st4

Inner structure V4 for lcb_create().

Same as V3, but allows to supply logger (

See also
LCB_CNTL_LOGGER).
Data Fields
const char * connstr Connection string.
const char * username Username to use for authentication.

This should only be set when connecting to a server 5.0 or greater.

const char * passwd Password for bucket.

Can also be password for username on servers >= 5.0

lcb_logprocs * logger Logger.
struct lcb_io_opt_st * io IO Options.
lcb_type_t type

◆ lcb_create_st

Typedef Documentation

◆ lcb_t

typedef struct lcb_st* lcb_t

Library handle representing a connection to a cluster and its data buckets.

The contents of this structure are opaque.

See also
lcb_create
lcb_destroy

◆ lcb_bootstrap_callback

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


Bootstrap callback.

Invoked once the instance is ready to perform operations

Parameters
instanceThe instance which was bootstrapped
errThe 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:

Enumeration Type Documentation

◆ lcb_type_t

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.

◆ lcb_BTYPE

enum lcb_BTYPE

Type of the bucket.

See also
https://developer.couchbase.com/documentation/server/current/architecture/core-data-access-buckets.html
Enumerator
LCB_BTYPE_UNSPEC 

Unknown or unspecified.

LCB_BTYPE_COUCHBASE 

Data persisted and replicated.

LCB_BTYPE_EPHEMERAL 

Data not persisted, but replicated.

LCB_BTYPE_MEMCACHED 

Data not persisted and not replicated.