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