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 
00430 HAM_EXPORT ham_status_t HAM_CALLCONV
00431 ham_env_create(ham_env_t *env, const char *filename,
00432         ham_u32_t flags, ham_u32_t mode);
00433 
00531 HAM_EXPORT ham_status_t HAM_CALLCONV
00532 ham_env_create_ex(ham_env_t *env, const char *filename,
00533         ham_u32_t flags, ham_u32_t mode, const ham_parameter_t *param);
00534 
00543 HAM_EXPORT ham_status_t HAM_CALLCONV
00544 ham_env_open(ham_env_t *env, const char *filename, ham_u32_t flags);
00545 
00641 HAM_EXPORT ham_status_t HAM_CALLCONV
00642 ham_env_open_ex(ham_env_t *env, const char *filename,
00643         ham_u32_t flags, const ham_parameter_t *param);
00644 
00672 HAM_EXPORT ham_status_t HAM_CALLCONV
00673 ham_env_get_parameters(ham_env_t *env, ham_parameter_t *param);
00674 
00749 HAM_EXPORT ham_status_t HAM_CALLCONV
00750 ham_env_create_db(ham_env_t *env, ham_db_t *db,
00751         ham_u16_t name, ham_u32_t flags, const ham_parameter_t *params);
00752 
00806 HAM_EXPORT ham_status_t HAM_CALLCONV
00807 ham_env_open_db(ham_env_t *env, ham_db_t *db,
00808         ham_u16_t name, ham_u32_t flags, const ham_parameter_t *params);
00809 
00834 HAM_EXPORT ham_status_t HAM_CALLCONV
00835 ham_env_rename_db(ham_env_t *env, ham_u16_t oldname, 
00836                 ham_u16_t newname, ham_u32_t flags);
00837 
00856 HAM_EXPORT ham_status_t HAM_CALLCONV
00857 ham_env_erase_db(ham_env_t *env, ham_u16_t name, ham_u32_t flags);
00858 
00874 HAM_EXPORT ham_status_t HAM_CALLCONV
00875 ham_env_flush(ham_env_t *env, ham_u32_t flags);
00876 
00911 HAM_EXPORT ham_status_t HAM_CALLCONV
00912 ham_env_enable_encryption(ham_env_t *env, ham_u8_t key[16], ham_u32_t flags);
00913 
00936 HAM_EXPORT ham_status_t HAM_CALLCONV
00937 ham_env_get_database_names(ham_env_t *env, ham_u16_t *names, ham_size_t *count);
00938 
00976 HAM_EXPORT ham_status_t HAM_CALLCONV
00977 ham_env_close(ham_env_t *env, ham_u32_t flags);
00978 
00995 struct ham_txn_t;
00996 typedef struct ham_txn_t ham_txn_t;
00997 
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 
01055 HAM_EXPORT ham_status_t
01056 ham_txn_commit(ham_txn_t *txn, ham_u32_t flags);
01057 
01059 #define HAM_TXN_FORCE_WRITE                                    1
01060 
01079 HAM_EXPORT ham_status_t
01080 ham_txn_abort(ham_txn_t *txn, ham_u32_t flags);
01081 
01082 /* note: ham_txn_abort flag 0x0001 is reserved for internal use: 
01083  * DO_NOT_NUKE_PAGE_STATS */
01084 
01103 HAM_EXPORT ham_status_t HAM_CALLCONV
01104 ham_new(ham_db_t **db);
01105 
01117 HAM_EXPORT ham_status_t HAM_CALLCONV
01118 ham_delete(ham_db_t *db);
01119 
01128 HAM_EXPORT ham_status_t HAM_CALLCONV
01129 ham_create(ham_db_t *db, const char *filename,
01130         ham_u32_t flags, ham_u32_t mode);
01131 
01253 HAM_EXPORT ham_status_t HAM_CALLCONV
01254 ham_create_ex(ham_db_t *db, const char *filename,
01255         ham_u32_t flags, ham_u32_t mode, const ham_parameter_t *param);
01256 
01265 HAM_EXPORT ham_status_t HAM_CALLCONV
01266 ham_open(ham_db_t *db, const char *filename, ham_u32_t flags);
01267 
01364 HAM_EXPORT ham_status_t HAM_CALLCONV
01365 ham_open_ex(ham_db_t *db, const char *filename,
01366         ham_u32_t flags, const ham_parameter_t *param);
01367 
01371 #define HAM_WRITE_THROUGH            0x00000001
01372 
01373 /* unused                            0x00000002 */
01374 
01377 #define HAM_READ_ONLY                0x00000004
01378 
01379 /* unused                            0x00000008 */
01380 
01383 #define HAM_USE_BTREE                0x00000010
01384 
01385 /* reserved                          0x00000020 */
01386 
01389 #define HAM_DISABLE_VAR_KEYLEN       0x00000040
01390 
01393 #define HAM_IN_MEMORY_DB             0x00000080
01394 
01395 /* reserved: DB_USE_MMAP (not persistent)      0x00000100 */
01396 
01400 #define HAM_DISABLE_MMAP             0x00000200
01401 
01405 #define HAM_CACHE_STRICT             0x00000400
01406 
01410 #define HAM_DISABLE_FREELIST_FLUSH   0x00000800
01411 
01414 #define HAM_LOCK_EXCLUSIVE           0x00001000
01415 
01418 #define HAM_RECORD_NUMBER            0x00002000
01419 
01422 #define HAM_ENABLE_DUPLICATES        0x00004000
01423 
01427 #define HAM_ENABLE_RECOVERY          0x00008000
01428 
01431 #define HAM_AUTO_RECOVERY            0x00010000
01432 
01436 #define HAM_ENABLE_TRANSACTIONS      0x00020000
01437 
01441 #define HAM_CACHE_UNLIMITED          0x00040000
01442 
01443 /* reserved: DB_ENV_IS_PRIVATE (not persistent)      0x00080000 */
01444 
01448 #define HAM_SORT_DUPLICATES          0x00100000
01449 
01450 /* reserved: DB_IS_REMOTE     (not persistent)       0x00200000 */
01451 
01461 HAM_EXPORT ham_status_t HAM_CALLCONV
01462 ham_get_error(ham_db_t *db);
01463 
01476 typedef int HAM_CALLCONV (*ham_prefix_compare_func_t)
01477                                  (ham_db_t *db, 
01478                                   const ham_u8_t *lhs, ham_size_t lhs_length, 
01479                                   ham_size_t lhs_real_length,
01480                                   const ham_u8_t *rhs, ham_size_t rhs_length,
01481                                   ham_size_t rhs_real_length);
01482 
01498 HAM_EXPORT ham_status_t HAM_CALLCONV
01499 ham_set_prefix_compare_func(ham_db_t *db, ham_prefix_compare_func_t foo);
01500 
01509 typedef int HAM_CALLCONV (*ham_compare_func_t)(ham_db_t *db, 
01510                                   const ham_u8_t *lhs, ham_size_t lhs_length, 
01511                                   const ham_u8_t *rhs, ham_size_t rhs_length);
01512 
01535 HAM_EXPORT ham_status_t HAM_CALLCONV
01536 ham_set_compare_func(ham_db_t *db, ham_compare_func_t foo);
01537 
01550 typedef int HAM_CALLCONV (*ham_duplicate_compare_func_t)(ham_db_t *db, 
01551                                   const ham_u8_t *lhs, ham_size_t lhs_length, 
01552                                   const ham_u8_t *rhs, ham_size_t rhs_length);
01553 
01584 HAM_EXPORT ham_status_t HAM_CALLCONV
01585 ham_set_duplicate_compare_func(ham_db_t *db, ham_duplicate_compare_func_t foo);
01586 
01617 HAM_EXPORT ham_status_t HAM_CALLCONV
01618 ham_enable_compression(ham_db_t *db, ham_u32_t level, ham_u32_t flags);
01619 
01724 HAM_EXPORT ham_status_t HAM_CALLCONV
01725 ham_find(ham_db_t *db, ham_txn_t *txn, ham_key_t *key,
01726         ham_record_t *record, ham_u32_t flags);
01727 
01803 HAM_EXPORT ham_status_t HAM_CALLCONV
01804 ham_insert(ham_db_t *db, ham_txn_t *txn, ham_key_t *key,
01805         ham_record_t *record, ham_u32_t flags);
01806 
01818 #define HAM_OVERWRITE                   0x0001
01819 
01821 #define HAM_DUPLICATE                   0x0002
01822 
01824 #define HAM_DUPLICATE_INSERT_BEFORE     0x0004
01825 
01827 #define HAM_DUPLICATE_INSERT_AFTER      0x0008
01828 
01830 #define HAM_DUPLICATE_INSERT_FIRST      0x0010
01831 
01833 #define HAM_DUPLICATE_INSERT_LAST       0x0020
01834 
01836 #define HAM_DIRECT_ACCESS               0x0040
01837 
01840 #define HAM_PARTIAL                     0x0080
01841 
01854 #define HAM_HINT_APPEND               0x00080000
01855 
01868 #define HAM_HINT_PREPEND              0x00100000
01869 
01874 #define HAM_HINTS_MASK                0x00FF0000
01875 
01897 HAM_EXPORT ham_status_t HAM_CALLCONV
01898 ham_erase(ham_db_t *db, ham_txn_t *txn, ham_key_t *key, ham_u32_t flags);
01899 
01913 HAM_EXPORT ham_status_t HAM_CALLCONV
01914 ham_flush(ham_db_t *db, ham_u32_t flags);
01915 
01941 HAM_EXPORT ham_status_t HAM_CALLCONV
01942 ham_get_key_count(ham_db_t *db, ham_txn_t *txn, ham_u32_t flags,
01943             ham_offset_t *keycount);
01944 
01948 #define HAM_FAST_ESTIMATE           0x0001
01949 
01982 HAM_EXPORT ham_status_t HAM_CALLCONV
01983 ham_get_parameters(ham_db_t *db, ham_parameter_t *param);
01984 
01987 #define HAM_PARAM_CACHESIZE          0x00000100
01988 
01991 #define HAM_PARAM_PAGESIZE           0x00000101
01992 
01994 #define HAM_PARAM_KEYSIZE            0x00000102
01995 
01998 #define HAM_PARAM_MAX_ENV_DATABASES  0x00000103
01999 
02003 #define HAM_PARAM_DATA_ACCESS_MODE   0x00000104
02004 
02010 #define HAM_PARAM_GET_FLAGS                0x00000200
02011 
02017 #define HAM_PARAM_GET_FILEMODE            0x00000201
02018 
02026 #define HAM_PARAM_GET_FILENAME            0x00000202
02027 
02035 #define HAM_PARAM_GET_DATABASE_NAME       0x00000203
02036 #define HAM_PARAM_DBNAME                  HAM_PARAM_GET_DATABASE_NAME
02037 
02046 #define HAM_PARAM_GET_KEYS_PER_PAGE        0x00000204
02047 
02051 #define HAM_PARAM_GET_DATA_ACCESS_MODE     0x00000205
02052 #define HAM_PARAM_GET_DAM                  HAM_PARAM_GET_DATA_ACCESS_MODE
02053 
02065 HAM_EXPORT ham_u32_t HAM_CALLCONV
02066 ham_get_flags(ham_db_t *db);
02067 
02081 HAM_EXPORT ham_env_t *HAM_CALLCONV
02082 ham_get_env(ham_db_t *db);
02083 
02108 HAM_EXPORT int HAM_CALLCONV
02109 ham_key_get_approximate_match_type(ham_key_t *key);
02110 
02148 HAM_EXPORT ham_status_t HAM_CALLCONV
02149 ham_close(ham_db_t *db, ham_u32_t flags);
02150 
02152 #define HAM_AUTO_CLEANUP            1
02153 
02155 #define HAM_DONT_CLEAR_LOG          2
02156 
02158 #define HAM_TXN_AUTO_ABORT          4
02159 
02161 #define HAM_TXN_AUTO_COMMIT         8
02162 
02194 HAM_EXPORT ham_status_t HAM_CALLCONV
02195 ham_cursor_create(ham_db_t *db, ham_txn_t *txn, ham_u32_t flags,
02196             ham_cursor_t **cursor);
02197 
02216 HAM_EXPORT ham_status_t HAM_CALLCONV
02217 ham_cursor_clone(ham_cursor_t *src, ham_cursor_t **dest);
02218 
02304 HAM_EXPORT ham_status_t HAM_CALLCONV
02305 ham_cursor_move(ham_cursor_t *cursor, ham_key_t *key,
02306         ham_record_t *record, ham_u32_t flags);
02307 
02309 #define HAM_CURSOR_FIRST            0x0001
02310 
02312 #define HAM_CURSOR_LAST             0x0002
02313 
02315 #define HAM_CURSOR_NEXT             0x0004
02316 
02318 #define HAM_CURSOR_PREVIOUS         0x0008
02319 
02321 #define HAM_SKIP_DUPLICATES         0x0010
02322 
02324 #define HAM_ONLY_DUPLICATES         0x0020
02325 
02346 HAM_EXPORT ham_status_t HAM_CALLCONV
02347 ham_cursor_overwrite(ham_cursor_t *cursor, ham_record_t *record,
02348             ham_u32_t flags);
02349 
02475 HAM_EXPORT ham_status_t HAM_CALLCONV
02476 ham_cursor_find(ham_cursor_t *cursor, ham_key_t *key, ham_u32_t flags);
02477 
02621 HAM_EXPORT ham_status_t HAM_CALLCONV
02622 ham_cursor_find_ex(ham_cursor_t *cursor, ham_key_t *key, 
02623             ham_record_t *record, ham_u32_t flags);
02624 
02631 #define HAM_FIND_EXACT_MATCH        0x4000
02632 
02637 #define HAM_FIND_LT_MATCH           0x1000
02638 
02643 #define HAM_FIND_GT_MATCH           0x2000
02644 
02652 #define HAM_FIND_LEQ_MATCH          (HAM_FIND_LT_MATCH | HAM_FIND_EXACT_MATCH)
02653 
02661 #define HAM_FIND_GEQ_MATCH          (HAM_FIND_GT_MATCH | HAM_FIND_EXACT_MATCH)
02662 
02676 #define HAM_FIND_NEAR_MATCH         (HAM_FIND_LT_MATCH | HAM_FIND_GT_MATCH    \
02677                                         | HAM_FIND_EXACT_MATCH)
02678 
02801 HAM_EXPORT ham_status_t HAM_CALLCONV
02802 ham_cursor_insert(ham_cursor_t *cursor, ham_key_t *key,
02803             ham_record_t *record, ham_u32_t flags);
02804 
02824 HAM_EXPORT ham_status_t HAM_CALLCONV
02825 ham_cursor_erase(ham_cursor_t *cursor, ham_u32_t flags);
02826 
02842 HAM_EXPORT ham_status_t HAM_CALLCONV
02843 ham_cursor_get_duplicate_count(ham_cursor_t *cursor, 
02844         ham_size_t *count, ham_u32_t flags);
02845 
02860 HAM_EXPORT ham_status_t HAM_CALLCONV
02861 ham_cursor_close(ham_cursor_t *cursor);
02862 
02867 #ifdef __cplusplus
02868 } // extern "C"
02869 #endif
02870 
02871 #endif /* HAM_HAMSTERDB_H__ */
Generated by  doxygen 1.6.3