From acb2f01fbd0e885b9654c8125f4437aa810f90df Mon Sep 17 00:00:00 2001 From: Adam Dickmeiss Date: Tue, 4 Apr 2006 00:10:09 +0000 Subject: [PATCH] Doxygen comments --- include/idzebra/bfile.h | 120 +++++++++++++++++++++++++++++++++++++---------- 1 file changed, 96 insertions(+), 24 deletions(-) diff --git a/include/idzebra/bfile.h b/include/idzebra/bfile.h index 1db5fed..04b7703 100644 --- a/include/idzebra/bfile.h +++ b/include/idzebra/bfile.h @@ -1,4 +1,4 @@ -/* $Id: bfile.h,v 1.5 2005-05-17 08:50:48 adam Exp $ +/* $Id: bfile.h,v 1.6 2006-04-04 00:10:09 adam Exp $ Copyright (C) 1995-2005 Index Data ApS @@ -20,6 +20,13 @@ Free Software Foundation, 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ +/** \file bfile.h + \brief Zebra Block File Layer + + Providers an interface to a file system , AKA persistent storage. + The interface allows safe updates - using a shadow file facility. +*/ + #ifndef BFILE_H #define BFILE_H @@ -28,74 +35,139 @@ Free Software Foundation, 59 Temple Place - Suite 330, Boston, MA YAZ_BEGIN_CDECL +/** \var BFiles + \brief A collection of BFile(s). +*/ typedef struct BFiles_struct *BFiles; + +/** \var BFile + \brief A Block File +*/ typedef struct BFile_struct *BFile; +/** \brief creates a Block files collection + \param spec register specification , e.g. "d1:100M d2:1G" + \param base base directory for register spec (if that is relative path) +*/ BFiles bfs_create (const char *spec, const char *base); + +/** \brief destroys a block files handle + \param bfiles block files handle + + The files in the block files collection are not deleted. Only the + handle is +*/ void bfs_destroy (BFiles bfiles); -/* bf_close: closes bfile. - returns 0 if successful; non-zero otherwise +/** \brief closes a Block file + \param bf block file */ YAZ_EXPORT -int bf_close (BFile); +int bf_close (BFile bf); +/** \brief closes an extended Block file handle.. + \param bf extended block file opened with bf_xopen + \param version version to be put in a file + \param more_info more information to be stored in file (header) +*/ YAZ_EXPORT int bf_xclose (BFile bf, int version, const char *more_info); -/* bf_open: opens bfile. - opens bfile with name 'name' and with 'block_size' as block size. - returns bfile handle is successful; NULL otherwise - */ +/** \brief opens and returns a Block file handle + \param bfs block files + \param name filename + \param block_size block size in bytes + \param wflag 1=opened for read&write, 0=read only +*/ YAZ_EXPORT BFile bf_open (BFiles bfs, const char *name, int block_size, int wflag); +/** \brief opens and returns an extended Block file handle + \param bfs block files + \param name filename + \param block_size block size in bytes + \param wflag 1=opened for read&write, 0=read only + \param magic magic string to be used for file + \param read_version holds after completion of bf_xopen the version + \param more_info holds more_info as read from file (header) +*/ YAZ_EXPORT -BFile bf_xopen(BFiles bfs, const char *name, int block_size, int wrflag, +BFile bf_xopen(BFiles bfs, const char *name, int block_size, int wflag, const char *magic, int *read_version, const char **more_info); -/* bf_read: reads bytes from bfile 'bf'. - reads 'nbytes' bytes (or whole block if 0) from offset 'offset' from - block 'no'. stores contents in buffer 'buf'. - returns 1 if whole block could be read; 0 otherwise. +/** \brief read from block file + \param bf block file handle + \param no block no (first block is 0, second is 1..) + \param offset offset within block to be read + \param nbytes number of bytes to read (0 for whole block) + \param buf raw bytes with content (at least nbytes of size) + + Returns 1 if whole block could be read; 0 otherwise. */ YAZ_EXPORT int bf_read (BFile bf, zint no, int offset, int nbytes, void *buf); -/* bf_write: writes bytes to bfile 'bf'. - writes 'nbytes' bytes (or whole block if 0) at offset 'offset' to - block 'no'. retrieves contents from buffer 'buf'. - returns 0 if successful; non-zero otherwise. +/** \brief writes bytes to file + \param bf block file handle + \param no block no + \param offset within block + \param nbytes number of bytes to write + \param buf buffer to write + + Writes the content of buffer to a block within a block file (or + whole block). Returns 1 if successful; 0 otherwise. */ YAZ_EXPORT int bf_write (BFile bf, zint no, int offset, int nbytes, const void *buf); -/* bf_cache: enables bfile cache if spec is not NULL */ +/** \brief enables or disables shadow for block files + \param bfs block files + \param spec such as "shadow:100M /other:200M"; or NULL to disable +*/ YAZ_EXPORT ZEBRA_RES bf_cache (BFiles bfs, const char *spec); -/* bf_commitExists: returns 1 if commit is pending; 0 otherwise */ +/** \brief Check if there is content in shadow area (to be committed). + \param bfs block files + + Returns 1 if there is content in shadow area; 0 otherwise. +*/ YAZ_EXPORT int bf_commitExists (BFiles bfs); -/* bf_commitExec: executes commit */ +/** \brief Executes commit operation + \param bfs block files +*/ YAZ_EXPORT void bf_commitExec (BFiles bfs); -/* bf_commitClean: cleans commit files, etc */ +/** \brief Cleans shadow files (remove them) + \param bfs block files + \param spec shadow specification +*/ YAZ_EXPORT void bf_commitClean (BFiles bfs, const char *spec); -/* bf_reset: delete register and shadow completely */ +/** \brief Removes register and shadow completely + \param bfs block files +*/ YAZ_EXPORT void bf_reset (BFiles bfs); -/* bf_alloc: allocate one or more blocks */ +/** \brief Allocates one or more blocks in an extended block file + \param bf extended block file + \param no number of blocks to allocate + \param blocks output array of size no with block offsets +*/ YAZ_EXPORT int bf_alloc(BFile bf, int no, zint *blocks); -/* bf_alloc: allocate one or more blocks */ +/** \brief Releases one or more blocks in an extended block file + \param bf extended block file + \param no numer of blocks to release + \param blocks input array with block offsets (IDs) to release +*/ YAZ_EXPORT int bf_free(BFile bf, int no, const zint *blocks); -- 1.7.10.4