Apache Portable Runtime
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
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  *  db   for Berkeley DB files
00067  *  gdbm for GDBM files
00068  *  ndbm for NDBM files
00069  *  sdbm for SDBM files (always available)
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  * @bug In apr-util 0.9 and 1.x, the type arg was case insensitive.  This
00085  * was highly inefficient, and as of 2.x the dbm name must be provided in
00086  * the correct case (lower case for all bundled providers)
00087  */
00088 
00089 APR_DECLARE(apr_status_t) apr_dbm_open_ex(apr_dbm_t **dbm, const char* type, 
00090                                        const char *name, 
00091                                        apr_int32_t mode, apr_fileperms_t perm,
00092                                        apr_pool_t *cntxt);
00093 
00094 
00095 /**
00096  * Open a dbm file by file name
00097  * @param dbm The newly opened database
00098  * @param name The dbm file name to open
00099  * @param mode The flag value
00100  * <PRE>
00101  *           APR_DBM_READONLY   open for read-only access
00102  *           APR_DBM_READWRITE  open for read-write access
00103  *           APR_DBM_RWCREATE   open for r/w, create if needed
00104  *           APR_DBM_RWTRUNC    open for r/w, truncate if already there
00105  * </PRE>
00106  * @param perm Permissions to apply to if created
00107  * @param cntxt The pool to use when creating the dbm
00108  * @remark The dbm name may not be a true file name, as many dbm packages
00109  * append suffixes for seperate data and index files.
00110  */
00111 APR_DECLARE(apr_status_t) apr_dbm_open(apr_dbm_t **dbm, const char *name, 
00112                                        apr_int32_t mode, apr_fileperms_t perm,
00113                                        apr_pool_t *cntxt);
00114 
00115 /**
00116  * Close a dbm file previously opened by apr_dbm_open
00117  * @param dbm The database to close
00118  */
00119 APR_DECLARE(void) apr_dbm_close(apr_dbm_t *dbm);
00120 
00121 /**
00122  * Fetch a dbm record value by key
00123  * @param dbm The database 
00124  * @param key The key datum to find this record
00125  * @param pvalue The value datum retrieved for this record
00126  */
00127 APR_DECLARE(apr_status_t) apr_dbm_fetch(apr_dbm_t *dbm, apr_datum_t key,
00128                                         apr_datum_t *pvalue);
00129 /**
00130  * Store a dbm record value by key
00131  * @param dbm The database 
00132  * @param key The key datum to store this record by
00133  * @param value The value datum to store in this record
00134  */
00135 APR_DECLARE(apr_status_t) apr_dbm_store(apr_dbm_t *dbm, apr_datum_t key, 
00136                                         apr_datum_t value);
00137 
00138 /**
00139  * Delete a dbm record value by key
00140  * @param dbm The database 
00141  * @param key The key datum of the record to delete
00142  * @remark It is not an error to delete a non-existent record.
00143  */
00144 APR_DECLARE(apr_status_t) apr_dbm_delete(apr_dbm_t *dbm, apr_datum_t key);
00145 
00146 /**
00147  * Search for a key within the dbm
00148  * @param dbm The database 
00149  * @param key The datum describing a key to test
00150  */
00151 APR_DECLARE(int) apr_dbm_exists(apr_dbm_t *dbm, apr_datum_t key);
00152 
00153 /**
00154  * Retrieve the first record key from a dbm
00155  * @param dbm The database 
00156  * @param pkey The key datum of the first record
00157  */
00158 APR_DECLARE(apr_status_t) apr_dbm_firstkey(apr_dbm_t *dbm, apr_datum_t *pkey);
00159 
00160 /**
00161  * Retrieve the next record key from a dbm
00162  * @param dbm The database 
00163  * @param pkey The key datum of the next record
00164  */
00165 APR_DECLARE(apr_status_t) apr_dbm_nextkey(apr_dbm_t *dbm, apr_datum_t *pkey);
00166 
00167 /**
00168  * Proactively toss any memory associated with the apr_datum_t.
00169  * @param dbm The database 
00170  * @param data The datum to free.
00171  */
00172 APR_DECLARE(void) apr_dbm_freedatum(apr_dbm_t *dbm, apr_datum_t data);
00173 
00174 /**
00175  * Report more information when an apr_dbm function fails.
00176  * @param dbm The database
00177  * @param errcode A DBM-specific value for the error (for logging). If this
00178  *                isn't needed, it may be NULL.
00179  * @param errbuf Location to store the error text
00180  * @param errbufsize The size of the provided buffer
00181  * @return The errbuf parameter, for convenience.
00182  */
00183 APR_DECLARE(char *) apr_dbm_geterror(apr_dbm_t *dbm, int *errcode,
00184                                      char *errbuf, apr_size_t errbufsize);
00185 /**
00186  * If the specified file/path were passed to apr_dbm_open(), return the
00187  * actual file/path names which would be (created and) used. At most, two
00188  * files may be used; used2 may be NULL if only one file is used.
00189  * @param pool The pool for allocating used1 and used2.
00190  * @param type The type of DBM you require info on @see apr_dbm_open_ex
00191  * @param pathname The path name to generate used-names from.
00192  * @param used1 The first pathname used by the apr_dbm implementation.
00193  * @param used2 The second pathname used by apr_dbm. If only one file is
00194  *              used by the specific implementation, this will be set to NULL.
00195  * @return An error if the specified type is invalid.
00196  * @remark The dbm file(s) don't need to exist. This function only manipulates
00197  *      the pathnames.
00198  */
00199 APR_DECLARE(apr_status_t) apr_dbm_get_usednames_ex(apr_pool_t *pool,
00200                                                    const char *type,
00201                                                    const char *pathname,
00202                                                    const char **used1,
00203                                                    const char **used2);
00204 
00205 /**
00206  * If the specified file/path were passed to apr_dbm_open(), return the
00207  * actual file/path names which would be (created and) used. At most, two
00208  * files may be used; used2 may be NULL if only one file is used.
00209  * @param pool The pool for allocating used1 and used2.
00210  * @param pathname The path name to generate used-names from.
00211  * @param used1 The first pathname used by the apr_dbm implementation.
00212  * @param used2 The second pathname used by apr_dbm. If only one file is
00213  *              used by the specific implementation, this will be set to NULL.
00214  * @remark The dbm file(s) don't need to exist. This function only manipulates
00215  *      the pathnames.
00216  */
00217 APR_DECLARE(void) apr_dbm_get_usednames(apr_pool_t *pool,
00218                                         const char *pathname,
00219                                         const char **used1,
00220                                         const char **used2);
00221 
00222 /** @} */
00223 #ifdef __cplusplus
00224 }
00225 #endif
00226 
00227 #endif  /* !APR_DBM_H */
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Defines