hamsterdb.h

Go to the documentation of this file.

/*
 * Copyright (C) 2005-2013 Christoph Rupp (chris@crupp.de).
 *
 * This program is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License as published by the
 * Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * See files COPYING.* for License information.
 */

#ifndef HAM_HAMSTERDB_H__
#define HAM_HAMSTERDB_H__

#include <ham/types.h>

#ifdef __cplusplus
extern "C" {
#endif

#define HAM_API_REVISION        2

struct ham_db_t;
typedef struct ham_db_t ham_db_t;

struct ham_env_t;
typedef struct ham_env_t ham_env_t;

struct ham_cursor_t;
typedef struct ham_cursor_t ham_cursor_t;

typedef struct {
  ham_u32_t size;

  void *data;

  ham_u32_t flags;

  ham_u32_t partial_offset;

  ham_u32_t partial_size;

  ham_u32_t _intflags;

  ham_u64_t _rid;

} ham_record_t;

#define HAM_RECORD_USER_ALLOC   1

typedef struct {
  ham_u16_t size;

  void *data;

  ham_u32_t flags;

  ham_u32_t _flags;

} ham_key_t;

#define HAM_KEY_USER_ALLOC    1

typedef struct {
  ham_u32_t name;

  ham_u64_t value;

} ham_parameter_t;


#define HAM_SUCCESS                     (  0)

#define HAM_INV_KEYSIZE                 ( -3)

#define HAM_INV_PAGESIZE                ( -4)

#define HAM_OUT_OF_MEMORY               ( -6)

#define HAM_INV_PARAMETER               ( -8)

#define HAM_INV_FILE_HEADER             ( -9)

#define HAM_INV_FILE_VERSION            (-10)

#define HAM_KEY_NOT_FOUND               (-11)

#define HAM_DUPLICATE_KEY               (-12)

#define HAM_INTEGRITY_VIOLATED          (-13)

#define HAM_INTERNAL_ERROR              (-14)

#define HAM_WRITE_PROTECTED             (-15)

#define HAM_BLOB_NOT_FOUND              (-16)

#define HAM_PREFIX_REQUEST_FULLKEY      (-17)

#define HAM_IO_ERROR                    (-18)

#define HAM_CACHE_FULL                  (-19)

#define HAM_NOT_IMPLEMENTED             (-20)

#define HAM_FILE_NOT_FOUND              (-21)

#define HAM_WOULD_BLOCK                 (-22)

#define HAM_NOT_READY                   (-23)

#define HAM_LIMITS_REACHED              (-24)

#define HAM_ALREADY_INITIALIZED         (-27)

#define HAM_NEED_RECOVERY               (-28)

#define HAM_CURSOR_STILL_OPEN           (-29)

#define HAM_FILTER_NOT_FOUND            (-30)

#define HAM_TXN_CONFLICT                (-31)
/* internal use: key was erased in a Transaction */
#define HAM_KEY_ERASED_IN_TXN           (-32)

#define HAM_TXN_STILL_OPEN              (-33)

#define HAM_CURSOR_IS_NIL               (-100)

#define HAM_DATABASE_NOT_FOUND          (-200)

#define HAM_DATABASE_ALREADY_EXISTS     (-201)

#define HAM_DATABASE_ALREADY_OPEN       (-202)

#define HAM_ENVIRONMENT_ALREADY_OPEN    (-203)

#define HAM_LOG_INV_FILE_HEADER         (-300)

#define HAM_NETWORK_ERROR               (-400)

typedef void HAM_CALLCONV (*ham_errhandler_fun)(int level, const char *message);

#define HAM_DEBUG_LEVEL_DEBUG     0

#define HAM_DEBUG_LEVEL_NORMAL    1

#define HAM_DEBUG_LEVEL_FATAL     3

HAM_EXPORT void HAM_CALLCONV
ham_set_errhandler(ham_errhandler_fun f);

HAM_EXPORT const char * HAM_CALLCONV
ham_strerror(ham_status_t status);

HAM_EXPORT void HAM_CALLCONV
ham_get_version(ham_u32_t *major, ham_u32_t *minor,
            ham_u32_t *revision);

HAM_EXPORT void HAM_CALLCONV
ham_get_license(const char **licensee, const char **product);

HAM_EXPORT ham_status_t HAM_CALLCONV
ham_env_create(ham_env_t **env, const char *filename,
            ham_u32_t flags, ham_u32_t mode, const ham_parameter_t *param);

HAM_EXPORT ham_status_t HAM_CALLCONV
ham_env_open(ham_env_t **env, const char *filename,
            ham_u32_t flags, const ham_parameter_t *param);

HAM_EXPORT ham_status_t HAM_CALLCONV
ham_env_get_parameters(ham_env_t *env, ham_parameter_t *param);

HAM_EXPORT ham_status_t HAM_CALLCONV
ham_env_create_db(ham_env_t *env, ham_db_t **db,
            ham_u16_t name, ham_u32_t flags, const ham_parameter_t *params);

HAM_EXPORT ham_status_t HAM_CALLCONV
ham_env_open_db(ham_env_t *env, ham_db_t **db,
            ham_u16_t name, ham_u32_t flags, const ham_parameter_t *params);

HAM_EXPORT ham_status_t HAM_CALLCONV
ham_env_rename_db(ham_env_t *env, ham_u16_t oldname,
            ham_u16_t newname, ham_u32_t flags);

HAM_EXPORT ham_status_t HAM_CALLCONV
ham_env_erase_db(ham_env_t *env, ham_u16_t name, ham_u32_t flags);

HAM_EXPORT ham_status_t HAM_CALLCONV
ham_env_flush(ham_env_t *env, ham_u32_t flags);

/* internal use only - don't lock mutex */
#define HAM_DONT_LOCK        0xf0000000

HAM_EXPORT ham_status_t HAM_CALLCONV
ham_env_get_database_names(ham_env_t *env, ham_u16_t *names,
            ham_size_t *count);

HAM_EXPORT ham_status_t HAM_CALLCONV
ham_env_close(ham_env_t *env, ham_u32_t flags);

struct ham_txn_t;
typedef struct ham_txn_t ham_txn_t;

HAM_EXPORT ham_status_t
ham_txn_begin(ham_txn_t **txn, ham_env_t *env, const char *name,
            void *reserved, ham_u32_t flags);

#define HAM_TXN_READ_ONLY                     1

/* Internal flag for @ref ham_txn_begin */
#define HAM_TXN_TEMPORARY                     2

HAM_EXPORT const char *
ham_txn_get_name(ham_txn_t *txn);

HAM_EXPORT ham_status_t
ham_txn_commit(ham_txn_t *txn, ham_u32_t flags);

HAM_EXPORT ham_status_t
ham_txn_abort(ham_txn_t *txn, ham_u32_t flags);

/* note: ham_txn_abort flag 0x0001 is reserved for internal use:
 * DO_NOT_NUKE_PAGE_STATS */

#define HAM_ENABLE_FSYNC                            0x00000001

/* unused                                           0x00000002 */

#define HAM_READ_ONLY                               0x00000004

/* unused                                           0x00000008 */

/* unused                                           0x00000010 */

/* reserved                                         0x00000020 */

#define HAM_DISABLE_VAR_KEYLEN                      0x00000040

#define HAM_IN_MEMORY                               0x00000080

/* reserved: DB_USE_MMAP (not persistent)           0x00000100 */

#define HAM_DISABLE_MMAP                            0x00000200

#define HAM_CACHE_STRICT                            0x00000400

#define HAM_RECORD_NUMBER                           0x00002000

#define HAM_ENABLE_DUPLICATES                       0x00004000

#define HAM_ENABLE_RECOVERY                         0x00008000

#define HAM_AUTO_RECOVERY                           0x00010000

#define HAM_ENABLE_TRANSACTIONS                     0x00020000

#define HAM_CACHE_UNLIMITED                         0x00040000

#define HAM_ENABLE_EXTENDED_KEYS                    0x00080000

/* reserved: DB_IS_REMOTE   (not persistent)        0x00200000 */

/* reserved: DB_DISABLE_AUTO_FLUSH (not persistent) 0x00400000 */

HAM_EXPORT ham_status_t HAM_CALLCONV
ham_db_get_error(ham_db_t *db);

typedef int HAM_CALLCONV (*ham_prefix_compare_func_t)
                 (ham_db_t *db,
                  const ham_u8_t *lhs, ham_size_t lhs_length,
                  ham_size_t lhs_real_length,
                  const ham_u8_t *rhs, ham_size_t rhs_length,
                  ham_size_t rhs_real_length);

HAM_EXPORT ham_status_t HAM_CALLCONV
ham_db_set_prefix_compare_func(ham_db_t *db, ham_prefix_compare_func_t foo);

typedef int HAM_CALLCONV (*ham_compare_func_t)(ham_db_t *db,
                  const ham_u8_t *lhs, ham_size_t lhs_length,
                  const ham_u8_t *rhs, ham_size_t rhs_length);

HAM_EXPORT ham_status_t HAM_CALLCONV
ham_db_set_compare_func(ham_db_t *db, ham_compare_func_t foo);

HAM_EXPORT ham_status_t HAM_CALLCONV
ham_db_find(ham_db_t *db, ham_txn_t *txn, ham_key_t *key,
            ham_record_t *record, ham_u32_t flags);

HAM_EXPORT ham_status_t HAM_CALLCONV
ham_db_insert(ham_db_t *db, ham_txn_t *txn, ham_key_t *key,
            ham_record_t *record, ham_u32_t flags);

#define HAM_OVERWRITE                   0x0001

#define HAM_DUPLICATE                   0x0002

#define HAM_DUPLICATE_INSERT_BEFORE     0x0004

#define HAM_DUPLICATE_INSERT_AFTER      0x0008

#define HAM_DUPLICATE_INSERT_FIRST      0x0010

#define HAM_DUPLICATE_INSERT_LAST       0x0020

#define HAM_DIRECT_ACCESS               0x0040

#define HAM_PARTIAL                     0x0080

#define HAM_HINT_APPEND                 0x00080000

#define HAM_HINT_PREPEND                0x00100000

#define HAM_HINTS_MASK                  0x001F0000

HAM_EXPORT ham_status_t HAM_CALLCONV
ham_db_erase(ham_db_t *db, ham_txn_t *txn, ham_key_t *key, ham_u32_t flags);

/* internal flag for ham_db_erase() - do not use */
#define HAM_ERASE_ALL_DUPLICATES                1

HAM_EXPORT ham_status_t HAM_CALLCONV
ham_db_get_key_count(ham_db_t *db, ham_txn_t *txn, ham_u32_t flags,
            ham_u64_t *keycount);

HAM_EXPORT ham_status_t HAM_CALLCONV
ham_db_get_parameters(ham_db_t *db, ham_parameter_t *param);

#define HAM_PARAM_CACHESIZE             0x00000100

#define HAM_PARAM_PAGESIZE              0x00000101

#define HAM_PARAM_KEYSIZE               0x00000102

#define HAM_PARAM_MAX_DATABASES         0x00000103

#define HAM_PARAM_LOG_DIRECTORY         0x00000105

#define HAM_PARAM_FLAGS                 0x00000200

#define HAM_PARAM_FILEMODE              0x00000201

#define HAM_PARAM_FILENAME              0x00000202

#define HAM_PARAM_DATABASE_NAME         0x00000203

#define HAM_PARAM_MAX_KEYS_PER_PAGE     0x00000204

HAM_EXPORT ham_env_t *HAM_CALLCONV
ham_db_get_env(ham_db_t *db);

HAM_EXPORT int HAM_CALLCONV
ham_key_get_approximate_match_type(ham_key_t *key);

HAM_EXPORT ham_status_t HAM_CALLCONV
ham_db_close(ham_db_t *db, ham_u32_t flags);

#define HAM_AUTO_CLEANUP                1

#define HAM_DONT_CLEAR_LOG              2

#define HAM_TXN_AUTO_ABORT              4

#define HAM_TXN_AUTO_COMMIT             8

HAM_EXPORT ham_status_t HAM_CALLCONV
ham_cursor_create(ham_cursor_t **cursor, ham_db_t *db, ham_txn_t *txn,
            ham_u32_t flags);

HAM_EXPORT ham_status_t HAM_CALLCONV
ham_cursor_clone(ham_cursor_t *src, ham_cursor_t **dest);

HAM_EXPORT ham_status_t HAM_CALLCONV
ham_cursor_move(ham_cursor_t *cursor, ham_key_t *key,
            ham_record_t *record, ham_u32_t flags);

#define HAM_CURSOR_FIRST                0x0001

#define HAM_CURSOR_LAST                 0x0002

#define HAM_CURSOR_NEXT                 0x0004

#define HAM_CURSOR_PREVIOUS             0x0008

#define HAM_SKIP_DUPLICATES             0x0010

#define HAM_ONLY_DUPLICATES             0x0020

HAM_EXPORT ham_status_t HAM_CALLCONV
ham_cursor_overwrite(ham_cursor_t *cursor, ham_record_t *record,
            ham_u32_t flags);

HAM_EXPORT ham_status_t HAM_CALLCONV
ham_cursor_find(ham_cursor_t *cursor, ham_key_t *key,
            ham_record_t *record, ham_u32_t flags);

#define HAM_FIND_EXACT_MATCH            0x4000

#define HAM_FIND_LT_MATCH               0x1000

#define HAM_FIND_GT_MATCH               0x2000

#define HAM_FIND_LEQ_MATCH      (HAM_FIND_LT_MATCH | HAM_FIND_EXACT_MATCH)

#define HAM_FIND_GEQ_MATCH      (HAM_FIND_GT_MATCH | HAM_FIND_EXACT_MATCH)

#define HAM_FIND_NEAR_MATCH     (HAM_FIND_LT_MATCH | HAM_FIND_GT_MATCH  \
                                  | HAM_FIND_EXACT_MATCH)

HAM_EXPORT ham_status_t HAM_CALLCONV
ham_cursor_insert(ham_cursor_t *cursor, ham_key_t *key,
            ham_record_t *record, ham_u32_t flags);

HAM_EXPORT ham_status_t HAM_CALLCONV
ham_cursor_erase(ham_cursor_t *cursor, ham_u32_t flags);

HAM_EXPORT ham_status_t HAM_CALLCONV
ham_cursor_get_duplicate_count(ham_cursor_t *cursor,
            ham_size_t *count, ham_u32_t flags);

HAM_EXPORT ham_status_t HAM_CALLCONV
ham_cursor_get_record_size(ham_cursor_t *cursor, ham_u64_t *size);

HAM_EXPORT ham_status_t HAM_CALLCONV
ham_cursor_close(ham_cursor_t *cursor);

#ifdef __cplusplus
} // extern "C"
#endif

#endif /* HAM_HAMSTERDB_H__ */