hamsterdb.h

About: hamsterdb is a database engine written in ANSI C. It supports a B+Tree index structure, uses

/**
 * \mainpage hamsterdb embeddable database
 * \file hamsterdb.h
 * \brief Include file for hamsterdb.
 * \author Christoph Rupp, [e-mail]
 * \version 0.4.4
 *
 * Copyright (C) 2005-2007 Christoph Rupp ([e-mail]).
 * All rights reserved. See file LICENSE for licence and copyright
 * information.
 *
 */

#ifndef HAM_HAMSTERDB_H__
#define HAM_HAMSTERDB_H__

#ifdef __cplusplus
extern "C" {
#endif

#include <ham/types.h>

/**
 * The hamsterdb database structure.
 *
 * This structure is allocated with @a ham_new and deleted with
 * @a ham_delete.
 */
struct ham_db_t;
typedef struct ham_db_t ham_db_t;

/**
 * The hamsterdb environment structure.
 *
 * This structure is allocated with @a ham_env_new and deleted with
 * @a ham_env_delete.
 */
struct ham_env_t;
typedef struct ham_env_t ham_env_t;

/**
 * A database cursor.
 *
 * A cursor is used for bi-directionally traversing the database and
 * for inserting/deleting/searching database items.
 *
 * This structure is allocated with @a ham_cursor_create and deleted with
 * @a ham_cursor_close.
 */
struct ham_cursor_t;
typedef struct ham_cursor_t ham_cursor_t;

/**
 * A generic record.
 *
 * A record represents data items in hamsterdb. Before using a record, it
 * is important to initialize all record fields with zeroes, i.e. with
 * the C library routines memset(3) or bzero(2).
 *
 * When hamsterdb returns a record structure, the pointer to the record
 * data is provided in @a data. This pointer is only temporary and will be
 * overwritten by subsequent hamsterdb API calls.
 *
 * To avoid this, the calling application can allocate the @a data pointer.
 * In this case, you have to set the flag @a HAM_RECORD_USER_ALLOC. The
 * @a size parameter will then return the size of the record. It's the
 * responsibility of the caller to make sure that the @a data parameter is
 * large enough for the record.
 *
 */
typedef struct
{
    /** The size of the record data, in bytes */
    ham_size_t size;

    /** The record data, usually a temporary pointer allocated by hamsterdb */
    void *data;

    /** The record flags */
    ham_u32_t flags;

    /** For internal use */
    ham_size_t _allocsize;

    /** For internal use */
    ham_u32_t _intflags;

    /** For internal use */
    ham_u64_t _rid;

} ham_record_t;

/** Flag for @a ham_record_t */
#define HAM_RECORD_USER_ALLOC   1

/**
 * A generic key.
 *
 * A key represents key items in hamsterdb. Before using a key, it
 * is important to initialize all key fields with zeroes, i.e. with
 * the C library routines memset(3) or bzero(2).
 *
 * hamsterdb usually uses keys to insert, delete or search for items.
 * However, when using database cursors and the function @a ham_cursor_move,
 * hamsterdb also returns keys. In this case, the pointer to the key
 * data is provided in @a data. This pointer is only temporary and will be
 * overwritten by subsequent calls to @a ham_cursor_move.
 *
 * To avoid this, the calling application can allocate the @a data pointer.
 * In this case, you have to set the flag @a HAM_KEY_USER_ALLOC. The
 * @a size parameter will then return the size of the key. It's the
 * responsibility of the caller to make sure that the @a data parameter is
 * large enough for the key.
 *
 */
typedef struct
{
    /** The size of the key, in bytes */
    ham_u16_t size;

    /** The data of the key */
    void *data;

    /** The flags of the key */
    ham_u32_t flags;

    /** For internal use */
    ham_u32_t _flags;
} ham_key_t;

/** Flag for @a ham_key_t in combination with @a ham_cursor_move */
#define HAM_KEY_USER_ALLOC      1

/**
 * A named parameter.
 *
 * These parameter structures are used for functions like @a ham_open_ex,
 * @a ham_create_ex etc to pass variable length parameter lists.
 *
 * The lists are always arrays of type ham_parameter_t, with a terminating
 * element of { 0, NULL}, e.g.
 *
 * <pre>
 *   ham_parameter_t parameters[]={
 *      { HAM_PARAM_CACHESIZE, 1024 },
 *      { HAM_PARAM_PAGESIZE, 1024*4 },
 *      { 0, NULL }
 *   };
 * </pre>
 */
typedef struct {
    /** The name of the parameter; all HAM_PARAM_*-constants */
    ham_u32_t name;

    /** The value of the parameter. Pointer values are casted into
     * @a value like this:
     * <pre>
     *   // a string value - cast the pointer to ham_u64_t:
     *   value=(ham_u64_t)"hello world";
     * </pre>
     */
    ham_u64_t value;

} ham_parameter_t;

/**
 * @defgroup ham_status_codes hamsterdb Status Codes
 * @{
 */

/** Operation completed successfully */
#define HAM_SUCCESS                  (  0)
/** Failed to read the database file */
#define HAM_SHORT_READ               ( -1)
/** Failed to write the database file */
#define HAM_SHORT_WRITE              ( -2)
/** Invalid key size */
#define HAM_INV_KEYSIZE              ( -3)
/** Invalid page size (must be a not a multiple of 1024) */
#define HAM_INV_PAGESIZE             ( -4)
/** Database is already open */
#define HAM_DB_ALREADY_OPEN          ( -5)
/** Memory allocation failed - out of memory */
#define HAM_OUT_OF_MEMORY            ( -6)
/** Invalid backend index */
#define HAM_INV_INDEX                ( -7)
/** Invalid function parameter */
#define HAM_INV_PARAMETER            ( -8)
/** Invalid database file header */
#define HAM_INV_FILE_HEADER          ( -9)
/** Invalid database file version */
#define HAM_INV_FILE_VERSION         (-10)
/** Key was not found */
#define HAM_KEY_NOT_FOUND            (-11)
/** Tried to insert a key which already exists */
#define HAM_DUPLICATE_KEY            (-12)
/** Internal database integrity violated */
#define HAM_INTEGRITY_VIOLATED       (-13)
/** Internal hamsterdb error */
#define HAM_INTERNAL_ERROR           (-14)
/** Tried to modify the database, but the file was opened as read-only */
#define HAM_DB_READ_ONLY             (-15)
/** Database record not found */
#define HAM_BLOB_NOT_FOUND           (-16)
/** Prefix comparison function needs more data */
#define HAM_PREFIX_REQUEST_FULLKEY   (-17)
/** Generic file I/O error */
#define HAM_IO_ERROR                 (-18)
/** Database cache is full */
#define HAM_CACHE_FULL               (-19)
/** Function is not yet implemented */
#define HAM_NOT_IMPLEMENTED          (-20)
/** Database file not found */
#define HAM_FILE_NOT_FOUND           (-21)
/** Operation would block */
#define HAM_WOULD_BLOCK              (-22)
/** Object was not initialized correctly */
#define HAM_NOT_READY                (-23)
/** Cursor does not point to a valid database item */
#define HAM_CURSOR_IS_NIL           (-100)
/** Not all databases were closed before closing the environment */
#define HAM_ENV_NOT_EMPTY           (-200)
/** Database not found */
#define HAM_DATABASE_NOT_FOUND      (-201)
/** Database name already exists */
#define HAM_DATABASE_ALREADY_EXISTS (-202)
/** Database already open */
#define HAM_DATABASE_ALREADY_OPEN   (-203)
/** Environment is full */
#define HAM_ENV_FULL                (-204)

/**
 * @}
 */

/**
 * @defgroup ham_static hamsterdb Static Functions
 * @{
 */

/**
 * A typedef for a custom error handler function.
 *
 * @param message The error message.
 */
typedef void (*ham_errhandler_fun)(const char *message);

/**
 * Sets the global error handler.
 *
 * This handler will receive <b>all</b> debug messages that are emitted
 * by hamsterdb. You can install the default handler by setting @a f to 0.
 *
 * The default error handler prints all messages to stderr. To install a
 * different logging facility, you can provide your own error handler.
 *
 * @param f A pointer to the error handler function, or NULL to restore
 *          the default handler.
 */
HAM_EXPORT void
ham_set_errhandler(ham_errhandler_fun f);

/**
 * Translates a hamsterdb status code to a descriptive error string.
 *
 * @param status The hamsterdb status code.
 *
 * @return Returns a pointer to a descriptive error string.
 */
HAM_EXPORT const char *
ham_strerror(ham_status_t status);

/**
 * Returns the version of the hamsterdb library.
 */
HAM_EXPORT void
ham_get_version(ham_u32_t *major, ham_u32_t *minor,
        ham_u32_t *revision);

/**
 * @}
 */

/**
 * @defgroup ham_env hamsterdb Environment Functions
 * @{
 */
/**
 * Allocates a ham_env_t handle.
 *
 * @param env Pointer to the pointer which is allocated.
 *
 * @return @a HAM_SUCCESS upon success.
 * @return @a HAM_OUT_OF_MEMORY if memory allocation failed.
 */
HAM_EXPORT ham_status_t
ham_env_new(ham_env_t **env);

/**
 * Deletes a ham_env_t handle.
 *
 * Frees the ham_env_t structure, but does not close the
 * environment. Call this function <b>AFTER</b> you have closed the
 * environment using @a ham_env_close, or you will lose your data!
 *
 * @param env A valid environment handle.
 *
 * @return This function always returns @a HAM_SUCCESS.
 */
HAM_EXPORT ham_status_t
ham_env_delete(ham_env_t *env);

/**
 * Creates a database environment.
 *
 * @param env A valid environment handle.
 * @param filename The filename of the environment file. If the file already
 *          exists, it is overwritten. Can be NULL if you create an
 *          in-memory environment.
 * @param flags Optional flags for opening the environment, combined with
 *        bitwise OR. For allowed flags, see @a ham_env_create_ex.
 * @param mode File access rights for the new file. This is the @a mode
 *        parameter for creat(2). Ignored on Microsoft Windows.
 *
 * @return @a HAM_SUCCESS upon success.
 * @return @a HAM_INV_PARAMETER if the @a env pointer is NULL or an