Couchbase C Client
2.5.6
|
Main header file for Couchbase. More...
#include <stddef.h>
#include <time.h>
#include <stdarg.h>
#include <stdio.h>
#include <libcouchbase/sysdefs.h>
#include <libcouchbase/assert.h>
#include <libcouchbase/visibility.h>
#include <libcouchbase/error.h>
#include <libcouchbase/iops.h>
#include <libcouchbase/http.h>
#include <libcouchbase/configuration.h>
#include <libcouchbase/kvbuf.h>
#include <libcouchbase/_cxxwrap.h>
#include <libcouchbase/subdoc.h>
#include <libcouchbase/cntl.h>
#include <libcouchbase/deprecated.h>
#include <libcouchbase/api-legacy.h>
Go to the source code of this file.
Data Structures | |
struct | lcb_create_st3 |
Innser structure for lcb_create(). More... | |
struct | lcb_create_st |
Wrapper structure for lcb_create() More... | |
union | lcb_create_st::lcb_CRST_u |
This union contains the set of current and historical options. More... | |
struct | lcb_CMDBASE |
Common ABI header for all commands. More... | |
struct | lcb_RESPBASE |
Base response structure for callbacks. More... | |
struct | lcb_RESPSERVERBASE |
Base structure for informational commands from servers This contains an additional lcb_RESPSERVERBASE::server field containing the server which emitted this response. More... | |
struct | lcb_MUTATION_TOKEN |
Structure representing a synchronization token. More... | |
struct | lcb_CMDGET |
Command for retrieving a single item. More... | |
struct | lcb_RESPGET |
Response structure when retrieving a single item. More... | |
struct | lcb_CMDGETREPLICA |
Command for requesting an item from a replica. More... | |
struct | lcb_CMDSTORE |
Command for storing an item to the server. More... | |
struct | lcb_RESPSTORE |
Response structure for lcb_store3() More... | |
struct | lcb_MULTICMD_CTX |
Multi Command Context API Some commands (notably, OBSERVE and its higher level equivalent, endue) are handled more efficiently at the cluster side by stuffing multiple items into a single packet. More... | |
struct | lcb_DURABILITYOPTSv0 |
Options for lcb_endure3_ctxnew() More... | |
struct | lcb_durability_opts_t |
Options for lcb_endure3_ctxnew() (wrapper) More... | |
struct | lcb_CMDENDURE |
Command structure for endure. More... | |
struct | lcb_RESPENDURE |
Response structure for endure. More... | |
struct | lcb_CMDSTOREDUR |
Command structure for lcb_storedur3() This is much like lcb_CMDSTORE, but also includes durability options. More... | |
struct | lcb_RESPSTOREDUR |
Response structure for `LCB_CALLBACK_STOREDUR. More... | |
struct | lcb_CMDOBSERVE |
Structure for an observe request. More... | |
struct | lcb_RESPOBSERVE |
Response structure for an observe command. More... | |
struct | lcb_CMDOBSEQNO |
Command structure for lcb_observe_seqno3(). More... | |
struct | lcb_RESPOBSEQNO |
Response structure for lcb_observe_seqno3() More... | |
struct | lcb_CMDCOUNTER |
Command for counter operations. More... | |
struct | lcb_RESPCOUNTER |
Response structure for counter operations. More... | |
struct | lcb_RESPSTATS |
Response structure for cluster statistics. More... | |
struct | lcb_RESPMCVERSION |
Response structure for the version command. More... | |
struct | lcb_CMDHTTP |
Structure for performing an HTTP request. More... | |
struct | lcb_RESPHTTP |
Structure for HTTP responses. More... | |
Macros | |
#define | LCB_CONFIG_MCD_PORT |
#define | LCB_CONFIG_MCD_SSL_PORT |
#define | LCB_CONFIG_HTTP_PORT |
#define | LCB_CONFIG_HTTP_SSL_PORT |
#define | LCB_CONFIG_MCCOMPAT_PORT |
#define | LCB_CMDGET_F_CLEAREXP |
If this bit is set in lcb_CMDGET::cmdflags then the expiry time is cleared if lcb_CMDGET::exptime is 0. More... | |
#define | LCB_CMD_SET_VALUE(scmd, valbuf, vallen) |
Set the value buffer for the command. This may be used when the new value is a single contiguous buffer. More... | |
#define | LCB_CMD_SET_VALUEIOV(scmd, iovs, niovs) |
Set value from a series of input buffers. This may be used when the input buffer is not contiguous. Using this call eliminates the need for creating a temporary contiguous buffer in which to store the value. More... | |
#define | LCB_MUTATION_TOKEN_ID(p) |
Get the vBucket UUID. | |
#define | LCB_MUTATION_TOKEN_SEQ(p) |
Get the sequence number. | |
#define | LCB_MUTATION_TOKEN_VB(p) |
Get the vBucket number itself. | |
#define | LCB_MUTATION_TOKEN_ISVALID(p) |
Whether this mutation token has valid contents. | |
#define | LCB_CMDHTTP_F_STREAM |
Command flag for HTTP to indicate that the callback is to be invoked multiple times for each new chunk of incoming data. More... | |
#define | LCB_CMDHTTP_F_CASTMO |
If specified, the lcb_CMDHTTP::cas field becomes the timeout for this specific request. | |
#define | LCB_DATATYPE_JSON |
#define | LCB_GETNODE_UNAVAILABLE |
String constant returned by lcb_get_node() when the LCB_NODE_NEVERNULL flag is specified, and no node can be returned. | |
#define | LCB_VERSION_STRING |
libcouchbase version string | |
#define | LCB_VERSION |
libcouchbase hex version More... | |
#define | LCB_VERSION_CHANGESET |
The SCM revision ID. More... | |
#define | LCB_SUPPORTS_SSL |
Whether the library has SSL support. | |
#define | LCB_SUPPORTS_SNAPPY |
Whether the library has experimental compression support. | |
Creating Commands | |
Issuing a command to the Cluster involves selecting the correct command structure, populating it with the data relevant for the command, optionally associating the command with your own application data, issuing the command to a spooling function, and finally receiving the response. Command structures all derive from the common lcb_CMDBASE structure. This structure defines the common fields for all commands. Almost all commands need to contain a key, which should be assigned using the LCB_CMD_SET_KEY() macro. | |
#define | LCB_CMD_BASE |
#define | LCB_CMD_F_INTERNAL_CALLBACK |
Flag for lcb_CMDBASE::cmdflags which indicates that the lcb_CMDBASE::cookie is a special callback object. More... | |
#define | LCB_CMD_SET_KEY(cmd, keybuf, keylen) |
#define | LCB_CMD__SETVBID(cmd, vbid) |
Typedefs | |
typedef struct lcb_st * | lcb_t |
Library handle representing a connection to a data bucket. More... | |
typedef struct lcb_http_request_st * | lcb_http_request_t |
typedef lcb_U8 | lcb_datatype_t |
typedef lcb_U32 | lcb_USECS |
typedef void(* | lcb_bootstrap_callback) (lcb_t instance, lcb_error_t err) |
Bootstrap callback. More... | |
typedef lcb_CMDBASE | lcb_CMDREMOVE |
Command for removing an item from the server. More... | |
typedef lcb_RESPBASE | lcb_RESPREMOVE |
Response structure for removal operation. More... | |
typedef lcb_CMDBASE | lcb_CMDUNLOCK |
Command for lcb_unlock3() More... | |
typedef lcb_RESPBASE | lcb_RESPUNLOCK |
Response structure for an unlock command. More... | |
typedef lcb_CMDBASE | lcb_CMDTOUCH |
Command structure for a touch request. More... | |
typedef lcb_RESPBASE | lcb_RESPTOUCH |
Response structure for a touch request. More... | |
typedef lcb_CMDBASE | lcb_CMDCBFLUSH |
typedef lcb_RESPBASE | lcb_RESPCBFLUSH |
typedef lcb_CMDBASE | lcb_CMDFLUSH |
typedef lcb_RESPSERVERBASE | lcb_RESPFLUSH |
typedef void(* | lcb_destroy_callback) (const void *cookie) |
Callback received when instance is about to be destroyed. More... | |
typedef enum lcb_timeunit_t | lcb_timeunit_t |
typedef void(* | lcb_timings_callback) (lcb_t instance, const void *cookie, lcb_timeunit_t timeunit, lcb_U32 min, lcb_U32 max, lcb_U32 total, lcb_U32 maxtotal) |
The following function is called for each bucket in the timings histogram when you call lcb_get_timings. More... | |
typedef struct lcb_histogram_st | lcb_HISTOGRAM |
typedef void(* | lcb_HISTOGRAM_CALLBACK) (const void *cookie, lcb_timeunit_t timeunit, lcb_U32 min, lcb_U32 max, lcb_U32 total, lcb_U32 maxtotal) |
Enumerations | |
enum | lcb_type_t |
Handle types. More... | |
enum | lcb_replica_t |
Select get-replica mode. More... | |
enum | lcb_storage_t |
Values for lcb_CMDSTORE::operation. More... | |
enum | lcb_http_type_t |
The type of HTTP request to execute. More... | |
enum | lcb_http_method_t |
HTTP Request method enumeration These just enumerate the various types of HTTP request methods supported. More... | |
enum | lcb_WAITFLAGS |
Flags for lcb_wait3() More... | |
enum | lcb_GETNODETYPE |
Type of node to retrieve for the lcb_get_node() function. More... | |
enum | lcb_timeunit_t |
Time units reported by lcb_get_timings() More... | |
enum | lcb_DUMPFLAGS |
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... | |
lcb_error_t | lcb_get3 (lcb_t instance, const void *cookie, const lcb_CMDGET *cmd) |
Spool a single get operation. More... | |
lcb_error_t | lcb_rget3 (lcb_t instance, const void *cookie, const lcb_CMDGETREPLICA *cmd) |
Spool a single get-with-replica request. More... | |
lcb_error_t | lcb_store3 (lcb_t instance, const void *cookie, const lcb_CMDSTORE *cmd) |
Schedule a single storage request. More... | |
lcb_error_t | lcb_remove3 (lcb_t instance, const void *cookie, const lcb_CMDREMOVE *cmd) |
Spool a removal of an item. More... | |
const lcb_MUTATION_TOKEN * | lcb_resp_get_mutation_token (int cbtype, const lcb_RESPBASE *rb) |
Retrieves the mutation token from the response structure. More... | |
const lcb_MUTATION_TOKEN * | lcb_get_mutation_token (lcb_t instance, const lcb_KEYBUF *kb, lcb_error_t *errp) |
lcb_error_t | lcb_counter3 (lcb_t instance, const void *cookie, const lcb_CMDCOUNTER *cmd) |
Schedule single counter operation. More... | |
lcb_error_t | lcb_unlock3 (lcb_t instance, const void *cookie, const lcb_CMDUNLOCK *cmd) |
Unlock a previously locked item using lcb_CMDGET::lock. More... | |
lcb_error_t | lcb_touch3 (lcb_t instance, const void *cookie, const lcb_CMDTOUCH *cmd) |
Spool a touch request. More... | |
lcb_error_t | lcb_cbflush3 (lcb_t instance, const void *cookie, const lcb_CMDCBFLUSH *cmd) |
uncommitted More... | |
lcb_error_t | lcb_flush3 (lcb_t instance, const void *cookie, const lcb_CMDFLUSH *cmd) |
lcb_error_t | lcb_http3 (lcb_t instance, const void *cookie, const lcb_CMDHTTP *cmd) |
void | lcb_cancel_http_request (lcb_t instance, lcb_http_request_t request) |
Cancel ongoing HTTP request. 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... | |
lcb_error_t | lcb_tick_nowait (lcb_t instance) |
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... | |
int | lcb_is_waiting (lcb_t instance) |
Check if instance is blocked in the event loop. More... | |
void | lcb_refresh_config (lcb_t instance) |
Force the library to refetch the cluster configuration. More... | |
void | lcb_sched_enter (lcb_t instance) |
Enter a scheduling context. More... | |
void | lcb_sched_leave (lcb_t instance) |
Leave the current scheduling context, scheduling the commands within the context to be flushed to the network. More... | |
void | lcb_sched_fail (lcb_t instance) |
Fail all commands in the current scheduling context. More... | |
void | lcb_sched_flush (lcb_t instance) |
Request commands to be flushed to the network. More... | |
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... | |
const char * | lcb_get_node (lcb_t instance, lcb_GETNODETYPE type, unsigned index) |
Return a string of host:port for a node of the given type. More... | |
const char * | lcb_get_keynode (lcb_t instance, const void *key, size_t nkey) |
Get the target server for a given key. More... | |
lcb_S32 | lcb_get_num_replicas (lcb_t instance) |
Get the number of the replicas in the cluster. More... | |
lcb_S32 | lcb_get_num_nodes (lcb_t instance) |
Get the number of the nodes in the cluster. More... | |
const char *const * | lcb_get_server_list (lcb_t instance) |
Get a list of nodes in the cluster. More... | |
void | lcb_dump (lcb_t instance, FILE *fp, lcb_U32 flags) |
Write a textual dump to a file. More... | |
lcb_error_t | lcb_cntl (lcb_t instance, int mode, int cmd, void *arg) |
This function exposes an ioctl/fcntl-like interface to read and write various configuration properties to and from an lcb_t handle. More... | |
lcb_error_t | lcb_cntl_string (lcb_t instance, const char *key, const char *value) |
Alternate way to set configuration settings by passing a string key and value. More... | |
lcb_error_t | lcb_cntl_setu32 (lcb_t instance, int cmd, lcb_U32 arg) |
Convenience function to set a value as an lcb_U32. More... | |
lcb_U32 | lcb_cntl_getu32 (lcb_t instance, int cmd) |
Retrieve an lcb_U32 setting. More... | |
int | lcb_cntl_exists (int ctl) |
Determine if a specific control code exists. More... | |
lcb_error_t | lcb_enable_timings (lcb_t instance) |
Start recording timing metrics for the different operations. More... | |
lcb_error_t | lcb_disable_timings (lcb_t instance) |
Stop recording (and release all resources from previous measurements) timing metrics. More... | |
lcb_error_t | lcb_get_timings (lcb_t instance, const void *cookie, lcb_timings_callback callback) |
Get the timings histogram. More... | |
const char * | lcb_get_version (lcb_U32 *version) |
Get the version of the library. More... | |
int | lcb_supports_feature (int n) |
void * | lcb_mem_alloc (lcb_SIZE size) |
Functions to allocate and free memory related to libcouchbase. More... | |
void | lcb_mem_free (void *ptr) |
Use this to free memory allocated with lcb_mem_alloc. | |
LCB_INTERNAL_API void | lcb_histogram_print (lcb_HISTOGRAM *hg, FILE *stream) |
Print the histogram to the specified FILE. More... | |
Server Versions | |
| |
lcb_error_t | lcb_server_versions3 (lcb_t instance, const void *cookie, const lcb_CMDBASE *cmd) |
Variables | |
LCB_EXTERN_VAR const lcb_U32 | lcb_version_g |
Global/extern variable containing the version of the library. | |
Receiving Responses | |
This section describes the APIs used in receiving responses. Each command will have a callback invoked (typically once, for some commands this may be more than once) with a response structure. The response structure will be of a type that extends lcb_RESPBASE. The response structure should not be modified and any of its fields should be considered to point to memory which will be released after the callback exits. The common response header contains the lcb_RESPBASE::cookie field which is the pointer to your application context (passed as the second argument to the spooling function) and allows you to associate a specific command with a specific response. The header will also contain the key (lcb_RESPBASE::key) field which can also help identify the specific command. This is useful if you maintain a single cookie for multiple commands, and have per-item specific data you wish to associate within the cookie itself. Success or failure of the operation is signalled through the lcb_RESPBASE::rc field. Note that even in the case of failure, the lcb_RESPBASE::cookie and lcb_RESPBASE::key fields will always be populated. Most commands also return the CAS of the item (as it exists on the server) and this is placed inside the lcb_RESPBASE::cas field, however it is only valid in the case where lcb_RESPBASE::rc is LCB_SUCCESS. | |
#define | LCB_RESP_BASE |
Response specific flags. More... | |
#define | LCB_RESP_SERVER_FIELDS |
#define | LCB_CALLBACK_VIEWQUERY |
Callback type for views (cannot be used for lcb_install_callback3()) | |
#define | LCB_CALLBACK_N1QL |
Callback type for N1QL (cannot be used for lcb_install_callback3()) | |
enum | lcb_RESPFLAGS |
Response flags. More... | |
enum | lcb_CALLBACKTYPE |
The type of response passed to the callback. More... | |
typedef void(* | lcb_RESPCALLBACK) (lcb_t instance, int cbtype, const lcb_RESPBASE *resp) |
lcb_RESPCALLBACK | lcb_install_callback3 (lcb_t instance, int cbtype, lcb_RESPCALLBACK cb) |
lcb_RESPCALLBACK | lcb_get_callback3 (lcb_t instance, int cbtype) |
const char * | lcb_strcbtype (int cbtype) |
Wait for a mutation to be persisted/replicated | |
#define | LCB_CMDENDURE_F_MUTATION_TOKEN |
Must specify this flag if using the 'mutation_token' field, as it was added in a later version. | |
#define | LCB_DURABILITY_VALIDATE_CAPMAX |
enum | lcb_DURMODE |
Type of durability polling to use. More... | |
lcb_MULTICMD_CTX * | lcb_endure3_ctxnew (lcb_t instance, const lcb_durability_opts_t *options, lcb_error_t *err) |
Return a new command context for scheduling endure operations. More... | |
lcb_error_t | lcb_storedur3 (lcb_t instance, const void *cookie, const lcb_CMDSTOREDUR *cmd) |
lcb_error_t | lcb_durability_validate (lcb_t instance, lcb_U16 *persist_to, lcb_U16 *replicate_to, int options) |
Retrieve current persistence/replication status | |
#define | LCB_CMDOBSERVE_F_MASTER_ONLY |
Set this bit in the cmdflags field to indicate that only the master node should be contacted. | |
enum | lcb_observe_t |
Possible statuses for keys in OBSERVE response. More... | |
lcb_MULTICMD_CTX * | lcb_observe3_ctxnew (lcb_t instance) |
Create a new multi context for an observe operation. More... | |
lcb_error_t | lcb_observe_seqno3 (lcb_t instance, const void *cookie, const lcb_CMDOBSEQNO *cmd) |
Get the persistence/replication status for a given mutation token. More... | |
Server Statistics | |
#define | LCB_CMDSTATS_F_KV |
The key is a stored item for which statistics should be retrieved. More... | |
typedef lcb_CMDBASE | lcb_CMDSTATS |
Command structure for stats request The lcb_CMDSTATS::key field should contain the statistics key, or be empty if the default statistics are desired. More... | |
lcb_error_t | lcb_stats3 (lcb_t instance, const void *cookie, const lcb_CMDSTATS *cmd) |
Schedule a request for statistics from the cluster. More... | |
Server Log Verbosity | |
enum | lcb_verbosity_level_t |
level field for lcb_server_verbosity3 () | |
typedef lcb_RESPSERVERBASE | lcb_RESPVERBOSITY |
lcb_error_t | lcb_server_verbosity3 (lcb_t instance, const void *cookie, const lcb_CMDVERBOSITY *cmd) |
Main header file for Couchbase.
enum lcb_DUMPFLAGS |
void lcb_refresh_config | ( | lcb_t | instance | ) |
Force the library to refetch the cluster configuration.
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:
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.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:
void* lcb_mem_alloc | ( | lcb_SIZE | size | ) |
Functions to allocate and free memory related to libcouchbase.
This is mainly for use on Windows where it is possible that the DLL and EXE are using two different CRTs
LCB_INTERNAL_API void lcb_histogram_print | ( | lcb_HISTOGRAM * | hg, |
FILE * | stream | ||
) |
Print the histogram to the specified FILE.
This essentially outputs the same raw information as lcb_histogram_read(), except it prints in implementation-defined format. It's simpler to use than lcb_histogram_read, but less flexible.
hg | the histogram |
stream | File to print the histogram to. |