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