#ifndef _TIMEOUTLIST_H_
#define _TIMEOUTLIST_H_

/*
 * Copyright (c) 2008 Telappliant Ltd.
 *
 * Permission is hereby granted, free of charge, to any person
 * obtaining a copy of this software and associated documentation
 * files (the "Software"), to deal in the Software without
 * restriction, including without limitation the rights to use,
 * copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the
 * Software is furnished to do so, subject to the following
 * conditions:
 *
 * The above copyright notice and this permission notice shall be
 * included in all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
 * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
 * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
 * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
 * OTHER DEALINGS IN THE SOFTWARE.
 *
 */

#include <time.h>

struct tol_entry
{
	unsigned long	hash;
	char*		name;
	time_t		timeout;

	/** Prev entry which expires earlier */
	struct tol_entry*	prev;

	/** Next entry who expires later */
	struct tol_entry*	next;
};

struct timeoutlist
{
	struct tol_entry*	start;
	struct tol_entry*	finish;
};

/**
 * Create a new timeout list
 *
 * @return New timeout list structure
 */
struct timeoutlist*
tol_new( void );

/**
 * Get the nearest expiry time
 *
 * @param list Timeout list
 *
 * @return next expiry time, or 0 if no elements left.
 */
time_t
tol_expiry( struct timeoutlist* list );

/**
 * Delete the whole timeout list
 *
 * @param list Timeout list
 *
 * @return All remaining items on the timeout list
 */
struct tol_entry*
tol_delete( struct timeoutlist* list );

/**
 * Add a new item to the timeout list
 *
 * @param list Timeout list
 * @param name Name of the timeout list entry
 * @param timeout Time this item will expire at
 *
 * @return New list item created
 */
struct tol_entry*
tol_add( struct timeoutlist* list, char* name, time_t timeout );

/**
 * Search for an entry in the list
 *
 * @param list Timeout list
 * @param name Item name to search for
 *
 * @return NULL if not found, otherwise the item
 */
struct tol_entry*
tol_search( struct timeoutlist* list, char* name );

/**
 * Remove an entry from the list
 *
 * @param list Timeout list
 * @param entry Entry to be removed
 */
void
tol_remove_entry( struct timeoutlist* list, struct tol_entry* entry );

/**
 * Modify the expiry time for an entry given it's name
 *
 * @param list Timeout list
 * @param name Name of the entry
 * @param timeout New timeout
 */
void
tol_modify( struct timeoutlist* list, char* name, time_t timeout );

/**
 * Free up an entry after use
 */
struct tol_entry*
tol_delete_entry( struct tol_entry* entry );

/**
 * Expire all times whos expiry date is greater than the expiry time given
 *
 * @param list Timeout list
 * @param expiry Cutoff expiry time
 *
 * @return List of expired items, or NULL if no expired items
 */
struct tol_entry*
tol_expire( struct timeoutlist* list, time_t expiry );

#endif