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
50extern "C" {
51#endif
52
53/* Exported types */
54
55typedef struct leveldb_t leveldb_t;
56typedef struct leveldb_cache_t leveldb_cache_t;
57typedef struct leveldb_comparator_t leveldb_comparator_t;
58typedef struct leveldb_env_t leveldb_env_t;
59typedef struct leveldb_filelock_t leveldb_filelock_t;
60typedef struct leveldb_filterpolicy_t leveldb_filterpolicy_t;
61typedef struct leveldb_iterator_t leveldb_iterator_t;
62typedef struct leveldb_logger_t leveldb_logger_t;
63typedef struct leveldb_options_t leveldb_options_t;
64typedef struct leveldb_randomfile_t leveldb_randomfile_t;
65typedef struct leveldb_readoptions_t leveldb_readoptions_t;
66typedef struct leveldb_seqfile_t leveldb_seqfile_t;
67typedef struct leveldb_snapshot_t leveldb_snapshot_t;
68typedef struct leveldb_writablefile_t leveldb_writablefile_t;
69typedef struct leveldb_writebatch_t leveldb_writebatch_t;
70typedef struct leveldb_writeoptions_t leveldb_writeoptions_t;
71
72/* DB operations */
73
74LEVELDB_EXPORT leveldb_t* leveldb_open(const leveldb_options_t* options,
75 const char* name, char** errptr);
76
77LEVELDB_EXPORT void leveldb_close(leveldb_t* db);
78
79LEVELDB_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
84LEVELDB_EXPORT void leveldb_delete(leveldb_t* db,
85 const leveldb_writeoptions_t* options,
86 const char* key, size_t keylen,
87 char** errptr);
88
89LEVELDB_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. */
95LEVELDB_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
100LEVELDB_EXPORT leveldb_iterator_t* leveldb_create_iterator(
101 leveldb_t* db, const leveldb_readoptions_t* options);
102
103LEVELDB_EXPORT const leveldb_snapshot_t* leveldb_create_snapshot(leveldb_t* db);
104
105LEVELDB_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. */
110LEVELDB_EXPORT char* leveldb_property_value(leveldb_t* db,
111 const char* propname);
112
113LEVELDB_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
118LEVELDB_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
125LEVELDB_EXPORT void leveldb_destroy_db(const leveldb_options_t* options,
126 const char* name, char** errptr);
127
128LEVELDB_EXPORT void leveldb_repair_db(const leveldb_options_t* options,
129 const char* name, char** errptr);
130
131/* Iterator */
132
133LEVELDB_EXPORT void leveldb_iter_destroy(leveldb_iterator_t*);
134LEVELDB_EXPORT uint8_t leveldb_iter_valid(const leveldb_iterator_t*);
135LEVELDB_EXPORT void leveldb_iter_seek_to_first(leveldb_iterator_t*);
136LEVELDB_EXPORT void leveldb_iter_seek_to_last(leveldb_iterator_t*);
137LEVELDB_EXPORT void leveldb_iter_seek(leveldb_iterator_t*, const char* k,
138 size_t klen);
139LEVELDB_EXPORT void leveldb_iter_next(leveldb_iterator_t*);
140LEVELDB_EXPORT void leveldb_iter_prev(leveldb_iterator_t*);
141LEVELDB_EXPORT const char* leveldb_iter_key(const leveldb_iterator_t*,
142 size_t* klen);
143LEVELDB_EXPORT const char* leveldb_iter_value(const leveldb_iterator_t*,
144 size_t* vlen);
145LEVELDB_EXPORT void leveldb_iter_get_error(const leveldb_iterator_t*,
146 char** errptr);
147
148/* Write batch */
149
150LEVELDB_EXPORT leveldb_writebatch_t* leveldb_writebatch_create(void);
151LEVELDB_EXPORT void leveldb_writebatch_destroy(leveldb_writebatch_t*);
152LEVELDB_EXPORT void leveldb_writebatch_clear(leveldb_writebatch_t*);
153LEVELDB_EXPORT void leveldb_writebatch_put(leveldb_writebatch_t*,
154 const char* key, size_t klen,
155 const char* val, size_t vlen);
156LEVELDB_EXPORT void leveldb_writebatch_delete(leveldb_writebatch_t*,
157 const char* key, size_t klen);
158LEVELDB_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));
162LEVELDB_EXPORT void leveldb_writebatch_append(
163 leveldb_writebatch_t* destination, const leveldb_writebatch_t* source);
164
165/* Options */
166
167LEVELDB_EXPORT leveldb_options_t* leveldb_options_create(void);
168LEVELDB_EXPORT void leveldb_options_destroy(leveldb_options_t*);
169LEVELDB_EXPORT void leveldb_options_set_comparator(leveldb_options_t*,
170 leveldb_comparator_t*);
171LEVELDB_EXPORT void leveldb_options_set_filter_policy(leveldb_options_t*,
172 leveldb_filterpolicy_t*);
173LEVELDB_EXPORT void leveldb_options_set_create_if_missing(leveldb_options_t*,
174 uint8_t);
175LEVELDB_EXPORT void leveldb_options_set_error_if_exists(leveldb_options_t*,
176 uint8_t);
177LEVELDB_EXPORT void leveldb_options_set_paranoid_checks(leveldb_options_t*,
178 uint8_t);
179LEVELDB_EXPORT void leveldb_options_set_env(leveldb_options_t*, leveldb_env_t*);
180LEVELDB_EXPORT void leveldb_options_set_info_log(leveldb_options_t*,
181 leveldb_logger_t*);
182LEVELDB_EXPORT void leveldb_options_set_write_buffer_size(leveldb_options_t*,
183 size_t);
184LEVELDB_EXPORT void leveldb_options_set_max_open_files(leveldb_options_t*, int);
185LEVELDB_EXPORT void leveldb_options_set_cache(leveldb_options_t*,
186 leveldb_cache_t*);
187LEVELDB_EXPORT void leveldb_options_set_block_size(leveldb_options_t*, size_t);
188LEVELDB_EXPORT void leveldb_options_set_block_restart_interval(
189 leveldb_options_t*, int);
190LEVELDB_EXPORT void leveldb_options_set_max_file_size(leveldb_options_t*,
191 size_t);
192
193enum { leveldb_no_compression = 0, leveldb_snappy_compression = 1 };
194LEVELDB_EXPORT void leveldb_options_set_compression(leveldb_options_t*, int);
195
196/* Comparator */
197
198LEVELDB_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*));
203LEVELDB_EXPORT void leveldb_comparator_destroy(leveldb_comparator_t*);
204
205/* Filter policy */
206
207LEVELDB_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*));
215LEVELDB_EXPORT void leveldb_filterpolicy_destroy(leveldb_filterpolicy_t*);
216
217LEVELDB_EXPORT leveldb_filterpolicy_t* leveldb_filterpolicy_create_bloom(
218 int bits_per_key);
219
220/* Read options */
221
222LEVELDB_EXPORT leveldb_readoptions_t* leveldb_readoptions_create(void);
223LEVELDB_EXPORT void leveldb_readoptions_destroy(leveldb_readoptions_t*);
224LEVELDB_EXPORT void leveldb_readoptions_set_verify_checksums(
225 leveldb_readoptions_t*, uint8_t);
226LEVELDB_EXPORT void leveldb_readoptions_set_fill_cache(leveldb_readoptions_t*,
227 uint8_t);
228LEVELDB_EXPORT void leveldb_readoptions_set_snapshot(leveldb_readoptions_t*,
229 const leveldb_snapshot_t*);
230
231/* Write options */
232
233LEVELDB_EXPORT leveldb_writeoptions_t* leveldb_writeoptions_create(void);
234LEVELDB_EXPORT void leveldb_writeoptions_destroy(leveldb_writeoptions_t*);
235LEVELDB_EXPORT void leveldb_writeoptions_set_sync(leveldb_writeoptions_t*,
236 uint8_t);
237
238/* Cache */
239
240LEVELDB_EXPORT leveldb_cache_t* leveldb_cache_create_lru(size_t capacity);
241LEVELDB_EXPORT void leveldb_cache_destroy(leveldb_cache_t* cache);
242
243/* Env */
244
245LEVELDB_EXPORT leveldb_env_t* leveldb_create_default_env(void);
246LEVELDB_EXPORT void leveldb_env_destroy(leveldb_env_t*);
247
248/* If not NULL, the returned buffer must be released using leveldb_free(). */
249LEVELDB_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. */
258LEVELDB_EXPORT void leveldb_free(void* ptr);
259
260/* Return the major version number for this release. */
261LEVELDB_EXPORT int leveldb_major_version(void);
262
263/* Return the minor version number for this release. */
264LEVELDB_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