git.m6w6.name Git - awesomized/libmemcached/blob - docs/source/libmemcached/memcached_result_st.rst

   1 Working with result sets
   2 ========================
   3
   4 SYNOPSIS
   5 --------
   6
   7 #include <libmemcached/memcached.h>
   8     Compile and link with -lmemcachedutil -lmemcached
   9
  10 .. type:: struct memcached_result_st memcached_result_st
  11
  12 .. function:: memcached_result_st *memcached_result_create (memcached_st *ptr, memcached_result_st *result)
  13
  14     :param ptr: pointer to initialized `memcached_st` struct
  15     :param result: pointer to an `memcached_result_st` instance to initialize or
  16                    nullptr to allocate a new instance
  17     :returns: pointer to initialized `memcached_result_st` instance
  18
  19 .. function:: void memcached_result_free (memcached_result_st *result)
  20
  21     :param result: pointer to initialized `memcached_result_st` struct
  22
  23 .. function:: const char * memcached_result_key_value (memcached_result_st *result)
  24
  25     :param result: pointer to initialized `memcached_result_st` struct
  26     :returns: the key value associated with the current result object
  27
  28 .. function:: size_t memcached_result_key_length (const memcached_result_st *result)
  29
  30     :param result: pointer to initialized `memcached_result_st` struct
  31     :returns: the key length associated with the current result object
  32
  33 .. function:: const char *memcached_result_value (memcached_result_st *result)
  34
  35     :param result: pointer to initialized `memcached_result_st` struct
  36     :returns: the result value associated with the current result object
  37
  38 .. function:: char *memcached_result_take_value (memcached_result_st *result)
  39
  40     :param result: pointer to initialized `memcached_result_st` struct
  41     :returns: the result value associated with the current result object
  42
  43 .. function:: size_t memcached_result_length (const memcached_result_st *result)
  44
  45     :param result: pointer to initialized `memcached_result_st` struct
  46     :returns: the result length associated with the current result object
  47
  48 .. function:: uint32_t memcached_result_flags (const memcached_result_st *result)
  49
  50     :param result: pointer to initialized `memcached_result_st` struct
  51     :returns: the flags associated with the current result object
  52
  53 .. function:: uint64_t memcached_result_cas (const memcached_result_st *result)
  54
  55     :param result: pointer to initialized `memcached_result_st` struct
  56     :returns: the cas associated with the current result object
  57
  58 .. function:: memcached_return_t memcached_result_set_value (memcached_result_st *result, const char *value, size_t length)
  59
  60     :param result: pointer to initialized `memcached_result_st` struct
  61     :param value: byte array to set the value of the current result object to
  62     :param length: the length of `value` wothout any terminating zero
  63     :returns: `memcached_return_t` indicating success
  64
  65 .. function:: void memcached_result_set_flags (memcached_result_st *result, uint32_t flags)
  66
  67     :param result: pointer to initialized `memcached_result_st` struct
  68     :param flags: a new value for the flags field
  69
  70 .. function:: void memcached_result_set_expiration (memcached_result_st *result, time_t expiration)
  71
  72     :param result: pointer to initialized `memcached_result_st` struct
  73     :param expiration: a new value for the expiration field
  74
  75
  76 DESCRIPTION
  77 -----------
  78
  79 `libmemcached` can optionally return a :type:`memcached_result_st` which
  80 acts as a result object. The result objects have added benefits over the
  81 character pointer return values, in that they are forward compatible with new
  82 return items that future memcached servers may implement (the best current
  83 example of this is the CAS return item). The structures can also be reused,
  84 which will save on calls to :manpage:`malloc(3)`. It is suggested that you use
  85 result objects over char \* return functions.
  86
  87 The structure of :type:`memcached_result_st` has been encapsulated, you should
  88 not write code directly accessing members of the structure.
  89
  90 :func:`memcached_result_create` will either allocate memory for a
  91 :type:`memcached_result_st` or will initialize a structure passed to it.
  92
  93 :func:`memcached_result_free` will deallocate any memory attached to the
  94 structure. If the structure was also allocated, it will deallocate it.
  95
  96 :func:`memcached_result_key_value` returns the key value associated with the
  97 current result object.
  98
  99 :func:`memcached_result_key_length` returns the key length associated with
 100 the current result object.
 101
 102 :func:`memcached_result_value` returns the result value associated with the
 103 current result object.
 104
 105 :func:`memcached_result_take_value` returns and hands over the result value
 106 associated with the current result object. You must call :manpage:`free(3)` to
 107 release this value, unless you have made use of a custom allocator. Use of a
 108 custom allocator requires that you create your own custom free() to release it.
 109
 110 :func:`memcached_result_length` returns the result length associated with
 111 the current result object.
 112
 113 :func:`memcached_result_flags` returns the flags associated with the
 114 current result object.
 115
 116 :func:`memcached_result_cas` returns the cas associated with the
 117 current result object. This value will only be available if the server
 118 tests it.
 119
 120 :func:`memcached_result_set_value` takes a byte array and a size and sets
 121 the result to this value. This function is used for trigger responses.
 122
 123 :func:`memcached_result_set_flags` takes a result structure and stores a new
 124 value for the flags field.
 125
 126 :func:`memcached_result_set_expiration` takes a result structure and stores
 127 a new value for the expiration field (this is only used by read through
 128 triggers).
 129
 130
 131 RETURN VALUE
 132 ------------
 133
 134 Varies, see particular functions. All structures must have
 135 :func:`memcached_result_free` called on them for cleanup purposes. Failure
 136 to do this will result in leaked memory.
 137
 138 SEE ALSO
 139 --------
 140
 141 .. only:: man
 142
 143     :manpage:`memcached(1)`
 144     :manpage:`libmemcached(3)`
 145     :manpage:`memcached_strerror(3)`
 146     :manpage:`memcached_memory_allocators(3)`
 147
 148 .. only:: html
 149
 150     * :manpage:`memcached(1)`
 151     * :doc:`../libmemcached`
 152     * :doc:`memcached_strerror`
 153     * :doc:`memcached_memory_allocators`