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 #ifdef __cplusplus 44 extern "C" { 45 #endif 46 47 #include <stdarg.h> 48 #include <stddef.h> 49 #include <stdint.h> 50 51 #include "leveldb/export.h" 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