Name

lcb_create — Create instance

Synopsis

cc [ flag … ] file… -lcouchbase [ library … ]

#include <libcouchbase/couchbase.h>
lcb_error_t lcb_create(lcb_t *instance,
                       const struct lcb_create_st *options);

DESCRIPTION

lcb_create() creates and stores the newly created instance in the instance parameter. If the options parameter is set to NULL it tries to connect to the default bucket on "127.0.0.1". lcb_create_st is a structure defined in <libcouchbase/arguments.h>:

struct lcb_create_st {
    int version; /* Specifies which filed in v to use */
    union {
        struct {
            const char *host;   /* host (list) to use */
            const char *user;   /* username for authentication */
            const char *passwd; /* password for authentication */
            const char *bucket; /* bucket to connect to */
            struct lcb_io_opt_st *io; /* IO instance to use */
        } v0;
        struct {
            const char *host;   /* host (list) to use */
            const char *user;   /* username for authentication */
            const char *passwd; /* password for authentication */
            const char *bucket; /* bucket to connect to */
            struct lcb_io_opt_st *io; /* IO instance to use */
            lcb_type_t type;    /* type of handle */
        } v1;
    } v;

A lcb_create_st structure should be initialized by using memset to 0, causing the default values to be used for all options not specified.

The "version" member specifies how the "v" union should be interpreted. The only difference between version 0 and version 1 is that version 1 allows you to create an instance to use for http requests (without binding to a bucket).

Hosts may be specified as a list of hosts separated by ;. If the Couchbase cluster is using a non-standard port, it may be specified by appending ":port" per host. ex: "host1;host2:9000;host3". The hostname parameter may alternatively be specified as an URI like: http://hostname:8091/pools. libcouchbase does not support any other schema than http, and the only supported path is "/pools". If no value is specified for host, "localhost:8091" is used.

If specified user and password specifies the credentials used for authorization. It is recommended to use principle of least privilege when accessing the cluster, i.e. when you only need to perform data operations, you should use bucket-level credentials instead of Administrator account (see examples 3 and 4).

If specified bucket specifies the bucket in the cluster to connect to. If not specified the "default" bucket is selected.

If specified io specifies the io instance used for communications. See lcb_create_io_ops(3couchbase) for more information. If not specified a default io instance will be created.

RETURN VALUES

lcb_create() returns the LCB_SUCCESS on success, or a specific error code upon failure. See lcb_strerror(3couchbase) for more information.

EXAMPLES

Example 1: 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);
}

Example 2: Provide a special serverlist

lcb_t instance;
lcb_error_t err;
struct lcb_create_st options;
memset(&options, 0, sizeof(options));
options.v.v0.host = "host1;host2;host3";
err = lcb_create(&instance, &options);
if (err != LCB_SUCCESS) {
    fprintf(stderr, "Failed to create instance: %s\n",
            lcb_strerror(NULL, err));
    exit(EXIT_FAILURE);
}

Example 3: Create an handle to use for management requests

lcb_t instance;
lcb_error_t err;
struct lcb_create_st options;
memset(&options, 0, sizeof(options));
options.version = 1;
options.v.v1.host = "host1";
options.v.v1.user = "Administrator";
options.v.v1.passwd = "secret";
options.v.v1.type = LCB_TYPE_CLUSTER;
err = lcb_create(&instance, &options);
if (err != LCB_SUCCESS) {
    fprintf(stderr, "Failed to create instance: %s\n",
            lcb_strerror(NULL, err));
    exit(EXIT_FAILURE);
}

Example 4: Create an handle for data requests to protected bucket

lcb_t instance;
lcb_error_t err;
struct lcb_create_st options;
memset(&options, 0, sizeof(options));
options.version = 1;
options.v.v1.host = "example.com:8091;example.org";
options.v.v1.bucket = "protected";
options.v.v1.user = "protected";
options.v.v1.passwd = "secret";
options.v.v1.type = LCB_TYPE_BUCKET;
err = lcb_create(&instance, &options);
if (err != LCB_SUCCESS) {
    fprintf(stderr, "Failed to create instance: %s\n",
            lcb_strerror(NULL, err));
    exit(EXIT_FAILURE);
}

ATTRIBUTES

See lcb_attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Interface Stability

Committed

MT-Level

MT-Safe

COPYRIGHT

Copyright 2010-2013 Couchbase, Inc.

SEE ALSO

Learn more at http://www.couchbase.com/communities/c.

libcouchbase(3lib), lcb_connect(3couchbase), lcb_destroy(3couchbase), lcb_attributes(5)