include/apr-0/apr_dbm.h

   1 /* Copyright 2000-2005 The Apache Software Foundation or its licensors, as
   2  * applicable.
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *     http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #ifndef APR_DBM_H
  18 #define APR_DBM_H
  19
  20 #include "apu.h"
  21 #include "apr.h"
  22 #include "apr_errno.h"
  23 #include "apr_pools.h"
  24 #include "apr_file_info.h"
  25
  26 #ifdef __cplusplus
  27 extern "C" {
  28 #endif
  29
  30 /**
  31  * @file apr_dbm.h
  32  * @brief APR-UTIL DBM library
  33  */
  34 /**
  35  * @defgroup APR_Util_DBM DBM routines
  36  * @ingroup APR_Util
  37  * @{
  38  */
  39 /**
  40  * Structure for referencing a dbm
  41  */
  42 typedef struct apr_dbm_t apr_dbm_t;
  43
  44 /**
  45  * Structure for referencing the datum record within a dbm
  46  */
  47 typedef struct
  48 {
  49     /** pointer to the 'data' to retrieve/store in the DBM */
  50     char *dptr;
  51     /** size of the 'data' to retrieve/store in the DBM */
  52     apr_size_t dsize;
  53 } apr_datum_t;
  54
  55 /* modes to open the DB */
  56 #define APR_DBM_READONLY        1       /**< open for read-only access */
  57 #define APR_DBM_READWRITE       2       /**< open for read-write access */
  58 #define APR_DBM_RWCREATE        3       /**< open for r/w, create if needed */
  59 #define APR_DBM_RWTRUNC         4       /**< open for r/w, truncating an existing
  60                                           DB if present */
  61 /**
  62  * Open a dbm file by file name and type of DBM
  63  * @param dbm The newly opened database
  64  * @param type The type of the DBM (not all may be available at run time)
  65  * <pre>
  66  *  GDBM for GDBM files
  67  *  SDBM for SDBM files
  68  *  DB   for berkeley DB files
  69  *  NDBM for NDBM files
  70  *  default for the default DBM type
  71  *  </pre>
  72  * @param name The dbm file name to open
  73  * @param mode The flag value
  74  * <PRE>
  75  *           APR_DBM_READONLY   open for read-only access
  76  *           APR_DBM_READWRITE  open for read-write access
  77  *           APR_DBM_RWCREATE   open for r/w, create if needed
  78  *           APR_DBM_RWTRUNC    open for r/w, truncate if already there
  79  * </PRE>
  80  * @param perm Permissions to apply to if created
  81  * @param cntxt The pool to use when creating the dbm
  82  * @remark The dbm name may not be a true file name, as many dbm packages
  83  * append suffixes for seperate data and index files.
  84  */
  85
  86 APU_DECLARE(apr_status_t) apr_dbm_open_ex(apr_dbm_t **dbm, const char* type,
  87                                        const char *name,
  88                                        apr_int32_t mode, apr_fileperms_t perm,
  89                                        apr_pool_t *cntxt);
  90
  91
  92 /**
  93  * Open a dbm file by file name
  94  * @param dbm The newly opened database
  95  * @param name The dbm file name to open
  96  * @param mode The flag value
  97  * <PRE>
  98  *           APR_DBM_READONLY   open for read-only access
  99  *           APR_DBM_READWRITE  open for read-write access
 100  *           APR_DBM_RWCREATE   open for r/w, create if needed
 101  *           APR_DBM_RWTRUNC    open for r/w, truncate if already there
 102  * </PRE>
 103  * @param perm Permissions to apply to if created
 104  * @param cntxt The pool to use when creating the dbm
 105  * @remark The dbm name may not be a true file name, as many dbm packages
 106  * append suffixes for seperate data and index files.
 107  */
 108 APU_DECLARE(apr_status_t) apr_dbm_open(apr_dbm_t **dbm, const char *name,
 109                                        apr_int32_t mode, apr_fileperms_t perm,
 110                                        apr_pool_t *cntxt);
 111
 112 /**
 113  * Close a dbm file previously opened by apr_dbm_open
 114  * @param dbm The database to close
 115  */
 116 APU_DECLARE(void) apr_dbm_close(apr_dbm_t *dbm);
 117
 118 /**
 119  * Fetch a dbm record value by key
 120  * @param dbm The database
 121  * @param key The key datum to find this record
 122  * @param pvalue The value datum retrieved for this record
 123  */
 124 APU_DECLARE(apr_status_t) apr_dbm_fetch(apr_dbm_t *dbm, apr_datum_t key,
 125                                         apr_datum_t *pvalue);
 126 /**
 127  * Store a dbm record value by key
 128  * @param dbm The database
 129  * @param key The key datum to store this record by
 130  * @param value The value datum to store in this record
 131  */
 132 APU_DECLARE(apr_status_t) apr_dbm_store(apr_dbm_t *dbm, apr_datum_t key,
 133                                         apr_datum_t value);
 134
 135 /**
 136  * Delete a dbm record value by key
 137  * @param dbm The database
 138  * @param key The key datum of the record to delete
 139  * @remark It is not an error to delete a non-existent record.
 140  */
 141 APU_DECLARE(apr_status_t) apr_dbm_delete(apr_dbm_t *dbm, apr_datum_t key);
 142
 143 /**
 144  * Search for a key within the dbm
 145  * @param dbm The database
 146  * @param key The datum describing a key to test
 147  */
 148 APU_DECLARE(int) apr_dbm_exists(apr_dbm_t *dbm, apr_datum_t key);
 149
 150 /**
 151  * Retrieve the first record key from a dbm
 152  * @param dbm The database
 153  * @param pkey The key datum of the first record
 154  */
 155 APU_DECLARE(apr_status_t) apr_dbm_firstkey(apr_dbm_t *dbm, apr_datum_t *pkey);
 156
 157 /**
 158  * Retrieve the next record key from a dbm
 159  * @param dbm The database
 160  * @param pkey The key datum of the next record
 161  */
 162 APU_DECLARE(apr_status_t) apr_dbm_nextkey(apr_dbm_t *dbm, apr_datum_t *pkey);
 163
 164 /**
 165  * Proactively toss any memory associated with the apr_datum_t.
 166  * @param dbm The database
 167  * @param data The datum to free.
 168  */
 169 APU_DECLARE(void) apr_dbm_freedatum(apr_dbm_t *dbm, apr_datum_t data);
 170
 171 /**
 172  * Report more information when an apr_dbm function fails.
 173  * @param dbm The database
 174  * @param errcode A DBM-specific value for the error (for logging). If this
 175  *                isn't needed, it may be NULL.
 176  * @param errbuf Location to store the error text
 177  * @param errbufsize The size of the provided buffer
 178  * @return The errbuf parameter, for convenience.
 179  */
 180 APU_DECLARE(char *) apr_dbm_geterror(apr_dbm_t *dbm, int *errcode,
 181                                      char *errbuf, apr_size_t errbufsize);
 182 /**
 183  * If the specified file/path were passed to apr_dbm_open(), return the
 184  * actual file/path names which would be (created and) used. At most, two
 185  * files may be used; used2 may be NULL if only one file is used.
 186  * @param pool The pool for allocating used1 and used2.
 187  * @param type The type of DBM you require info on
 188  * @param pathname The path name to generate used-names from.
 189  * @param used1 The first pathname used by the apr_dbm implementation.
 190  * @param used2 The second pathname used by apr_dbm. If only one file is
 191  *              used by the specific implementation, this will be set to NULL.
 192  * @return An error if the specified type is invalid.
 193  * @remark The dbm file(s) don't need to exist. This function only manipulates
 194  *      the pathnames.
 195  */
 196 APU_DECLARE(apr_status_t) apr_dbm_get_usednames_ex(apr_pool_t *pool,
 197                                                    const char *type,
 198                                                    const char *pathname,
 199                                                    const char **used1,
 200                                                    const char **used2);
 201
 202 /**
 203  * If the specified file/path were passed to apr_dbm_open(), return the
 204  * actual file/path names which would be (created and) used. At most, two
 205  * files may be used; used2 may be NULL if only one file is used.
 206  * @param pool The pool for allocating used1 and used2.
 207  * @param pathname The path name to generate used-names from.
 208  * @param used1 The first pathname used by the apr_dbm implementation.
 209  * @param used2 The second pathname used by apr_dbm. If only one file is
 210  *              used by the specific implementation, this will be set to NULL.
 211  * @remark The dbm file(s) don't need to exist. This function only manipulates
 212  *      the pathnames.
 213  */
 214 APU_DECLARE(void) apr_dbm_get_usednames(apr_pool_t *pool,
 215                                         const char *pathname,
 216                                         const char **used1,
 217                                         const char **used2);
 218
 219 /** @} */
 220 #ifdef __cplusplus
 221 }
 222 #endif
 223
 224 #endif  /* !APR_DBM_H */