Couchbase C Client
2.5.6
|
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_SET_KEY(cmd, keybuf, keylen) |
#define | LCB_CMD__SETVBID(cmd, vbid) |
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) |
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) |
#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()) | |
lcb_RESPCALLBACK lcb_install_callback3 | ( | lcb_t | instance, |
int | cbtype, | ||
lcb_RESPCALLBACK | cb | ||
) |
Install a new-style callback for an operation. The callback will be invoked with the relevant response structure.
instance | the handle |
cbtype | the type of operation for which this callback should be installed. The value should be one of the lcb_CALLBACKTYPE constants |
cb | the callback to install |
cbtype
to LCB_CALLBACK_DEFAULT then your 2.x
callbacks will not work.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
. lcb_RESPCALLBACK lcb_get_callback3 | ( | lcb_t | instance, |
int | cbtype | ||
) |
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
.
instance | the handle |
cbtype | the type of callback to retrieve |
const char* lcb_strcbtype | ( | int | cbtype | ) |
Returns the type of the callback as a string. This function is helpful for debugging and demonstrative processes.
cbtype | the type of the callback (the second argument to the callback) |
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 |
|
struct lcb_RESPBASE |
Base response structure for callbacks.
All responses structures derive from this ABI.
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 |
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. |
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() |
#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.
#define LCB_CMD_SET_KEY | ( | cmd, | |
keybuf, | |||
keylen | |||
) |
Set the key for the command.
cmd | A command derived from lcb_CMDBASE |
keybuf | the buffer for the key |
keylen | the length of the key. |
The storage for keybuf
may be released or modified after the command has been spooled.
#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.
cmd | the command structure |
vbid | the vBucket ID for the key. |
#define LCB_RESP_BASE |
Response specific flags.
see lcb_RESPFLAGS
typedef void(* lcb_RESPCALLBACK) (lcb_t instance, int cbtype, const lcb_RESPBASE *resp) |
Callback invoked for responses.
instance | The handle |
cbtype | The type of callback - or in other words, the type of operation this callback has been invoked for. |
resp | The response for the operation. Depending on the operation this response structure should be casted into a more specialized type. |
enum 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. |
enum 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.
Enumerator | |
---|---|
LCB_CALLBACK_DEFAULT |
Default callback invoked as a fallback. |
LCB_CALLBACK_GET | |
LCB_CALLBACK_STORE | |
LCB_CALLBACK_COUNTER | |
LCB_CALLBACK_TOUCH | |
LCB_CALLBACK_REMOVE | |
LCB_CALLBACK_UNLOCK | |
LCB_CALLBACK_STATS | |
LCB_CALLBACK_VERSIONS | |
LCB_CALLBACK_VERBOSITY | |
LCB_CALLBACK_FLUSH | |
LCB_CALLBACK_OBSERVE | |
LCB_CALLBACK_GETREPLICA | |
LCB_CALLBACK_ENDURE | |
LCB_CALLBACK_HTTP | |
LCB_CALLBACK_CBFLUSH | |
LCB_CALLBACK_OBSEQNO | |
LCB_CALLBACK_SDLOOKUP |
<for lcb_storedur3() |