Functions | |
HAM_EXPORT ham_status_t HAM_CALLCONV | ham_env_new (ham_env_t **env) |
HAM_EXPORT ham_status_t HAM_CALLCONV | ham_env_delete (ham_env_t *env) |
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) |
HAM_EXPORT ham_status_t HAM_CALLCONV | ham_env_create_ex (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) |
HAM_EXPORT ham_status_t HAM_CALLCONV | ham_env_open_ex (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) |
HAM_EXPORT ham_status_t HAM_CALLCONV | ham_env_enable_encryption (ham_env_t *env, ham_u8_t key[16], ham_u32_t flags) |
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) |
HAM_EXPORT ham_status_t HAM_CALLCONV ham_env_close | ( | ham_env_t * | env, | |
ham_u32_t | flags | |||
) |
Closes the Database Environment
This function closes the Database Environment. It does not free the memory resources allocated in the env handle - use ham_env_delete to free env.
If the flag HAM_AUTO_CLEANUP is specified, hamsterdb automatically calls ham_close with flag HAM_AUTO_CLEANUP on all open Databases (which closes all open Databases and their Cursors). This invalidates the ham_db_t and ham_cursor_t handles!
If the flag is not specified, the application must close all Database handles with ham_close to prevent memory leaks.
This function also aborts all Transactions which were not yet committed, and therefore renders all Transaction handles invalid. If the flag HAM_TXN_AUTO_COMMIT is specified, all Transactions will be committed.
This function removes all file-level filters installed with ham_env_add_file_filter (and hence also, implicitly, the filter installed by ham_env_enable_encryption).
env | A valid Environment handle | |
flags | Optional flags for closing the handle. Possible flags are:
|
Referenced by ham::env::close().
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 | |||
) |
Creates a Database Environment
A Database Environment is a collection of Databases, which are all stored in one physical file (or in-memory). Per default, up to 16 Databases can be stored in one file (see ham_env_create_ex on how to store even more Databases).
Each Database is identified by a positive 16bit value (except 0 and values at or above 0xf000 (HAM_EMPTY_DATABASE_NAME)). Databases in an Environment can be created with ham_env_create_db or opened with ham_env_open_db.
env | A valid Environment handle, which was created with ham_env_new | |
filename | The filename of the Environment file. If the file already exists, it is overwritten. Can be NULL if an In-Memory Environment is created. | |
flags | Optional flags for opening the Environment, combined with bitwise OR. For allowed flags, see ham_env_create_ex. | |
mode | File access rights for the new file. This is the mode parameter for creat(2). Ignored on Microsoft Windows. |
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 | |||
) |
Creates a new Database in a Database Environment
env | A valid Environment handle. | |
db | A valid Database handle, which will point to the created Database. To close the handle, use ham_close. | |
name | The name of the Database. If a Database with this name already exists, the function will fail with HAM_DATABASE_ALREADY_EXISTS. Database names from 0xf000 to 0xffff and 0 are reserved. | |
flags | Optional flags for creating the Database, combined with bitwise OR. Possible flags are:
| |
params | An array of ham_parameter_t structures. The following parameters are available:
|
Referenced by ham::env::create_db().
HAM_EXPORT ham_status_t HAM_CALLCONV ham_env_create_ex | ( | ham_env_t * | env, | |
const char * | filename, | |||
ham_u32_t | flags, | |||
ham_u32_t | mode, | |||
const ham_parameter_t * | param | |||
) |
Creates a Database Environment - extended version
A Database Environment is a collection of Databases, which are all stored in one physical file (or in-memory). Per default, up to 16 Databases can be stored in one file, but this setting can be overwritten by specifying the parameter HAM_PARAM_MAX_ENV_DATABASES.
Each Database is identified by a positive 16bit value (except 0 and values at or above 0xf000 (HAM_EMPTY_DATABASE_NAME)). Databases in an Environment can be created with ham_env_create_db or opened with ham_env_open_db.
env | A valid Environment handle, which was created with ham_env_new | |
filename | The filename of the Environment file. If the file already exists, it is overwritten. Can be NULL for an In-Memory Environment. | |
flags | Optional flags for opening the Environment, combined with bitwise OR. Possible flags are:
| |
mode | File access rights for the new file. This is the mode parameter for creat(2). Ignored on Microsoft Windows. | |
param | An array of ham_parameter_t structures. The following parameters are available:
|
Referenced by ham::env::create().
HAM_EXPORT ham_status_t HAM_CALLCONV ham_env_delete | ( | ham_env_t * | env | ) |
Frees a ham_env_t handle
Frees the ham_env_t structure, but does not close the Environment. Call this function AFTER you have closed the Environment using ham_env_close, or you will lose your data!
env | A valid Environment handle |
Referenced by ham::env::close().
HAM_EXPORT ham_status_t HAM_CALLCONV ham_env_enable_encryption | ( | ham_env_t * | env, | |
ham_u8_t | key[16], | |||
ham_u32_t | flags | |||
) |
Enables AES encryption
This function enables AES encryption for every Database in the Environment. The AES key is cached in the Environment handle. The AES encryption/decryption is only active when file chunks are written to disk/read from disk; the cached pages in RAM are decrypted. Please read the FAQ for security relevant notes.
The encryption has no effect on In-Memory Environments, but the function will return HAM_SUCCESS.
Log files and the header page of the Database are not encrypted.
The encryption will be active till ham_env_close is called. If the Environment handle is reused after calling ham_env_close, the encryption is no longer active. ham_env_enable_encryption should be called immediately after ham_env_create[_ex] or ham_env_open[_ex].
env | A valid Environment handle | |
key | A 128bit AES key | |
flags | Optional flags for encrypting; unused, set to 0 |
Referenced by ham::env::enable_encryption().
HAM_EXPORT ham_status_t HAM_CALLCONV ham_env_erase_db | ( | ham_env_t * | env, | |
ham_u16_t | name, | |||
ham_u32_t | flags | |||
) |
Deletes a Database from an Environment
env | A valid Environment handle | |
name | The name of the Database to delete. If a Database with this name does not exist, the function will fail with HAM_DATABASE_NOT_FOUND. If the Database was already opened, the function will fail with HAM_DATABASE_ALREADY_OPEN. | |
flags | Optional flags for deleting the Database; unused, set to 0. |
Referenced by ham::env::erase_db().
HAM_EXPORT ham_status_t HAM_CALLCONV ham_env_flush | ( | ham_env_t * | env, | |
ham_u32_t | flags | |||
) |
Flushes the Environment
This function flushes the Environment caches and writes the whole file to disk. All Databases of this Environment are flushed as well.
Since In-Memory Databases do not have a file on disk, the function will have no effect and will return HAM_SUCCESS.
env | A valid Environment handle | |
flags | Optional flags for flushing; unused, set to 0 |
HAM_EXPORT ham_status_t HAM_CALLCONV ham_env_get_database_names | ( | ham_env_t * | env, | |
ham_u16_t * | names, | |||
ham_size_t * | count | |||
) |
Returns the names of all Databases in an Environment
This function returns the names of all Databases and the number of Databases in an Environment.
The memory for names must be allocated by the user. count must be the size of names when calling the function, and will be the number of Databases when the function returns. The function returns HAM_LIMITS_REACHED if names is not big enough; in this case, the caller should resize the array and call the function again.
env | A valid Environment handle | |
names | Pointer to an array for the Database names | |
count | Pointer to the size of the array; will be used to store the number of Databases when the function returns. |
Referenced by ham::env::get_database_names().
HAM_EXPORT ham_status_t HAM_CALLCONV ham_env_get_parameters | ( | ham_env_t * | env, | |
ham_parameter_t * | param | |||
) |
Retrieve the current value for a given Environment setting
Only those values requested by the parameter array will be stored.
env | A valid Environment handle | |
param | An array of ham_parameter_t structures. The following parameters are available:
|
Referenced by ham::env::get_parameters().
HAM_EXPORT ham_status_t HAM_CALLCONV ham_env_new | ( | ham_env_t ** | env | ) |
Allocates a ham_env_t handle
env | Pointer to the pointer which is allocated |
Referenced by ham::env::create(), and ham::env::open().
HAM_EXPORT ham_status_t HAM_CALLCONV ham_env_open | ( | ham_env_t * | env, | |
const char * | filename, | |||
ham_u32_t | flags | |||
) |
Opens an existing Database Environment
env | A valid Environment handle, which was created with ham_env_new | |
filename | The filename of the Environment file | |
flags | Optional flags for opening the Environment, combined with bitwise OR. See the documentation of ham_env_open_ex for the allowed flags. |
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 | |||
) |
Opens a Database in a Database Environment
env | A valid Environment handle | |
db | A valid Database handle, which will point to the opened Database. To close the handle, use |
name | The name of the Database. If a Database with this name does not exist, the function will fail with HAM_DATABASE_NOT_FOUND. | |
flags | Optional flags for opening the Database, combined with bitwise OR. Possible flags are:
| |
param | An array of ham_parameter_t structures. The following parameters are available:
|
Referenced by ham::env::open_db().
HAM_EXPORT ham_status_t HAM_CALLCONV ham_env_open_ex | ( | ham_env_t * | env, | |
const char * | filename, | |||
ham_u32_t | flags, | |||
const ham_parameter_t * | param | |||
) |
Opens an existing Database Environment - extended version
env | A valid Environment handle | |
filename | The filename of the Environment file | |
flags | Optional flags for opening the Environment, combined with bitwise OR. Possible flags are:
| |
param | An array of ham_parameter_t structures. The following parameters are available:
|
Referenced by ham::env::open().
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 | |||
) |
Renames a Database in an Environment.
env | A valid Environment handle. | |
oldname | The old name of the existing Database. If a Database with this name does not exist, the function will fail with HAM_DATABASE_NOT_FOUND. | |
newname | The new name of this Database. If a Database with this name already exists, the function will fail with HAM_DATABASE_ALREADY_EXISTS. | |
flags | Optional flags for renaming the Database, combined with bitwise OR; unused, set to 0. |
Referenced by ham::env::rename_db().