hamsterdb Embedded Database 1.1.14

hamsterdb.h

Go to the documentation of this file.
00001 /*
00002  * Copyright (C) 2005-2011 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 
00105 #ifndef HAM_HAMSTERDB_H__
00106 #define HAM_HAMSTERDB_H__
00107 
00108 #include <ham/types.h>
00109 
00110 #ifdef __cplusplus
00111 extern "C" {
00112 #endif
00113 
00120 struct ham_db_t;
00121 typedef struct ham_db_t ham_db_t;
00122 
00129 struct ham_env_t;
00130 typedef struct ham_env_t ham_env_t;
00131 
00141 struct ham_cursor_t;
00142 typedef struct ham_cursor_t ham_cursor_t;
00143 
00161 typedef struct
00162 {
00164     ham_size_t size;
00165 
00167     void *data;
00168 
00170     ham_u32_t flags;
00171 
00173     ham_u32_t partial_offset;
00174 
00176     ham_size_t partial_size;
00177 
00179     ham_u32_t _intflags;
00180 
00182     ham_u64_t _rid;
00183 
00184 } ham_record_t;
00185 
00190 #define HAM_RECORD_USER_ALLOC   1
00191 
00211 typedef struct
00212 {
00214     ham_u16_t size;
00215 
00217     void *data;
00218 
00220     ham_u32_t flags;
00221 
00223     ham_u32_t _flags;
00224 } ham_key_t;
00225 
00230 #define HAM_KEY_USER_ALLOC      1
00231 
00249 typedef struct {
00251     ham_u32_t name;
00252 
00254     ham_u64_t value;
00255 
00256 } ham_parameter_t;
00257 
00258 
00291 #define HAM_DAM_RANDOM_WRITE            0x0001
00292 
00301 #define HAM_DAM_SEQUENTIAL_INSERT        0x0002
00302 
00303 /* internal use only - will be set implicitly when opening a file from 1.0.x */ 
00304 #define HAM_DAM_ENFORCE_PRE110_FORMAT    0x8000
00305 
00317 #define HAM_SUCCESS                  (  0)
00318 
00319 #define HAM_INV_KEYSIZE              ( -3)
00320 
00321 #define HAM_INV_PAGESIZE             ( -4)
00322 
00323 #define HAM_OUT_OF_MEMORY            ( -6)
00324 
00325 #define HAM_NOT_INITIALIZED          ( -7)
00326 
00327 #define HAM_INV_PARAMETER            ( -8)
00328 
00329 #define HAM_INV_FILE_HEADER          ( -9)
00330 
00331 #define HAM_INV_FILE_VERSION         (-10)
00332 
00333 #define HAM_KEY_NOT_FOUND            (-11)
00334 
00335 #define HAM_DUPLICATE_KEY            (-12)
00336 
00337 #define HAM_INTEGRITY_VIOLATED       (-13)
00338 
00339 #define HAM_INTERNAL_ERROR           (-14)
00340 
00341 #define HAM_DB_READ_ONLY             (-15)
00342 
00343 #define HAM_BLOB_NOT_FOUND           (-16)
00344 
00345 #define HAM_PREFIX_REQUEST_FULLKEY   (-17)
00346 
00347 #define HAM_IO_ERROR                 (-18)
00348 
00349 #define HAM_CACHE_FULL               (-19)
00350 
00351 #define HAM_NOT_IMPLEMENTED          (-20)
00352 
00353 #define HAM_FILE_NOT_FOUND           (-21)
00354 
00355 #define HAM_WOULD_BLOCK              (-22)
00356 
00357 #define HAM_NOT_READY                (-23)
00358 
00359 #define HAM_LIMITS_REACHED           (-24)
00360 
00361 #define HAM_ACCESS_DENIED            (-25)
00362 
00363 #define HAM_ALREADY_INITIALIZED      (-27)
00364 
00365 #define HAM_NEED_RECOVERY            (-28)
00366 
00367 #define HAM_CURSOR_STILL_OPEN        (-29)
00368 
00369 #define HAM_FILTER_NOT_FOUND         (-30)
00370 
00371 #define HAM_CURSOR_IS_NIL           (-100)
00372 
00373 #define HAM_DATABASE_NOT_FOUND      (-200)
00374 
00375 #define HAM_DATABASE_ALREADY_EXISTS (-201)
00376 
00377 #define HAM_DATABASE_ALREADY_OPEN   (-202)
00378 
00379 #define HAM_ENVIRONMENT_ALREADY_OPEN   (-203)
00380 
00381 #define HAM_LOG_INV_FILE_HEADER     (-300)
00382 
00383 #define HAM_NETWORK_ERROR           (-400)
00384 
00412 typedef void HAM_CALLCONV (*ham_errhandler_fun)
00413                     (int level, const char *message);
00414 
00416 #define HAM_DEBUG_LEVEL_DEBUG       0
00417 
00419 #define HAM_DEBUG_LEVEL_NORMAL      1
00420 
00422 #define HAM_DEBUG_LEVEL_FATAL       3
00423 
00439 HAM_EXPORT void HAM_CALLCONV
00440 ham_set_errhandler(ham_errhandler_fun f);
00441 
00449 HAM_EXPORT const char * HAM_CALLCONV
00450 ham_strerror(ham_status_t status);
00451 
00459 HAM_EXPORT void HAM_CALLCONV
00460 ham_get_version(ham_u32_t *major, ham_u32_t *minor,
00461         ham_u32_t *revision);
00462 
00470 HAM_EXPORT void HAM_CALLCONV
00471 ham_get_license(const char **licensee, const char **product);
00472 
00491 HAM_EXPORT ham_status_t HAM_CALLCONV
00492 ham_env_new(ham_env_t **env);
00493 
00505 HAM_EXPORT ham_status_t HAM_CALLCONV
00506 ham_env_delete(ham_env_t *env);
00507 
00516 HAM_EXPORT ham_status_t HAM_CALLCONV
00517 ham_env_create(ham_env_t *env, const char *filename,
00518         ham_u32_t flags, ham_u32_t mode);
00519 
00621 HAM_EXPORT ham_status_t HAM_CALLCONV
00622 ham_env_create_ex(ham_env_t *env, const char *filename,
00623         ham_u32_t flags, ham_u32_t mode, const ham_parameter_t *param);
00624 
00633 HAM_EXPORT ham_status_t HAM_CALLCONV
00634 ham_env_open(ham_env_t *env, const char *filename, ham_u32_t flags);
00635 
00734 HAM_EXPORT ham_status_t HAM_CALLCONV
00735 ham_env_open_ex(ham_env_t *env, const char *filename,
00736         ham_u32_t flags, const ham_parameter_t *param);
00737 
00765 HAM_EXPORT ham_status_t HAM_CALLCONV
00766 ham_env_get_parameters(ham_env_t *env, ham_parameter_t *param);
00767 
00842 HAM_EXPORT ham_status_t HAM_CALLCONV
00843 ham_env_create_db(ham_env_t *env, ham_db_t *db,
00844         ham_u16_t name, ham_u32_t flags, const ham_parameter_t *params);
00845 
00899 HAM_EXPORT ham_status_t HAM_CALLCONV
00900 ham_env_open_db(ham_env_t *env, ham_db_t *db,
00901         ham_u16_t name, ham_u32_t flags, const ham_parameter_t *params);
00902 
00927 HAM_EXPORT ham_status_t HAM_CALLCONV
00928 ham_env_rename_db(ham_env_t *env, ham_u16_t oldname, 
00929                 ham_u16_t newname, ham_u32_t flags);
00930 
00949 HAM_EXPORT ham_status_t HAM_CALLCONV
00950 ham_env_erase_db(ham_env_t *env, ham_u16_t name, ham_u32_t flags);
00951 
00967 HAM_EXPORT ham_status_t HAM_CALLCONV
00968 ham_env_flush(ham_env_t *env, ham_u32_t flags);
00969 
01004 HAM_EXPORT ham_status_t HAM_CALLCONV
01005 ham_env_enable_encryption(ham_env_t *env, ham_u8_t key[16], ham_u32_t flags);
01006 
01029 HAM_EXPORT ham_status_t HAM_CALLCONV
01030 ham_env_get_database_names(ham_env_t *env, ham_u16_t *names, ham_size_t *count);
01031 
01069 HAM_EXPORT ham_status_t HAM_CALLCONV
01070 ham_env_close(ham_env_t *env, ham_u32_t flags);
01071 
01088 struct ham_txn_t;
01089 typedef struct ham_txn_t ham_txn_t;
01090 
01124 HAM_EXPORT ham_status_t
01125 ham_txn_begin(ham_txn_t **txn, ham_db_t *db, ham_u32_t flags);
01126 
01128 #define HAM_TXN_READ_ONLY                                       1
01129 
01156 HAM_EXPORT ham_status_t
01157 ham_txn_commit(ham_txn_t *txn, ham_u32_t flags);
01158 
01185 HAM_EXPORT ham_status_t
01186 ham_txn_abort(ham_txn_t *txn, ham_u32_t flags);
01187 
01188 /* note: ham_txn_abort flag 0x0001 is reserved for internal use: 
01189  * DO_NOT_NUKE_PAGE_STATS */
01190 
01209 HAM_EXPORT ham_status_t HAM_CALLCONV
01210 ham_new(ham_db_t **db);
01211 
01223 HAM_EXPORT ham_status_t HAM_CALLCONV
01224 ham_delete(ham_db_t *db);
01225 
01234 HAM_EXPORT ham_status_t HAM_CALLCONV
01235 ham_create(ham_db_t *db, const char *filename,
01236         ham_u32_t flags, ham_u32_t mode);
01237 
01363 HAM_EXPORT ham_status_t HAM_CALLCONV
01364 ham_create_ex(ham_db_t *db, const char *filename,
01365         ham_u32_t flags, ham_u32_t mode, const ham_parameter_t *param);
01366 
01375 HAM_EXPORT ham_status_t HAM_CALLCONV
01376 ham_open(ham_db_t *db, const char *filename, ham_u32_t flags);
01377 
01477 HAM_EXPORT ham_status_t HAM_CALLCONV
01478 ham_open_ex(ham_db_t *db, const char *filename,
01479         ham_u32_t flags, const ham_parameter_t *param);
01480 
01484 #define HAM_WRITE_THROUGH            0x00000001
01485 
01486 /* unused                            0x00000002 */
01487 
01490 #define HAM_READ_ONLY                0x00000004
01491 
01492 /* unused                            0x00000008 */
01493 
01496 #define HAM_USE_BTREE                0x00000010
01497 
01498 /* reserved                          0x00000020 */
01499 
01502 #define HAM_DISABLE_VAR_KEYLEN       0x00000040
01503 
01506 #define HAM_IN_MEMORY_DB             0x00000080
01507 
01508 /* reserved: DB_USE_MMAP (not persistent)      0x00000100 */
01509 
01513 #define HAM_DISABLE_MMAP             0x00000200
01514 
01518 #define HAM_CACHE_STRICT             0x00000400
01519 
01523 #define HAM_DISABLE_FREELIST_FLUSH   0x00000800
01524 
01527 #define HAM_LOCK_EXCLUSIVE           0x00001000
01528 
01531 #define HAM_RECORD_NUMBER            0x00002000
01532 
01535 #define HAM_ENABLE_DUPLICATES        0x00004000
01536 
01540 #define HAM_ENABLE_RECOVERY          0x00008000
01541 
01544 #define HAM_AUTO_RECOVERY            0x00010000
01545 
01549 #define HAM_ENABLE_TRANSACTIONS      0x00020000
01550 
01554 #define HAM_CACHE_UNLIMITED          0x00040000
01555 
01556 /* reserved: DB_ENV_IS_PRIVATE (not persistent)      0x00080000 */
01557 
01561 #define HAM_SORT_DUPLICATES          0x00100000
01562 
01563 /* reserved: DB_IS_REMOTE     (not persistent)       0x00200000 */
01564 
01574 HAM_EXPORT ham_status_t HAM_CALLCONV
01575 ham_get_error(ham_db_t *db);
01576 
01589 typedef int HAM_CALLCONV (*ham_prefix_compare_func_t)
01590                                  (ham_db_t *db, 
01591                                   const ham_u8_t *lhs, ham_size_t lhs_length, 
01592                                   ham_size_t lhs_real_length,
01593                                   const ham_u8_t *rhs, ham_size_t rhs_length,
01594                                   ham_size_t rhs_real_length);
01595 
01611 HAM_EXPORT ham_status_t HAM_CALLCONV
01612 ham_set_prefix_compare_func(ham_db_t *db, ham_prefix_compare_func_t foo);
01613 
01622 typedef int HAM_CALLCONV (*ham_compare_func_t)(ham_db_t *db, 
01623                                   const ham_u8_t *lhs, ham_size_t lhs_length, 
01624                                   const ham_u8_t *rhs, ham_size_t rhs_length);
01625 
01648 HAM_EXPORT ham_status_t HAM_CALLCONV
01649 ham_set_compare_func(ham_db_t *db, ham_compare_func_t foo);
01650 
01663 typedef int HAM_CALLCONV (*ham_duplicate_compare_func_t)(ham_db_t *db, 
01664                                   const ham_u8_t *lhs, ham_size_t lhs_length, 
01665                                   const ham_u8_t *rhs, ham_size_t rhs_length);
01666 
01697 HAM_EXPORT ham_status_t HAM_CALLCONV
01698 ham_set_duplicate_compare_func(ham_db_t *db, ham_duplicate_compare_func_t foo);
01699 
01730 HAM_EXPORT ham_status_t HAM_CALLCONV
01731 ham_enable_compression(ham_db_t *db, ham_u32_t level, ham_u32_t flags);
01732 
01837 HAM_EXPORT ham_status_t HAM_CALLCONV
01838 ham_find(ham_db_t *db, ham_txn_t *txn, ham_key_t *key,
01839         ham_record_t *record, ham_u32_t flags);
01840 
01916 HAM_EXPORT ham_status_t HAM_CALLCONV
01917 ham_insert(ham_db_t *db, ham_txn_t *txn, ham_key_t *key,
01918         ham_record_t *record, ham_u32_t flags);
01919 
01931 #define HAM_OVERWRITE                   0x0001
01932 
01934 #define HAM_DUPLICATE                   0x0002
01935 
01937 #define HAM_DUPLICATE_INSERT_BEFORE     0x0004
01938 
01940 #define HAM_DUPLICATE_INSERT_AFTER      0x0008
01941 
01943 #define HAM_DUPLICATE_INSERT_FIRST      0x0010
01944 
01946 #define HAM_DUPLICATE_INSERT_LAST       0x0020
01947 
01949 #define HAM_DIRECT_ACCESS               0x0040
01950 
01953 #define HAM_PARTIAL                     0x0080
01954 
01967 #define HAM_HINT_APPEND               0x00080000
01968 
01981 #define HAM_HINT_PREPEND              0x00100000
01982 
01987 #define HAM_HINTS_MASK                0x00FF0000
01988 
02010 HAM_EXPORT ham_status_t HAM_CALLCONV
02011 ham_erase(ham_db_t *db, ham_txn_t *txn, ham_key_t *key, ham_u32_t flags);
02012 
02026 HAM_EXPORT ham_status_t HAM_CALLCONV
02027 ham_flush(ham_db_t *db, ham_u32_t flags);
02028 
02054 HAM_EXPORT ham_status_t HAM_CALLCONV
02055 ham_get_key_count(ham_db_t *db, ham_txn_t *txn, ham_u32_t flags,
02056             ham_offset_t *keycount);
02057 
02061 #define HAM_FAST_ESTIMATE           0x0001
02062 
02095 HAM_EXPORT ham_status_t HAM_CALLCONV
02096 ham_get_parameters(ham_db_t *db, ham_parameter_t *param);
02097 
02100 #define HAM_PARAM_CACHESIZE          0x00000100
02101 
02104 #define HAM_PARAM_PAGESIZE           0x00000101
02105 
02107 #define HAM_PARAM_KEYSIZE            0x00000102
02108 
02111 #define HAM_PARAM_MAX_ENV_DATABASES  0x00000103
02112 
02116 #define HAM_PARAM_DATA_ACCESS_MODE   0x00000104
02117 
02123 #define HAM_PARAM_GET_FLAGS                0x00000200
02124 
02130 #define HAM_PARAM_GET_FILEMODE            0x00000201
02131 
02139 #define HAM_PARAM_GET_FILENAME            0x00000202
02140 
02148 #define HAM_PARAM_GET_DATABASE_NAME       0x00000203
02149 #define HAM_PARAM_DBNAME                  HAM_PARAM_GET_DATABASE_NAME
02150 
02159 #define HAM_PARAM_GET_KEYS_PER_PAGE        0x00000204
02160 
02164 #define HAM_PARAM_GET_DATA_ACCESS_MODE     0x00000205
02165 #define HAM_PARAM_GET_DAM                  HAM_PARAM_GET_DATA_ACCESS_MODE
02166 
02178 HAM_EXPORT ham_u32_t HAM_CALLCONV
02179 ham_get_flags(ham_db_t *db);
02180 
02194 HAM_EXPORT ham_env_t *HAM_CALLCONV
02195 ham_get_env(ham_db_t *db);
02196 
02221 HAM_EXPORT int HAM_CALLCONV
02222 ham_key_get_approximate_match_type(ham_key_t *key);
02223 
02261 HAM_EXPORT ham_status_t HAM_CALLCONV
02262 ham_close(ham_db_t *db, ham_u32_t flags);
02263 
02265 #define HAM_AUTO_CLEANUP            1
02266 
02268 #define HAM_DONT_CLEAR_LOG          2
02269 
02271 #define HAM_TXN_AUTO_ABORT          4
02272 
02274 #define HAM_TXN_AUTO_COMMIT         8
02275 
02307 HAM_EXPORT ham_status_t HAM_CALLCONV
02308 ham_cursor_create(ham_db_t *db, ham_txn_t *txn, ham_u32_t flags,
02309             ham_cursor_t **cursor);
02310 
02329 HAM_EXPORT ham_status_t HAM_CALLCONV
02330 ham_cursor_clone(ham_cursor_t *src, ham_cursor_t **dest);
02331 
02417 HAM_EXPORT ham_status_t HAM_CALLCONV
02418 ham_cursor_move(ham_cursor_t *cursor, ham_key_t *key,
02419         ham_record_t *record, ham_u32_t flags);
02420 
02422 #define HAM_CURSOR_FIRST            0x0001
02423 
02425 #define HAM_CURSOR_LAST             0x0002
02426 
02428 #define HAM_CURSOR_NEXT             0x0004
02429 
02431 #define HAM_CURSOR_PREVIOUS         0x0008
02432 
02434 #define HAM_SKIP_DUPLICATES         0x0010
02435 
02437 #define HAM_ONLY_DUPLICATES         0x0020
02438 
02459 HAM_EXPORT ham_status_t HAM_CALLCONV
02460 ham_cursor_overwrite(ham_cursor_t *cursor, ham_record_t *record,
02461             ham_u32_t flags);
02462 
02588 HAM_EXPORT ham_status_t HAM_CALLCONV
02589 ham_cursor_find(ham_cursor_t *cursor, ham_key_t *key, ham_u32_t flags);
02590 
02734 HAM_EXPORT ham_status_t HAM_CALLCONV
02735 ham_cursor_find_ex(ham_cursor_t *cursor, ham_key_t *key, 
02736             ham_record_t *record, ham_u32_t flags);
02737 
02744 #define HAM_FIND_EXACT_MATCH        0x4000
02745 
02750 #define HAM_FIND_LT_MATCH           0x1000
02751 
02756 #define HAM_FIND_GT_MATCH           0x2000
02757 
02765 #define HAM_FIND_LEQ_MATCH          (HAM_FIND_LT_MATCH | HAM_FIND_EXACT_MATCH)
02766 
02774 #define HAM_FIND_GEQ_MATCH          (HAM_FIND_GT_MATCH | HAM_FIND_EXACT_MATCH)
02775 
02789 #define HAM_FIND_NEAR_MATCH         (HAM_FIND_LT_MATCH | HAM_FIND_GT_MATCH    \
02790                                         | HAM_FIND_EXACT_MATCH)
02791 
02914 HAM_EXPORT ham_status_t HAM_CALLCONV
02915 ham_cursor_insert(ham_cursor_t *cursor, ham_key_t *key,
02916             ham_record_t *record, ham_u32_t flags);
02917 
02937 HAM_EXPORT ham_status_t HAM_CALLCONV
02938 ham_cursor_erase(ham_cursor_t *cursor, ham_u32_t flags);
02939 
02955 HAM_EXPORT ham_status_t HAM_CALLCONV
02956 ham_cursor_get_duplicate_count(ham_cursor_t *cursor, 
02957         ham_size_t *count, ham_u32_t flags);
02958 
02971 HAM_EXPORT ham_status_t HAM_CALLCONV
02972 ham_cursor_get_record_size(ham_cursor_t *cursor, ham_offset_t *size);
02973 
02988 HAM_EXPORT ham_status_t HAM_CALLCONV
02989 ham_cursor_close(ham_cursor_t *cursor);
02990 
02995 #ifdef __cplusplus
02996 } // extern "C"
02997 #endif
02998 
02999 #endif /* HAM_HAMSTERDB_H__ */