hamsterdb.h

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

 *
 * @return @a HAM_SUCCESS upon success.
 * @return @a HAM_INV_PARAMETER if @a db, @a key or @a record is NULL.
 * @return @a HAM_KEY_NOT_FOUND if the @a key does not exist.
 */
HAM_EXPORT ham_status_t
ham_find(ham_db_t *db, void *reserved, ham_key_t *key,
        ham_record_t *record, ham_u32_t flags);

/**
 * Inserts a database item.
 *
 * This function inserts a key/record pair as a new database item.
 *
 * If the key already exists in the database, error @a HAM_DUPLICATE_KEY
 * is returned. If you wish to overwrite an existing entry specify the
 * flag @a HAM_OVERWRITE.
 *
 * @param db A valid database handle.
 * @param reserved A reserved value; set to NULL.
 * @param key The key of the new item.
 * @param record The record of the new item.
 * @param flags Insert flags. Currently, only one flag is available:
 *         @a HAM_OVERWRITE. If the @a key already exists, the record is
 *              overwritten. Otherwise, the key is inserted.
 *
 * @return @a HAM_SUCCESS upon success.
 * @return @a HAM_INV_PARAMETER if @a db, @a key or @a record is NULL.
 * @return @a HAM_DB_READ_ONLY if you tried to insert a key in a read-only
 *              database.
 * @return @a HAM_INV_KEYSIZE if the key's size is larger than the @a keysize
 *              parameter specified for @a ham_create_ex and variable
 *              key sizes are disabled (see @a HAM_DISABLE_VAR_KEYLEN)
 *              OR if the @a keysize parameter specified for @a ham_create_ex
 *              is smaller than 8.
 */
HAM_EXPORT ham_status_t
ham_insert(ham_db_t *db, void *reserved, ham_key_t *key,
        ham_record_t *record, ham_u32_t flags);

/** Flag for @a ham_insert and @a ham_cursor_insert */
#define HAM_OVERWRITE               1

/**
 * Erases a database item.
 *
 * This function erases a database item. If the item @a key
 * does not exist, @a HAM_KEY_NOT_FOUND is returned.
 *
 * @param db A valid database handle.
 * @param reserved A reserved value; set to NULL.
 * @param key The key to delete.
 * @param flags Erase flags; unused, set to 0.
 *
 * @return @a HAM_SUCCESS upon success.
 * @return @a HAM_INV_PARAMETER if @a db or @a key is NULL.
 * @return @a HAM_DB_READ_ONLY if you tried to erase a key from a read-only
 *              database.
 * @return @a HAM_KEY_NOT_FOUND if @a key was not found.
 */
HAM_EXPORT ham_status_t
ham_erase(ham_db_t *db, void *reserved, ham_key_t *key,
        ham_u32_t flags);

/**
 * Flushes the database.
 *
 * This function flushes the database cache and writes the whole file
 * to disk.
 *
 * Since in-memory databases do not have a file on disk, the
 * function will have no effect and will return @a HAM_SUCCESS.
 *
 * @param db A valid database handle.
 * @param flags Flush flags; unused, set to 0.
 *
 * @return @a HAM_SUCCESS upon success.
 * @return @a HAM_INV_PARAMETER if @a db is NULL.
 */
HAM_EXPORT ham_status_t
ham_flush(ham_db_t *db, ham_u32_t flags);

/**
 * Closes the database.
 *
 * This function flushes the database and then closes the file handle.
 * It does not free the memory resources allocated in the @a db handle -
 * use @a ham_delete to free @a db.
 *
 * The application should close all database cursors before closing
 * the database.
 *
 * @param db A valid database handle.
 *
 * @return @a HAM_SUCCESS upon success.
 * @return @a HAM_INV_PARAMETER if @a db is NULL.
 */
HAM_EXPORT ham_status_t
ham_close(ham_db_t *db);

/**
 * @}
 */

/**
 * @defgroup ham_cursor hamsterdb Cursor Functions
 * @{
 */

/**
 * Creates a database cursor.
 *
 * Creates a new database cursor. Cursors can be used to
 * traverse the database from start to end or vice versa. Cursors
 * can also be used to insert, delete or search database items.
 * A created cursor does not point to any item in the database.
 *
 * The application should close all database cursors before closing
 * the database.
 *
 * @param db A valid database handle.
 * @param reserved A reserved value; set to NULL
 * @param flags Flags for creating the cursor; unused, set to 0
 * @param cursor A pointer to a pointer which is allocated for the
 *          new cursor handle
 *
 * @return @a HAM_SUCCESS upon success.
 * @return @a HAM_INV_PARAMETER if @a db or @a cursor is NULL.
 * @return @a HAM_OUT_OF_MEMORY if the new structure could not be allocated.
 */
HAM_EXPORT ham_status_t
ham_cursor_create(ham_db_t *db, void *reserved, ham_u32_t flags,
        ham_cursor_t **cursor);

/**
 * Clones a database cursor.
 *
 * Clones an existing cursor. The new cursor will point to
 * exactly the same item as the old cursor. If the old cursor did not point
 * to any item, so will the new cursor.
 *
 * @param src The existing cursor.
 * @param dest A pointer to a pointer, which is allocated for the
 *          cloned cursor handle.
 *
 * @return @a HAM_SUCCESS upon success.
 * @return @a HAM_INV_PARAMETER if @a src or @a dest is NULL.
 * @return @a HAM_OUT_OF_MEMORY if the new structure could not be allocated.
 */
HAM_EXPORT ham_status_t
ham_cursor_clone(ham_cursor_t *src, ham_cursor_t **dest);

/**
 * Moves the cursor.
 *
 * Moves the cursor. You may specify the direction in the @a flags.
 * After the move, key and record of the item are returned.
 *
 * If the direction is not specified, the cursor will not move. Do not
 * specify a direction, if you want to fetch the key and/or record of
 * the current item.
 *
 * @param cursor A valid cursor handle.
 * @param key An optional pointer to a @a ham_key_t structure. If this
 *      pointer is not NULL, the key of the new item is returned.
 *      Note that key->data will point to temporary data. This pointer
 *      will be invalidated by subsequent hamsterdb API calls. See
 *      @a HAM_KEY_USER_ALLOC on how to change this behaviour.
 * @param record An optional pointer to a @a ham_record_t structure. If this
 *      pointer is not NULL, the record of the new item is returned.
 *      Note that record->data will point to temporary data. This pointer
 *      will be invalidated by subsequent hamsterdb API calls. See
 *      @a HAM_RECORD_USER_ALLOC on how to change this behaviour.
 * @param flags The flags for this operation. They are used to specify
 *      the direction for the "move". If you do not specify a direction,
 *      the cursor will remain on the current position.
 *          @a HAM_CURSOR_FIRST positions the cursor on the first item
 *              in the database
 *          @a HAM_CURSOR_LAST positions the cursor on the last item
 *              in the database
 *          @a HAM_CURSOR_NEXT positions the cursor on the next item
 *              in the database; if the cursor does not point to any
 *              item, the function behaves as if direction was
 *              HAM_CURSOR_FIRST.
 *          @a HAM_CURSOR_PREVIOUS positions the cursor on the previous item
 *              in the database; if the cursor does not point to any
 *              item, the function behaves as if direction was
 *              HAM_CURSOR_LAST.
 *
 * @return @a HAM_SUCCESS upon success.
 * @return @a HAM_INV_PARAMETER if @a cursor is NULL.
 * @return @a HAM_CURSOR_IS_NIL if the cursor does not point to an item, but
 *              key and/or record were requested.
 * @return @a HAM_KEY_NOT_FOUND if @a cursor points to the first (or last)
 *              item, and a move to the previous (or next) item was
 *              requested.
 */
HAM_EXPORT ham_status_t
ham_cursor_move(ham_cursor_t *cursor, ham_key_t *key,
        ham_record_t *record, ham_u32_t flags);

/** Flag for @a ham_cursor_move */
#define HAM_CURSOR_FIRST            1

/** Flag for @a ham_cursor_move */
#define HAM_CURSOR_LAST             2

/** Flag for @a ham_cursor_move */
#define HAM_CURSOR_NEXT             4

/** Flag for @a ham_cursor_move */
#define HAM_CURSOR_PREVIOUS         8

/**
 * Replaces the current record.
 *
 * This function replaces the record of the current cursor item.
 *
 * @param cursor A valid cursor handle.
 * @param record A valid record structure.
 * @param flags Flags for replacing the item; unused, set to 0.
 *
 * @return @a HAM_SUCCESS upon success.
 * @return @a HAM_INV_PARAMETER if @a cursor or @a record is NULL.
 * @return @a HAM_CURSOR_IS_NIL if the cursor does not point to an item.
 */
HAM_EXPORT ham_status_t
ham_cursor_replace(ham_cursor_t *cursor, ham_record_t *record,
            ham_u32_t flags);

/**
 * Searches a key and points the cursor to this key.
 *
 * Searches for an item in the database and points the
 * cursor to this item. If the item could not be found, the cursor is
 * not modified.
 *
 * @param cursor A valid cursor handle.
 * @param key A valid key structure.
 * @param flags Flags for searching the item; unused, set to 0.
 *
 * @return @a HAM_SUCCESS upon success.
 * @return @a HAM_INV_PARAMETER if @a cursor or @a key is NULL.
 * @return @a HAM_KEY_NOT_FOUND if the requested key was not found.
 */
HAM_EXPORT ham_status_t
ham_cursor_find(ham_cursor_t *cursor, ham_key_t *key, ham_u32_t flags);

/**
 * Inserts (or updates) a key.
 *
 * Inserts a key to the database. If the flag @a HAM_OVERWRITE
 * is specified, a pre-existing item with this key is overwritten.
 * Otherwise, @a HAM_DUPLICATE_ITEM is returned.
 * In case of an error the cursor is not modified.
 *
 * After insertion, the cursor will point to the new item. If inserting
 * the item failed, the cursor is not modified.
 *
 * @param cursor A valid cursor handle.
 * @param key A valid key structure.
 * @param record A valid record structure.
 * @param flags Flags for inserting the item.
 *         Specify @a HAM_OVERWRITE to overwrite an existing
 *              record. Otherwise a new key will be inserted.
 *
 * @return @a HAM_SUCCESS upon success.
 * @return @a HAM_INV_PARAMETER if @a key or @a record is NULL.
 * @return @a HAM_DB_READ_ONLY if you tried to insert a key to a read-only
 *              database.
 * @return @a HAM_INV_KEYSIZE if the key's size is larger than the @a keysize
 *              parameter specified for @a ham_create_ex and variable
 *              key sizes are disabled (see @a HAM_DISABLE_VAR_KEYLEN)
 *              OR if the @a keysize parameter specified for @a ham_create_ex
 *              is smaller than 8.
 */
HAM_EXPORT ham_status_t
ham_cursor_insert(ham_cursor_t *cursor, ham_key_t *key,
            ham_record_t *record, ham_u32_t flags);

/**
 * Erases the key.
 *
 * Erases a key from the database. If the erase was
 * successfull, the cursor is invalidated, and does no longer point to
 * any item. In case of an error, the cursor is not modified.
 *
 * @param cursor A valid cursor handle.
 * @param flags Erase flags; unused, set to 0.
 *
 * @return @a HAM_SUCCESS upon success.
 * @return @a HAM_INV_PARAMETER if @a cursor is NULL.
 * @return @a HAM_DB_READ_ONLY if you tried to erase a key from a read-only
 *              database.
 * @return @a HAM_KEY_NOT_FOUND if the key was not found.
 */
HAM_EXPORT ham_status_t
ham_cursor_erase(ham_cursor_t *cursor, ham_u32_t flags);

/**
 * Closes a database cursor.
 *
 * Closes a cursor and frees allocated memory. All cursors
 * should be closed before closing the database (see @a ham_close).
 *
 * @param cursor A valid cursor handle.
 *
 * @return @a HAM_SUCCESS upon success.
 * @return @a HAM_INV_PARAMETER if @a cursor is NULL.
 *
 */
HAM_EXPORT ham_status_t
ham_cursor_close(ham_cursor_t *cursor);

/*
 * @}
 */

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

#endif /* HAM_HAMSTERDB_H__ */