1 | /* Copyright (c) 2011 The LevelDB Authors. All rights reserved. |
2 | Use of this source code is governed by a BSD-style license that can be |
3 | found in the LICENSE file. See the AUTHORS file for names of contributors. |
4 | |
5 | C bindings for leveldb. May be useful as a stable ABI that can be |
6 | used by programs that keep leveldb in a shared library, or for |
7 | a JNI api. |
8 | |
9 | Does not support: |
10 | . getters for the option types |
11 | . custom comparators that implement key shortening |
12 | . custom iter, db, env, cache implementations using just the C bindings |
13 | |
14 | Some conventions: |
15 | |
16 | (1) We expose just opaque struct pointers and functions to clients. |
17 | This allows us to change internal representations without having to |
18 | recompile clients. |
19 | |
20 | (2) For simplicity, there is no equivalent to the Slice type. Instead, |
21 | the caller has to pass the pointer and length as separate |
22 | arguments. |
23 | |
24 | (3) Errors are represented by a null-terminated c string. NULL |
25 | means no error. All operations that can raise an error are passed |
26 | a "char** errptr" as the last argument. One of the following must |
27 | be true on entry: |
28 | *errptr == NULL |
29 | *errptr points to a malloc()ed null-terminated error message |
30 | (On Windows, *errptr must have been malloc()-ed by this library.) |
31 | On success, a leveldb routine leaves *errptr unchanged. |
32 | On failure, leveldb frees the old value of *errptr and |
33 | set *errptr to a malloc()ed error message. |
34 | |
35 | (4) Bools have the type uint8_t (0 == false; rest == true) |
36 | |
37 | (5) All of the pointer arguments must be non-NULL. |
38 | */ |
39 | |
40 | #ifndef STORAGE_LEVELDB_INCLUDE_C_H_ |
41 | #define STORAGE_LEVELDB_INCLUDE_C_H_ |
42 | |
43 | #include <stdarg.h> |
44 | #include <stddef.h> |
45 | #include <stdint.h> |
46 | |
47 | #include "leveldb/export.h" |
48 | |
49 | #ifdef __cplusplus |
50 | extern "C" { |
51 | #endif |
52 | |
53 | /* Exported types */ |
54 | |
55 | typedef struct leveldb_t leveldb_t; |
56 | typedef struct leveldb_cache_t leveldb_cache_t; |
57 | typedef struct leveldb_comparator_t leveldb_comparator_t; |
58 | typedef struct leveldb_env_t leveldb_env_t; |
59 | typedef struct leveldb_filelock_t leveldb_filelock_t; |
60 | typedef struct leveldb_filterpolicy_t leveldb_filterpolicy_t; |
61 | typedef struct leveldb_iterator_t leveldb_iterator_t; |
62 | typedef struct leveldb_logger_t leveldb_logger_t; |
63 | typedef struct leveldb_options_t leveldb_options_t; |
64 | typedef struct leveldb_randomfile_t leveldb_randomfile_t; |
65 | typedef struct leveldb_readoptions_t leveldb_readoptions_t; |
66 | typedef struct leveldb_seqfile_t leveldb_seqfile_t; |
67 | typedef struct leveldb_snapshot_t leveldb_snapshot_t; |
68 | typedef struct leveldb_writablefile_t leveldb_writablefile_t; |
69 | typedef struct leveldb_writebatch_t leveldb_writebatch_t; |
70 | typedef struct leveldb_writeoptions_t leveldb_writeoptions_t; |
71 | |
72 | /* DB operations */ |
73 | |
74 | LEVELDB_EXPORT leveldb_t* leveldb_open(const leveldb_options_t* options, |
75 | const char* name, char** errptr); |
76 | |
77 | LEVELDB_EXPORT void leveldb_close(leveldb_t* db); |
78 | |
79 | LEVELDB_EXPORT void leveldb_put(leveldb_t* db, |
80 | const leveldb_writeoptions_t* options, |
81 | const char* key, size_t keylen, const char* val, |
82 | size_t vallen, char** errptr); |
83 | |
84 | LEVELDB_EXPORT void leveldb_delete(leveldb_t* db, |
85 | const leveldb_writeoptions_t* options, |
86 | const char* key, size_t keylen, |
87 | char** errptr); |
88 | |
89 | LEVELDB_EXPORT void leveldb_write(leveldb_t* db, |
90 | const leveldb_writeoptions_t* options, |
91 | leveldb_writebatch_t* batch, char** errptr); |
92 | |
93 | /* Returns NULL if not found. A malloc()ed array otherwise. |
94 | Stores the length of the array in *vallen. */ |
95 | LEVELDB_EXPORT char* leveldb_get(leveldb_t* db, |
96 | const leveldb_readoptions_t* options, |
97 | const char* key, size_t keylen, size_t* vallen, |
98 | char** errptr); |
99 | |
100 | LEVELDB_EXPORT leveldb_iterator_t* leveldb_create_iterator( |
101 | leveldb_t* db, const leveldb_readoptions_t* options); |
102 | |
103 | LEVELDB_EXPORT const leveldb_snapshot_t* leveldb_create_snapshot(leveldb_t* db); |
104 | |
105 | LEVELDB_EXPORT void leveldb_release_snapshot( |
106 | leveldb_t* db, const leveldb_snapshot_t* snapshot); |
107 | |
108 | /* Returns NULL if property name is unknown. |
109 | Else returns a pointer to a malloc()-ed null-terminated value. */ |
110 | LEVELDB_EXPORT char* leveldb_property_value(leveldb_t* db, |
111 | const char* propname); |
112 | |
113 | LEVELDB_EXPORT void leveldb_approximate_sizes( |
114 | leveldb_t* db, int num_ranges, const char* const* range_start_key, |
115 | const size_t* range_start_key_len, const char* const* range_limit_key, |
116 | const size_t* range_limit_key_len, uint64_t* sizes); |
117 | |
118 | LEVELDB_EXPORT void leveldb_compact_range(leveldb_t* db, const char* start_key, |
119 | size_t start_key_len, |
120 | const char* limit_key, |
121 | size_t limit_key_len); |
122 | |
123 | /* Management operations */ |
124 | |
125 | LEVELDB_EXPORT void leveldb_destroy_db(const leveldb_options_t* options, |
126 | const char* name, char** errptr); |
127 | |
128 | LEVELDB_EXPORT void leveldb_repair_db(const leveldb_options_t* options, |
129 | const char* name, char** errptr); |
130 | |
131 | /* Iterator */ |
132 | |
133 | LEVELDB_EXPORT void leveldb_iter_destroy(leveldb_iterator_t*); |
134 | LEVELDB_EXPORT uint8_t leveldb_iter_valid(const leveldb_iterator_t*); |
135 | LEVELDB_EXPORT void leveldb_iter_seek_to_first(leveldb_iterator_t*); |
136 | LEVELDB_EXPORT void leveldb_iter_seek_to_last(leveldb_iterator_t*); |
137 | LEVELDB_EXPORT void leveldb_iter_seek(leveldb_iterator_t*, const char* k, |
138 | size_t klen); |
139 | LEVELDB_EXPORT void leveldb_iter_next(leveldb_iterator_t*); |
140 | LEVELDB_EXPORT void leveldb_iter_prev(leveldb_iterator_t*); |
141 | LEVELDB_EXPORT const char* leveldb_iter_key(const leveldb_iterator_t*, |
142 | size_t* klen); |
143 | LEVELDB_EXPORT const char* leveldb_iter_value(const leveldb_iterator_t*, |
144 | size_t* vlen); |
145 | LEVELDB_EXPORT void leveldb_iter_get_error(const leveldb_iterator_t*, |
146 | char** errptr); |
147 | |
148 | /* Write batch */ |
149 | |
150 | LEVELDB_EXPORT leveldb_writebatch_t* leveldb_writebatch_create(void); |
151 | LEVELDB_EXPORT void leveldb_writebatch_destroy(leveldb_writebatch_t*); |
152 | LEVELDB_EXPORT void leveldb_writebatch_clear(leveldb_writebatch_t*); |
153 | LEVELDB_EXPORT void leveldb_writebatch_put(leveldb_writebatch_t*, |
154 | const char* key, size_t klen, |
155 | const char* val, size_t vlen); |
156 | LEVELDB_EXPORT void leveldb_writebatch_delete(leveldb_writebatch_t*, |
157 | const char* key, size_t klen); |
158 | LEVELDB_EXPORT void leveldb_writebatch_iterate( |
159 | const leveldb_writebatch_t*, void* state, |
160 | void (*put)(void*, const char* k, size_t klen, const char* v, size_t vlen), |
161 | void (*deleted)(void*, const char* k, size_t klen)); |
162 | LEVELDB_EXPORT void leveldb_writebatch_append( |
163 | leveldb_writebatch_t* destination, const leveldb_writebatch_t* source); |
164 | |
165 | /* Options */ |
166 | |
167 | LEVELDB_EXPORT leveldb_options_t* leveldb_options_create(void); |
168 | LEVELDB_EXPORT void leveldb_options_destroy(leveldb_options_t*); |
169 | LEVELDB_EXPORT void leveldb_options_set_comparator(leveldb_options_t*, |
170 | leveldb_comparator_t*); |
171 | LEVELDB_EXPORT void leveldb_options_set_filter_policy(leveldb_options_t*, |
172 | leveldb_filterpolicy_t*); |
173 | LEVELDB_EXPORT void leveldb_options_set_create_if_missing(leveldb_options_t*, |
174 | uint8_t); |
175 | LEVELDB_EXPORT void leveldb_options_set_error_if_exists(leveldb_options_t*, |
176 | uint8_t); |
177 | LEVELDB_EXPORT void leveldb_options_set_paranoid_checks(leveldb_options_t*, |
178 | uint8_t); |
179 | LEVELDB_EXPORT void leveldb_options_set_env(leveldb_options_t*, leveldb_env_t*); |
180 | LEVELDB_EXPORT void leveldb_options_set_info_log(leveldb_options_t*, |
181 | leveldb_logger_t*); |
182 | LEVELDB_EXPORT void leveldb_options_set_write_buffer_size(leveldb_options_t*, |
183 | size_t); |
184 | LEVELDB_EXPORT void leveldb_options_set_max_open_files(leveldb_options_t*, int); |
185 | LEVELDB_EXPORT void leveldb_options_set_cache(leveldb_options_t*, |
186 | leveldb_cache_t*); |
187 | LEVELDB_EXPORT void leveldb_options_set_block_size(leveldb_options_t*, size_t); |
188 | LEVELDB_EXPORT void leveldb_options_set_block_restart_interval( |
189 | leveldb_options_t*, int); |
190 | LEVELDB_EXPORT void leveldb_options_set_max_file_size(leveldb_options_t*, |
191 | size_t); |
192 | |
193 | enum { leveldb_no_compression = 0, leveldb_snappy_compression = 1 }; |
194 | LEVELDB_EXPORT void leveldb_options_set_compression(leveldb_options_t*, int); |
195 | |
196 | /* Comparator */ |
197 | |
198 | LEVELDB_EXPORT leveldb_comparator_t* leveldb_comparator_create( |
199 | void* state, void (*destructor)(void*), |
200 | int (*compare)(void*, const char* a, size_t alen, const char* b, |
201 | size_t blen), |
202 | const char* (*name)(void*)); |
203 | LEVELDB_EXPORT void leveldb_comparator_destroy(leveldb_comparator_t*); |
204 | |
205 | /* Filter policy */ |
206 | |
207 | LEVELDB_EXPORT leveldb_filterpolicy_t* leveldb_filterpolicy_create( |
208 | void* state, void (*destructor)(void*), |
209 | char* (*create_filter)(void*, const char* const* key_array, |
210 | const size_t* key_length_array, int num_keys, |
211 | size_t* filter_length), |
212 | uint8_t (*key_may_match)(void*, const char* key, size_t length, |
213 | const char* filter, size_t filter_length), |
214 | const char* (*name)(void*)); |
215 | LEVELDB_EXPORT void leveldb_filterpolicy_destroy(leveldb_filterpolicy_t*); |
216 | |
217 | LEVELDB_EXPORT leveldb_filterpolicy_t* leveldb_filterpolicy_create_bloom( |
218 | int bits_per_key); |
219 | |
220 | /* Read options */ |
221 | |
222 | LEVELDB_EXPORT leveldb_readoptions_t* leveldb_readoptions_create(void); |
223 | LEVELDB_EXPORT void leveldb_readoptions_destroy(leveldb_readoptions_t*); |
224 | LEVELDB_EXPORT void leveldb_readoptions_set_verify_checksums( |
225 | leveldb_readoptions_t*, uint8_t); |
226 | LEVELDB_EXPORT void leveldb_readoptions_set_fill_cache(leveldb_readoptions_t*, |
227 | uint8_t); |
228 | LEVELDB_EXPORT void leveldb_readoptions_set_snapshot(leveldb_readoptions_t*, |
229 | const leveldb_snapshot_t*); |
230 | |
231 | /* Write options */ |
232 | |
233 | LEVELDB_EXPORT leveldb_writeoptions_t* leveldb_writeoptions_create(void); |
234 | LEVELDB_EXPORT void leveldb_writeoptions_destroy(leveldb_writeoptions_t*); |
235 | LEVELDB_EXPORT void leveldb_writeoptions_set_sync(leveldb_writeoptions_t*, |
236 | uint8_t); |
237 | |
238 | /* Cache */ |
239 | |
240 | LEVELDB_EXPORT leveldb_cache_t* leveldb_cache_create_lru(size_t capacity); |
241 | LEVELDB_EXPORT void leveldb_cache_destroy(leveldb_cache_t* cache); |
242 | |
243 | /* Env */ |
244 | |
245 | LEVELDB_EXPORT leveldb_env_t* leveldb_create_default_env(void); |
246 | LEVELDB_EXPORT void leveldb_env_destroy(leveldb_env_t*); |
247 | |
248 | /* If not NULL, the returned buffer must be released using leveldb_free(). */ |
249 | LEVELDB_EXPORT char* leveldb_env_get_test_directory(leveldb_env_t*); |
250 | |
251 | /* Utility */ |
252 | |
253 | /* Calls free(ptr). |
254 | REQUIRES: ptr was malloc()-ed and returned by one of the routines |
255 | in this file. Note that in certain cases (typically on Windows), you |
256 | may need to call this routine instead of free(ptr) to dispose of |
257 | malloc()-ed memory returned by this library. */ |
258 | LEVELDB_EXPORT void leveldb_free(void* ptr); |
259 | |
260 | /* Return the major version number for this release. */ |
261 | LEVELDB_EXPORT int leveldb_major_version(void); |
262 | |
263 | /* Return the minor version number for this release. */ |
264 | LEVELDB_EXPORT int leveldb_minor_version(void); |
265 | |
266 | #ifdef __cplusplus |
267 | } /* end extern "C" */ |
268 | #endif |
269 | |
270 | #endif /* STORAGE_LEVELDB_INCLUDE_C_H_ */ |
271 | |