This document details the LibDBX api.

/* dbx_open - Opens a dbx file and returns a DBX struct to the caller
	@fname - Filename of dbx file to open*/
DBX *dbx_open(const char* fname);

opens a dbx file and returns the handle in the form of a DBX
struct. 

If an error is encountered, NULL is returned and dbx_errno is set to
one of the following values:

    DBX_BADFILE: File doesn't exist, or is not readable. This value is
    also returned if the file is not a type that can be handled by LibDBX.

    DBX_END_OF_FILE: An end of file is encountered even before trying
    to read anything

    DBX_DATA_READ: The signature at the beginning of the file could
    not be read.

    DBX_INDEX_READ: The index pointer in the dbx file could not be
    read from the file.

    DBX_ITEMCOUNT: The count of items could not be read from the file.

    DBX_INDEX_UNDERREAD: The number of indexs read from the dbx file
    is less than was stated in the file header.

    DBX_INDEX_OVERREAD: The number indexs read from the dbx file has
    just exceeded the number of indexes stated in the header.

If no error occurs, dbx_errno is set to DBX_NOERROR.


/* dbx_open_stream - Creates a DBX struct from an existing FILE * stream
   @fp - FILE * of open stream */
DBX *dbx_open_stream(FILE *fp);

Same as dbx_open, but is passed an already open file stream.

On error returns NULL. dbx_errno values are the same as for dbx_open.


/* dbx_close - Closes a dbx file and deletes the internal struct
	@dbx - DBX struct associated with dbx */
int dbx_close(DBX *dbx);

use this function to close a dbx file. It will close the dbx file,
delete the indexes, and delete the structure. Do not attempt to access
the structure after this function has completed successfully.

On success, this function returns 0, otherwise it will return -1. On
error, dbx_errno is set to the following values:

   DBX_BADFILE: Either the handle is a NULL pointer, or there
   isn't a file open.


/* dbx_free - Frees any malloced buffers in a struct
   @dbx - Handle for the DBX file associated with this item
   @item - item to free. Can be DBXEMAIL* or DBXFOLDER* */
int dbx_free(DBX *dbx, void *item);

dbx_free clears the item passed. The DBX handle remains unaltered. Use
this function after dbx_get to delete the item from memory. All the
fields are free'ed, as is the structure. Do not attempt to access the
structure after this function has completed successfully. This
function works with both DBXEMAIL and DBXFOLDER types. It will clear
all the dynamically allocated space for both types.

On success it returns 0 and on error -1. dbx_errno is not changed by
this function


/* dbx_get - Gets an item from a dbx file
	@dbx - dbx file to get item from
	@index - item 0..itemcount to fetch
	@flags - which parts to get. Can be 0 or DBX_FLAG_BODY*/
void * dbx_get(DBX *dbx, int index, int flags);

dbx_get will fetch 1 item from a dbx file specified by dbx. The index
is in the range 0..dbx->indexCount inclusive. If the flags parameter
is 0 and the dbx->type is DBX_TYPE_EMAIL then the email's body is
*not* loaded. Specify DBX_FLAG_BODY to fetch the body and the
fields. This parameter has no effect on other types.

On success, it returns a void* pointer to either a DBXFOLDER or
DBXEMAIL. Use the dbx->type parameter to decide whether to convert to
DBXEMAIL or DBXFOLDER. On error NULL is returned and dbx_errno is set
to one of the following:

   DBX_BADFILE: dbx handle isn't open, is NULL or is of invalid type

   DBX_INDEXCOUNT: the index is outside of the possible range (less
   than zero or greater than dbx->indexCount).

   DBX_INDEX_READ: could not read header of email block.

   DBX_DATA_READ: could not read the data from the file.


/* dbx_perror - Print the error message to stderr
	@str - prepend this message */
int dbx_perror(const char *str);

dbx_perror takes one parameter that is an error indicator to print to
stderr. This function works exactly the same as perror(char*) but
handles error messages generated by LibDBX. It will print an error
message that will hopefully mean something to the user who is running
the program.

Always returns 0.


/* dbx_get_body - Load the body for the current email
    @dbx - handle for the dbx file
    @start - file offset from email pointer
    @ptr - location to store data */
int dbx_get_body(DBX* dbx, int start, char** ptr);

dbx_get_body can be used if dbx_get is used without the DBX_FLAG_BODY
flag. Using this method, you can load and delete email bodies as you
wish. 

start is a file offset pointing to the start of the email body. This
is stored in email->data_offset.

ptr is a pointer to a char *. After the function is finished, the char
* will point to the email body. You may delete this block of memory
whenever you wish.

On success, the number of bytes read is returned. On error, -1 is
returned and dbx_errno is set to the following values:
 
   DBX_BADFILE: Handle is NULL or dbx file isn't open.

   DBX_DATA_READ: Header or body could not be read.



/* dbx_get_email_body - Load the body of an email and store it in the email
	@dbx - handle for the dbx file
	@email - email to fillin
*/
int dbx_get_email_body(DBX *dbx, DBXEMAIL* email);

dbx_get_email_body is similar to dbx_get_body but will add the data to
the email->email pointer. To clear this block of memory it is
recommended that you use dbx_free_email_body. The return values are
the same as dbx_get_body.


/* dbx_free_email_body - Clear the body of an email. To be called after dbx_get_email_body
	@dbx - handle for dbx file
	@email - email to remove body from */
int dbx_free_email_body(DBX *dbx, DBXEMAIL* email);

dbx_free_email_body will free the email body from email and set the
pointer to NULL. It will always return 0. No sanity checks are
performed in this function.