Merge pull request #140 from hussainnaqvee/patch-1
[awesomized/libmemcached] / 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`