/*
 * Originally from apache 2.0
 * Modifications for general use by <nielsen@memberwebs.com>
 */

/* Copyright 2000-2004 The Apache Software Foundation
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

#ifndef __HASH_H__
#define __HASH_H__

/*
 * Features to define. You need to build both this file and
 * the corresponding hash.c file with whatever options you set here
 */

/* Keep timestamps for the entries */
#define HASH_TIMESTAMP  1

/* Keep key values internally */
#define HASH_COPYKEYS   1

/* Hash callback functionality */
#define HASH_CALLBACKS  1


#ifdef __cplusplus
extern "C" {
#endif

/**
 * When passing a key to hash_set or hash_get, this value can be passed to
 * indicate a string-valued key, and have hash compute the length automatically.
 */
#define HASH_KEY_STRING     (-1)

/* Abstract type for hash tables. */
typedef struct hash_t hash_t;

/* Abstract type for scanning hash tables.  */
typedef struct hash_index_t hash_index_t;

/* A callback during remove operations */
#ifdef HASH_CALLBACKS
  typedef void (*hash_free_val_t)(void* arg, void* val);
#endif

/* Create a hash table */
#ifdef HASH_CALLBACKS
  #ifdef HASH_COPYKEYS
    hash_t* hash_create(size_t klen, hash_free_val_t f_free, void* arg);
  #else
    hash_t* hash_create(hash_free_val_t f_free, void* arg);
  #endif
#else
  #ifdef HASH_COPYKEYS
    hash_t* hash_create(size_t klen);
  #else
    hash_t* hash_create();
  #endif
#endif /* HASH_CALLBACKS */


/* To release all resources for a hash table */
void hash_free(hash_t* ht);


/**
 * Associate a value with a key in a hash table.
 *
 * ht The hash table
 * key Pointer to the key
 * klen Length of the key. Can be HASH_KEY_STRING to use the string length.
 * val Value to associate with the key
 *
 * val must not be null
 */
#ifdef HASH_COPYKEYS
  int hash_set(hash_t* ht, const void* key, void* val);
#else
  int hash_set(hash_t* ht, const void* key, size_t klen, void* val);
#endif


/**
 * Remove a value and key form the hash table
 *
 * ht The hash table
 * key Pointer to the key
 * klen Length of the key. Can be HASH_KEY_STRING to use the string length
 */
#ifdef HASH_COPYKEYS
  void* hash_rem(hash_t* ht, const void* key);
#else
  void* hash_rem(hash_t* ht, const void* key, size_t klen);
#endif


/**
 * Look up the value associated with a key in a hash table.
 *
 * ht The hash table
 * key Pointer to the key
 * klen Length of the key. Can be APR_HASH_KEY_STRING to use the string length.
 *
 * Returns NULL if the key is not present.
 */
#ifdef HASH_COPYKEYS
  void* hash_get(hash_t* ht, const void* key);
#else
  void* hash_get(hash_t* ht, const void* key, size_t klen);
#endif


/**
 * Start iterating over the entries in a hash table.
 *
 * ht The hash table
 *
 * There is no restriction on adding or deleting hash entries during
 * an iteration (although the results may be unpredictable unless all you do
 * is delete the current entry). Only one iteration can be in progress at once.
 */
hash_index_t* hash_first(hash_t* ht);


/**
 * Continue iterating over the entries in a hash table.
 *
 * hi The iteration state
 *
 * Returns a pointer to the updated iteration state.
 * NULL if there are no more entries.
 */
hash_index_t* hash_next(hash_index_t* hi);


/**
 * Get the current entry's details from the iteration state.
 *
 * hi The iteration state
 * key Return pointer for the pointer to the key.
 * klen Return pointer for the key length.
 * val Return pointer for the associated value.
 *
 * The return pointers should point to a variable that will be set to the
 * corresponding data, or they may be NULL if the data isn't interesting.
 */
#ifdef HASH_COPYKEYS
  void* hash_this(hash_index_t* hi, const void** key);
#else
  void* hash_this(hash_index_t* hi, const void** key, size_t* klen);
#endif


/**
 * Purge entries before a certain timestamp
 */
#ifdef HASH_TIMESTAMP

int hash_purge(hash_t* ht, time_t stamp);

#ifdef HASH_COPYKEYS
  void hash_touch(hash_t* ht, const void* key);
#else
  void hash_touch(hash_t* ht, const void* key, size_t* klen);
#endif

/* Bumps the oldest out */
int hash_bump(hash_t* ht);

#endif


/**
 * Get the number of key/value pairs in the hash table.
 *
 * ht The hash table
 *
 * The number of key/value pairs in the hash table.
 */
unsigned int hash_count(hash_t* ht);


#ifdef __cplusplus
}
#endif

#endif  /* __HASH_H__ */