Couchbase C Client  3.2.4
Asynchronous C Client for Couchbase
Create/Update

Detailed Description

Set the value of a document.

Functions

lcb_STATUS lcb_respstore_status (const lcb_RESPSTORE *resp)
 
lcb_STATUS lcb_respstore_error_context (const lcb_RESPSTORE *resp, const lcb_KEY_VALUE_ERROR_CONTEXT **ctx)
 
lcb_STATUS lcb_respstore_cookie (const lcb_RESPSTORE *resp, void **cookie)
 
lcb_STATUS lcb_respstore_cas (const lcb_RESPSTORE *resp, uint64_t *cas)
 
lcb_STATUS lcb_respstore_key (const lcb_RESPSTORE *resp, const char **key, size_t *key_len)
 
lcb_STATUS lcb_respstore_operation (const lcb_RESPSTORE *resp, lcb_STORE_OPERATION *operation)
 
lcb_STATUS lcb_respstore_mutation_token (const lcb_RESPSTORE *resp, lcb_MUTATION_TOKEN *token)
 
int lcb_respstore_observe_attached (const lcb_RESPSTORE *resp)
 
lcb_STATUS lcb_respstore_observe_stored (const lcb_RESPSTORE *resp, int *store_ok)
 
lcb_STATUS lcb_respstore_observe_master_exists (const lcb_RESPSTORE *resp, int *master_exists)
 
lcb_STATUS lcb_respstore_observe_master_persisted (const lcb_RESPSTORE *resp, int *master_persisted)
 
lcb_STATUS lcb_respstore_observe_num_responses (const lcb_RESPSTORE *resp, uint16_t *num_responses)
 
lcb_STATUS lcb_respstore_observe_num_persisted (const lcb_RESPSTORE *resp, uint16_t *num_persisted)
 
lcb_STATUS lcb_respstore_observe_num_replicated (const lcb_RESPSTORE *resp, uint16_t *num_replicated)
 
lcb_STATUS lcb_cmdstore_create (lcb_CMDSTORE **cmd, lcb_STORE_OPERATION operation)
 
lcb_STATUS lcb_cmdstore_destroy (lcb_CMDSTORE *cmd)
 
lcb_STATUS lcb_cmdstore_parent_span (lcb_CMDSTORE *cmd, lcbtrace_SPAN *span)
 
lcb_STATUS lcb_cmdstore_collection (lcb_CMDSTORE *cmd, const char *scope, size_t scope_len, const char *collection, size_t collection_len)
 
lcb_STATUS lcb_cmdstore_key (lcb_CMDSTORE *cmd, const char *key, size_t key_len)
 
lcb_STATUS lcb_cmdstore_value (lcb_CMDSTORE *cmd, const char *value, size_t value_len)
 
lcb_STATUS lcb_cmdstore_value_iov (lcb_CMDSTORE *cmd, const lcb_IOV *value, size_t value_len)
 
lcb_STATUS lcb_cmdstore_expiry (lcb_CMDSTORE *cmd, uint32_t expiration)
 
lcb_STATUS lcb_cmdstore_preserve_expiry (lcb_CMDSTORE *cmd, int should_preserve)
 
lcb_STATUS lcb_cmdstore_cas (lcb_CMDSTORE *cmd, uint64_t cas)
 
lcb_STATUS lcb_cmdstore_flags (lcb_CMDSTORE *cmd, uint32_t flags)
 
lcb_STATUS lcb_cmdstore_datatype (lcb_CMDSTORE *cmd, uint8_t datatype)
 
lcb_STATUS lcb_cmdstore_durability (lcb_CMDSTORE *cmd, lcb_DURABILITY_LEVEL level)
 
lcb_STATUS lcb_cmdstore_durability_observe (lcb_CMDSTORE *cmd, int persist_to, int replicate_to)
 
lcb_STATUS lcb_cmdstore_timeout (lcb_CMDSTORE *cmd, uint32_t timeout)
 
lcb_STATUS lcb_cmdstore_on_behalf_of (lcb_CMDSTORE *cmd, const char *data, size_t data_len)
 
lcb_STATUS lcb_store (lcb_INSTANCE *instance, void *cookie, const lcb_CMDSTORE *cmd)
 

Typedefs

typedef struct lcb_RESPSTORE_ lcb_RESPSTORE
 Schedule a single storage request. More...
 
typedef struct lcb_CMDSTORE_ lcb_CMDSTORE
 

Enumerations

enum  lcb_STORE_OPERATION
 Values for lcb_CMDSTORE::operation. More...
 

Function Documentation

◆ lcb_cmdstore_on_behalf_of()

lcb_STATUS lcb_cmdstore_on_behalf_of ( lcb_CMDSTORE *  cmd,
const char *  data,
size_t  data_len 
)
Stability
Internal:
Internal: This should never be used and is not supported.

Typedef Documentation

◆ lcb_RESPSTORE

typedef struct lcb_RESPSTORE_ lcb_RESPSTORE

Schedule a single storage request.

Stability
Committed:
Parameters
instancethe handle
cookiepointer to associate with the command
cmdthe command structure
Returns
LCB_SUCCESS on success, error code on failure

Request

lcb_CMDSTORE* cmd;
// insert only if key doesn't already exist
lcb_cmdstore_create(&cmd, LCB_STORE_INSERT);
lcb_cmdstore_key(cmd, "Key", 3);
lcb_cmdstore_value(cmd, "value", 5);
lcb_cmdstore_expiry(cmd, 60); // expire in a minute
lcb_store(instance, cookie, &cmd);
@ LCB_STORE_INSERT
Will cause the operation to fail if the key already exists in the cluster.
Definition: couchbase.h:878
lcb_STATUS lcb_wait(lcb_INSTANCE *instance, lcb_WAITFLAGS flags)
Wait for completion of scheduled operations.
@ LCB_WAIT_NOCHECK
Do not check pending operations before running the event loop.
Definition: couchbase.h:1823

Response

lcb_install_callback(instance, LCB_CALLBACK_STORE, store_callback);
void store_callback(lcb_INSTANCE *instance, int cbtype, const lcb_RESPBASE *rb)
{
uint64_t cas;
const lcb_RESPSTORE resp = (const lcb_RESPSTORE*)rb;
lcb_STATUS rc = lcb_respstore_status(resp);
if (rc == LCB_SUCCESS) {
lcb_respstore_cas(resp, &cas)
printf("Store success: CAS=%llx\n", cas);
} else {
printf("Store failed: %s\n", lcb_strerror_short(rc);
}
}
LCB_INTERNAL_API const char * lcb_strerror_short(lcb_STATUS error)
Get a shorter textual description of an error message.
lcb_STATUS
Error codes returned by the library.
Definition: error.h:212
struct lcb_st lcb_INSTANCE
Library handle representing a connection to a cluster and its data buckets.
Definition: couchbase.h:35
lcb_RESPCALLBACK lcb_install_callback(lcb_INSTANCE *instance, int cbtype, lcb_RESPCALLBACK cb)
@ LCB_CALLBACK_STORE
lcb_store()
Definition: couchbase.h:472
struct lcb_RESPSTORE_ lcb_RESPSTORE
Schedule a single storage request.
Definition: couchbase.h:956

Operation-specific error codes include:

  • ::LCB_ERR_DOCUMENT_NOT_FOUND if ::LCB_REPLACE was used and the key does not exist
  • ::LCB_ERR_DOCUMENT_EXISTS if ::LCB_INSERT was used and the key already exists
  • ::LCB_ERR_DOCUMENT_EXISTS if the CAS was specified (for an operation other than ::LCB_INSERT) and the item exists on the server with a different CAS
  • ::LCB_ERR_DOCUMENT_EXISTS if the item was locked and the CAS supplied did not match the locked item's CAS (or if no CAS was supplied)
  • ::LCB_ERR_NOT_STORED if an ::LCB_APPEND or ::LCB_PREPEND operation was performed and the item did not exist on the server.
  • ::LCB_ERR_VALUE_TOO_LARGE if the size of the value exceeds the cluster per-item value limit (currently 20MB).

For a 6.5 or later cluster, you should use the lcb_cmdstore_durability to make the lcb_store not return until the requested durabilty is met. If the cluster is an older version, you can use lcb_cmdstore_durability_observe.

Enumeration Type Documentation

◆ lcb_STORE_OPERATION

Values for lcb_CMDSTORE::operation.

Storing an item in couchbase is only one operation with a different set of attributes / constraints.

Enumerator
LCB_STORE_UPSERT 

The default storage mode.

This constant was added in version 2.6.2 for the sake of maintaining a default storage mode, eliminating the need for simple storage operations to explicitly define lcb_CMDSTORE::operation. Behaviorally it is identical to LCB_STORE_UPSERT in that it will make the server unconditionally store the item, whether it exists or not.

LCB_STORE_INSERT 

Will cause the operation to fail if the key already exists in the cluster.

LCB_STORE_REPLACE 

Will cause the operation to fail unless the key already exists in the cluster.

LCB_STORE_APPEND 

Rather than setting the contents of the entire document, take the value specified in lcb_CMDSTORE::value and append it to the existing bytes in the value.

LCB_STORE_PREPEND 

Like LCB_STORE_APPEND, but prepends the new value to the existing value.