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 
00328 #define HAM_DEBUG_LEVEL_DEBUG       0
00329 
00331 #define HAM_DEBUG_LEVEL_NORMAL      1
00332 
00334 #define HAM_DEBUG_LEVEL_FATAL       3
00335 
00351 HAM_EXPORT void HAM_CALLCONV
00352 ham_set_errhandler(ham_errhandler_fun f);
00353 
00361 HAM_EXPORT const char * HAM_CALLCONV
00362 ham_strerror(ham_status_t status);
00363 
00371 HAM_EXPORT void HAM_CALLCONV
00372 ham_get_version(ham_u32_t *major, ham_u32_t *minor,
00373         ham_u32_t *revision);
00374 
00382 HAM_EXPORT void HAM_CALLCONV
00383 ham_get_license(const char **licensee, const char **product);
00384 
00403 HAM_EXPORT ham_status_t HAM_CALLCONV
00404 ham_env_new(ham_env_t **env);
00405 
00417 HAM_EXPORT ham_status_t HAM_CALLCONV
00418 ham_env_delete(ham_env_t *env);
00419 
00456 HAM_EXPORT ham_status_t HAM_CALLCONV
00457 ham_env_create(ham_env_t *env, const char *filename,
00458         ham_u32_t flags, ham_u32_t mode);
00459 
00557 HAM_EXPORT ham_status_t HAM_CALLCONV
00558 ham_env_create_ex(ham_env_t *env, const char *filename,
00559         ham_u32_t flags, ham_u32_t mode, const ham_parameter_t *param);
00560 
00582 HAM_EXPORT ham_status_t HAM_CALLCONV
00583 ham_env_open(ham_env_t *env, const char *filename, ham_u32_t flags);
00584 
00663 HAM_EXPORT ham_status_t HAM_CALLCONV
00664 ham_env_open_ex(ham_env_t *env, const char *filename,
00665         ham_u32_t flags, const ham_parameter_t *param);
00666 
00697 HAM_EXPORT ham_status_t HAM_CALLCONV
00698 ham_env_get_parameters(ham_env_t *env, ham_parameter_t *param);
00699 
00763 HAM_EXPORT ham_status_t HAM_CALLCONV
00764 ham_env_create_db(ham_env_t *env, ham_db_t *db,
00765         ham_u16_t name, ham_u32_t flags, const ham_parameter_t *params);
00766 
00812 HAM_EXPORT ham_status_t HAM_CALLCONV
00813 ham_env_open_db(ham_env_t *env, ham_db_t *db,
00814         ham_u16_t name, ham_u32_t flags, const ham_parameter_t *params);
00815 
00840 HAM_EXPORT ham_status_t HAM_CALLCONV
00841 ham_env_rename_db(ham_env_t *env, ham_u16_t oldname, 
00842                 ham_u16_t newname, ham_u32_t flags);
00843 
00862 HAM_EXPORT ham_status_t HAM_CALLCONV
00863 ham_env_erase_db(ham_env_t *env, ham_u16_t name, ham_u32_t flags);
00864 
00880 HAM_EXPORT ham_status_t HAM_CALLCONV
00881 ham_env_flush(ham_env_t *env, ham_u32_t flags);
00882 
00917 HAM_EXPORT ham_status_t HAM_CALLCONV
00918 ham_env_enable_encryption(ham_env_t *env, ham_u8_t key[16], ham_u32_t flags);
00919 
00942 HAM_EXPORT ham_status_t HAM_CALLCONV
00943 ham_env_get_database_names(ham_env_t *env, ham_u16_t *names, ham_size_t *count);
00944 
00982 HAM_EXPORT ham_status_t HAM_CALLCONV
00983 ham_env_close(ham_env_t *env, ham_u32_t flags);
00984 
01001 struct ham_txn_t;
01002 typedef struct ham_txn_t ham_txn_t;
01003 
01027 HAM_EXPORT ham_status_t
01028 ham_txn_begin(ham_txn_t **txn, ham_db_t *db, ham_u32_t flags);
01029 
01031 #define HAM_TXN_READ_ONLY                                       1
01032 
01050 HAM_EXPORT ham_status_t
01051 ham_txn_commit(ham_txn_t *txn, ham_u32_t flags);
01052 
01054 #define HAM_TXN_FORCE_WRITE                                    1
01055 
01073 HAM_EXPORT ham_status_t
01074 ham_txn_abort(ham_txn_t *txn, ham_u32_t flags);
01075 
01076 /* note: ham_txn_abort flag 0x0001 is reserved for internal use: 
01077  * DO_NOT_NUKE_PAGE_STATS */
01078 
01097 HAM_EXPORT ham_status_t HAM_CALLCONV
01098 ham_new(ham_db_t **db);
01099 
01111 HAM_EXPORT ham_status_t HAM_CALLCONV
01112 ham_delete(ham_db_t *db);
01113 
01139 HAM_EXPORT ham_status_t HAM_CALLCONV
01140 ham_create(ham_db_t *db, const char *filename,
01141         ham_u32_t flags, ham_u32_t mode);
01142 
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 
01277 HAM_EXPORT ham_status_t HAM_CALLCONV
01278 ham_open(ham_db_t *db, const char *filename, ham_u32_t flags);
01279 
01365 HAM_EXPORT ham_status_t HAM_CALLCONV
01366 ham_open_ex(ham_db_t *db, const char *filename,
01367         ham_u32_t flags, const ham_parameter_t *param);
01368 
01372 #define HAM_WRITE_THROUGH            0x00000001
01373 
01374 /* unused                            0x00000002 */
01375 
01378 #define HAM_READ_ONLY                0x00000004
01379 
01380 /* unused                            0x00000008 */
01381 
01384 #define HAM_USE_BTREE                0x00000010
01385 
01386 /* reserved                          0x00000020 */
01387 
01390 #define HAM_DISABLE_VAR_KEYLEN       0x00000040
01391 
01394 #define HAM_IN_MEMORY_DB             0x00000080
01395 
01396 /* reserved: DB_USE_MMAP (not persistent)      0x00000100 */
01397 
01401 #define HAM_DISABLE_MMAP             0x00000200
01402 
01406 #define HAM_CACHE_STRICT             0x00000400
01407 
01411 #define HAM_DISABLE_FREELIST_FLUSH   0x00000800
01412 
01415 #define HAM_LOCK_EXCLUSIVE           0x00001000
01416 
01419 #define HAM_RECORD_NUMBER            0x00002000
01420 
01423 #define HAM_ENABLE_DUPLICATES        0x00004000
01424 
01428 #define HAM_ENABLE_RECOVERY          0x00008000
01429 
01432 #define HAM_AUTO_RECOVERY            0x00010000
01433 
01437 #define HAM_ENABLE_TRANSACTIONS      0x00020000
01438 
01442 #define HAM_CACHE_UNLIMITED          0x00040000
01443 
01444 /* reserved: DB_ENV_IS_PRIVATE (not persistent)      0x00080000 */
01445 
01449 #define HAM_SORT_DUPLICATES          0x00100000
01450 
01460 HAM_EXPORT ham_status_t HAM_CALLCONV
01461 ham_get_error(ham_db_t *db);
01462 
01475 typedef int HAM_CALLCONV (*ham_prefix_compare_func_t)
01476                                  (ham_db_t *db, 
01477                                   const ham_u8_t *lhs, ham_size_t lhs_length, 
01478                                   ham_size_t lhs_real_length,
01479                                   const ham_u8_t *rhs, ham_size_t rhs_length,
01480                                   ham_size_t rhs_real_length);
01481 
01497 HAM_EXPORT ham_status_t HAM_CALLCONV
01498 ham_set_prefix_compare_func(ham_db_t *db, ham_prefix_compare_func_t foo);
01499 
01508 typedef int HAM_CALLCONV (*ham_compare_func_t)(ham_db_t *db, 
01509                                   const ham_u8_t *lhs, ham_size_t lhs_length, 
01510                                   const ham_u8_t *rhs, ham_size_t rhs_length);
01511 
01534 HAM_EXPORT ham_status_t HAM_CALLCONV
01535 ham_set_compare_func(ham_db_t *db, ham_compare_func_t foo);
01536 
01549 typedef int HAM_CALLCONV (*ham_duplicate_compare_func_t)(ham_db_t *db, 
01550                                   const ham_u8_t *lhs, ham_size_t lhs_length, 
01551                                   const ham_u8_t *rhs, ham_size_t rhs_length);
01552 
01583 HAM_EXPORT ham_status_t HAM_CALLCONV
01584 ham_set_duplicate_compare_func(ham_db_t *db, ham_duplicate_compare_func_t foo);
01585 
01616 HAM_EXPORT ham_status_t HAM_CALLCONV
01617 ham_enable_compression(ham_db_t *db, ham_u32_t level, ham_u32_t flags);
01618 
01723 HAM_EXPORT ham_status_t HAM_CALLCONV
01724 ham_find(ham_db_t *db, ham_txn_t *txn, ham_key_t *key,
01725         ham_record_t *record, ham_u32_t flags);
01726 
01802 HAM_EXPORT ham_status_t HAM_CALLCONV
01803 ham_insert(ham_db_t *db, ham_txn_t *txn, ham_key_t *key,
01804         ham_record_t *record, ham_u32_t flags);
01805 
01817 #define HAM_OVERWRITE                   0x0001
01818 
01820 #define HAM_DUPLICATE                   0x0002
01821 
01823 #define HAM_DUPLICATE_INSERT_BEFORE     0x0004
01824 
01826 #define HAM_DUPLICATE_INSERT_AFTER      0x0008
01827 
01829 #define HAM_DUPLICATE_INSERT_FIRST      0x0010
01830 
01832 #define HAM_DUPLICATE_INSERT_LAST       0x0020
01833 
01835 #define HAM_DIRECT_ACCESS               0x0040
01836 
01839 #define HAM_PARTIAL                     0x0080
01840 
01853 #define HAM_HINT_APPEND               0x00080000
01854 
01867 #define HAM_HINT_PREPEND              0x00100000
01868 
01873 #define HAM_HINTS_MASK                0x00FF0000
01874 
01896 HAM_EXPORT ham_status_t HAM_CALLCONV
01897 ham_erase(ham_db_t *db, ham_txn_t *txn, ham_key_t *key, ham_u32_t flags);
01898 
01915 HAM_EXPORT ham_status_t HAM_CALLCONV
01916 ham_flush(ham_db_t *db, ham_u32_t flags);
01917 
01943 HAM_EXPORT ham_status_t HAM_CALLCONV
01944 ham_get_key_count(ham_db_t *db, ham_txn_t *txn, ham_u32_t flags,
01945             ham_offset_t *keycount);
01946 
01950 #define HAM_FAST_ESTIMATE           0x0001
01951 
01987 HAM_EXPORT ham_status_t HAM_CALLCONV
01988 ham_get_parameters(ham_db_t *db, ham_parameter_t *param);
01989 
01992 #define HAM_PARAM_CACHESIZE          0x00000100
01993 
01996 #define HAM_PARAM_PAGESIZE           0x00000101
01997 
01999 #define HAM_PARAM_KEYSIZE            0x00000102
02000 
02003 #define HAM_PARAM_MAX_ENV_DATABASES  0x00000103
02004 
02008 #define HAM_PARAM_DATA_ACCESS_MODE   0x00000104
02009 
02015 #define HAM_PARAM_GET_FLAGS                0x00000200
02016 
02022 #define HAM_PARAM_GET_FILEMODE            0x00000201
02023 
02031 #define HAM_PARAM_GET_FILENAME            0x00000202
02032 
02040 #define HAM_PARAM_GET_DATABASE_NAME       0x00000203
02041 #define HAM_PARAM_DBNAME                  HAM_PARAM_GET_DATABASE_NAME
02042 
02051 #define HAM_PARAM_GET_KEYS_PER_PAGE        0x00000204
02052 
02056 #define HAM_PARAM_GET_DATA_ACCESS_MODE     0x00000205
02057 #define HAM_PARAM_GET_DAM                  HAM_PARAM_GET_DATA_ACCESS_MODE
02058 
02074 #define HAM_PARAM_GET_STATISTICS        0x00000206
02075 
02087 HAM_EXPORT ham_u32_t HAM_CALLCONV
02088 ham_get_flags(ham_db_t *db);
02089 
02103 HAM_EXPORT ham_env_t *HAM_CALLCONV
02104 ham_get_env(ham_db_t *db);
02105 
02130 HAM_EXPORT int HAM_CALLCONV
02131 ham_key_get_approximate_match_type(ham_key_t *key);
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 
02216 HAM_EXPORT ham_status_t HAM_CALLCONV
02217 ham_cursor_create(ham_db_t *db, ham_txn_t *txn, ham_u32_t flags,
02218             ham_cursor_t **cursor);
02219 
02238 HAM_EXPORT ham_status_t HAM_CALLCONV
02239 ham_cursor_clone(ham_cursor_t *src, ham_cursor_t **dest);
02240 
02326 HAM_EXPORT ham_status_t HAM_CALLCONV
02327 ham_cursor_move(ham_cursor_t *cursor, ham_key_t *key,
02328         ham_record_t *record, ham_u32_t flags);
02329 
02331 #define HAM_CURSOR_FIRST            0x0001
02332 
02334 #define HAM_CURSOR_LAST             0x0002
02335 
02337 #define HAM_CURSOR_NEXT             0x0004
02338 
02340 #define HAM_CURSOR_PREVIOUS         0x0008
02341 
02343 #define HAM_SKIP_DUPLICATES         0x0010
02344 
02346 #define HAM_ONLY_DUPLICATES         0x0020
02347 
02368 HAM_EXPORT ham_status_t HAM_CALLCONV
02369 ham_cursor_overwrite(ham_cursor_t *cursor, ham_record_t *record,
02370             ham_u32_t flags);
02371 
02497 HAM_EXPORT ham_status_t HAM_CALLCONV
02498 ham_cursor_find(ham_cursor_t *cursor, ham_key_t *key, ham_u32_t flags);
02499 
02643 HAM_EXPORT ham_status_t HAM_CALLCONV
02644 ham_cursor_find_ex(ham_cursor_t *cursor, ham_key_t *key, 
02645             ham_record_t *record, ham_u32_t flags);
02646 
02653 #define HAM_FIND_EXACT_MATCH        0x4000
02654 
02659 #define HAM_FIND_LT_MATCH           0x1000
02660 
02665 #define HAM_FIND_GT_MATCH           0x2000
02666 
02674 #define HAM_FIND_LEQ_MATCH          (HAM_FIND_LT_MATCH | HAM_FIND_EXACT_MATCH)
02675 
02683 #define HAM_FIND_GEQ_MATCH          (HAM_FIND_GT_MATCH | HAM_FIND_EXACT_MATCH)
02684 
02698 #define HAM_FIND_NEAR_MATCH         (HAM_FIND_LT_MATCH | HAM_FIND_GT_MATCH    \
02699                                         | HAM_FIND_EXACT_MATCH)
02700 
02823 HAM_EXPORT ham_status_t HAM_CALLCONV
02824 ham_cursor_insert(ham_cursor_t *cursor, ham_key_t *key,
02825             ham_record_t *record, ham_u32_t flags);
02826 
02846 HAM_EXPORT ham_status_t HAM_CALLCONV
02847 ham_cursor_erase(ham_cursor_t *cursor, ham_u32_t flags);
02848 
02864 HAM_EXPORT ham_status_t HAM_CALLCONV
02865 ham_cursor_get_duplicate_count(ham_cursor_t *cursor, 
02866         ham_size_t *count, ham_u32_t flags);
02867 
02882 HAM_EXPORT ham_status_t HAM_CALLCONV
02883 ham_cursor_close(ham_cursor_t *cursor);
02884 
02889 #ifdef __cplusplus
02890 } // extern "C"
02891 #endif
02892 
02893 #endif /* HAM_HAMSTERDB_H__ */

Generated on Wed Apr 14 20:37:55 2010 for hamsterdb Embedded Database by  doxygen 1.6.1