hamsterdb.h

Go to the documentation of this file.
00001 /*
00002  * Copyright (C) 2005-2010 Christoph Rupp (chris@crupp.de).
00003  *
00004  * This program is free software; you can redistribute it and/or modify it
00005  * under the terms of the GNU General Public License as published by the
00006  * Free Software Foundation; either version 2 of the License, or 
00007  * (at your option) any later version.
00008  *
00009  * See files COPYING.* for License information.
00010  */
00011 
00019 #ifndef HAM_HAMSTERDB_H__
00020 #define HAM_HAMSTERDB_H__
00021 
00022 #include <ham/types.h>
00023 
00024 #ifdef __cplusplus
00025 extern "C" {
00026 #endif
00027 
00034 struct ham_db_t;
00035 typedef struct ham_db_t ham_db_t;
00036 
00043 struct ham_env_t;
00044 typedef struct ham_env_t ham_env_t;
00045 
00055 struct ham_cursor_t;
00056 typedef struct ham_cursor_t ham_cursor_t;
00057 
00075 typedef struct
00076 {
00078     ham_size_t size;
00079 
00081     void *data;
00082 
00084     ham_u32_t flags;
00085 
00087     ham_u32_t partial_offset;
00088 
00090     ham_size_t partial_size;
00091 
00093     ham_u32_t _intflags;
00094 
00096     ham_u64_t _rid;
00097 
00098 } ham_record_t;
00099 
00104 #define HAM_RECORD_USER_ALLOC   1
00105 
00125 typedef struct
00126 {
00128     ham_u16_t size;
00129 
00131     void *data;
00132 
00134     ham_u32_t flags;
00135 
00137     ham_u32_t _flags;
00138 } ham_key_t;
00139 
00144 #define HAM_KEY_USER_ALLOC      1
00145 
00163 typedef struct {
00165     ham_u32_t name;
00166 
00168     ham_u64_t value;
00169 
00170 } ham_parameter_t;
00171 
00172 
00205 #define HAM_DAM_RANDOM_WRITE            0x0001
00206 
00215 #define HAM_DAM_SEQUENTIAL_INSERT        0x0002
00216 
00217 /* internal use only - will be set implicitly when opening a file from 1.0.x */ 
00218 #define HAM_DAM_ENFORCE_PRE110_FORMAT    0x8000
00219 
00231 #define HAM_SUCCESS                  (  0)
00232 
00233 #define HAM_INV_KEYSIZE              ( -3)
00234 
00235 #define HAM_INV_PAGESIZE             ( -4)
00236 
00237 #define HAM_OUT_OF_MEMORY            ( -6)
00238 
00239 #define HAM_NOT_INITIALIZED          ( -7)
00240 
00241 #define HAM_INV_PARAMETER            ( -8)
00242 
00243 #define HAM_INV_FILE_HEADER          ( -9)
00244 
00245 #define HAM_INV_FILE_VERSION         (-10)
00246 
00247 #define HAM_KEY_NOT_FOUND            (-11)
00248 
00249 #define HAM_DUPLICATE_KEY            (-12)
00250 
00251 #define HAM_INTEGRITY_VIOLATED       (-13)
00252 
00253 #define HAM_INTERNAL_ERROR           (-14)
00254 
00255 #define HAM_DB_READ_ONLY             (-15)
00256 
00257 #define HAM_BLOB_NOT_FOUND           (-16)
00258 
00259 #define HAM_PREFIX_REQUEST_FULLKEY   (-17)
00260 
00261 #define HAM_IO_ERROR                 (-18)
00262 
00263 #define HAM_CACHE_FULL               (-19)
00264 
00265 #define HAM_NOT_IMPLEMENTED          (-20)
00266 
00267 #define HAM_FILE_NOT_FOUND           (-21)
00268 
00269 #define HAM_WOULD_BLOCK              (-22)
00270 
00271 #define HAM_NOT_READY                (-23)
00272 
00273 #define HAM_LIMITS_REACHED           (-24)
00274 
00275 #define HAM_ACCESS_DENIED            (-25)
00276 
00277 #define HAM_ALREADY_INITIALIZED      (-27)
00278 
00279 #define HAM_NEED_RECOVERY            (-28)
00280 
00281 #define HAM_CURSOR_STILL_OPEN        (-29)
00282 
00283 #define HAM_FILTER_NOT_FOUND         (-30)
00284 
00285 #define HAM_CURSOR_IS_NIL           (-100)
00286 
00287 #define HAM_DATABASE_NOT_FOUND      (-200)
00288 
00289 #define HAM_DATABASE_ALREADY_EXISTS (-201)
00290 
00291 #define HAM_DATABASE_ALREADY_OPEN   (-202)
00292 
00293 #define HAM_ENVIRONMENT_ALREADY_OPEN   (-203)
00294 
00295 #define HAM_LOG_INV_FILE_HEADER     (-300)
00296 
00297 #define HAM_NETWORK_ERROR           (-400)
00298 
00326 typedef void HAM_CALLCONV (*ham_errhandler_fun)
00327                     (int level, const char *message);
00328 
00330 #define HAM_DEBUG_LEVEL_DEBUG       0
00331 
00333 #define HAM_DEBUG_LEVEL_NORMAL      1
00334 
00336 #define HAM_DEBUG_LEVEL_FATAL       3
00337 
00353 HAM_EXPORT void HAM_CALLCONV
00354 ham_set_errhandler(ham_errhandler_fun f);
00355 
00363 HAM_EXPORT const char * HAM_CALLCONV
00364 ham_strerror(ham_status_t status);
00365 
00373 HAM_EXPORT void HAM_CALLCONV
00374 ham_get_version(ham_u32_t *major, ham_u32_t *minor,
00375         ham_u32_t *revision);
00376 
00384 HAM_EXPORT void HAM_CALLCONV
00385 ham_get_license(const char **licensee, const char **product);
00386 
00405 HAM_EXPORT ham_status_t HAM_CALLCONV
00406 ham_env_new(ham_env_t **env);
00407 
00419 HAM_EXPORT ham_status_t HAM_CALLCONV
00420 ham_env_delete(ham_env_t *env);
00421 
00458 HAM_EXPORT ham_status_t HAM_CALLCONV
00459 ham_env_create(ham_env_t *env, const char *filename,
00460         ham_u32_t flags, ham_u32_t mode);
00461 
00559 HAM_EXPORT ham_status_t HAM_CALLCONV
00560 ham_env_create_ex(ham_env_t *env, const char *filename,
00561         ham_u32_t flags, ham_u32_t mode, const ham_parameter_t *param);
00562 
00588 HAM_EXPORT ham_status_t HAM_CALLCONV
00589 ham_env_open(ham_env_t *env, const char *filename, ham_u32_t flags);
00590 
00673 HAM_EXPORT ham_status_t HAM_CALLCONV
00674 ham_env_open_ex(ham_env_t *env, const char *filename,
00675         ham_u32_t flags, const ham_parameter_t *param);
00676 
00704 HAM_EXPORT ham_status_t HAM_CALLCONV
00705 ham_env_get_parameters(ham_env_t *env, ham_parameter_t *param);
00706 
00770 HAM_EXPORT ham_status_t HAM_CALLCONV
00771 ham_env_create_db(ham_env_t *env, ham_db_t *db,
00772         ham_u16_t name, ham_u32_t flags, const ham_parameter_t *params);
00773 
00819 HAM_EXPORT ham_status_t HAM_CALLCONV
00820 ham_env_open_db(ham_env_t *env, ham_db_t *db,
00821         ham_u16_t name, ham_u32_t flags, const ham_parameter_t *params);
00822 
00847 HAM_EXPORT ham_status_t HAM_CALLCONV
00848 ham_env_rename_db(ham_env_t *env, ham_u16_t oldname, 
00849                 ham_u16_t newname, ham_u32_t flags);
00850 
00869 HAM_EXPORT ham_status_t HAM_CALLCONV
00870 ham_env_erase_db(ham_env_t *env, ham_u16_t name, ham_u32_t flags);
00871 
00887 HAM_EXPORT ham_status_t HAM_CALLCONV
00888 ham_env_flush(ham_env_t *env, ham_u32_t flags);
00889 
00924 HAM_EXPORT ham_status_t HAM_CALLCONV
00925 ham_env_enable_encryption(ham_env_t *env, ham_u8_t key[16], ham_u32_t flags);
00926 
00949 HAM_EXPORT ham_status_t HAM_CALLCONV
00950 ham_env_get_database_names(ham_env_t *env, ham_u16_t *names, ham_size_t *count);
00951 
00989 HAM_EXPORT ham_status_t HAM_CALLCONV
00990 ham_env_close(ham_env_t *env, ham_u32_t flags);
00991 
01008 struct ham_txn_t;
01009 typedef struct ham_txn_t ham_txn_t;
01010 
01034 HAM_EXPORT ham_status_t
01035 ham_txn_begin(ham_txn_t **txn, ham_db_t *db, ham_u32_t flags);
01036 
01038 #define HAM_TXN_READ_ONLY                                       1
01039 
01057 HAM_EXPORT ham_status_t
01058 ham_txn_commit(ham_txn_t *txn, ham_u32_t flags);
01059 
01061 #define HAM_TXN_FORCE_WRITE                                    1
01062 
01080 HAM_EXPORT ham_status_t
01081 ham_txn_abort(ham_txn_t *txn, ham_u32_t flags);
01082 
01083 /* note: ham_txn_abort flag 0x0001 is reserved for internal use: 
01084  * DO_NOT_NUKE_PAGE_STATS */
01085 
01104 HAM_EXPORT ham_status_t HAM_CALLCONV
01105 ham_new(ham_db_t **db);
01106 
01118 HAM_EXPORT ham_status_t HAM_CALLCONV
01119 ham_delete(ham_db_t *db);
01120 
01146 HAM_EXPORT ham_status_t HAM_CALLCONV
01147 ham_create(ham_db_t *db, const char *filename,
01148         ham_u32_t flags, ham_u32_t mode);
01149 
01260 HAM_EXPORT ham_status_t HAM_CALLCONV
01261 ham_create_ex(ham_db_t *db, const char *filename,
01262         ham_u32_t flags, ham_u32_t mode, const ham_parameter_t *param);
01263 
01284 HAM_EXPORT ham_status_t HAM_CALLCONV
01285 ham_open(ham_db_t *db, const char *filename, ham_u32_t flags);
01286 
01372 HAM_EXPORT ham_status_t HAM_CALLCONV
01373 ham_open_ex(ham_db_t *db, const char *filename,
01374         ham_u32_t flags, const ham_parameter_t *param);
01375 
01379 #define HAM_WRITE_THROUGH            0x00000001
01380 
01381 /* unused                            0x00000002 */
01382 
01385 #define HAM_READ_ONLY                0x00000004
01386 
01387 /* unused                            0x00000008 */
01388 
01391 #define HAM_USE_BTREE                0x00000010
01392 
01393 /* reserved                          0x00000020 */
01394 
01397 #define HAM_DISABLE_VAR_KEYLEN       0x00000040
01398 
01401 #define HAM_IN_MEMORY_DB             0x00000080
01402 
01403 /* reserved: DB_USE_MMAP (not persistent)      0x00000100 */
01404 
01408 #define HAM_DISABLE_MMAP             0x00000200
01409 
01413 #define HAM_CACHE_STRICT             0x00000400
01414 
01418 #define HAM_DISABLE_FREELIST_FLUSH   0x00000800
01419 
01422 #define HAM_LOCK_EXCLUSIVE           0x00001000
01423 
01426 #define HAM_RECORD_NUMBER            0x00002000
01427 
01430 #define HAM_ENABLE_DUPLICATES        0x00004000
01431 
01435 #define HAM_ENABLE_RECOVERY          0x00008000
01436 
01439 #define HAM_AUTO_RECOVERY            0x00010000
01440 
01444 #define HAM_ENABLE_TRANSACTIONS      0x00020000
01445 
01449 #define HAM_CACHE_UNLIMITED          0x00040000
01450 
01451 /* reserved: DB_ENV_IS_PRIVATE (not persistent)      0x00080000 */
01452 
01456 #define HAM_SORT_DUPLICATES          0x00100000
01457 
01458 /* reserved: DB_IS_REMOTE     (not persistent)       0x00200000 */
01459 
01469 HAM_EXPORT ham_status_t HAM_CALLCONV
01470 ham_get_error(ham_db_t *db);
01471 
01484 typedef int HAM_CALLCONV (*ham_prefix_compare_func_t)
01485                                  (ham_db_t *db, 
01486                                   const ham_u8_t *lhs, ham_size_t lhs_length, 
01487                                   ham_size_t lhs_real_length,
01488                                   const ham_u8_t *rhs, ham_size_t rhs_length,
01489                                   ham_size_t rhs_real_length);
01490 
01506 HAM_EXPORT ham_status_t HAM_CALLCONV
01507 ham_set_prefix_compare_func(ham_db_t *db, ham_prefix_compare_func_t foo);
01508 
01517 typedef int HAM_CALLCONV (*ham_compare_func_t)(ham_db_t *db, 
01518                                   const ham_u8_t *lhs, ham_size_t lhs_length, 
01519                                   const ham_u8_t *rhs, ham_size_t rhs_length);
01520 
01543 HAM_EXPORT ham_status_t HAM_CALLCONV
01544 ham_set_compare_func(ham_db_t *db, ham_compare_func_t foo);
01545 
01558 typedef int HAM_CALLCONV (*ham_duplicate_compare_func_t)(ham_db_t *db, 
01559                                   const ham_u8_t *lhs, ham_size_t lhs_length, 
01560                                   const ham_u8_t *rhs, ham_size_t rhs_length);
01561 
01592 HAM_EXPORT ham_status_t HAM_CALLCONV
01593 ham_set_duplicate_compare_func(ham_db_t *db, ham_duplicate_compare_func_t foo);
01594 
01625 HAM_EXPORT ham_status_t HAM_CALLCONV
01626 ham_enable_compression(ham_db_t *db, ham_u32_t level, ham_u32_t flags);
01627 
01732 HAM_EXPORT ham_status_t HAM_CALLCONV
01733 ham_find(ham_db_t *db, ham_txn_t *txn, ham_key_t *key,
01734         ham_record_t *record, ham_u32_t flags);
01735 
01811 HAM_EXPORT ham_status_t HAM_CALLCONV
01812 ham_insert(ham_db_t *db, ham_txn_t *txn, ham_key_t *key,
01813         ham_record_t *record, ham_u32_t flags);
01814 
01826 #define HAM_OVERWRITE                   0x0001
01827 
01829 #define HAM_DUPLICATE                   0x0002
01830 
01832 #define HAM_DUPLICATE_INSERT_BEFORE     0x0004
01833 
01835 #define HAM_DUPLICATE_INSERT_AFTER      0x0008
01836 
01838 #define HAM_DUPLICATE_INSERT_FIRST      0x0010
01839 
01841 #define HAM_DUPLICATE_INSERT_LAST       0x0020
01842 
01844 #define HAM_DIRECT_ACCESS               0x0040
01845 
01848 #define HAM_PARTIAL                     0x0080
01849 
01862 #define HAM_HINT_APPEND               0x00080000
01863 
01876 #define HAM_HINT_PREPEND              0x00100000
01877 
01882 #define HAM_HINTS_MASK                0x00FF0000
01883 
01905 HAM_EXPORT ham_status_t HAM_CALLCONV
01906 ham_erase(ham_db_t *db, ham_txn_t *txn, ham_key_t *key, ham_u32_t flags);
01907 
01924 HAM_EXPORT ham_status_t HAM_CALLCONV
01925 ham_flush(ham_db_t *db, ham_u32_t flags);
01926 
01952 HAM_EXPORT ham_status_t HAM_CALLCONV
01953 ham_get_key_count(ham_db_t *db, ham_txn_t *txn, ham_u32_t flags,
01954             ham_offset_t *keycount);
01955 
01959 #define HAM_FAST_ESTIMATE           0x0001
01960 
01993 HAM_EXPORT ham_status_t HAM_CALLCONV
01994 ham_get_parameters(ham_db_t *db, ham_parameter_t *param);
01995 
01998 #define HAM_PARAM_CACHESIZE          0x00000100
01999 
02002 #define HAM_PARAM_PAGESIZE           0x00000101
02003 
02005 #define HAM_PARAM_KEYSIZE            0x00000102
02006 
02009 #define HAM_PARAM_MAX_ENV_DATABASES  0x00000103
02010 
02014 #define HAM_PARAM_DATA_ACCESS_MODE   0x00000104
02015 
02021 #define HAM_PARAM_GET_FLAGS                0x00000200
02022 
02028 #define HAM_PARAM_GET_FILEMODE            0x00000201
02029 
02037 #define HAM_PARAM_GET_FILENAME            0x00000202
02038 
02046 #define HAM_PARAM_GET_DATABASE_NAME       0x00000203
02047 #define HAM_PARAM_DBNAME                  HAM_PARAM_GET_DATABASE_NAME
02048 
02057 #define HAM_PARAM_GET_KEYS_PER_PAGE        0x00000204
02058 
02062 #define HAM_PARAM_GET_DATA_ACCESS_MODE     0x00000205
02063 #define HAM_PARAM_GET_DAM                  HAM_PARAM_GET_DATA_ACCESS_MODE
02064 
02076 HAM_EXPORT ham_u32_t HAM_CALLCONV
02077 ham_get_flags(ham_db_t *db);
02078 
02092 HAM_EXPORT ham_env_t *HAM_CALLCONV
02093 ham_get_env(ham_db_t *db);
02094 
02119 HAM_EXPORT int HAM_CALLCONV
02120 ham_key_get_approximate_match_type(ham_key_t *key);
02121 
02159 HAM_EXPORT ham_status_t HAM_CALLCONV
02160 ham_close(ham_db_t *db, ham_u32_t flags);
02161 
02163 #define HAM_AUTO_CLEANUP            1
02164 
02166 #define HAM_DONT_CLEAR_LOG          2
02167 
02169 #define HAM_TXN_AUTO_ABORT          4
02170 
02172 #define HAM_TXN_AUTO_COMMIT         8
02173 
02205 HAM_EXPORT ham_status_t HAM_CALLCONV
02206 ham_cursor_create(ham_db_t *db, ham_txn_t *txn, ham_u32_t flags,
02207             ham_cursor_t **cursor);
02208 
02227 HAM_EXPORT ham_status_t HAM_CALLCONV
02228 ham_cursor_clone(ham_cursor_t *src, ham_cursor_t **dest);
02229 
02315 HAM_EXPORT ham_status_t HAM_CALLCONV
02316 ham_cursor_move(ham_cursor_t *cursor, ham_key_t *key,
02317         ham_record_t *record, ham_u32_t flags);
02318 
02320 #define HAM_CURSOR_FIRST            0x0001
02321 
02323 #define HAM_CURSOR_LAST             0x0002
02324 
02326 #define HAM_CURSOR_NEXT             0x0004
02327 
02329 #define HAM_CURSOR_PREVIOUS         0x0008
02330 
02332 #define HAM_SKIP_DUPLICATES         0x0010
02333 
02335 #define HAM_ONLY_DUPLICATES         0x0020
02336 
02357 HAM_EXPORT ham_status_t HAM_CALLCONV
02358 ham_cursor_overwrite(ham_cursor_t *cursor, ham_record_t *record,
02359             ham_u32_t flags);
02360 
02486 HAM_EXPORT ham_status_t HAM_CALLCONV
02487 ham_cursor_find(ham_cursor_t *cursor, ham_key_t *key, ham_u32_t flags);
02488 
02632 HAM_EXPORT ham_status_t HAM_CALLCONV
02633 ham_cursor_find_ex(ham_cursor_t *cursor, ham_key_t *key, 
02634             ham_record_t *record, ham_u32_t flags);
02635 
02642 #define HAM_FIND_EXACT_MATCH        0x4000
02643 
02648 #define HAM_FIND_LT_MATCH           0x1000
02649 
02654 #define HAM_FIND_GT_MATCH           0x2000
02655 
02663 #define HAM_FIND_LEQ_MATCH          (HAM_FIND_LT_MATCH | HAM_FIND_EXACT_MATCH)
02664 
02672 #define HAM_FIND_GEQ_MATCH          (HAM_FIND_GT_MATCH | HAM_FIND_EXACT_MATCH)
02673 
02687 #define HAM_FIND_NEAR_MATCH         (HAM_FIND_LT_MATCH | HAM_FIND_GT_MATCH    \
02688                                         | HAM_FIND_EXACT_MATCH)
02689 
02812 HAM_EXPORT ham_status_t HAM_CALLCONV
02813 ham_cursor_insert(ham_cursor_t *cursor, ham_key_t *key,
02814             ham_record_t *record, ham_u32_t flags);
02815 
02835 HAM_EXPORT ham_status_t HAM_CALLCONV
02836 ham_cursor_erase(ham_cursor_t *cursor, ham_u32_t flags);
02837 
02853 HAM_EXPORT ham_status_t HAM_CALLCONV
02854 ham_cursor_get_duplicate_count(ham_cursor_t *cursor, 
02855         ham_size_t *count, ham_u32_t flags);
02856 
02871 HAM_EXPORT ham_status_t HAM_CALLCONV
02872 ham_cursor_close(ham_cursor_t *cursor);
02873 
02878 #ifdef __cplusplus
02879 } // extern "C"
02880 #endif
02881 
02882 #endif /* HAM_HAMSTERDB_H__ */
Generated by  doxygen 1.6.3