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 
00324 typedef void HAM_CALLCONV (*ham_errhandler_fun)
00325                     (int level, const char *message);
00326 
00332 #define HAM_DEBUG_LEVEL_DEBUG       0
00333 
00339 #define HAM_DEBUG_LEVEL_NORMAL      1
00340 
00348 #define HAM_DEBUG_LEVEL_FATAL       3
00349 
00365 HAM_EXPORT void HAM_CALLCONV
00366 ham_set_errhandler(ham_errhandler_fun f);
00367 
00375 HAM_EXPORT const char * HAM_CALLCONV
00376 ham_strerror(ham_status_t status);
00377 
00385 HAM_EXPORT void HAM_CALLCONV
00386 ham_get_version(ham_u32_t *major, ham_u32_t *minor,
00387         ham_u32_t *revision);
00388 
00396 HAM_EXPORT void HAM_CALLCONV
00397 ham_get_license(const char **licensee, const char **product);
00398 
00417 HAM_EXPORT ham_status_t HAM_CALLCONV
00418 ham_env_new(ham_env_t **env);
00419 
00431 HAM_EXPORT ham_status_t HAM_CALLCONV
00432 ham_env_delete(ham_env_t *env);
00433 
00470 HAM_EXPORT ham_status_t HAM_CALLCONV
00471 ham_env_create(ham_env_t *env, const char *filename,
00472         ham_u32_t flags, ham_u32_t mode);
00473 
00571 HAM_EXPORT ham_status_t HAM_CALLCONV
00572 ham_env_create_ex(ham_env_t *env, const char *filename,
00573         ham_u32_t flags, ham_u32_t mode, const ham_parameter_t *param);
00574 
00596 HAM_EXPORT ham_status_t HAM_CALLCONV
00597 ham_env_open(ham_env_t *env, const char *filename, ham_u32_t flags);
00598 
00677 HAM_EXPORT ham_status_t HAM_CALLCONV
00678 ham_env_open_ex(ham_env_t *env, const char *filename,
00679         ham_u32_t flags, const ham_parameter_t *param);
00680 
00700 HAM_EXPORT ham_status_t HAM_CALLCONV
00701 ham_env_get_parameters(ham_env_t *env, ham_parameter_t *param);
00702 
00766 HAM_EXPORT ham_status_t HAM_CALLCONV
00767 ham_env_create_db(ham_env_t *env, ham_db_t *db,
00768         ham_u16_t name, ham_u32_t flags, const ham_parameter_t *params);
00769 
00816 HAM_EXPORT ham_status_t HAM_CALLCONV
00817 ham_env_open_db(ham_env_t *env, ham_db_t *db,
00818         ham_u16_t name, ham_u32_t flags, const ham_parameter_t *params);
00819 
00844 HAM_EXPORT ham_status_t HAM_CALLCONV
00845 ham_env_rename_db(ham_env_t *env, ham_u16_t oldname, 
00846                 ham_u16_t newname, ham_u32_t flags);
00847 
00866 HAM_EXPORT ham_status_t HAM_CALLCONV
00867 ham_env_erase_db(ham_env_t *env, ham_u16_t name, ham_u32_t flags);
00868 
00884 HAM_EXPORT ham_status_t HAM_CALLCONV
00885 ham_env_flush(ham_env_t *env, ham_u32_t flags);
00886 
00921 HAM_EXPORT ham_status_t HAM_CALLCONV
00922 ham_env_enable_encryption(ham_env_t *env, ham_u8_t key[16], ham_u32_t flags);
00923 
00946 HAM_EXPORT ham_status_t HAM_CALLCONV
00947 ham_env_get_database_names(ham_env_t *env, ham_u16_t *names, ham_size_t *count);
00948 
00986 HAM_EXPORT ham_status_t HAM_CALLCONV
00987 ham_env_close(ham_env_t *env, ham_u32_t flags);
00988 
01005 struct ham_txn_t;
01006 typedef struct ham_txn_t ham_txn_t;
01007 
01031 HAM_EXPORT ham_status_t
01032 ham_txn_begin(ham_txn_t **txn, ham_db_t *db, ham_u32_t flags);
01033 
01035 #define HAM_TXN_READ_ONLY                                       1
01036 
01054 HAM_EXPORT ham_status_t
01055 ham_txn_commit(ham_txn_t *txn, ham_u32_t flags);
01056 
01058 #define HAM_TXN_FORCE_WRITE                                    1
01059 
01077 HAM_EXPORT ham_status_t
01078 ham_txn_abort(ham_txn_t *txn, ham_u32_t flags);
01079 
01080 /* note: ham_txn_abort flag 0x0001 is reserved for internal use: 
01081  * DO_NOT_NUKE_PAGE_STATS */
01082 
01101 HAM_EXPORT ham_status_t HAM_CALLCONV
01102 ham_new(ham_db_t **db);
01103 
01115 HAM_EXPORT ham_status_t HAM_CALLCONV
01116 ham_delete(ham_db_t *db);
01117 
01143 HAM_EXPORT ham_status_t HAM_CALLCONV
01144 ham_create(ham_db_t *db, const char *filename,
01145         ham_u32_t flags, ham_u32_t mode);
01146 
01257 HAM_EXPORT ham_status_t HAM_CALLCONV
01258 ham_create_ex(ham_db_t *db, const char *filename,
01259         ham_u32_t flags, ham_u32_t mode, const ham_parameter_t *param);
01260 
01281 HAM_EXPORT ham_status_t HAM_CALLCONV
01282 ham_open(ham_db_t *db, const char *filename, ham_u32_t flags);
01283 
01369 HAM_EXPORT ham_status_t HAM_CALLCONV
01370 ham_open_ex(ham_db_t *db, const char *filename,
01371         ham_u32_t flags, const ham_parameter_t *param);
01372 
01383 #define HAM_WRITE_THROUGH            0x00000001
01384 
01385 /* unused                            0x00000002 */
01386 
01389 #define HAM_READ_ONLY                0x00000004
01390 
01391 /* unused                            0x00000008 */
01392 
01395 #define HAM_USE_BTREE                0x00000010
01396 
01397 /* reserved                          0x00000020 */
01398 
01401 #define HAM_DISABLE_VAR_KEYLEN       0x00000040
01402 
01405 #define HAM_IN_MEMORY_DB             0x00000080
01406 
01407 /* reserved: DB_USE_MMAP (not persistent)      0x00000100 */
01408 
01412 #define HAM_DISABLE_MMAP             0x00000200
01413 
01417 #define HAM_CACHE_STRICT             0x00000400
01418 
01422 #define HAM_DISABLE_FREELIST_FLUSH   0x00000800
01423 
01426 #define HAM_LOCK_EXCLUSIVE           0x00001000
01427 
01430 #define HAM_RECORD_NUMBER            0x00002000
01431 
01434 #define HAM_ENABLE_DUPLICATES        0x00004000
01435 
01439 #define HAM_ENABLE_RECOVERY          0x00008000
01440 
01443 #define HAM_AUTO_RECOVERY            0x00010000
01444 
01448 #define HAM_ENABLE_TRANSACTIONS      0x00020000
01449 
01453 #define HAM_CACHE_UNLIMITED          0x00040000
01454 
01455 /* reserved: DB_ENV_IS_PRIVATE (not persistent)      0x00080000 */
01456 
01460 #define HAM_SORT_DUPLICATES          0x00100000
01461 
01477 #define HAM_PARAM_CACHESIZE          0x00000100
01478 
01481 #define HAM_PARAM_PAGESIZE           0x00000101
01482 
01484 #define HAM_PARAM_KEYSIZE            0x00000102
01485 
01488 #define HAM_PARAM_MAX_ENV_DATABASES  0x00000103
01489 
01493 #define HAM_PARAM_DATA_ACCESS_MODE   0x00000104
01494 
01510 #define HAM_PARAM_GET_FLAGS                0x00000200
01511 
01517 #define HAM_PARAM_GET_FILEMODE            0x00000201
01518 
01526 #define HAM_PARAM_GET_FILENAME            0x00000202
01527 
01535 #define HAM_PARAM_DBNAME                  0x00000203
01536 
01545 #define HAM_PARAM_GET_KEYS_PER_PAGE        0x00000204
01546 
01550 #define HAM_PARAM_GET_DAM                  0x00000205
01551 
01567 #define HAM_PARAM_GET_STATISTICS        0x00000206
01568 
01586 HAM_EXPORT ham_status_t HAM_CALLCONV
01587 ham_get_parameters(ham_db_t *db, ham_parameter_t *param);
01588 
01600 HAM_EXPORT ham_u32_t HAM_CALLCONV
01601 ham_get_flags(ham_db_t *db);
01602 
01616 HAM_EXPORT ham_env_t *HAM_CALLCONV
01617 ham_get_env(ham_db_t *db);
01618 
01643 HAM_EXPORT int HAM_CALLCONV
01644 ham_key_get_approximate_match_type(ham_key_t *key);
01645 
01655 HAM_EXPORT ham_status_t HAM_CALLCONV
01656 ham_get_error(ham_db_t *db);
01657 
01670 typedef int HAM_CALLCONV (*ham_prefix_compare_func_t)
01671                                  (ham_db_t *db, 
01672                                   const ham_u8_t *lhs, ham_size_t lhs_length, 
01673                                   ham_size_t lhs_real_length,
01674                                   const ham_u8_t *rhs, ham_size_t rhs_length,
01675                                   ham_size_t rhs_real_length);
01676 
01692 HAM_EXPORT ham_status_t HAM_CALLCONV
01693 ham_set_prefix_compare_func(ham_db_t *db, ham_prefix_compare_func_t foo);
01694 
01703 typedef int HAM_CALLCONV (*ham_compare_func_t)(ham_db_t *db, 
01704                                   const ham_u8_t *lhs, ham_size_t lhs_length, 
01705                                   const ham_u8_t *rhs, ham_size_t rhs_length);
01706 
01729 HAM_EXPORT ham_status_t HAM_CALLCONV
01730 ham_set_compare_func(ham_db_t *db, ham_compare_func_t foo);
01731 
01744 typedef int HAM_CALLCONV (*ham_duplicate_compare_func_t)(ham_db_t *db, 
01745                                   const ham_u8_t *lhs, ham_size_t lhs_length, 
01746                                   const ham_u8_t *rhs, ham_size_t rhs_length);
01747 
01774 HAM_EXPORT ham_status_t HAM_CALLCONV
01775 ham_set_duplicate_compare_func(ham_db_t *db, ham_duplicate_compare_func_t foo);
01776 
01807 HAM_EXPORT ham_status_t HAM_CALLCONV
01808 ham_enable_compression(ham_db_t *db, ham_u32_t level, ham_u32_t flags);
01809 
01914 HAM_EXPORT ham_status_t HAM_CALLCONV
01915 ham_find(ham_db_t *db, ham_txn_t *txn, ham_key_t *key,
01916         ham_record_t *record, ham_u32_t flags);
01917 
01993 HAM_EXPORT ham_status_t HAM_CALLCONV
01994 ham_insert(ham_db_t *db, ham_txn_t *txn, ham_key_t *key,
01995         ham_record_t *record, ham_u32_t flags);
01996 
02008 #define HAM_OVERWRITE                   0x0001
02009 
02011 #define HAM_DUPLICATE                   0x0002
02012 
02014 #define HAM_DUPLICATE_INSERT_BEFORE     0x0004
02015 
02017 #define HAM_DUPLICATE_INSERT_AFTER      0x0008
02018 
02020 #define HAM_DUPLICATE_INSERT_FIRST      0x0010
02021 
02023 #define HAM_DUPLICATE_INSERT_LAST       0x0020
02024 
02026 #define HAM_DIRECT_ACCESS               0x0040
02027 
02030 #define HAM_PARTIAL                     0x0080
02031 
02064 #define HAM_HINT_APPEND               0x00080000
02065 
02078 #define HAM_HINT_PREPEND              0x00100000
02079 
02084 #define HAM_HINTS_MASK                0x00FF0000
02085 
02111 HAM_EXPORT ham_status_t HAM_CALLCONV
02112 ham_erase(ham_db_t *db, ham_txn_t *txn, ham_key_t *key, ham_u32_t flags);
02113 
02130 HAM_EXPORT ham_status_t HAM_CALLCONV
02131 ham_flush(ham_db_t *db, ham_u32_t flags);
02132 
02158 HAM_EXPORT ham_status_t HAM_CALLCONV
02159 ham_get_key_count(ham_db_t *db, ham_txn_t *txn, ham_u32_t flags,
02160             ham_offset_t *keycount);
02161 
02165 #define HAM_FAST_ESTIMATE           0x0001
02166 
02204 HAM_EXPORT ham_status_t HAM_CALLCONV
02205 ham_close(ham_db_t *db, ham_u32_t flags);
02206 
02208 #define HAM_AUTO_CLEANUP            1
02209 
02211 #define HAM_DONT_CLEAR_LOG          2
02212 
02214 #define HAM_TXN_AUTO_ABORT          4
02215 
02217 #define HAM_TXN_AUTO_COMMIT         8
02218 
02251 HAM_EXPORT ham_status_t HAM_CALLCONV
02252 ham_cursor_create(ham_db_t *db, ham_txn_t *txn, ham_u32_t flags,
02253             ham_cursor_t **cursor);
02254 
02273 HAM_EXPORT ham_status_t HAM_CALLCONV
02274 ham_cursor_clone(ham_cursor_t *src, ham_cursor_t **dest);
02275 
02361 HAM_EXPORT ham_status_t HAM_CALLCONV
02362 ham_cursor_move(ham_cursor_t *cursor, ham_key_t *key,
02363         ham_record_t *record, ham_u32_t flags);
02364 
02366 #define HAM_CURSOR_FIRST            0x0001
02367 
02369 #define HAM_CURSOR_LAST             0x0002
02370 
02372 #define HAM_CURSOR_NEXT             0x0004
02373 
02375 #define HAM_CURSOR_PREVIOUS         0x0008
02376 
02378 #define HAM_SKIP_DUPLICATES         0x0010
02379 
02381 #define HAM_ONLY_DUPLICATES         0x0020
02382 
02403 HAM_EXPORT ham_status_t HAM_CALLCONV
02404 ham_cursor_overwrite(ham_cursor_t *cursor, ham_record_t *record,
02405             ham_u32_t flags);
02406 
02532 HAM_EXPORT ham_status_t HAM_CALLCONV
02533 ham_cursor_find(ham_cursor_t *cursor, ham_key_t *key, ham_u32_t flags);
02534 
02678 HAM_EXPORT ham_status_t HAM_CALLCONV
02679 ham_cursor_find_ex(ham_cursor_t *cursor, ham_key_t *key, 
02680             ham_record_t *record, ham_u32_t flags);
02681 
02688 #define HAM_FIND_EXACT_MATCH        0x4000
02689 
02694 #define HAM_FIND_LT_MATCH           0x1000
02695 
02700 #define HAM_FIND_GT_MATCH           0x2000
02701 
02709 #define HAM_FIND_LEQ_MATCH          (HAM_FIND_LT_MATCH | HAM_FIND_EXACT_MATCH)
02710 
02718 #define HAM_FIND_GEQ_MATCH          (HAM_FIND_GT_MATCH | HAM_FIND_EXACT_MATCH)
02719 
02733 #define HAM_FIND_NEAR_MATCH         (HAM_FIND_LT_MATCH | HAM_FIND_GT_MATCH    \
02734                                         | HAM_FIND_EXACT_MATCH)
02735 
02858 HAM_EXPORT ham_status_t HAM_CALLCONV
02859 ham_cursor_insert(ham_cursor_t *cursor, ham_key_t *key,
02860             ham_record_t *record, ham_u32_t flags);
02861 
02881 HAM_EXPORT ham_status_t HAM_CALLCONV
02882 ham_cursor_erase(ham_cursor_t *cursor, ham_u32_t flags);
02883 
02899 HAM_EXPORT ham_status_t HAM_CALLCONV
02900 ham_cursor_get_duplicate_count(ham_cursor_t *cursor, 
02901         ham_size_t *count, ham_u32_t flags);
02902 
02917 HAM_EXPORT ham_status_t HAM_CALLCONV
02918 ham_cursor_close(ham_cursor_t *cursor);
02919 
02924 #ifdef __cplusplus
02925 } // extern "C"
02926 #endif
02927 
02928 #endif /* HAM_HAMSTERDB_H__ */

Generated on Tue Mar 16 20:19:44 2010 for hamsterdb Embedded Database by  doxygen 1.6.1