apr_dbm.h

Go to the documentation of this file.
00001 /* Licensed to the Apache Software Foundation (ASF) under one or more
00002  * contributor license agreements.  See the NOTICE file distributed with
00003  * this work for additional information regarding copyright ownership.
00004  * The ASF licenses this file to You under the Apache License, Version 2.0
00005  * (the "License"); you may not use this file except in compliance with
00006  * the License.  You may obtain a copy of the License at
00007  *
00008  *     http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 
00017 #ifndef APR_DBM_H
00018 #define APR_DBM_H
00019 
00020 #include "apu.h"
00021 #include "apr.h"
00022 #include "apr_errno.h"
00023 #include "apr_pools.h"
00024 #include "apr_file_info.h"
00025 
00026 #ifdef __cplusplus
00027 extern "C" {
00028 #endif
00029 
00030 /**
00031  * @file apr_dbm.h
00032  * @brief APR-UTIL DBM library
00033  */
00034 /** 
00035  * @defgroup APR_Util_DBM DBM routines
00036  * @ingroup APR_Util
00037  * @{
00038  */
00039 /**
00040  * Structure for referencing a dbm
00041  */
00042 typedef struct apr_dbm_t apr_dbm_t;
00043 
00044 /**
00045  * Structure for referencing the datum record within a dbm
00046  */
00047 typedef struct
00048 {
00049     /** pointer to the 'data' to retrieve/store in the DBM */
00050     char *dptr;
00051     /** size of the 'data' to retrieve/store in the DBM */
00052     apr_size_t dsize;
00053 } apr_datum_t;
00054 
00055 /* modes to open the DB */
00056 #define APR_DBM_READONLY        1       /**< open for read-only access */
00057 #define APR_DBM_READWRITE       2       /**< open for read-write access */
00058 #define APR_DBM_RWCREATE        3       /**< open for r/w, create if needed */
00059 #define APR_DBM_RWTRUNC         4       /**< open for r/w, truncating an existing
00060                                           DB if present */
00061 /**
00062  * Open a dbm file by file name and type of DBM
00063  * @param dbm The newly opened database
00064  * @param type The type of the DBM (not all may be available at run time)
00065  * <pre>
00066  *  GDBM for GDBM files
00067  *  SDBM for SDBM files
00068  *  DB   for berkeley DB files
00069  *  NDBM for NDBM files
00070  *  default for the default DBM type
00071  *  </pre>
00072  * @param name The dbm file name to open
00073  * @param mode The flag value
00074  * <PRE>
00075  *           APR_DBM_READONLY   open for read-only access
00076  *           APR_DBM_READWRITE  open for read-write access
00077  *           APR_DBM_RWCREATE   open for r/w, create if needed
00078  *           APR_DBM_RWTRUNC    open for r/w, truncate if already there
00079  * </PRE>
00080  * @param perm Permissions to apply to if created
00081  * @param cntxt The pool to use when creating the dbm
00082  * @remark The dbm name may not be a true file name, as many dbm packages
00083  * append suffixes for seperate data and index files.
00084  */
00085 
00086 APU_DECLARE(apr_status_t) apr_dbm_open_ex(apr_dbm_t **dbm, const char* type, 
00087                                        const char *name, 
00088                                        apr_int32_t mode, apr_fileperms_t perm,
00089                                        apr_pool_t *cntxt);
00090 
00091 
00092 /**
00093  * Open a dbm file by file name
00094  * @param dbm The newly opened database
00095  * @param name The dbm file name to open
00096  * @param mode The flag value
00097  * <PRE>
00098  *           APR_DBM_READONLY   open for read-only access
00099  *           APR_DBM_READWRITE  open for read-write access
00100  *           APR_DBM_RWCREATE   open for r/w, create if needed
00101  *           APR_DBM_RWTRUNC    open for r/w, truncate if already there
00102  * </PRE>
00103  * @param perm Permissions to apply to if created
00104  * @param cntxt The pool to use when creating the dbm
00105  * @remark The dbm name may not be a true file name, as many dbm packages
00106  * append suffixes for seperate data and index files.
00107  */
00108 APU_DECLARE(apr_status_t) apr_dbm_open(apr_dbm_t **dbm, const char *name, 
00109                                        apr_int32_t mode, apr_fileperms_t perm,
00110                                        apr_pool_t *cntxt);
00111 
00112 /**
00113  * Close a dbm file previously opened by apr_dbm_open
00114  * @param dbm The database to close
00115  */
00116 APU_DECLARE(void) apr_dbm_close(apr_dbm_t *dbm);
00117 
00118 /**
00119  * Fetch a dbm record value by key
00120  * @param dbm The database 
00121  * @param key The key datum to find this record
00122  * @param pvalue The value datum retrieved for this record
00123  */
00124 APU_DECLARE(apr_status_t) apr_dbm_fetch(apr_dbm_t *dbm, apr_datum_t key,
00125                                         apr_datum_t *pvalue);
00126 /**
00127  * Store a dbm record value by key
00128  * @param dbm The database 
00129  * @param key The key datum to store this record by
00130  * @param value The value datum to store in this record
00131  */
00132 APU_DECLARE(apr_status_t) apr_dbm_store(apr_dbm_t *dbm, apr_datum_t key, 
00133                                         apr_datum_t value);
00134 
00135 /**
00136  * Delete a dbm record value by key
00137  * @param dbm The database 
00138  * @param key The key datum of the record to delete
00139  * @remark It is not an error to delete a non-existent record.
00140  */
00141 APU_DECLARE(apr_status_t) apr_dbm_delete(apr_dbm_t *dbm, apr_datum_t key);
00142 
00143 /**
00144  * Search for a key within the dbm
00145  * @param dbm The database 
00146  * @param key The datum describing a key to test
00147  */
00148 APU_DECLARE(int) apr_dbm_exists(apr_dbm_t *dbm, apr_datum_t key);
00149 
00150 /**
00151  * Retrieve the first record key from a dbm
00152  * @param dbm The database 
00153  * @param pkey The key datum of the first record
00154  */
00155 APU_DECLARE(apr_status_t) apr_dbm_firstkey(apr_dbm_t *dbm, apr_datum_t *pkey);
00156 
00157 /**
00158  * Retrieve the next record key from a dbm
00159  * @param dbm The database 
00160  * @param pkey The key datum of the next record
00161  */
00162 APU_DECLARE(apr_status_t) apr_dbm_nextkey(apr_dbm_t *dbm, apr_datum_t *pkey);
00163 
00164 /**
00165  * Proactively toss any memory associated with the apr_datum_t.
00166  * @param dbm The database 
00167  * @param data The datum to free.
00168  */
00169 APU_DECLARE(void) apr_dbm_freedatum(apr_dbm_t *dbm, apr_datum_t data);
00170 
00171 /**
00172  * Report more information when an apr_dbm function fails.
00173  * @param dbm The database
00174  * @param errcode A DBM-specific value for the error (for logging). If this
00175  *                isn't needed, it may be NULL.
00176  * @param errbuf Location to store the error text
00177  * @param errbufsize The size of the provided buffer
00178  * @return The errbuf parameter, for convenience.
00179  */
00180 APU_DECLARE(char *) apr_dbm_geterror(apr_dbm_t *dbm, int *errcode,
00181                                      char *errbuf, apr_size_t errbufsize);
00182 /**
00183  * If the specified file/path were passed to apr_dbm_open(), return the
00184  * actual file/path names which would be (created and) used. At most, two
00185  * files may be used; used2 may be NULL if only one file is used.
00186  * @param pool The pool for allocating used1 and used2.
00187  * @param type The type of DBM you require info on
00188  * @param pathname The path name to generate used-names from.
00189  * @param used1 The first pathname used by the apr_dbm implementation.
00190  * @param used2 The second pathname used by apr_dbm. If only one file is
00191  *              used by the specific implementation, this will be set to NULL.
00192  * @return An error if the specified type is invalid.
00193  * @remark The dbm file(s) don't need to exist. This function only manipulates
00194  *      the pathnames.
00195  */
00196 APU_DECLARE(apr_status_t) apr_dbm_get_usednames_ex(apr_pool_t *pool,
00197                                                    const char *type,
00198                                                    const char *pathname,
00199                                                    const char **used1,
00200                                                    const char **used2);
00201 
00202 /**
00203  * If the specified file/path were passed to apr_dbm_open(), return the
00204  * actual file/path names which would be (created and) used. At most, two
00205  * files may be used; used2 may be NULL if only one file is used.
00206  * @param pool The pool for allocating used1 and used2.
00207  * @param pathname The path name to generate used-names from.
00208  * @param used1 The first pathname used by the apr_dbm implementation.
00209  * @param used2 The second pathname used by apr_dbm. If only one file is
00210  *              used by the specific implementation, this will be set to NULL.
00211  * @remark The dbm file(s) don't need to exist. This function only manipulates
00212  *      the pathnames.
00213  */
00214 APU_DECLARE(void) apr_dbm_get_usednames(apr_pool_t *pool,
00215                                         const char *pathname,
00216                                         const char **used1,
00217                                         const char **used2);
00218 
00219 /** @} */
00220 #ifdef __cplusplus
00221 }
00222 #endif
00223 
00224 #endif  /* !APR_DBM_H */

Generated on Sat Jan 19 01:49:04 2008 for Apache Portable Runtime by  doxygen 1.5.4