/*
 * db.h
 * File Revision 0
 * Interface specification and inclusion header for database library.
 * (c) 2000 Jacob Lundberg, jacob@chaos2.org
 */


/*
 * 2000.10.14	Initial revision
 */


#ifndef __DB_H__
#define __DB_H__


/* There are some includes we need everyone to hit. */
#include <stdio.h>
#include <stdlib.h>
#include <string.h>


/* Constants the user might be interested in. */
#define  DB_PATH_MAX            1024
#define  DB_KEY_MAX             1024


/*
 * The data locking struct.
 * The lock_bits are defined in dblock.c because they should
 * be opaque to readers outside of the locking implementation.
 */
#define  DB_LOCK_SIZE           sizeof(db_lock)
typedef struct _db_lock {
   int lock_pid;                /* locking for this lock structure */
   int lock_bits;               /* info about the state of the lock */
   int write_pid;               /* the pid of the current writer */
   int read_count;              /* the current number of read locks */
} db_lock;


/* Functions exported for external use. */
int db_lock_read(FILE *file, off_t offset);
int db_lock_write(FILE *file, off_t offset);
int db_lock_advise(FILE *file, off_t offset);
int db_unlock_read(FILE *file, off_t offset);
int db_unlock_write(FILE *file, off_t offset);
int db_unlock_advise(FILE *file, off_t offset);
int db_lock_has_advisory(FILE *file, off_t offset);
off_t db_upgrade_advisory(FILE *file, off_t offset);


/* The DB_FILE struct describes an open database (like FILE in stdio). */
#define  DB_FILE_SIZE           sizeof(DB_FILE)
typedef struct _db_file {
   off_t fpos;                  /* iterative position within the file */
   int ldepth;                  /* iterative depth into a collision list */
   FILE *file;                  /* FILE pointer for I/O use */
} DB_FILE;


/* The database header can be block read into the following struct. */
#define  DB_HEADER_SIZE         sizeof(db_header)
typedef struct _db_header {
   db_lock lock;                /* locking for the database header */
   int hash_size;               /* translation hash size at present */
   int max_key_size;            /* current maximum key size (bounds) */
   int min_data_size;           /* current minimum data size (optimize) */
   off_t space_table;           /* file offset for the free space table */
   off_t trans_table;           /* file offset for the translation table */
} db_header;


/* Pure data entries have their own headers too. */
#define  DB_DATA_HEADER_SIZE    sizeof(db_data_header)
typedef struct _db_data_header {
   db_lock lock;                /* locking for this data */
   int size;                    /* size of the attached data */
   off_t next;                  /* pointer to next data with same hash */
} db_data_header;


/* Exported functions. */
int db_close(DB_FILE *db_fp);
int db_key_size(DB_FILE *db_fp);
int db_data_size(DB_FILE *db_fp);
int db_hash_size(DB_FILE *db_fp);
int db_begin_scan(DB_FILE *db_fp);
DB_FILE *db_open(char *file_name);
int db_read_size(DB_FILE *db_fp, char *key);
int db_read(DB_FILE *db_fp, char *key, void *data);
int db_read_next(DB_FILE *db_fp, char *key, void *data);
int db_write(DB_FILE *db_fp, char *key, void *data, size_t length);
int db_create(char *file_name, int key_size, int data_size, int hash_size);


#endif /* ndef __DB_H__ */