Couchbase C Client
2.5.6
|
Set the value of a document.
Functions | |
lcb_error_t | lcb_store3 (lcb_t instance, const void *cookie, const lcb_CMDSTORE *cmd) |
Schedule a single storage request. More... | |
Macros | |
#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... | |
Enumerations | |
enum | lcb_storage_t |
Values for lcb_CMDSTORE::operation. More... | |
lcb_error_t lcb_store3 | ( | lcb_t | instance, |
const void * | cookie, | ||
const lcb_CMDSTORE * | cmd | ||
) |
Schedule a single storage request.
instance | the handle |
cookie | pointer to associate with the command |
cmd | the command structure |
### Response
Operation-specific error codes include:
struct lcb_CMDSTORE |
Command for storing an item to the server.
This command must contain the key to mutate, the value which should be set (or appended/prepended) in the lcb_CMDSTORE::value field (see LCB_CMD_SET_VALUE()) and the operation indicating the mutation type (lcb_CMDSTORE::operation).
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 |
|
lcb_VALBUF | value |
Value to store on the server. The value may be set using the LCB_CMD_SET_VALUE() or LCB_CMD_SET_VALUEIOV() API |
lcb_U32 | flags |
Format flags used by clients to determine the underlying encoding of the value. This value is also returned during retrieval operations in the lcb_RESPGET::itmflags field |
lcb_datatype_t | datatype | Do not set this value for now. |
lcb_storage_t | operation |
Controls how the operation is perfomed. See the documentation for lcb_storage_t for the options. There is no default value for this field. |
struct lcb_RESPSTORE |
Response structure for lcb_store3()
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_storage_t | op | The type of operation which was performed. |
#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.
scmd | an lcb_CMDSTORE pointer |
valbuf | the buffer for the value |
vallen | the length of the buffer |
The buffer needs to remain valid only until the command is passed to the lcb_store3() function.
#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.
scmd | the command which needs a value |
iovs | an array of lcb_IOV structures |
niovs | number of items in the array. |
The buffers (and the IOV array itself) need to remain valid only until the scheduler function is called. Once the scheduling function is called, the buffer contents are copied into the library's internal buffers.
enum lcb_storage_t |
Values for lcb_CMDSTORE::operation.
Storing an item in couchbase is only one operation with a different set of attributes / constraints.
Enumerator | |
---|---|
LCB_ADD |
Will cause the operation to fail if the key already exists in the cluster. |
LCB_REPLACE |
Will cause the operation to fail unless the key already exists in the cluster. |
LCB_SET |
Unconditionally store the item in the cluster. |
LCB_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. This is functionally equivalent to the following: {
const char *to_append = "stuff to append";
char *new_value;
size_t new_value_len;
lcb_CMDSTORE cmd = { 0 };
lcb_IOV iov[2];
cmd.operation = LCB_APPEND;
iov[0].iov_base = (void *)resp->value;
iov[0].iov_len = resp->nvalue;
iov[1].iov_base = (void *)to_append;
iov[1].iov_len = strlen(to_append);
LCB_CMD_SET_VALUEIOV(&cmd, iov, 2);
lcb_store3(instance, NULL, &cmd);
}
|
LCB_PREPEND |
Like LCB_APPEND, but prepends the new value to the existing value. |