C SDK

The Couchbase C SDK provides a fast, callback-based API for interacting with your Couchbase cluster. It operates as a single threaded asynchronous I/O library which may be optionally integrated with an existing asynchronous application. It may also run standalone within a traditional synchronous or threaded application as well.

The SDK is cross platform and may be used on Linux, Mac OS X, or Windows.

Operations

Interacting with your cluster involves populating a command structure and receiving a related response structure in the callback. The response contains an optional pointer which can be set to application-level data, so that you may have your application context within the callback.

Callbacks are installed as handlers for specific command types, so retrieving objects will have one callback while saving them will have another. Response structures also vary depending on the operation performed; for example a response for a get request will contain the value retrieved from the server, while a response for a store request will only contain status information.

A callback model is employed so that response data does not need to be copied to a temporary buffer, but is rather passed to your callback as it is received off the network, making functionality very fast.

Commands

A command structure describes the various inputs for the operation which is to be performed on the server. For example, a command for a get request will contain a pointer to the buffer of the key to retrieve:

lcb_get_cmd_t gcmd = { 0 };
gcmd.v.v0.key = "id_key";
gcmd.v.v0.nkey = strlen(gcmd.v.v0.key);

The length, or nkey field must be provided to tell the library how many bytes to read from the buffer.

Operation Functions

Once an operation structure has been populated, you may pass this to the appropriate operation API. The operation APIs all take an array of command pointers (so as to enable passing multiple commands to a single API). In addition to the command structure itself, the APIs also allow for a pointer (named cookie) which is passed to the callback handler, to allow you to associate application data within the callback.

lcb_get_cmd_t *cmdlist[] = { &gcmd };
lcb_get(instance, "cookie_pointer", 1, cmdlist);

In the above snippet, instance is a library object, which represents the connection to your cluster (see Managing server connections). The lcb_get API is described in more detail in Retrieving documents

Operation Responses

To receive a response for the operation, the library must first be instructed to send the request to the cluster and await its response. In order for the response to be delivered to the application, the application will have needed to install a callback for the specific operation type.

The callback is passed the cookie pointer (the application data), a status code (to check if the operation failed or not), and a response structure containing the details of the result.

static void
get_handler(lcb_t instance,
            const void *cookie,
            lcb_error_t err,
            const lcb_get_resp_t *resp)
{
  printf("Got response for key: %.*s\n", (int)resp->v.v0.nkey, resp->v.v0.key);
  printf("Value: %.*s\n", (int)resp->v.v0.nbytes, resp->v.v0.bytes);
  printf("My cookie is: %s\n", cookie);
}

For get operations, the response contains the key passed to the command and the value of the item retrieved from the server. Note that the cookie passed along here is the same pointer passed to the lcb_get operation (and in this example, will print "cookie". Note that your context need not be a string, or even be a valid pointer in memory - as it is not dereferenced by the library at all.

To associate the callback with get operations, simply call:

lcb_set_get_callback(instance, get_callback)

Note that the callback is invoked for all get operations performed on the specific instance object, and thus need only be installed once per instance.

To actually wait for the response to arrive, simply call:

lcb_wait(instance);

Which will wait for the operation to complete. When the operation is complete, the callback will be invoked (in other words, the callback is always invoked with the lcb_wait function at the bottom of the call stack).

Storing Items

Storing items follows the same semantics as above, save for differences in API calls and command structures. When storing an item to the cluster, the value must be provided to the command structure as well:

lcb_store_cmd_t scmd = { 0 };
scmd.v.v0.key = "id_key";
scmd.v.v0.bytes = "{\"json\":\"value\"}";
scmd.v.v0.nkey = strlen(scmd.v.v0.key);
scmd.v.v0.nbytes = strlen(scmd.v.v0.bytes);
scmd.v.v0.operation = LCB_ADD; /* Fail if the item already exists */

/* Create the command array */
lcb_store_cmd_t *cmdlist[] = { &scmd };
lcb_store(instance, "some cookie", 1, cmdlist);
lcb_wait(instance);

Normally you would also wish to install a callback to inspect the status of the storage operation. More details about the lcb_store function can be found in Creating documents

Note that you are not limited to storing JSON. You may store any sequence of bytes into the cluster (however JSON is most simple to work with if you wish to query the data using views).