Couchbase C Client  2.8.5
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.
 
 Delete
 Remove documents from the cluster.
 
 MULTICMD API
 
 Durability
 Ensure persistence and mutation of documents.
 
 Mutation Tokens
 
 Counters
 Manipulate the numeric content of a document.
 
 Lock/Unlock
 
 Touch/Expiry
 Modify or clear a document's expiration time.
 

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_F_MULTIAUTH
 If this flag is set, then multiple authentication credentials will be passed to the server. More...
 
#define LCB_CMD_SET_KEY(cmd, keybuf, keylen)
 Set the key for the command. More...
 
#define LCB_CMD__SETVBID(cmd, vbid)
 Sets the vBucket ID for the item. More...
 

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.

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)
 Callback invoked for responses. More...
 
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)
 Returns the type of the callback as a string. More...
 
#define LCB_RESP_BASE
 
#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())
 
#define LCB_CALLBACK_IXMGMT
 Callback type for N1QL index management (cannot be used for lcb_install_callback3())
 

Function Documentation

◆ lcb_install_callback3()

lcb_RESPCALLBACK lcb_install_callback3 ( lcb_t  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_CALLBACKTYPE 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, and example/minimal/minimal.c.

◆ lcb_get_callback3()

lcb_RESPCALLBACK lcb_get_callback3 ( lcb_t  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/minimal/minimal.c.

Data Structure Documentation

◆ lcb_CMDBASE

struct lcb_CMDBASE

Common ABI header for all commands.

Any command may be safely casted to this type.

Data Fields
lcb_U32 cmdflags Common flags for the command.

These modify the command itself. Currently the lower 16 bits of this field are reserved, and the higher 16 bits are used for individual commands.

lcb_U32 exptime Specify the expiration time.

This is either an absolute Unix time stamp or a relative offset from now, in seconds. If the value of this number is greater than the value of thirty days in seconds, then it is a Unix timestamp. This field is used in mutation operations (lcb_store3()) to indicate the lifetime of the item. It is used in lcb_get3() with the lcb_CMDGET::lock option to indicate the lock expiration itself.

lcb_U64 cas The known CAS of the item.

This is passed to mutation to commands to ensure the item is only changed if the server-side CAS value matches the one specified here. For other operations (such as lcb_CMDENDURE) this is used to ensure that the item has been persisted/replicated to a number of servers with the value specified here.

lcb_KEYBUF key The key for the document itself.

This should be set via LCB_CMD_SET_KEY()

lcb_KEYBUF _hashkey
Stability
Volatile:

◆ lcb_RESPBASE

struct lcb_RESPBASE

Base response structure for callbacks.

All responses structures derive from this ABI.

Examples:
example/libeventdirect/main.c, and example/minimal/minimal.c.
Data Fields
void * cookie Application-defined pointer passed as the cookie parameter when scheduling the command.
const void * key Key for request.
lcb_SIZE nkey Size of key.
lcb_CAS cas CAS for response (if applicable)
lcb_error_t rc Status code.
lcb_U16 version ABI version for response.
lcb_U16 rflags Response specific flags.

see lcb_RESPFLAGS

◆ lcb_RESPSERVERBASE

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.

Data Fields
void * cookie Application-defined pointer passed as the cookie parameter when scheduling the command.
const void * key Key for request.
lcb_SIZE nkey Size of key.
lcb_CAS cas CAS for response (if applicable)
lcb_error_t rc Status code.
lcb_U16 version ABI version for response.
lcb_U16 rflags Response specific flags.

see lcb_RESPFLAGS

const char * server String containing the host:port of the server which sent this response.

◆ lcb_MUTATION_TOKEN

struct lcb_MUTATION_TOKEN

Structure representing a synchronization token.

This token may be used for durability operations and N1QL queries. The contents of this structure should be considered opaque, and accessed via the various macros

Data Fields
lcb_U64 uuid_ Use LCB_MUTATION_TOKEN_ID()
lcb_U64 seqno_ Use LCB_MUTATION_TOKEN_SEQ()
lcb_U16 vbid_ Use LCB_MUTATION_TOKEN_VB()

Macro Definition Documentation

◆ LCB_CMD_F_INTERNAL_CALLBACK

#define LCB_CMD_F_INTERNAL_CALLBACK

Flag for lcb_CMDBASE::cmdflags which indicates that the lcb_CMDBASE::cookie is a special callback object.

This flag is used internally within the library.

Stability
Internal:

◆ LCB_CMD_F_MULTIAUTH

#define LCB_CMD_F_MULTIAUTH

If this flag is set, then multiple authentication credentials will be passed to the server.

By default only the bucket's credentials (i.e. bucket SASL password) are passed.

◆ LCB_CMD_SET_KEY

#define LCB_CMD_SET_KEY (   cmd,
  keybuf,
  keylen 
)

Set the key for the command.

Parameters
cmdA command derived from lcb_CMDBASE
keybufthe buffer for the key
keylenthe length of the key.
lcb_CMDGET cmd = { 0 };
LCB_CMD_SET_KEY(&cmd, "key", strlen("key"));

The storage for keybuf may be released or modified after the command has been spooled.

Examples:
example/libeventdirect/main.c, and example/minimal/minimal.c.

◆ LCB_CMD__SETVBID

#define LCB_CMD__SETVBID (   cmd,
  vbid 
)

Sets the vBucket ID for the item.

This accomplishes the same effect as hashkey except that this assumes the vBucket has already been obtained.

The intent of this API is to override the default vBucket hashing/calculation.

Parameters
cmdthe command structure
vbidthe vBucket ID for the key.
Stability
Volatile:

Typedef Documentation

◆ lcb_RESPCALLBACK

typedef void(* lcb_RESPCALLBACK) (lcb_t 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.

Enumeration Type Documentation

◆ lcb_RESPFLAGS

Response flags.

These provide additional 'meta' information about the response One of more of these values can be set in lcb_RESPBASE::rflags

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_CALLBACKTYPE

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_get3()

LCB_CALLBACK_STORE 

lcb_store3()

LCB_CALLBACK_COUNTER 

lcb_counter3()

LCB_CALLBACK_TOUCH 

lcb_touch3()

LCB_CALLBACK_REMOVE 

lcb_remove3()

LCB_CALLBACK_UNLOCK 

lcb_unlock3()

LCB_CALLBACK_STATS 

lcb_stats3()

LCB_CALLBACK_VERSIONS 

lcb_server_versions3()

LCB_CALLBACK_VERBOSITY 

lcb_server_verbosity3()

LCB_CALLBACK_FLUSH 

lcb_flush3()

LCB_CALLBACK_OBSERVE 

lcb_observe3_ctxnew()

LCB_CALLBACK_GETREPLICA 

lcb_rget3()

LCB_CALLBACK_ENDURE 

lcb_endure3_ctxnew()

LCB_CALLBACK_HTTP 

lcb_http3()

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()