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 / F277228_apr_sdbm.h < prev    next >
C/C++ Source or Header  |  2004-02-13  |  6KB  |  175 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. /*
  17.  * sdbm - ndbm work-alike hashed database library
  18.  * based on Per-Ake Larson's Dynamic Hashing algorithms. BIT 18 (1978).
  19.  * author: oz@nexus.yorku.ca
  20.  * status: ex-public domain
  21.  */
  22.  
  23. #ifndef APR_SDBM_H
  24. #define APR_SDBM_H
  25.  
  26. #include "apu.h"
  27. #include "apr_errno.h"
  28. #include "apr_file_io.h"   /* for apr_fileperms_t */
  29.  
  30. /** 
  31.  * @file apr_sdbm.h
  32.  * @brief apr-util SDBM library
  33.  */
  34. /**
  35.  * @defgroup APR_Util_DBM_SDBM SDBM library
  36.  * @ingroup APR_Util_DBM
  37.  * @{
  38.  */
  39.  
  40. /**
  41.  * Structure for referencing an sdbm
  42.  */
  43. typedef struct apr_sdbm_t apr_sdbm_t;
  44.  
  45. /**
  46.  * Structure for referencing the datum record within an sdbm
  47.  */
  48. typedef struct {
  49.     /** pointer to the data stored/retrieved */
  50.     char *dptr;
  51.     /** size of data */
  52.     int dsize;
  53. } apr_sdbm_datum_t;
  54.  
  55. /* The extensions used for the database files */
  56. /** SDBM Directory file extension */
  57. #define APR_SDBM_DIRFEXT    ".dir"
  58. /** SDBM page file extension */
  59. #define APR_SDBM_PAGFEXT    ".pag"
  60.  
  61. /* flags to sdbm_store */
  62. #define APR_SDBM_INSERT     0   /**< Insert */
  63. #define APR_SDBM_REPLACE    1   /**< Replace */
  64. #define APR_SDBM_INSERTDUP  2   /**< Insert with duplicates */
  65.  
  66. /**
  67.  * Open an sdbm database by file name
  68.  * @param db The newly opened database
  69.  * @param name The sdbm file to open
  70.  * @param mode The flag values (APR_READ and APR_BINARY flags are implicit)
  71.  * <PRE>
  72.  *           APR_WRITE          open for read-write access
  73.  *           APR_CREATE         create the sdbm if it does not exist
  74.  *           APR_TRUNCATE       empty the contents of the sdbm
  75.  *           APR_EXCL           fail for APR_CREATE if the file exists
  76.  *           APR_DELONCLOSE     delete the sdbm when closed
  77.  *           APR_SHARELOCK      support locking across process/machines
  78.  * </PRE>
  79.  * @param perms Permissions to apply to if created
  80.  * @param p The pool to use when creating the sdbm
  81.  * @remark The sdbm name is not a true file name, as sdbm appends suffixes 
  82.  * for seperate data and index files.
  83.  */
  84. APU_DECLARE(apr_status_t) apr_sdbm_open(apr_sdbm_t **db, const char *name, 
  85.                                         apr_int32_t mode, 
  86.                                         apr_fileperms_t perms, apr_pool_t *p);
  87.  
  88. /**
  89.  * Close an sdbm file previously opened by apr_sdbm_open
  90.  * @param db The database to close
  91.  */
  92. APU_DECLARE(apr_status_t) apr_sdbm_close(apr_sdbm_t *db);
  93.  
  94. /**
  95.  * Lock an sdbm database for concurency of multiple operations
  96.  * @param db The database to lock
  97.  * @param type The lock type
  98.  * <PRE>
  99.  *           APR_FLOCK_SHARED
  100.  *           APR_FLOCK_EXCLUSIVE
  101.  * </PRE>
  102.  * @remark Calls to apr_sdbm_lock may be nested.  All apr_sdbm functions
  103.  * perform implicit locking.  Since an APR_FLOCK_SHARED lock cannot be 
  104.  * portably promoted to an APR_FLOCK_EXCLUSIVE lock, apr_sdbm_store and 
  105.  * apr_sdbm_delete calls will fail if an APR_FLOCK_SHARED lock is held.
  106.  * The apr_sdbm_lock call requires the database to be opened with the
  107.  * APR_SHARELOCK mode value.
  108.  */
  109. APU_DECLARE(apr_status_t) apr_sdbm_lock(apr_sdbm_t *db, int type);
  110.  
  111. /**
  112.  * Release an sdbm lock previously aquired by apr_sdbm_lock
  113.  * @param db The database to unlock
  114.  */
  115. APU_DECLARE(apr_status_t) apr_sdbm_unlock(apr_sdbm_t *db);
  116.  
  117. /**
  118.  * Fetch an sdbm record value by key
  119.  * @param db The database 
  120.  * @param value The value datum retrieved for this record
  121.  * @param key The key datum to find this record
  122.  */
  123. APU_DECLARE(apr_status_t) apr_sdbm_fetch(apr_sdbm_t *db, 
  124.                                          apr_sdbm_datum_t *value, 
  125.                                          apr_sdbm_datum_t key);
  126.  
  127. /**
  128.  * Store an sdbm record value by key
  129.  * @param db The database 
  130.  * @param key The key datum to store this record by
  131.  * @param value The value datum to store in this record
  132.  * @param opt The method used to store the record
  133.  * <PRE>
  134.  *           APR_SDBM_INSERT     return an error if the record exists
  135.  *           APR_SDBM_REPLACE    overwrite any existing record for key
  136.  * </PRE>
  137.  */
  138. APU_DECLARE(apr_status_t) apr_sdbm_store(apr_sdbm_t *db, apr_sdbm_datum_t key,
  139.                                          apr_sdbm_datum_t value, int opt);
  140.  
  141. /**
  142.  * Delete an sdbm record value by key
  143.  * @param db The database 
  144.  * @param key The key datum of the record to delete
  145.  * @remark It is not an error to delete a non-existent record.
  146.  */
  147. APU_DECLARE(apr_status_t) apr_sdbm_delete(apr_sdbm_t *db, 
  148.                                           const apr_sdbm_datum_t key);
  149.  
  150. /**
  151.  * Retrieve the first record key from a dbm
  152.  * @param db The database 
  153.  * @param key The key datum of the first record
  154.  * @remark The keys returned are not ordered.  To traverse the list of keys
  155.  * for an sdbm opened with APR_SHARELOCK, the caller must use apr_sdbm_lock
  156.  * prior to retrieving the first record, and hold the lock until after the
  157.  * last call to apr_sdbm_nextkey.
  158.  */
  159. APU_DECLARE(apr_status_t) apr_sdbm_firstkey(apr_sdbm_t *db, apr_sdbm_datum_t *key);
  160.  
  161. /**
  162.  * Retrieve the next record key from an sdbm
  163.  * @param db The database 
  164.  * @param key The key datum of the next record
  165.  */
  166. APU_DECLARE(apr_status_t) apr_sdbm_nextkey(apr_sdbm_t *db, apr_sdbm_datum_t *key);
  167.  
  168. /**
  169.  * Returns true if the sdbm database opened for read-only access
  170.  * @param db The database to test
  171.  */
  172. APU_DECLARE(int) apr_sdbm_rdonly(apr_sdbm_t *db);
  173. /** @} */
  174. #endif /* APR_SDBM_H */
  175.