Name

lcb_touch — touch (update expiry time) a document

Synopsis

cc [ flag … ] file… -lcouchbase [ library … ]

#include <libcouchbase/couchbase.h>
lcb_error_t lcb_touch(lcb_t instance,
                      const void *command_cookie,
                      lcb_size_t num,
                      const lcb_touch_cmd_t *const *commands);

DESCRIPTION

lcb_touch() is used to touch a document, which can increase or decrease the document’s time to live. If the library instance is using asynchronous mode (the default) this operation will return immediately and schedule the operations to be executed by the event loop, otherwise it will block until all commands are executed. command_cookie is is an opaque field that will be provided to the callback function. num is the number of entries in the commands array.

lcb_touch_cmd_t is a structure defined in <libcouchbase/arguments.h> as alias to lcb_get_cmd_t, therefore has the same layout:

typedef struct {
    int version;              /* The entry in "v" to use */
    union {
        struct {
            const void *key;    /* The key this response belongs to */
            lcb_size_t nkey;    /* The number of bytes in the key */
            lcb_time_t exptime; /* New key expiration time */
            int lock;           /* Lock the document if non-zero */
            const void *hashkey; /* hash key if != key */
            lcb_size_t nhashkey; /* number of bytes in hash key */
        } v0;
    } v;
} lcb_get_cmd_t;
typedef lcb_get_cmd_t lcb_touch_cmd_t;

Values of exptime larger than 30*24*60*60 seconds (30 days) are interpreted as absolute times (from the epoch).

Set cas to 0 unless you want to touch the document only if the key and cas match.

Please note that using the another key for hashing may lead to an unbalanced cluster if the key does not distribute well with a crc32 hash.

Upon completion the touch callback as set by lcb_set_touch_callback is called.

RETURN VALUES

lcb_touch() returns the LCB_SUCCESS on success, or a specific error code upon failure. See lcb_strerror(3couchbase) for more information.

EXAMPLES

#include <libcouchbase/couchbase.h>
...
lcb_t instance;
...
lcb_touch_cmd_t *touch = calloc(1, sizeof(*touch));
touch->version = 0;
touch->v.v0.key = "my-key";
touch->v.v0.nkey = strlen(touch->v.v0.key);
touch->v.v0.cas = 0x666;
lcb_touch_cmd_t* commands[] = { touch };
lcb_touch(instance, NULL, 1, commands);
...

ATTRIBUTES

See lcb_attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Interface Stability

Committed

MT-Level

MT-Safe

COPYRIGHT

Copyright 2010-2013 Couchbase, Inc.

SEE ALSO

Learn more at http://www.couchbase.com/communities/c.

libcouchbase(3lib), lcb_set_touch_callback(3couchbase), lcb_attributes(5)