src/leveldb/include/leveldb/c.h

   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 unsigned char (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 /* Exported types */
  52
  53 typedef struct leveldb_t               leveldb_t;
  54 typedef struct leveldb_cache_t         leveldb_cache_t;
  55 typedef struct leveldb_comparator_t    leveldb_comparator_t;
  56 typedef struct leveldb_env_t           leveldb_env_t;
  57 typedef struct leveldb_filelock_t      leveldb_filelock_t;
  58 typedef struct leveldb_filterpolicy_t  leveldb_filterpolicy_t;
  59 typedef struct leveldb_iterator_t      leveldb_iterator_t;
  60 typedef struct leveldb_logger_t        leveldb_logger_t;
  61 typedef struct leveldb_options_t       leveldb_options_t;
  62 typedef struct leveldb_randomfile_t    leveldb_randomfile_t;
  63 typedef struct leveldb_readoptions_t   leveldb_readoptions_t;
  64 typedef struct leveldb_seqfile_t       leveldb_seqfile_t;
  65 typedef struct leveldb_snapshot_t      leveldb_snapshot_t;
  66 typedef struct leveldb_writablefile_t  leveldb_writablefile_t;
  67 typedef struct leveldb_writebatch_t    leveldb_writebatch_t;
  68 typedef struct leveldb_writeoptions_t  leveldb_writeoptions_t;
  69
  70 /* DB operations */
  71
  72 extern leveldb_t* leveldb_open(
  73     const leveldb_options_t* options,
  74     const char* name,
  75     char** errptr);
  76
  77 extern void leveldb_close(leveldb_t* db);
  78
  79 extern void leveldb_put(
  80     leveldb_t* db,
  81     const leveldb_writeoptions_t* options,
  82     const char* key, size_t keylen,
  83     const char* val, size_t vallen,
  84     char** errptr);
  85
  86 extern void leveldb_delete(
  87     leveldb_t* db,
  88     const leveldb_writeoptions_t* options,
  89     const char* key, size_t keylen,
  90     char** errptr);
  91
  92 extern void leveldb_write(
  93     leveldb_t* db,
  94     const leveldb_writeoptions_t* options,
  95     leveldb_writebatch_t* batch,
  96     char** errptr);
  97
  98 /* Returns NULL if not found.  A malloc()ed array otherwise.
  99    Stores the length of the array in *vallen. */
 100 extern char* leveldb_get(
 101     leveldb_t* db,
 102     const leveldb_readoptions_t* options,
 103     const char* key, size_t keylen,
 104     size_t* vallen,
 105     char** errptr);
 106
 107 extern leveldb_iterator_t* leveldb_create_iterator(
 108     leveldb_t* db,
 109     const leveldb_readoptions_t* options);
 110
 111 extern const leveldb_snapshot_t* leveldb_create_snapshot(
 112     leveldb_t* db);
 113
 114 extern void leveldb_release_snapshot(
 115     leveldb_t* db,
 116     const leveldb_snapshot_t* snapshot);
 117
 118 /* Returns NULL if property name is unknown.
 119    Else returns a pointer to a malloc()-ed null-terminated value. */
 120 extern char* leveldb_property_value(
 121     leveldb_t* db,
 122     const char* propname);
 123
 124 extern void leveldb_approximate_sizes(
 125     leveldb_t* db,
 126     int num_ranges,
 127     const char* const* range_start_key, const size_t* range_start_key_len,
 128     const char* const* range_limit_key, const size_t* range_limit_key_len,
 129     uint64_t* sizes);
 130
 131 extern void leveldb_compact_range(
 132     leveldb_t* db,
 133     const char* start_key, size_t start_key_len,
 134     const char* limit_key, size_t limit_key_len);
 135
 136 /* Management operations */
 137
 138 extern void leveldb_destroy_db(
 139     const leveldb_options_t* options,
 140     const char* name,
 141     char** errptr);
 142
 143 extern void leveldb_repair_db(
 144     const leveldb_options_t* options,
 145     const char* name,
 146     char** errptr);
 147
 148 /* Iterator */
 149
 150 extern void leveldb_iter_destroy(leveldb_iterator_t*);
 151 extern unsigned char leveldb_iter_valid(const leveldb_iterator_t*);
 152 extern void leveldb_iter_seek_to_first(leveldb_iterator_t*);
 153 extern void leveldb_iter_seek_to_last(leveldb_iterator_t*);
 154 extern void leveldb_iter_seek(leveldb_iterator_t*, const char* k, size_t klen);
 155 extern void leveldb_iter_next(leveldb_iterator_t*);
 156 extern void leveldb_iter_prev(leveldb_iterator_t*);
 157 extern const char* leveldb_iter_key(const leveldb_iterator_t*, size_t* klen);
 158 extern const char* leveldb_iter_value(const leveldb_iterator_t*, size_t* vlen);
 159 extern void leveldb_iter_get_error(const leveldb_iterator_t*, char** errptr);
 160
 161 /* Write batch */
 162
 163 extern leveldb_writebatch_t* leveldb_writebatch_create();
 164 extern void leveldb_writebatch_destroy(leveldb_writebatch_t*);
 165 extern void leveldb_writebatch_clear(leveldb_writebatch_t*);
 166 extern void leveldb_writebatch_put(
 167     leveldb_writebatch_t*,
 168     const char* key, size_t klen,
 169     const char* val, size_t vlen);
 170 extern void leveldb_writebatch_delete(
 171     leveldb_writebatch_t*,
 172     const char* key, size_t klen);
 173 extern void leveldb_writebatch_iterate(
 174     leveldb_writebatch_t*,
 175     void* state,
 176     void (*put)(void*, const char* k, size_t klen, const char* v, size_t vlen),
 177     void (*deleted)(void*, const char* k, size_t klen));
 178
 179 /* Options */
 180
 181 extern leveldb_options_t* leveldb_options_create();
 182 extern void leveldb_options_destroy(leveldb_options_t*);
 183 extern void leveldb_options_set_comparator(
 184     leveldb_options_t*,
 185     leveldb_comparator_t*);
 186 extern void leveldb_options_set_filter_policy(
 187     leveldb_options_t*,
 188     leveldb_filterpolicy_t*);
 189 extern void leveldb_options_set_create_if_missing(
 190     leveldb_options_t*, unsigned char);
 191 extern void leveldb_options_set_error_if_exists(
 192     leveldb_options_t*, unsigned char);
 193 extern void leveldb_options_set_paranoid_checks(
 194     leveldb_options_t*, unsigned char);
 195 extern void leveldb_options_set_env(leveldb_options_t*, leveldb_env_t*);
 196 extern void leveldb_options_set_info_log(leveldb_options_t*, leveldb_logger_t*);
 197 extern void leveldb_options_set_write_buffer_size(leveldb_options_t*, size_t);
 198 extern void leveldb_options_set_max_open_files(leveldb_options_t*, int);
 199 extern void leveldb_options_set_cache(leveldb_options_t*, leveldb_cache_t*);
 200 extern void leveldb_options_set_block_size(leveldb_options_t*, size_t);
 201 extern void leveldb_options_set_block_restart_interval(leveldb_options_t*, int);
 202
 203 enum {
 204   leveldb_no_compression = 0,
 205   leveldb_snappy_compression = 1
 206 };
 207 extern void leveldb_options_set_compression(leveldb_options_t*, int);
 208
 209 /* Comparator */
 210
 211 extern leveldb_comparator_t* leveldb_comparator_create(
 212     void* state,
 213     void (*destructor)(void*),
 214     int (*compare)(
 215         void*,
 216         const char* a, size_t alen,
 217         const char* b, size_t blen),
 218     const char* (*name)(void*));
 219 extern void leveldb_comparator_destroy(leveldb_comparator_t*);
 220
 221 /* Filter policy */
 222
 223 extern leveldb_filterpolicy_t* leveldb_filterpolicy_create(
 224     void* state,
 225     void (*destructor)(void*),
 226     char* (*create_filter)(
 227         void*,
 228         const char* const* key_array, const size_t* key_length_array,
 229         int num_keys,
 230         size_t* filter_length),
 231     unsigned char (*key_may_match)(
 232         void*,
 233         const char* key, size_t length,
 234         const char* filter, size_t filter_length),
 235     const char* (*name)(void*));
 236 extern void leveldb_filterpolicy_destroy(leveldb_filterpolicy_t*);
 237
 238 extern leveldb_filterpolicy_t* leveldb_filterpolicy_create_bloom(
 239     int bits_per_key);
 240
 241 /* Read options */
 242
 243 extern leveldb_readoptions_t* leveldb_readoptions_create();
 244 extern void leveldb_readoptions_destroy(leveldb_readoptions_t*);
 245 extern void leveldb_readoptions_set_verify_checksums(
 246     leveldb_readoptions_t*,
 247     unsigned char);
 248 extern void leveldb_readoptions_set_fill_cache(
 249     leveldb_readoptions_t*, unsigned char);
 250 extern void leveldb_readoptions_set_snapshot(
 251     leveldb_readoptions_t*,
 252     const leveldb_snapshot_t*);
 253
 254 /* Write options */
 255
 256 extern leveldb_writeoptions_t* leveldb_writeoptions_create();
 257 extern void leveldb_writeoptions_destroy(leveldb_writeoptions_t*);
 258 extern void leveldb_writeoptions_set_sync(
 259     leveldb_writeoptions_t*, unsigned char);
 260
 261 /* Cache */
 262
 263 extern leveldb_cache_t* leveldb_cache_create_lru(size_t capacity);
 264 extern void leveldb_cache_destroy(leveldb_cache_t* cache);
 265
 266 /* Env */
 267
 268 extern leveldb_env_t* leveldb_create_default_env();
 269 extern void leveldb_env_destroy(leveldb_env_t*);
 270
 271 /* Utility */
 272
 273 /* Calls free(ptr).
 274    REQUIRES: ptr was malloc()-ed and returned by one of the routines
 275    in this file.  Note that in certain cases (typically on Windows), you
 276    may need to call this routine instead of free(ptr) to dispose of
 277    malloc()-ed memory returned by this library. */
 278 extern void leveldb_free(void* ptr);
 279
 280 /* Return the major version number for this release. */
 281 extern int leveldb_major_version();
 282
 283 /* Return the minor version number for this release. */
 284 extern int leveldb_minor_version();
 285
 286 #ifdef __cplusplus
 287 }  /* end extern "C" */
 288 #endif
 289
 290 #endif  /* STORAGE_LEVELDB_INCLUDE_C_H_ */