Couchbase C Client  3.0.5
Asynchronous C Client for Couchbase
Key/Value

Detailed Description

Preview APIs for performing commands.

Basic command and structure definitions for public API. This represents the "V3" API of libcouchbase. This API replaces the legacy API (which now wraps this one). It contains common definitions for scheduling, response structures and callback signatures.

Modules

 Read
 Retrieve a document from the cluster.
 
 Read (Replica)
 Retrieve a document from a replica if it cannot be fetched from the primary.
 
 Create/Update
 Set the value of a document.
 
 Open Bucket
 Open bucket in cluster.
 
 Remove
 Remove documents.
 
 Counters
 Manipulate the numeric content of a document.
 

Functions

int lcb_mutation_token_is_valid (const lcb_MUTATION_TOKEN *token)
 
lcb_RESPCALLBACK lcb_install_callback (lcb_INSTANCE *instance, int cbtype, lcb_RESPCALLBACK cb)
 
lcb_RESPCALLBACK lcb_get_callback (lcb_INSTANCE *instance, int cbtype)
 
const char * lcb_strcbtype (int cbtype)
 Returns the type of the callback as a string. More...
 
lcb_STATUS lcb_respexists_status (const lcb_RESPEXISTS *resp)
 
int lcb_respexists_is_found (const lcb_RESPEXISTS *resp)
 
lcb_STATUS lcb_respexists_error_context (const lcb_RESPEXISTS *resp, const lcb_KEY_VALUE_ERROR_CONTEXT **ctx)
 
lcb_STATUS lcb_respexists_cookie (const lcb_RESPEXISTS *resp, void **cookie)
 
lcb_STATUS lcb_respexists_cas (const lcb_RESPEXISTS *resp, uint64_t *cas)
 
lcb_STATUS lcb_respexists_key (const lcb_RESPEXISTS *resp, const char **key, size_t *key_len)
 
lcb_STATUS lcb_cmdexists_create (lcb_CMDEXISTS **cmd)
 
lcb_STATUS lcb_cmdexists_destroy (lcb_CMDEXISTS *cmd)
 
lcb_STATUS lcb_cmdexists_parent_span (lcb_CMDEXISTS *cmd, lcbtrace_SPAN *span)
 
lcb_STATUS lcb_cmdexists_collection (lcb_CMDEXISTS *cmd, const char *scope, size_t scope_len, const char *collection, size_t collection_len)
 
lcb_STATUS lcb_cmdexists_key (lcb_CMDEXISTS *cmd, const char *key, size_t key_len)
 
lcb_STATUS lcb_cmdexists_timeout (lcb_CMDEXISTS *cmd, uint32_t timeout)
 
lcb_STATUS lcb_exists (lcb_INSTANCE *instance, void *cookie, const lcb_CMDEXISTS *cmd)
 
lcb_STATUS lcb_respunlock_status (const lcb_RESPUNLOCK *resp)
 
lcb_STATUS lcb_respunlock_error_context (const lcb_RESPUNLOCK *resp, const lcb_KEY_VALUE_ERROR_CONTEXT **ctx)
 
lcb_STATUS lcb_respunlock_cookie (const lcb_RESPUNLOCK *resp, void **cookie)
 
lcb_STATUS lcb_respunlock_cas (const lcb_RESPUNLOCK *resp, uint64_t *cas)
 
lcb_STATUS lcb_respunlock_key (const lcb_RESPUNLOCK *resp, const char **key, size_t *key_len)
 
lcb_STATUS lcb_cmdunlock_create (lcb_CMDUNLOCK **cmd)
 
lcb_STATUS lcb_cmdunlock_destroy (lcb_CMDUNLOCK *cmd)
 
lcb_STATUS lcb_cmdunlock_parent_span (lcb_CMDUNLOCK *cmd, lcbtrace_SPAN *span)
 
lcb_STATUS lcb_cmdunlock_collection (lcb_CMDUNLOCK *cmd, const char *scope, size_t scope_len, const char *collection, size_t collection_len)
 
lcb_STATUS lcb_cmdunlock_key (lcb_CMDUNLOCK *cmd, const char *key, size_t key_len)
 
lcb_STATUS lcb_cmdunlock_cas (lcb_CMDUNLOCK *cmd, uint64_t cas)
 
lcb_STATUS lcb_cmdunlock_timeout (lcb_CMDUNLOCK *cmd, uint32_t timeout)
 
lcb_STATUS lcb_unlock (lcb_INSTANCE *instance, void *cookie, const lcb_CMDUNLOCK *cmd)
 

Macros

#define LCB_CALLBACK_VIEWQUERY
 Callback type for views (cannot be used for lcb_install_callback3())
 
#define LCB_CALLBACK_QUERY
 Callback type for N1QL (cannot be used for lcb_install_callback3())
 
#define LCB_CALLBACK_IXMGMT
 Callback type for N1QL index management (cannot be used for lcb_install_callback3())
 
#define LCB_CALLBACK_ANALYTICS
 Callback type for Analytics (cannot be used for lcb_install_callback3())
 
#define LCB_CALLBACK_SEARCH
 Callback type for Search (cannot be used for lcb_install_callback3())
 
#define LCB_CALLBACK_OPEN
 

Typedefs

typedef struct lcb_CMDBASE_ lcb_CMDBASE
 
typedef struct lcb_RESPBASE_ lcb_RESPBASE
 
typedef void(* lcb_RESPCALLBACK) (lcb_INSTANCE *instance, int cbtype, const lcb_RESPBASE *resp)
 Callback invoked for responses. More...
 
typedef struct lcb_RESPEXISTS_ lcb_RESPEXISTS
 
typedef struct lcb_CMDEXISTS_ lcb_CMDEXISTS
 
typedef struct lcb_RESPUNLOCK_ lcb_RESPUNLOCK
 Unlock a previously locked item using lcb_cmdunlock. More...
 
typedef struct lcb_CMDUNLOCK_ lcb_CMDUNLOCK
 

Enumerations

enum  lcb_RESPFLAGS
 Response flags. More...
 
enum  lcb_CALLBACK_TYPE
 The type of response passed to the callback. More...
 
enum  lcb_DURABILITY_LEVEL
 

Function Documentation

◆ lcb_install_callback()

lcb_RESPCALLBACK lcb_install_callback ( lcb_INSTANCE instance,
int  cbtype,
lcb_RESPCALLBACK  cb 
)
Stability
Committed:

Install a new-style callback for an operation. The callback will be invoked with the relevant response structure.

Parameters
instancethe handle
cbtypethe type of operation for which this callback should be installed. The value should be one of the lcb_CALLBACK_TYPE constants
cbthe callback to install
Returns
the old callback
Note
LCB_CALLBACK_DEFAULT is initialized to the default handler which proxies back to the older 2.x callbacks. If you set cbtype to LCB_CALLBACK_DEFAULT then your 2.x callbacks will not work.
The old callback may be NULL. It is usually not an error to have a NULL callback installed. If the callback is NULL, then the default callback invocation pattern will take place (as desribed above). However it is an error to set the default callback to NULL.
Examples
example/libeventdirect/main.c, example/minimal/minimal.c, example/minimal/query.c, example/observe/durability.c, example/subdoc/subdoc-xattrs.c, and example/tracing/tracing.c.

◆ lcb_get_callback()

lcb_RESPCALLBACK lcb_get_callback ( lcb_INSTANCE instance,
int  cbtype 
)
Stability
Committed:

Get the current callback installed as cbtype. Note that this does not perform any kind of resolution (as described in lcb_install_callback3) and will only return a non-NULL value if a callback had specifically been installed via lcb_install_callback3() with the given cbtype.

Parameters
instancethe handle
cbtypethe type of callback to retrieve
Returns
the installed callback for the type.

◆ lcb_strcbtype()

const char* lcb_strcbtype ( int  cbtype)

Returns the type of the callback as a string.

This function is helpful for debugging and demonstrative processes.

Parameters
cbtypethe type of the callback (the second argument to the callback)
Returns
a string describing the callback type
Examples
example/crypto/openssl_symmetric_decrypt.c, example/crypto/openssl_symmetric_encrypt.c, example/minimal/minimal.c, example/minimal/query.c, and example/tracing/tracing.c.

Typedef Documentation

◆ lcb_RESPCALLBACK

typedef void(* lcb_RESPCALLBACK) (lcb_INSTANCE *instance, int cbtype, const lcb_RESPBASE *resp)

Callback invoked for responses.

Parameters
instanceThe handle
cbtypeThe type of callback - or in other words, the type of operation this callback has been invoked for.
respThe response for the operation. Depending on the operation this response structure should be casted into a more specialized type.
Examples
example/libeventdirect/main.c, example/minimal/minimal.c, example/minimal/query.c, example/observe/durability.c, example/subdoc/subdoc-xattrs.c, and example/tracing/tracing.c.

◆ lcb_RESPUNLOCK

typedef struct lcb_RESPUNLOCK_ lcb_RESPUNLOCK

Unlock a previously locked item using lcb_cmdunlock.

Stability
Committed:
Parameters
instancethe instance
cookiethe context pointer to associate with the command
cmdthe command containing the information about the locked key
Returns
LCB_SUCCESS if successful, an error code otherwise Note that you must specify the cas of the item to unlock it, and the only way to get that cas is in the callback of the lock call. Outside that, the server will respond with a dummy cas if, for instance, you do a lcb_get.
See also
lcb_get()
void locked_callback(lcb_INSTANCE, lcb_CALLBACK_TYPE, const lcb_RESPBASE *rb) {
const lcb_RESPGET* resp = (const lcb_RESPLOCK*)rb;
lcb_CMDUNLOCK* cmd;
char* key;
size_t key_len;
unit64_t cas;
lcb_respget_cas(resp, &cas);
lcb_respget_key(resp, &key, &key_len);
lcb_cmdunlock_create(&cmd);
lcb_cmdunlock_key(cmd, key, key_len);
lcb_cmdunlock_cas(cmd, cas);
lcb_unlock(instance, cookie, cmd);
}

Enumeration Type Documentation

◆ lcb_RESPFLAGS

Response flags.

These provide additional 'meta' information about the response They can be read from the response object with a call like lcb_respXXX_flags, where the XXX is the operation – like get, exists, store, etc... There is also a lcb_respXXX_is_final method which reads the LCB_RESP_F_FINAL flag for those operations that execute the callback multiple times.

Enumerator
LCB_RESP_F_FINAL 

No more responses are to be received for this request.

LCB_RESP_F_CLIENTGEN 

The response was artificially generated inside the client.

This does not contain reply data from the server for the command, but rather contains the basic fields to indicate success or failure and is otherwise empty.

LCB_RESP_F_NMVGEN 

The response was a result of a not-my-vbucket error.

LCB_RESP_F_EXTDATA 

The response has additional internal data.

Used by lcb_resp_get_mutation_token()

LCB_RESP_F_SDSINGLE 

Flag, only valid for subdoc responses, indicates that the response was processed using the single-operation protocol.

LCB_RESP_F_ERRINFO 

The response has extra error information as value (see SDK-RFC-28).

◆ lcb_CALLBACK_TYPE

The type of response passed to the callback.

This is used to install callbacks for the library and to distinguish between responses if a single callback is used for multiple response types.

Note
These callbacks may conflict with the older version 2 callbacks. The rules are as follows:
  • If a callback has been installed using lcb_install_callback3(), then the older version 2 callback will not be invoked for that operation. The order of installation does not matter.
  • If the LCB_CALLBACK_DEFAULT callback is installed, none of the version 2 callbacks are invoked.
Enumerator
LCB_CALLBACK_DEFAULT 

Default callback invoked as a fallback.

LCB_CALLBACK_GET 

lcb_get()

LCB_CALLBACK_STORE 

lcb_store()

LCB_CALLBACK_COUNTER 

lcb_counter()

LCB_CALLBACK_TOUCH 

lcb_touch()

LCB_CALLBACK_REMOVE 

lcb_remove()

LCB_CALLBACK_UNLOCK 

lcb_unlock()

LCB_CALLBACK_STATS 

lcb_stats3()

LCB_CALLBACK_VERSIONS 

lcb_server_versions()

LCB_CALLBACK_VERBOSITY 

lcb_server_verbosity()

LCB_CALLBACK_OBSERVE 

lcb_observe3_ctxnew()

LCB_CALLBACK_GETREPLICA 

lcb_getreplica()

LCB_CALLBACK_ENDURE 

lcb_endure3_ctxnew()

LCB_CALLBACK_HTTP 

lcb_http()

LCB_CALLBACK_CBFLUSH 

lcb_cbflush3()

LCB_CALLBACK_OBSEQNO 

For lcb_observe_seqno3()

LCB_CALLBACK_SDLOOKUP 

<for lcb_storedur3()

LCB_CALLBACK_NOOP 

lcb_noop3()

LCB_CALLBACK_PING 

lcb_ping3()

LCB_CALLBACK_DIAG 

lcb_diag()

LCB_CALLBACK_COLLECTIONS_GET_MANIFEST 

lcb_getmanifest()

LCB_CALLBACK_GETCID 

lcb_getcid()

LCB_CALLBACK_EXISTS 

lcb_exists()

◆ lcb_DURABILITY_LEVEL

Stability
Uncommitted:
Durability levels
Enumerator
LCB_DURABILITYLEVEL_MAJORITY 

Mutation must be replicated to (i.e.

held in memory of that node) a majority ((configured_nodes / 2) + 1) of the configured nodes of the bucket.

LCB_DURABILITYLEVEL_MAJORITY_AND_PERSIST_TO_ACTIVE 

As majority, but additionally persisted to the active node.

LCB_DURABILITYLEVEL_PERSIST_TO_MAJORITY 

Mutation must be persisted to (i.e.

written and fsync'd to disk) a majority of the configured nodes of the bucket.

lcb_CALLBACK_TYPE
lcb_CALLBACK_TYPE
The type of response passed to the callback.
Definition: couchbase.h:466
lcb_INSTANCE
struct lcb_st lcb_INSTANCE
Library handle representing a connection to a cluster and its data buckets.
Definition: couchbase.h:35
lcb_RESPGET
struct lcb_RESPGET_ lcb_RESPGET
Command for retrieving a single item.
Definition: couchbase.h:685