hamsterdb Embedded Database 1.1.14
Data Structures | Modules | Defines | Typedefs | Functions

hamsterdb Enhanced API

Data Structures

struct  ham_file_filter_t
struct  ham_record_filter_t

Modules

 Special Database Names

Defines

#define HAM_PARAM_GET_STATISTICS   0x00000206

Typedefs

typedef struct ham_file_filter_t ham_file_filter_t
typedef ham_status_t(* ham_file_filter_before_write_cb_t )(ham_env_t *env, ham_file_filter_t *filter, ham_u8_t *file_data, ham_size_t file_size)
typedef ham_status_t(* ham_file_filter_after_read_cb_t )(ham_env_t *env, ham_file_filter_t *filter, ham_u8_t *file_data, ham_size_t file_size)
typedef void(* ham_file_filter_close_cb_t )(ham_env_t *env, ham_file_filter_t *filter)
typedef struct ham_record_filter_t ham_record_filter_t
typedef ham_status_t(* ham_record_filter_before_insert_cb_t )(ham_db_t *db, ham_record_filter_t *filter, ham_record_t *record)
typedef ham_status_t(* ham_record_filter_after_read_cb_t )(ham_db_t *db, ham_record_filter_t *filter, ham_record_t *record)
typedef void(* ham_record_filter_close_cb_t )(ham_db_t *db, ham_record_filter_t *filter)
typedef struct ham_device_t ham_device_t
typedef struct mem_allocator_t mem_allocator_t

Functions

HAM_EXPORT ham_status_t
HAM_CALLCONV 
ham_check_integrity (ham_db_t *db, ham_txn_t *txn)
HAM_EXPORT ham_status_t
HAM_CALLCONV 
ham_calc_maxkeys_per_page (ham_db_t *db, ham_size_t *keycount, ham_u16_t keysize)
HAM_EXPORT void HAM_CALLCONV ham_set_context_data (ham_db_t *db, void *data)
HAM_EXPORT void *HAM_CALLCONV ham_get_context_data (ham_db_t *db)
HAM_EXPORT ham_status_t
HAM_CALLCONV 
ham_env_add_file_filter (ham_env_t *env, ham_file_filter_t *filter)
HAM_EXPORT ham_status_t
HAM_CALLCONV 
ham_env_remove_file_filter (ham_env_t *env, ham_file_filter_t *filter)
HAM_EXPORT ham_status_t
HAM_CALLCONV 
ham_add_record_filter (ham_db_t *db, ham_record_filter_t *filter)
HAM_EXPORT ham_status_t
HAM_CALLCONV 
ham_remove_record_filter (ham_db_t *db, ham_record_filter_t *filter)
HAM_EXPORT ham_status_t
HAM_CALLCONV 
ham_env_set_device (ham_env_t *env, ham_device_t *device)
HAM_EXPORT ham_device_t
*HAM_CALLCONV 
ham_env_get_device (ham_env_t *env)
HAM_EXPORT ham_db_t *HAM_CALLCONV ham_cursor_get_database (ham_cursor_t *cursor)
HAM_EXPORT ham_status_t
HAM_CALLCONV 
ham_env_set_allocator (ham_env_t *env, mem_allocator_t *alloc)

Define Documentation

#define HAM_PARAM_GET_STATISTICS   0x00000206

Retrieve a ham_statistics_t structure with the current statistics.

Warning:
Please, heed the warnings and notes listed in the ham_statistics_t documentation section and follow the advice given there to the letter. Not adhering to these adminishions introduces the risk of hamsterdb becoming unstable and exhibiting unreliable and downright faulty behaviour over time. This includes, but is not limited to, core dumps or comparable system crashes.
See also:
ham_statistics_t
ham_get_parameters
ham_env_get_parameters

Definition at line 82 of file hamsterdb_int.h.


Typedef Documentation

typedef struct ham_device_t ham_device_t

Definition at line 353 of file hamsterdb_int.h.

A callback function for a file-level filter; called immediately after the data is read from disk

Definition at line 160 of file hamsterdb_int.h.

A callback function for a file-level filter; called before the data is written to disk

Definition at line 153 of file hamsterdb_int.h.

typedef void(* ham_file_filter_close_cb_t)(ham_env_t *env, ham_file_filter_t *filter)

A callback function for a file-level filter; called immediately before the Environment is closed. Can be used to avoid memory leaks.

Definition at line 167 of file hamsterdb_int.h.

Definition at line 147 of file hamsterdb_int.h.

A callback function for a record-level filter; called immediately after the record is read from disk, and before it is returned to the user.

Definition at line 252 of file hamsterdb_int.h.

A callback function for a record-level filter; called before the record is inserted

Definition at line 245 of file hamsterdb_int.h.

A callback function for a record-level filter; called immediately before the Database is closed. Can be used to avoid memory leaks.

Definition at line 259 of file hamsterdb_int.h.

Definition at line 239 of file hamsterdb_int.h.

Definition at line 397 of file hamsterdb_int.h.


Function Documentation

HAM_EXPORT ham_status_t HAM_CALLCONV ham_add_record_filter ( ham_db_t db,
ham_record_filter_t filter 
)

A function to install a record-level filter.

Record-level filters are usually installed immediately after the Database is created with ham_create[_ex] or opened with ham_open[_ex].

Parameters:
dbA valid Database handle
filterA pointer to a ham_record_filter_t structure
Returns:
HAM_SUCCESS upon success
HAM_INV_PARAMETER if db or filter is NULL
HAM_EXPORT ham_status_t HAM_CALLCONV ham_calc_maxkeys_per_page ( ham_db_t db,
ham_size_t keycount,
ham_u16_t  keysize 
)

Estimates the number of keys stored per page in the Database

Parameters:
dbA valid Database handle
keycountA reference to a variable which will receive the calculated key count per page
keysizeThe size of the key
Returns:
HAM_SUCCESS upon success
HAM_INV_PARAMETER if db or keycount is NULL
HAM_INV_KEYSIZE if the keycount turns out to be huge (i.e. larger than 65535); in this case keycount still contains a valid value, but this error indicates this keysize won't be usable with the given Database.
HAM_EXPORT ham_status_t HAM_CALLCONV ham_check_integrity ( ham_db_t db,
ham_txn_t txn 
)

Verifies the integrity of the Database

This function is only interesting if you want to debug hamsterdb.

Parameters:
dbA valid Database handle
txnA Transaction handle, or NULL
Returns:
HAM_SUCCESS upon success
HAM_INTEGRITY_VIOLATED if the Database is broken
HAM_NOT_IMPLEMENTED if hamsterdb was built without internal functions.
HAM_EXPORT ham_db_t* HAM_CALLCONV ham_cursor_get_database ( ham_cursor_t cursor)

Retrieves the Database handle of a Cursor

Parameters:
cursorA valid Cursor handle
Returns:
The Database handle of cursor
HAM_EXPORT ham_status_t HAM_CALLCONV ham_env_add_file_filter ( ham_env_t env,
ham_file_filter_t filter 
)

A function to install a file-level filter.

File-level filters are usually installed immediately after the Environment is created with ham_env_create[_ex] or opened with ham_env_open[_ex].

Parameters:
envA valid Environment handle
filterA pointer to a ham_file_filter_t structure
Returns:
HAM_SUCCESS upon success
HAM_INV_PARAMETER if env or filter is NULL
HAM_EXPORT ham_device_t* HAM_CALLCONV ham_env_get_device ( ham_env_t env)

Retrieves the current device object

Custom device objects can be used to overwrite the functions which open, create, read, write etc. to/from the file.

The device structure is defined in src/device.h. The default device objects (for file-based access and for in-memory access) are implemented in src/device.c.

Parameters:
envA valid Environment handle
Returns:
A pointer to a ham_device_t structure, or NULL if the device was not yet initialized
HAM_EXPORT ham_status_t HAM_CALLCONV ham_env_remove_file_filter ( ham_env_t env,
ham_file_filter_t filter 
)

A function to remove a file-level filter.

This function is usually not necessary - the lifetime of a file-filter usually starts before the first Database operation, and ends when the Environment is closed. It is not recommended to use this function.

Parameters:
envA valid Environment handle
filterA pointer to a ham_file_filter_t structure
Returns:
HAM_SUCCESS upon success
HAM_INV_PARAMETER if env or filter is NULL
HAM_FILTER_NOT_FOUND if filter was not registered
HAM_EXPORT ham_status_t HAM_CALLCONV ham_env_set_allocator ( ham_env_t env,
mem_allocator_t alloc 
)
HAM_EXPORT ham_status_t HAM_CALLCONV ham_env_set_device ( ham_env_t env,
ham_device_t device 
)
HAM_EXPORT void* HAM_CALLCONV ham_get_context_data ( ham_db_t db)

Retrieves a user-provided context pointer

This function retrieves a user-provided context pointer. This can be any arbitrary pointer which was previously stored with ham_set_context_data.

Parameters:
dbA valid Database handle
Returns:
The pointer to the context data
HAM_EXPORT ham_status_t HAM_CALLCONV ham_remove_record_filter ( ham_db_t db,
ham_record_filter_t filter 
)

A function to remove a record-level filter.

This function is usually not necessary - the lifetime of a record-filter usually starts before the first Database operation, and ends when the Database is closed. It is not recommended to use this function.

Parameters:
dbA valid Database handle
filterA pointer to a ham_record_filter_t structure
Returns:
HAM_SUCCESS upon success
HAM_INV_PARAMETER if db or filter is NULL
HAM_FILTER_NOT_FOUND if filter was not registered
HAM_EXPORT void HAM_CALLCONV ham_set_context_data ( ham_db_t db,
void *  data 
)

Set a user-provided context pointer

This function sets a user-provided context pointer. This can be any arbitrary pointer; it is stored in the Database handle and can be retrieved with ham_get_context_data. It is mainly used by Wrappers and language bindings.

Parameters:
dbA valid Database handle
dataThe pointer to the context data