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 _intflags;
00088 
00090     ham_u64_t _rid;
00091 
00092 } ham_record_t;
00093 
00098 #define HAM_RECORD_USER_ALLOC   1
00099 
00119 typedef struct
00120 {
00122     ham_u16_t size;
00123 
00125     void *data;
00126 
00128     ham_u32_t flags;
00129 
00131     ham_u32_t _flags;
00132 } ham_key_t;
00133 
00138 #define HAM_KEY_USER_ALLOC      1
00139 
00157 typedef struct {
00159     ham_u32_t name;
00160 
00162     ham_u64_t value;
00163 
00164 } ham_parameter_t;
00165 
00166 
00195 #define HAM_DAM_RANDOM_WRITE            0x0001
00196 
00205 #define HAM_DAM_SEQUENTIAL_INSERT        0x0002
00206 
00207 /* internal use only - will be set implicitly when opening a file from 1.0.x */ 
00208 #define HAM_DAM_ENFORCE_PRE110_FORMAT    0x8000
00209 
00221 #define HAM_SUCCESS                  (  0)
00222 
00223 #define HAM_INV_KEYSIZE              ( -3)
00224 
00225 #define HAM_INV_PAGESIZE             ( -4)
00226 
00227 #define HAM_OUT_OF_MEMORY            ( -6)
00228 
00229 #define HAM_NOT_INITIALIZED          ( -7)
00230 
00231 #define HAM_INV_PARAMETER            ( -8)
00232 
00233 #define HAM_INV_FILE_HEADER          ( -9)
00234 
00235 #define HAM_INV_FILE_VERSION         (-10)
00236 
00237 #define HAM_KEY_NOT_FOUND            (-11)
00238 
00239 #define HAM_DUPLICATE_KEY            (-12)
00240 
00241 #define HAM_INTEGRITY_VIOLATED       (-13)
00242 
00243 #define HAM_INTERNAL_ERROR           (-14)
00244 
00245 #define HAM_DB_READ_ONLY             (-15)
00246 
00247 #define HAM_BLOB_NOT_FOUND           (-16)
00248 
00249 #define HAM_PREFIX_REQUEST_FULLKEY   (-17)
00250 
00251 #define HAM_IO_ERROR                 (-18)
00252 
00253 #define HAM_CACHE_FULL               (-19)
00254 
00255 #define HAM_NOT_IMPLEMENTED          (-20)
00256 
00257 #define HAM_FILE_NOT_FOUND           (-21)
00258 
00259 #define HAM_WOULD_BLOCK              (-22)
00260 
00261 #define HAM_NOT_READY                (-23)
00262 
00263 #define HAM_LIMITS_REACHED           (-24)
00264 
00265 #define HAM_ACCESS_DENIED            (-25)
00266 
00267 #define HAM_ALREADY_INITIALIZED      (-27)
00268 
00269 #define HAM_NEED_RECOVERY            (-28)
00270 
00271 #define HAM_CURSOR_STILL_OPEN        (-29)
00272 
00273 #define HAM_FILTER_NOT_FOUND         (-30)
00274 
00275 #define HAM_CURSOR_IS_NIL           (-100)
00276 
00277 #define HAM_DATABASE_NOT_FOUND      (-200)
00278 
00279 #define HAM_DATABASE_ALREADY_EXISTS (-201)
00280 
00281 #define HAM_DATABASE_ALREADY_OPEN   (-202)
00282 
00283 #define HAM_ENVIRONMENT_ALREADY_OPEN   (-203)
00284 
00285 #define HAM_LOG_INV_FILE_HEADER     (-300)
00286 
00314 typedef void HAM_CALLCONV (*ham_errhandler_fun)
00315                     (int level, const char *message);
00316 
00322 #define HAM_DEBUG_LEVEL_DEBUG       0
00323 
00329 #define HAM_DEBUG_LEVEL_NORMAL      1
00330 
00338 #define HAM_DEBUG_LEVEL_FATAL       3
00339 
00355 HAM_EXPORT void HAM_CALLCONV
00356 ham_set_errhandler(ham_errhandler_fun f);
00357 
00365 HAM_EXPORT const char * HAM_CALLCONV
00366 ham_strerror(ham_status_t status);
00367 
00375 HAM_EXPORT void HAM_CALLCONV
00376 ham_get_version(ham_u32_t *major, ham_u32_t *minor,
00377         ham_u32_t *revision);
00378 
00386 HAM_EXPORT void HAM_CALLCONV
00387 ham_get_license(const char **licensee, const char **product);
00388 
00407 HAM_EXPORT ham_status_t HAM_CALLCONV
00408 ham_env_new(ham_env_t **env);
00409 
00421 HAM_EXPORT ham_status_t HAM_CALLCONV
00422 ham_env_delete(ham_env_t *env);
00423 
00460 HAM_EXPORT ham_status_t HAM_CALLCONV
00461 ham_env_create(ham_env_t *env, const char *filename,
00462         ham_u32_t flags, ham_u32_t mode);
00463 
00562 HAM_EXPORT ham_status_t HAM_CALLCONV
00563 ham_env_create_ex(ham_env_t *env, const char *filename,
00564         ham_u32_t flags, ham_u32_t mode, const ham_parameter_t *param);
00565 
00587 HAM_EXPORT ham_status_t HAM_CALLCONV
00588 ham_env_open(ham_env_t *env, const char *filename, ham_u32_t flags);
00589 
00670 HAM_EXPORT ham_status_t HAM_CALLCONV
00671 ham_env_open_ex(ham_env_t *env, const char *filename,
00672         ham_u32_t flags, const ham_parameter_t *param);
00673 
00695 HAM_EXPORT ham_status_t HAM_CALLCONV
00696 ham_env_get_parameters(ham_env_t *env, ham_parameter_t *param);
00697 
00761 HAM_EXPORT ham_status_t HAM_CALLCONV
00762 ham_env_create_db(ham_env_t *env, ham_db_t *db,
00763         ham_u16_t name, ham_u32_t flags, const ham_parameter_t *params);
00764 
00811 HAM_EXPORT ham_status_t HAM_CALLCONV
00812 ham_env_open_db(ham_env_t *env, ham_db_t *db,
00813         ham_u16_t name, ham_u32_t flags, const ham_parameter_t *params);
00814 
00839 HAM_EXPORT ham_status_t HAM_CALLCONV
00840 ham_env_rename_db(ham_env_t *env, ham_u16_t oldname, 
00841                 ham_u16_t newname, ham_u32_t flags);
00842 
00861 HAM_EXPORT ham_status_t HAM_CALLCONV
00862 ham_env_erase_db(ham_env_t *env, ham_u16_t name, ham_u32_t flags);
00863 
00898 HAM_EXPORT ham_status_t HAM_CALLCONV
00899 ham_env_enable_encryption(ham_env_t *env, ham_u8_t key[16], ham_u32_t flags);
00900 
00923 HAM_EXPORT ham_status_t HAM_CALLCONV
00924 ham_env_get_database_names(ham_env_t *env, ham_u16_t *names, ham_size_t *count);
00925 
00963 HAM_EXPORT ham_status_t HAM_CALLCONV
00964 ham_env_close(ham_env_t *env, ham_u32_t flags);
00965 
00982 struct ham_txn_t;
00983 typedef struct ham_txn_t ham_txn_t;
00984 
01008 HAM_EXPORT ham_status_t
01009 ham_txn_begin(ham_txn_t **txn, ham_db_t *db, ham_u32_t flags);
01010 
01012 #define HAM_TXN_READ_ONLY                                       1
01013 
01031 HAM_EXPORT ham_status_t
01032 ham_txn_commit(ham_txn_t *txn, ham_u32_t flags);
01033 
01035 #define HAM_TXN_FORCE_WRITE                                    1
01036 
01054 HAM_EXPORT ham_status_t
01055 ham_txn_abort(ham_txn_t *txn, ham_u32_t flags);
01056 
01057 /* note: ham_txn_abort flag 0x0001 is reserved for internal use: 
01058  * DO_NOT_NUKE_PAGE_STATS */
01059 
01078 HAM_EXPORT ham_status_t HAM_CALLCONV
01079 ham_new(ham_db_t **db);
01080 
01092 HAM_EXPORT ham_status_t HAM_CALLCONV
01093 ham_delete(ham_db_t *db);
01094 
01120 HAM_EXPORT ham_status_t HAM_CALLCONV
01121 ham_create(ham_db_t *db, const char *filename,
01122         ham_u32_t flags, ham_u32_t mode);
01123 
01236 HAM_EXPORT ham_status_t HAM_CALLCONV
01237 ham_create_ex(ham_db_t *db, const char *filename,
01238         ham_u32_t flags, ham_u32_t mode, const ham_parameter_t *param);
01239 
01260 HAM_EXPORT ham_status_t HAM_CALLCONV
01261 ham_open(ham_db_t *db, const char *filename, ham_u32_t flags);
01262 
01350 HAM_EXPORT ham_status_t HAM_CALLCONV
01351 ham_open_ex(ham_db_t *db, const char *filename,
01352         ham_u32_t flags, const ham_parameter_t *param);
01353 
01364 #define HAM_WRITE_THROUGH            0x00000001
01365 
01366 /* unused                            0x00000002 */
01367 
01370 #define HAM_READ_ONLY                0x00000004
01371 
01372 /* unused                            0x00000008 */
01373 
01376 #define HAM_USE_BTREE                0x00000010
01377 
01378 /* reserved                          0x00000020 */
01379 
01382 #define HAM_DISABLE_VAR_KEYLEN       0x00000040
01383 
01387 #define HAM_IN_MEMORY_DB             0x00000080
01388 
01389 /* reserved: DB_USE_MMAP (not persistent)      0x00000100 */
01390 
01394 #define HAM_DISABLE_MMAP             0x00000200
01395 
01399 #define HAM_CACHE_STRICT             0x00000400
01400 
01404 #define HAM_DISABLE_FREELIST_FLUSH   0x00000800
01405 
01408 #define HAM_LOCK_EXCLUSIVE           0x00001000
01409 
01412 #define HAM_RECORD_NUMBER            0x00002000
01413 
01416 #define HAM_ENABLE_DUPLICATES        0x00004000
01417 
01421 #define HAM_ENABLE_RECOVERY          0x00008000
01422 
01425 #define HAM_AUTO_RECOVERY            0x00010000
01426 
01430 #define HAM_ENABLE_TRANSACTIONS      0x00020000
01431 
01435 #define HAM_CACHE_UNLIMITED          0x00040000
01436 
01437 /* reserved: DB_ENV_IS_PRIVATE (not persistent)      0x00080000 */
01438 
01442 #define HAM_SORT_DUPLICATES          0x00100000
01443 
01459 #define HAM_PARAM_CACHESIZE          0x00000100
01460 
01463 #define HAM_PARAM_PAGESIZE           0x00000101
01464 
01466 #define HAM_PARAM_KEYSIZE            0x00000102
01467 
01470 #define HAM_PARAM_MAX_ENV_DATABASES  0x00000103
01471 
01475 #define HAM_PARAM_DATA_ACCESS_MODE   0x00000104
01476 
01492 #define HAM_PARAM_GET_FLAGS                0x00000200
01493 
01499 #define HAM_PARAM_GET_FILEMODE            0x00000201
01500 
01508 #define HAM_PARAM_GET_FILENAME            0x00000202
01509 
01517 #define HAM_PARAM_DBNAME                  0x00000203
01518 
01527 #define HAM_PARAM_GET_KEYS_PER_PAGE        0x00000204
01528 
01532 #define HAM_PARAM_GET_DAM                  0x00000205
01533 
01558 #define HAM_PARAM_GET_STATISTICS        0x00000206
01559 
01577 HAM_EXPORT ham_status_t HAM_CALLCONV
01578 ham_get_parameters(ham_db_t *db, ham_parameter_t *param);
01579 
01591 HAM_EXPORT ham_u32_t HAM_CALLCONV
01592 ham_get_flags(ham_db_t *db);
01593 
01618 HAM_EXPORT int HAM_CALLCONV
01619 ham_key_get_approximate_match_type(ham_key_t *key);
01620 
01630 HAM_EXPORT ham_status_t HAM_CALLCONV
01631 ham_get_error(ham_db_t *db);
01632 
01645 typedef int HAM_CALLCONV (*ham_prefix_compare_func_t)
01646                                  (ham_db_t *db, 
01647                                   const ham_u8_t *lhs, ham_size_t lhs_length, 
01648                                   ham_size_t lhs_real_length,
01649                                   const ham_u8_t *rhs, ham_size_t rhs_length,
01650                                   ham_size_t rhs_real_length);
01651 
01667 HAM_EXPORT ham_status_t HAM_CALLCONV
01668 ham_set_prefix_compare_func(ham_db_t *db, ham_prefix_compare_func_t foo);
01669 
01678 typedef int HAM_CALLCONV (*ham_compare_func_t)(ham_db_t *db, 
01679                                   const ham_u8_t *lhs, ham_size_t lhs_length, 
01680                                   const ham_u8_t *rhs, ham_size_t rhs_length);
01681 
01704 HAM_EXPORT ham_status_t HAM_CALLCONV
01705 ham_set_compare_func(ham_db_t *db, ham_compare_func_t foo);
01706 
01719 typedef int HAM_CALLCONV (*ham_duplicate_compare_func_t)(ham_db_t *db, 
01720                                   const ham_u8_t *lhs, ham_size_t lhs_length, 
01721                                   const ham_u8_t *rhs, ham_size_t rhs_length);
01722 
01749 HAM_EXPORT ham_status_t HAM_CALLCONV
01750 ham_set_duplicate_compare_func(ham_db_t *db, ham_duplicate_compare_func_t foo);
01751 
01782 HAM_EXPORT ham_status_t HAM_CALLCONV
01783 ham_enable_compression(ham_db_t *db, ham_u32_t level, ham_u32_t flags);
01784 
01882 HAM_EXPORT ham_status_t HAM_CALLCONV
01883 ham_find(ham_db_t *db, ham_txn_t *txn, ham_key_t *key,
01884         ham_record_t *record, ham_u32_t flags);
01885 
01945 HAM_EXPORT ham_status_t HAM_CALLCONV
01946 ham_insert(ham_db_t *db, ham_txn_t *txn, ham_key_t *key,
01947         ham_record_t *record, ham_u32_t flags);
01948 
01960 #define HAM_OVERWRITE                   0x0001
01961 
01963 #define HAM_DUPLICATE                   0x0002
01964 
01966 #define HAM_DUPLICATE_INSERT_BEFORE     0x0004
01967 
01969 #define HAM_DUPLICATE_INSERT_AFTER      0x0008
01970 
01972 #define HAM_DUPLICATE_INSERT_FIRST      0x0010
01973 
01975 #define HAM_DUPLICATE_INSERT_LAST       0x0020
01976 
01978 #define HAM_DIRECT_ACCESS               0x0040
01979 
02012 #define HAM_HINT_APPEND               0x00080000
02013 
02026 #define HAM_HINT_PREPEND              0x00100000
02027 
02032 #define HAM_HINTS_MASK                0x00FF0000
02033 
02059 HAM_EXPORT ham_status_t HAM_CALLCONV
02060 ham_erase(ham_db_t *db, ham_txn_t *txn, ham_key_t *key, ham_u32_t flags);
02061 
02077 HAM_EXPORT ham_status_t HAM_CALLCONV
02078 ham_env_flush(ham_env_t *env, ham_u32_t flags);
02079 
02096 HAM_EXPORT ham_status_t HAM_CALLCONV
02097 ham_flush(ham_db_t *db, ham_u32_t flags);
02098 
02124 HAM_EXPORT ham_status_t HAM_CALLCONV
02125 ham_get_key_count(ham_db_t *db, ham_txn_t *txn, ham_u32_t flags,
02126             ham_offset_t *keycount);
02127 
02131 #define HAM_FAST_ESTIMATE           0x0001
02132 
02170 HAM_EXPORT ham_status_t HAM_CALLCONV
02171 ham_close(ham_db_t *db, ham_u32_t flags);
02172 
02174 #define HAM_AUTO_CLEANUP            1
02175 
02177 #define HAM_DONT_CLEAR_LOG          2
02178 
02180 #define HAM_TXN_AUTO_ABORT          4
02181 
02183 #define HAM_TXN_AUTO_COMMIT         8
02184 
02217 HAM_EXPORT ham_status_t HAM_CALLCONV
02218 ham_cursor_create(ham_db_t *db, ham_txn_t *txn, ham_u32_t flags,
02219             ham_cursor_t **cursor);
02220 
02239 HAM_EXPORT ham_status_t HAM_CALLCONV
02240 ham_cursor_clone(ham_cursor_t *src, ham_cursor_t **dest);
02241 
02313 HAM_EXPORT ham_status_t HAM_CALLCONV
02314 ham_cursor_move(ham_cursor_t *cursor, ham_key_t *key,
02315         ham_record_t *record, ham_u32_t flags);
02316 
02318 #define HAM_CURSOR_FIRST            0x0001
02319 
02321 #define HAM_CURSOR_LAST             0x0002
02322 
02324 #define HAM_CURSOR_NEXT             0x0004
02325 
02327 #define HAM_CURSOR_PREVIOUS         0x0008
02328 
02330 #define HAM_SKIP_DUPLICATES         0x0010
02331 
02333 #define HAM_ONLY_DUPLICATES         0x0020
02334 
02355 HAM_EXPORT ham_status_t HAM_CALLCONV
02356 ham_cursor_overwrite(ham_cursor_t *cursor, ham_record_t *record,
02357             ham_u32_t flags);
02358 
02484 HAM_EXPORT ham_status_t HAM_CALLCONV
02485 ham_cursor_find(ham_cursor_t *cursor, ham_key_t *key, ham_u32_t flags);
02486 
02623 HAM_EXPORT ham_status_t HAM_CALLCONV
02624 ham_cursor_find_ex(ham_cursor_t *cursor, ham_key_t *key, 
02625             ham_record_t *record, ham_u32_t flags);
02626 
02633 #define HAM_FIND_EXACT_MATCH        0x4000
02634 
02639 #define HAM_FIND_LT_MATCH           0x1000
02640 
02645 #define HAM_FIND_GT_MATCH           0x2000
02646 
02654 #define HAM_FIND_LEQ_MATCH          (HAM_FIND_LT_MATCH | HAM_FIND_EXACT_MATCH)
02655 
02663 #define HAM_FIND_GEQ_MATCH          (HAM_FIND_GT_MATCH | HAM_FIND_EXACT_MATCH)
02664 
02678 #define HAM_FIND_NEAR_MATCH         (HAM_FIND_LT_MATCH | HAM_FIND_GT_MATCH    \
02679                                         | HAM_FIND_EXACT_MATCH)
02680 
02794 HAM_EXPORT ham_status_t HAM_CALLCONV
02795 ham_cursor_insert(ham_cursor_t *cursor, ham_key_t *key,
02796             ham_record_t *record, ham_u32_t flags);
02797 
02817 HAM_EXPORT ham_status_t HAM_CALLCONV
02818 ham_cursor_erase(ham_cursor_t *cursor, ham_u32_t flags);
02819 
02835 HAM_EXPORT ham_status_t HAM_CALLCONV
02836 ham_cursor_get_duplicate_count(ham_cursor_t *cursor, 
02837         ham_size_t *count, ham_u32_t flags);
02838 
02853 HAM_EXPORT ham_status_t HAM_CALLCONV
02854 ham_cursor_close(ham_cursor_t *cursor);
02855 
02860 #ifdef __cplusplus
02861 } // extern "C"
02862 #endif
02863 
02864 #endif /* HAM_HAMSTERDB_H__ */

Generated on Thu Feb 11 22:04:58 2010 for hamsterdb Embedded Database by  doxygen 1.6.1