#include <kvstore.h> kv_error_t kv_put_with_options(kv_store_t *store, const kv_key_t *key, const kv_value_t *value, const kv_version_t *if_version, kv_presence_enum if_presence, kv_version_t **new_version, kv_value_t **previous_value, kv_return_value_version_enum return_info, kv_durability_t durability, kv_timeout_t timeout_ms)
Writes the key/value pair to the store, inserting or overwriting as appropriate.
The key parameter is the key that you want to write to the store. It is created using kv_create_key() or kv_create_key_from_uri().
The value parameter is the value that you want to write to the store. It is created using kv_create_value().
The if_version parameter indicates that the record should be put only if the existing value matches the version supplied to this parameter. Use this parameter when updating a value to ensure that it has not changed since it was last read. The version is obtained using the kv_get_version() function.
The if_presence
parameter describes the conditions under which the
record can be put, based on the presence or absence of
the record in the store. For example,
KV_IF_PRESENT means that the record
can only be written to the store if a version of the
record already exists there.
For a list of all the available presence options, see kv_presence_enum.
The new_version
parameter references memory into which is copied the
key/value pair's new version information. This pointer
will be NULL if this function produces a non-zero
return code, or if
return_info is not
KV_RETURN_VALUE_ALL or
KV_RETURN_VALUE_VERSION.
You release the resources used by the version data structure using kv_release_version().
The previous_value
parameter references memory into which is copied the
previous value associated with the given key. Returns
NULL if there was no previous value (the operation is
inserting a new record, rather than updating an
existing one); or if
return_info is not
KV_RETURN_VALUE_ALL or
KV_RETURN_VALUE_VALUE.
You release the resources used by this parameter using kv_release_value().
The return_info parameter indicates what version and value information should be returned as a part of this operation. See kv_return_value_version_enum for a list of possible options.
The durability parameter provides the durability guarantee to be used with this write operation. Durability guarantees are created using kv_create_durability().
The timeout_ms parameter provides an upper bound on the time interval for processing the operation. A best effort is made not to exceed the specified limit. If zero, the default request timeout is used. The default request timeout is set using kv_config_set_timeouts().