[svn-upgrade] Integrating new upstream version, strongswan (4.2.4)

1 files changed, 78 insertions, 123 deletions

diff --git a/src/libstrongswan/utils/linked_list.h b/src/libstrongswan/utils/linked_list.h
index ac36ef46d..310e91e3c 100644
--- a/src/libstrongswan/utils/linked_list.h
+++ b/src/libstrongswan/utils/linked_list.h
@@ -1,12 +1,5 @@
-/**
- * @file linked_list.h
- * 
- * @brief Interface of linked_list_t.
- * 
- */
-
 /*
- * Copyright (C) 2007 Tobias Brunner
+ * Copyright (C) 2007-2008 Tobias Brunner
  * Copyright (C) 2005-2006 Martin Willi
  * Copyright (C) 2005 Jan Hutter
  * Hochschule fuer Technik Rapperswil
@@ -20,6 +13,13 @@
  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  * for more details.
+ *
+ * $Id: linked_list.h 3841 2008-04-18 11:48:53Z tobias $
+ */
+ 
+/**
+ * @defgroup linked_list linked_list
+ * @{ @ingroup utils
  */
 
 #ifndef LINKED_LIST_H_
@@ -42,51 +42,50 @@ typedef struct linked_list_t linked_list_t;
  * @return
  * 						- TRUE, if the item matched
  * 						- FALSE, otherwise
- * @ingroup utils
  */
 typedef bool (*linked_list_match_t)(void *item, ...);
 
 /**
- * @brief Class implementing a double linked list.
- *
- * General purpose linked list. This list is not synchronized.
+ * Method to be invoked on elements in a linked list (used in invoke_* functions)
  *
- * @b Costructors:
- * - linked_list_create()
+ * @param item			current list item
+ * @param ...			user supplied data (only pointers, at most 5)
+ */
+typedef void (*linked_list_invoke_t)(void *item, ...);
+
+/**
+ * Class implementing a double linked list.
  *
- * @ingroup utils
+ * General purpose linked list. This list is not synchronized.
  */
 struct linked_list_t {
 
 	/**
-	 * @brief Gets the count of items in the list.
+	 * Gets the count of items in the list.
 	 * 
-	 * @param this 		calling object
 	 * @return 			number of items in list
 	 */
 	int (*get_count) (linked_list_t *this);
 	
 	/**
-	 * @brief Creates a iterator for the given list.
+	 * Creates a iterator for the given list.
 	 * 
 	 * @warning Created iterator_t object has to get destroyed by the caller.
 	 *
 	 * @deprecated Iterator is obsolete and will disappear, it is too
 	 * complicated to implement. Use enumerator instead.
 	 * 
-	 * @param this 		calling object
 	 * @param forward 	iterator direction (TRUE: front to end)
 	 * @return			new iterator_t object
 	 */
 	iterator_t *(*create_iterator) (linked_list_t *this, bool forward);
 	
 	/**
-	 * @brief Creates a iterator, locking a mutex.
+	 * Creates a iterator, locking a mutex.
 	 *
 	 * The supplied mutex is acquired immediately, and released
 	 * when the iterator gets destroyed.
 	 * 
-	 * @param this	 	calling object
 	 * @param mutex 	mutex to use for exclusive access
 	 * @return			new iterator_t object
 	 */
@@ -94,113 +93,86 @@ struct linked_list_t {
 										   pthread_mutex_t *mutex);
 	
 	/**
-	 * @brief Create an enumerator over the list.
+	 * Create an enumerator over the list.
 	 *
 	 * The enumerator is a "lightweight" iterator. It only has two methods
 	 * and should therefore be much easier to implement.
 	 *
-	 * @param this		calling object
 	 * @return			enumerator over list items
 	 */
 	enumerator_t* (*create_enumerator)(linked_list_t *this);
 	
 	/**
-	 * @brief Inserts a new item at the beginning of the list.
+	 * Inserts a new item at the beginning of the list.
 	 *
-	 * @param this 		calling object
-	 * @param[in] item	item value to insert in list
+	 * @param item		item value to insert in list
 	 */
 	void (*insert_first) (linked_list_t *this, void *item);
 
 	/**
-	 * @brief Removes the first item in the list and returns its value.
+	 * Removes the first item in the list and returns its value.
 	 * 
-	 * @param this 		calling object
-	 * @param[out] item returned value of first item, or NULL
-	 * @return
-	 * 					- SUCCESS
-	 * 					- NOT_FOUND, if list is empty
+	 * @param item 		returned value of first item, or NULL
+	 * @return			SUCCESS, or NOT_FOUND if list is empty
 	 */
 	status_t (*remove_first) (linked_list_t *this, void **item);
-
-	/**
-	 * @brief Returns the value of the first list item without removing it.
-	 * 
-	 * @param this	 	calling object
-	 * @param[out] item	returned value of first item
-	 * @return
-	 * 					- SUCCESS
-	 * 					- NOT_FOUND, if list is empty
-	 */
-	status_t (*get_first) (linked_list_t *this, void **item);
-
+	
 	/**
-	 * @brief Inserts a new item at the end of the list.
-	 * 
-	 * @param this 		calling object
-	 * @param[in] item 	value to insert into list
+	 * Remove an item from the list where the enumerator points to.
+	 *
+	 * @param enumerator enumerator with position
 	 */
-	void (*insert_last) (linked_list_t *this, void *item);
+	void (*remove_at)(linked_list_t *this, enumerator_t *enumerator);
 	
 	/**
-	 * @brief Inserts a new item at a given position in the list.
+	 * Remove items from the list matching item.
 	 * 
-	 * @param this		calling object
-	 * @param position	position starting at 0 to insert new entry
-	 * @param[in] item	value to insert into list
-	 * @return
-	 * 					- SUCCESS
-	 * 					- INVALID_ARG if position not existing
+	 * If a compare function is given, it is called for each item, where
+	 * the first parameter is the current list item and the second parameter
+	 * is the supplied item parameter.
+	 * If compare is NULL, compare is is done by pointer.
+	 *
+	 * @param item		item to remove/pass to comparator
+	 * @param compare	compare function, or NULL
+	 * @return			number of removed items
 	 */
-	status_t (*insert_at_position) (linked_list_t *this,size_t position, void *item);
+	int (*remove)(linked_list_t *this, void *item, bool (*compare)(void *,void*));
 	
 	/**
-	 * @brief Removes an item from a given position in the list.
+	 * Returns the value of the first list item without removing it.
 	 * 
 	 * @param this	 	calling object
-	 * @param position	position starting at 0 to remove entry from
-	 * @param[out] item removed item will be stored at this location
-	 * @return
-	 * 						- SUCCESS
-	 * 						- INVALID_ARG if position not existing
+	 * @param item		returned value of first item
+	 * @return			SUCCESS, NOT_FOUND if list is empty
 	 */
-	status_t (*remove_at_position) (linked_list_t *this, size_t position, void **item);
+	status_t (*get_first) (linked_list_t *this, void **item);
 
 	/**
-	 * @brief Get an item from a given position in the list.
+	 * Inserts a new item at the end of the list.
 	 * 
-	 * @param this	 	calling object
-	 * @param position	position starting at 0 to get entry from
-	 * @param[out] item	item will be stored at this location
-	 * @return
-	 * 						- SUCCESS
-	 * 						- INVALID_ARG if position not existing
+	 * @param item 		value to insert into list
 	 */
-	status_t (*get_at_position) (linked_list_t *this, size_t position, void **item);
+	void (*insert_last) (linked_list_t *this, void *item);
 
 	/**
-	 * @brief Removes the last item in the list and returns its value.
+	 * Removes the last item in the list and returns its value.
 	 * 
 	 * @param this	 	calling object
-	 * @param[out] item	returned value of last item, or NULL
-	 * @return
-	 * 						- SUCCESS
-	 * 						- NOT_FOUND if list is empty
+	 * @param item		returned value of last item, or NULL
+	 * @return			SUCCESS, NOT_FOUND if list is empty
 	 */
 	status_t (*remove_last) (linked_list_t *this, void **item);
 
 	/**
-	 * @brief Returns the value of the last list item without removing it.
+	 * Returns the value of the last list item without removing it.
 	 * 
 	 * @param this 		calling object
-	 * @param[out] item	returned value of last item
-	 * @return
-	 * 					- SUCCESS
-	 * 					- NOT_FOUND if list is empty
+	 * @param item		returned value of last item
+	 * @return			SUCCESS, NOT_FOUND if list is empty
 	 */
 	status_t (*get_last) (linked_list_t *this, void **item);
 	
-	/** @brief Find the first matching element in the list.
+	/** Find the first matching element in the list.
 	 * 
 	 * The first object passed to the match function is the current list item,
 	 * followed by the user supplied data.
@@ -210,19 +182,15 @@ struct linked_list_t {
 	 * 
 	 * @warning Only use pointers as user supplied data.
 	 *
-	 * @param this			calling object
 	 * @param match			comparison function to call on each object
-	 * @param[out] item		
-	 * 						- the list item, if found
-	 * 						- NULL, otherwise
+	 * @param item			the list item, if found
 	 * @param ...			user data to supply to match function (limited to 5 arguments)
-	 * @return				
-	 * 						- SUCCESS, if found
-	 * 						- NOT_FOUND, otherwise
+	 * @return				SUCCESS if found, NOT_FOUND otherwise
 	 */
-	status_t (*find_first) (linked_list_t *this, linked_list_match_t match, void **item, ...);
+	status_t (*find_first) (linked_list_t *this, linked_list_match_t match,
+							void **item, ...);
 	
-	/** @brief Find the last matching element in the list.
+	/** Find the last matching element in the list.
 	 * 
 	 * The first object passed to the match function is the current list item,
 	 * followed by the user supplied data.
@@ -232,20 +200,16 @@ struct linked_list_t {
 	 * 
 	 * @warning Only use pointers as user supplied data.
 	 *
-	 * @param this			calling object
 	 * @param match			comparison function to call on each object
-	 * @param[out] item		
-	 * 						- the list item, if found
-	 * 						- NULL, otherwise
+	 * @param item			the list item, if found
 	 * @param ...			user data to supply to match function (limited to 5 arguments)
-	 * @return				
-	 * 						- SUCCESS, if found
-	 * 						- NOT_FOUND, otherwise
+	 * @return				SUCCESS if found, NOT_FOUND otherwise
 	 */
-	status_t (*find_last) (linked_list_t *this, linked_list_match_t match, void **item, ...);
+	status_t (*find_last) (linked_list_t *this, linked_list_match_t match,
+						   void **item, ...);
 	
 	/**
-	 * @brief Invoke a method on all of the contained objects.
+	 * Invoke a method on all of the contained objects.
 	 *
 	 * If a linked list contains objects with function pointers,
 	 * invoke() can call a method on each of the objects. The
@@ -253,79 +217,70 @@ struct linked_list_t {
 	 * which can be evalutated at compile time using the offsetof
 	 * macro, e.g.: list->invoke(list, offsetof(object_t, method));
 	 * 
-	 * @param this 		calling object
 	 * @param offset	offset of the method to invoke on objects
+	 * @param ...		user data to supply to called function (limited to 5 arguments)
 	 */
-	void (*invoke_offset) (linked_list_t *this, size_t offset);
+	void (*invoke_offset) (linked_list_t *this, size_t offset, ...);
 	
 	/**
-	 * @brief Invoke a function on all of the contained objects.
+	 * Invoke a function on all of the contained objects.
 	 * 
-	 * @param this 		calling object
-	 * @param offset	offset of the method to invoke on objects
+	 * @param function	offset of the method to invoke on objects
+	 * @param ...		user data to supply to called function (limited to 5 arguments)
 	 */
-	void (*invoke_function) (linked_list_t *this, void (*)(void*));
+	void (*invoke_function) (linked_list_t *this, linked_list_invoke_t function, ...);
 	
 	/**
-	 * @brief Clones a list and its objects using the objects' clone method.
+	 * Clones a list and its objects using the objects' clone method.
 	 * 
-	 * @param this		calling object
 	 * @param offset	offset ot the objects clone function
 	 * @return			cloned list
 	 */
 	linked_list_t *(*clone_offset) (linked_list_t *this, size_t offset);
 	
 	/**
-	 * @brief Clones a list and its objects using a given function.
+	 * Clones a list and its objects using a given function.
 	 * 
-	 * @param this		calling object
 	 * @param function	function that clones an object
 	 * @return			cloned list
 	 */
 	linked_list_t *(*clone_function) (linked_list_t *this, void*(*)(void*));
 	
 	/**
-	 * @brief Destroys a linked_list object.
-	 * 
-	 * @param this		calling object
+	 * Destroys a linked_list object.
 	 */
 	void (*destroy) (linked_list_t *this);
 	
 	/**
-	 * @brief Destroys a list and its objects using the destructor.
+	 * Destroys a list and its objects using the destructor.
 	 *
 	 * If a linked list and the contained objects should be destroyed, use
 	 * destroy_offset. The supplied offset specifies the destructor to
 	 * call on each object. The offset may be calculated using the offsetof
 	 * macro, e.g.: list->destroy_offset(list, offsetof(object_t, destroy));
 	 *
-	 * @param this	 	calling object
 	 * @param offset	offset of the objects destructor
 	 */
 	void (*destroy_offset) (linked_list_t *this, size_t offset);
 	
 	/**
-	 * @brief Destroys a list and its contents using a a cleanup function.
+	 * Destroys a list and its contents using a a cleanup function.
 	 * 
 	 * If a linked list and its contents should get destroyed using a specific
 	 * cleanup function, use destroy_function. This is useful when the
 	 * list contains malloc()-ed blocks which should get freed,
 	 * e.g.: list->destroy_function(list, free);
 	 *
-	 * @param this 		calling object
 	 * @param function	function to call on each object
 	 */
 	void (*destroy_function) (linked_list_t *this, void (*)(void*));
 };
 
 /**
- * @brief Creates an empty linked list object.
+ * Creates an empty linked list object.
  * 
  * @return 		linked_list_t object.
- * 
- * @ingroup utils
  */
 linked_list_t *linked_list_create(void);
 
-
-#endif /*LINKED_LIST_H_*/
+#endif /*LINKED_LIST_H_ @} */